wine/documentation/installing.sgml
Andreas Mohr 5ec74d6f72 - Move "questions and comments" at the top of the document.
- Removed elfdll documentation.
- Properly documented Desktop and Managed config.
- Rearranged config entries according to importance.
- "wine.conf" -> "the wine config file" in some cases.
- Updated to new FTP URLs.
- Fix non-backslash-escaped paths (ouch !).
- Replace text references by real links.
- Misc. other updates.
2002-07-24 03:00:02 +00:00

727 lines
29 KiB
Text

<chapter id="installing">
<title>Installing/compiling Wine</title>
<para>How to install Wine...</para>
<sect1 id="replace-windows" xreflabel="--Installing Section--">
<title>WWN #52 Feature: Replacing Windows</title>
<para>
Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
</para>
<sect2>
<title>Installation Overview</title>
<para>
A Windows installation consists of many different parts.
</para>
<itemizedlist>
<listitem>
<para>
Registry. Many keys are supposed to exist and contain
meaningful data, even in a newly-installed Windows.
</para>
</listitem>
<listitem>
<para>
Directory structure. Applications expect to find and/or
install things in specific predetermined locations. Most
of these directories are expected to exist. But unlike
Unix directory structures, most of these locations are
not hardcoded, and can be queried via the Windows API
and the registry. This places additional requirements on
a Wine installation.
</para>
</listitem>
<listitem>
<para>
System DLLs. In Windows, these usually reside in the
<filename>system</filename> (or
<filename>system32</filename>) directories. Some Windows
applications check for their existence in these
directories before attempting to load them. While Wine
is able to load its own internal DLLs
(<filename>.so</filename> files) when the application
asks for a DLL, Wine does not simulate the existence of
nonexisting files.
</para>
</listitem>
</itemizedlist>
<para>
While the users are of course free to set up everything
themselves, the Wine team will make the automated Wine source
installation script, <filename>tools/wineinstall</filename>,
do everything we find necessary to do; running the
conventional <userinput>configure && make depend && make && make
install</userinput> cycle is thus not recommended, unless
you know what you're doing. At the moment,
<filename>tools/wineinstall</filename> is able to create a
configuration file, install the registry, and create the
directory structure itself.
</para>
</sect2>
<sect2>
<title>The Registry</title>
<para>
The default registry is in the file
<filename>winedefault.reg</filename>. It contains directory
paths, class IDs, and more; it must be installed before most
<filename>INSTALL.EXE</filename> or
<filename>SETUP.EXE</filename> applications will work. The
registry is covered in more detail <link
linkend="registry">here</link>.
</para>
</sect2>
<sect2>
<title>Directory Structure</title>
<para>
Here's the fundamental layout that Windows applications and
installers expect. Without it, they seldom operate
correctly.
</para>
<programlisting>
C:\ Root directory of primary disk drive
Windows\ Windows directory, containing .INI files,
accessories, etc.
System\ Win3.x/95/98/ME directory for common DLLs
WinNT/2000 directory for common 16-bit DLLs
System32\ WinNT/2000 directory for common 32-bit DLLs
Start Menu\ Program launcher directory structure
Programs\ Program launcher links (.LNK files) to applications
Program Files\ Application binaries (.EXE and .DLL files)
</programlisting>
<para>
Wine emulates drives by placing their virtual drive roots to
user-configurable points in the Unix filesystem, so it's
your choice where <medialabel>C:</medialabel>'s root should
be (<filename>tools/wineinstall</filename> will even ask
you). If you choose, say, <filename>/var/wine</filename>, as
the root of your virtual drive <medialabel>C</medialabel>,
then you'd put this in your <filename>~/.wine/config</filename>:
</para>
<programlisting>
[Drive C]
"Path" = "/var/wine"
"Type" = "hd"
"Label" = "MS-DOS"
"Filesystem" = "win95"
</programlisting>
<para>
With this configuration, what windows apps think of as
"c:\windows\system" would map to
<filename>/var/wine/windows/system</filename> in the UNIX
filesystem. Note that you need to specify
<literal>"Filesystem" = "win95"</literal>, NOT
<literal>"Filesystem" = "unix"</literal>, to make Wine simulate a
Windows-compatible (case-insensitive) filesystem, otherwise
most apps won't work.
</para>
</sect2>
<sect2>
<title>System DLLs</title>
<para>
The Wine team has determined that it is necessary to create
fake DLL files to trick many applications that check for
file existence to determine whether a particular feature
(such as Winsock and its TCP/IP networking) is available. If
this is a problem for you, you can create empty files in the
configured <filename>c:\windows\system</filename> directory
to make the application think it's there, and Wine's built-in DLL
will be loaded when the application actually asks for it.
(Unfortunately, <filename>tools/wineinstall</filename> does
not create such empty files itself.)
</para>
<para>
Applications sometimes also try to inspect the version
resources from the physical files (for example, to determine
the DirectX version). Empty files will not do in this case,
it is rather necessary to install files with complete
version resources. This problem is currently being worked
on. In the meantime, you may still need to grab some real
DLL files to fool these apps with.
</para>
<para>
And there are of course DLLs that wine does not currently
implement very well (or at all). If you do not have a real
Windows you can steal necessary DLLs from, you can always
get some from one of the Windows DLL archive sites
that can be found via internet search engine.
Please make sure to obey any licenses on the DLLs you fetch...
(some are redistributable, some aren't).
</para>
</sect2>
</sect1>
<sect1 id="no-windows">
<title>Installing Wine Without Windows</title>
<para>
Written by &name-james-juran; <email>&email-james-juran;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/no-windows</filename>)
</para>
<para>
A major goal of Wine is to allow users to run Windows programs
without having to install Windows on their machine. Wine
implements the functionality of the main DLLs usually
provided with Windows. Therefore, once Wine is finished, you
will not need to have windows installed to use Wine.
</para>
<para>
Wine has already made enough progress that it may be possible
to run your target applications without Windows installed. If
you want to try it, follow these steps:
</para>
<orderedlist>
<listitem>
<para>
Create empty <filename>C:\windows</filename>,
<filename>C:\windows\system</filename>,
<filename>C:\windows\Start Menu</filename>, and
<filename>C:\windows\Start Menu\Programs</filename>
directories. Do not point Wine to a
<filename>Windows</filename> directory full of old
installations and a messy registry. (Wine creates a
special registry in your <filename >home</filename>
directory, in <filename>$HOME/.wine/*.reg</filename>.
Perhaps you have to remove these files).
</para>
</listitem>
<listitem>
<para>
Point <medialabel>[Drive C]</medialabel> in
<filename>~/.wine/config</filename> to where you want
<filename>C:</filename> to be. Refer to the Wine man page
for more information. Remember to use
<userinput>"Filesystem" = "win95"</userinput>!
</para>
</listitem>
<listitem>
<para>
Use <filename>tools/wineinstall</filename> to compile Wine
and install the default registry. Or if you prefer to do
it yourself, compile <filename>programs/regapi</filename>,
and run:
</para>
<screen>
<userinput>programs/regapi/regapi setValue &lt; winedefault.reg</userinput>
</screen>
</listitem>
<listitem>
<para>
Run and/or install your applications.
</para>
</listitem>
</orderedlist>
<para>
Because Wine is not yet complete, some programs will work
better with native Windows DLLs than with Wine's
replacements. Wine has been designed to make this possible.
Here are some tips by Juergen Schmied (and others) on how to
proceed. This assumes that your
<filename>C:\windows</filename> directory in the configuration
file does not point to a native Windows installation but is in
a separate Unix file system. (For instance, <quote>C:\windows</quote> is
really subdirectory <quote>windows</quote> located in
<quote>/home/ego/wine/drives/c</quote>).
</para>
<itemizedlist>
<listitem>
<para>
Run the application with <parameter>--debugmsg
+loaddll</parameter> to find out which files are
needed. Copy the required DLLs one by one to the
<filename>C:\windows\system</filename> directory. Do not
copy KERNEL/KERNEL32, GDI/GDI32, USER/USER32 or NTDLL. These
implement the core functionality of the Windows API, and
the Wine internal versions must be used.
</para>
</listitem>
<listitem>
<para>
Edit the <quote>[DllOverrides]</quote> section of
<filename>~/.wine/config</filename> to specify
<quote>native</quote> before <quote>builtin</quote> for
the Windows DLLs you want to use. For more information
about this, see the Wine manpage.
</para>
</listitem>
<listitem>
<para>
Note that some network DLLs are not needed even though
Wine is looking for them. The Windows
<filename>MPR.DLL</filename> currently does not work; you
must use the internal implementation.
</para>
</listitem>
<listitem>
<para>
Copy SHELL/SHELL32 and COMDLG/COMDLG32 COMMCTRL/COMCTL32
only as pairs to your Wine directory (these DLLs are
<quote>clean</quote> to use). Make sure you have these
specified in the <quote>[DllPairs]</quote> section of
<filename>~/.wine/config</filename>.
</para>
</listitem>
<listitem>
<para>
Be consistent: Use only DLLs from the same Windows version
together.
</para>
</listitem>
<listitem>
<para>
Put <filename>regedit.exe</filename> in the
<filename>C:\windows</filename> directory.
(<application>Office 95</application> imports a
<filename>*.reg</filename> file when it runs with an empty
registry, don't know about
<application>Office 97</application>).
</para>
</listitem>
<listitem>
<para>
Also add <filename>winhelp.exe</filename> and
<filename>winhlp32.exe</filename> if you want to be able
to browse through your programs' help function.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="vfat">
<title>Dealing With FAT/VFAT Partitions</title>
<para>
Written by &name-steven-elliott; <email>&email-steven-elliott;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/linux-fat-permissions</filename>)
</para>
<para>
This document describes how FAT and
VFAT file system permissions work in Linux
with a focus on configuring them for Wine.
</para>
<sect2>
<title>Introduction</title>
<para>
Linux is able to access DOS and Windows file systems using
either the FAT (older 8.3 DOS filesystems) or VFAT (newer
Windows 95 or later long filename filesystems) modules.
Mounted FAT or VFAT filesystems provide the primary means
for which existing applications and their data are accessed
through Wine for dual boot (Linux + Windows) systems.
</para>
<para>
Wine maps mounted FAT filesystems, such as
<filename>/c</filename>, to driver letters, such as
<quote>c:</quote>, as indicated by the
<filename>~/.wine/config</filename> file. The following excerpt
from a <filename>~/.wine/config</filename> file does this:
</para>
<programlisting>
[Drive C]
"Path" = "/c"
"Type" = "hd"
</programlisting>
<para>
Although VFAT filesystems are preferable to FAT filesystems
for their long filename support the term <quote>FAT</quote>
will be used throughout the remainder of this document to
refer to FAT filesystems and their derivatives. Also,
<quote>/c</quote> will be used as the FAT mount point in
examples throughout this document.
</para>
<para>
Most modern Linux distributions either detect or allow
existing FAT file systems to be configured so that they can be
mounted, in a location such as <filename>/c</filename>,
either persistently (on bootup) or on an as needed basis. In
either case, by default, the permissions will probably be
configured so that they look like:
</para>
<screen>
<prompt>~></prompt><userinput>cd /c</userinput>
<prompt>/c></prompt><userinput>ls -l</userinput>
<computeroutput>-rwxr-xr-x 1 root root 91 Oct 10 17:58 autoexec.bat
-rwxr-xr-x 1 root root 245 Oct 10 17:58 config.sys
drwxr-xr-x 41 root root 16384 Dec 30 1998 windows</computeroutput>
</screen>
<para>
where all the files are owned by "root", are in the "root"
group and are only writable by "root"
(<literal>755</literal> permissions). This is restrictive in
that it requires that Wine be run as root in order for
applications to be able to write to any part of the
filesystem.
</para>
<para>
There are three major approaches to overcoming the restrictive
permissions mentioned in the previous paragraph:
</para>
<orderedlist>
<listitem>
<para>
Run <application>Wine</application> as root
</para>
</listitem>
<listitem>
<para>
Mount the FAT filesystem with less restrictive
permissions
</para>
</listitem>
<listitem>
<para>
Shadow the FAT filesystem by completely or partially
copying it
</para>
</listitem>
</orderedlist>
<para>
Each approach will be discussed in the following sections.
</para>
</sect2>
<sect2>
<title>Running Wine as root</title>
<para>
Running Wine as root is the easiest and most thorough way of giving
applications that Wine runs unrestricted access to FAT files systems.
Running wine as root also allows applications to do things unrelated
to FAT filesystems, such as listening to ports that are less than
1024. Running Wine as root is dangerous since there is no limit to
what the application can do to the system.
</para>
</sect2>
<sect2>
<title>Mounting FAT filesystems</title>
<para>
The FAT filesystem can be mounted with permissions less restrictive
than the default. This can be done by either changing the user that
mounts the FAT filesystem or by explicitly changing the permissions
that the FAT filesystem is mounted with. The permissions are
inherited from the process that mounts the FAT filesystem. Since the
process that mounts the FAT filesystem is usually a startup script
running as root the FAT filesystem inherits root's permissions. This
results in the files on the FAT filesystem having permissions similar
to files created by root. For example:
</para>
<screen>
<prompt>~></prompt><userinput>whoami</userinput>
<computeroutput>root</computeroutput>
<prompt>~></prompt><userinput>touch root_file</userinput>
<prompt>~></prompt><userinput>ls -l root_file</userinput>
<computeroutput></computeroutput>-rw-r--r-- 1 root root 0 Dec 10 00:20 root_file
</screen>
<para>
which matches the owner, group and permissions of files seen
on the FAT filesystem except for the missing 'x's. The
permissions on the FAT filesystem can be changed by changing
root's umask (unset permissions bits). For example:
</para>
<screen>
<prompt>~></prompt><userinput>umount /c</userinput>
<prompt>~></prompt><userinput>umask</userinput>
<computeroutput>022</computeroutput>
<prompt>~></prompt><userinput>umask 073</userinput>
<prompt>~></prompt><userinput>mount /c</userinput>
<prompt>~></prompt><userinput>cd /c</userinput>
<prompt>/c></prompt><userinput>ls -l</userinput>
<computeroutput>-rwx---r-- 1 root root 91 Oct 10 17:58 autoexec.bat
-rwx---r-- 1 root root 245 Oct 10 17:58 config.sys
drwx---r-- 41 root root 16384 Dec 30 1998 windows</computeroutput>
</screen>
<para>
Mounting the FAT filesystem with a umask of
<literal>000</literal> gives all users complete control over
it. Explicitly specifying the permissions of the FAT
filesystem when it is mounted provides additional control.
There are three mount options that are relevant to FAT
permissions: <literal>uid</literal>, <literal>gid</literal>
and <literal>umask</literal>. They can each be specified
when the filesystem is manually mounted. For example:
</para>
<screen>
<prompt>~></prompt><userinput>umount /c</userinput>
<prompt>~></prompt><userinput>mount -o uid=500 -o gid=500 -o umask=002 /c</userinput>
<prompt>~></prompt><userinput>cd /c</userinput>
<prompt>/c></prompt><userinput>ls -l</userinput>
<computeroutput>-rwxrwxr-x 1 sle sle 91 Oct 10 17:58 autoexec.bat
-rwxrwxr-x 1 sle sle 245 Oct 10 17:58 config.sys
drwxrwxr-x 41 sle sle 16384 Dec 30 1998 windows</computeroutput>
</screen>
<para>
which gives "sle" complete control over
<filename>/c</filename>. The options listed above can be
made permanent by adding them to the
<filename>/etc/fstab</filename> file:
</para>
<screen>
<prompt>~></prompt><userinput>grep /c /etc/fstab</userinput>
<computeroutput>/dev/hda1 /c vfat uid=500,gid=500,umask=002,exec,dev,suid,rw 1 1</computeroutput>
</screen>
<para>
Note that the umask of <literal>002</literal> is common in
the user private group file permission scheme. On FAT file
systems this umask assures that all files are fully
accessible by all users in the specified group
(<literal>gid</literal>).
</para>
</sect2>
<sect2>
<title>Shadowing FAT filesystems</title>
<para>
Shadowing provides a finer granularity of control. Parts of
the original FAT filesystem can be copied so that the
application can safely work with those copied parts while
the application continues to directly read the remaining
parts. This is done with symbolic links. For example,
consider a system where an application named
<application>AnApp</application> must be able to read and
write to the <filename>c:\windows</filename> and
<filename>c:\AnApp</filename> directories as well as have
read access to the entire FAT filesystem. On this system
the FAT filesystem has default permissions which should not
be changed for security reasons or can not be changed due to
lack of root access. On this system a shadow directory
might be set up in the following manner:
</para>
<screen>
<prompt>~></prompt><userinput>cd /</userinput>
<prompt>/></prompt><userinput>mkdir c_shadow</userinput>
<prompt>/></prompt><userinput>cd c_shadow</userinput>
<prompt>/c_shadow></prompt><userinput>ln -s /c_/* .</userinput>
<prompt>/c_shadow></prompt><userinput>rm windows AnApp</userinput>
<prompt>/c_shadow></prompt><userinput>cp -R /c_/{windows,AnApp} .</userinput>
<prompt>/c_shadow></prompt><userinput>chmod -R 777 windows AnApp</userinput>
<prompt>/c_shadow></prompt><userinput>perl -p -i -e 's|/c$|/c_shadow|g' /usr/local/etc/wine.conf</userinput>
</screen>
<para>
The above gives everyone complete read and write access to
the <filename>windows</filename> and
<filename>AnApp</filename> directories while only root has
write access to all other directories.
</para>
</sect2>
</sect1>
<sect1 id="scsi-support">
<title>SCSI Support</title>
<para>
Written by &name-bruce-milner; <email>&email-bruce-milner;</email>;
Additions by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/aspi</filename>)
</para>
<para>
This file describes setting up the Windows ASPI interface.
</para>
<para>
<warning><title>Warning/Warning/Warning!!!!!!</title>
<para>This may trash your system if used incorrectly. It may
even trash your system when used <emphasis>correctly</>!
</para>
</warning>
</para>
<para>
Now that I have said that. ASPI is a direct link to SCSI devices from
windows programs. ASPI just forwards the SCSI commands that programs send
to it to the SCSI bus.
</para>
<para>
If you use the wrong SCSI device in your setup file, you can send
completely bogus commands to the wrong device - An example would be
formatting your hard drives (assuming the device gave you permission -
if you're running as root, all bets are off).
</para>
<para>
So please make sure that <emphasis>all</emphasis> SCSI devices not needed by the program
have their permissions set as restricted as possible !
</para>
<para>
Cookbook for setting up scanner: (At least how mine is to work)
(well, for other devices such as CD burners, MO drives, ..., too)
</para>
<sect2>
<title>Windows requirements</title>
<orderedlist>
<listitem>
<para>
The scanner software needs to use the "Adaptec"
compatible drivers (ASPI). At least with Mustek, they
allow you the choice of using the builtin card or the
"Adaptec (AHA)" compatible drivers. This will not work
any other way. Software that accesses the scanner via a
DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM]
</para>
</listitem>
<listitem>
<para>
You probably need a real windows install of the software
to set the LUN's/SCSI id's up correctly. I'm not exactly
sure.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>LINUX requirements:</title>
<orderedlist>
<listitem>
<para>
Your SCSI card must be supported under Linux. This will
not work with an unknown SCSI card. Even for cheap'n
crappy "scanner only" controllers some special Linux
drivers exist on the net.
If you intend to use your IDE device, you need to use the
ide-scsi emulation.
Read
<ulink url="http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html">
http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html</ulink>
for ide-scsi setup instructions.
</para>
</listitem>
<listitem>
<para>
Compile generic SCSI drivers into your kernel.
</para>
</listitem>
<listitem>
<para>
This seems to be not required any more for newer (2.2.x) kernels:
Linux by default uses smaller SCSI buffers than Windows.
There is a kernel build define <literal>SG_BIG_BUFF</literal> (in
<filename>sg.h</filename>) that is by default set too
low. The SANE project recommends
<literal>130560</literal> and this seems to work just
fine. This does require a kernel rebuild.
</para>
</listitem>
<listitem>
<para>
Make the devices for the scanner (generic SCSI devices)
- look at the SCSI programming HOWTO at
<ulink url="http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html">
http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html</ulink>
for device numbering.
</para>
</listitem>
<listitem>
<para>
I would recommend making the scanner device writable by
a group. I made a group called
<literal>scanner</literal> and added myself to it.
Running as root increases your risk of sending bad SCSI
commands to the wrong device. With a regular user, you
are better protected.
</para>
</listitem>
<listitem>
<para>
For Win32 software (WNASPI32), Wine has auto-detection in place.
For Win16 software (WINASPI), you need to add a SCSI device entry
for your particular scanner to ~/.wine/config. The format is
<literal>[scsi cCtTdD]</literal> where
<literal>"C" = "controller"</literal>,
<literal>"T" = "target"</literal>, <literal>D=LUN</literal>
</para>
<para>
For example, I set mine up as controller <literal>0</literal>,
Target <literal>6</literal>, LUN <literal>0</literal>.
<programlisting>
[scsi c0t6d0]
"Device" = "/dev/sgi"
</programlisting>
Yours will vary with your particular SCSI setup.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>General Information</title>
<para>
The mustek scanner I have was shipped with a package
"ipplus". This program uses the TWAIN driver specification
to access scanners.
</para>
<para>
(TWAIN MANAGER)
</para>
<para>
<programlisting>
ipplus.exe &lt;-&gt; (TWAIN INTERFACE) &lt;-&gt; (TWAIN DATA SOURCE.ASPI) -&gt; WINASPI
</programlisting>
</para>
</sect2>
<sect2>
<title>NOTES/BUGS</title>
<para>
The biggest is that it only works under Linux at the moment.
</para>
<para>
The ASPI code has only been tested with:
</para>
<itemizedlist>
<listitem>
<para>
a Mustek 800SP with a Buslogic controller under Linux [BM]
</para>
</listitem>
<listitem>
<para>
a Siemens Nixdorf 9036 with Adaptec AVA-1505 under Linux
accessed via DOSASPI. Note that I had color problems,
though (barely readable result) [AM]
</para>
</listitem>
<listitem>
<para>
a Fujitsu M2513A MO drive (640MB) using generic SCSI
drivers. Formatting and ejecting worked perfectly.
Thanks to Uwe Bonnes for access to the hardware ! [AM]
</para>
</listitem>
</itemizedlist>
<para>
I make no warranty to the ASPI code. It makes my scanner
work. Your devices may explode. I have no way of determining
this. I take zero responsibility!
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
End:
-->