[WINEDOCS] User Guide Update

[WINEDOCS] User Guide Update

Wine User Guide update attached. There's lots of areas that could be
explained better, but at least it's a usable starting point. Some
things to note:

1. Can Wine still use a ~/.wine/wine.userreg file? It's described in
the doc, but I'm not sure that still works.

2. I have no idea where I got the "System Administration Tips" from.
If I came up with that myself last year, then I think it needs to be
revisited. It doesn't look right to me, but the idea isn't too far off.

3. Most of the changes are to wineusr-configuring.sgml.

4. After applying, you can remove en/wineusr-fonts.sgml,
en/wineusr-printing.sgml, en/wineusr-registry.sgml. Both printing and
font support could be described better.

As usual, spelling and grammatical errors have been left for Francois
to find ;)

Index: en/wineusr-configuring.sgml
===================================================================
RCS file: /cvsroot/wine/docs/en/wineusr-configuring.sgml,v
retrieving revision 1.4
diff -u -u -r1.4 wineusr-configuring.sgml
--- en/wineusr-configuring.sgml 25 Sep 2005 16:13:41 -0000 1.4
+++ en/wineusr-configuring.sgml 17 Oct 2005 07:11:16 -0000
@@ -1,2649 +1,756 @@
- <chapter id="config-wine-main">
+<chapter id="config-wine-main">
<title>Configuring Wine</title>
- <para>
- Now that you hopefully managed to successfully install
- the Wine program files,
- this chapter will tell you how to configure the Wine environment
- properly to run your Windows programs.
- </para>
- <para>
- First, we'll give you an overview about which kinds of
- configuration and program execution aspects a fully configured
- Windows environment has to fulfill in order to ensure that many
- Windows programs run successfully without encountering any
- misconfigured or missing items.
- Next, we'll show you which easy helper programs exist
- to enable even novice users to complete the Wine environment
- configuration in a fast and easy way.
- The next section will explain the purpose of the Wine configuration file,
- and we'll list all of its settings.
- After that, the next section will detail the most important and
- unfortunately most difficult configuration part:
- how to configure the file system and DOS drive environment that
- Windows programs need.
- In the last step we'll tell you how to establish a working Windows
- registry base.
- Finally, the remaining parts of this chapter contain descriptions
- of specific Wine configuration items that might also be
- of interest to you.
- </para>
-
- <sect1 id="config-requirements-windows" xreflabel="--Installing Section--">
- <title>What are the requirements of a fully working Windows environment?</title>
-
- <para>
- A Windows installation is a very complex structure. It consists of
- many different parts with very different functionality.
- We'll try to outline the most important aspects of it.
- </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>) directory. Some Windows
- programs 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 program
- asks for a DLL, Wine does not simulate the presence of
- nonexistent 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>
-
- </sect1>
-
- <sect1 id="config-helper-programs">
- <title>Easy configuration helper programs</title>
-
- <para>
- Managing the Wine configuration file settings can be a
- difficult task, sometimes too difficult for some people.
- That's why there are some helper applications for easily setting up an
- initial wine configuration file with useful default settings.
- </para>
-
-
- <sect2 id="config-helper-wineinstall">
- <title>wineinstall</title>
- <para>
- <command>wineinstall</command> is a small configuration tool
- residing as <filename>tools/wineinstall</filename> in a Wine
- source code tree. It has been written to allow for an easy
- and complete compilation/installation of Wine source code for
- people who don't bother with reading heaps of very valuable
- and informative documentation ;-)
- </para>
- <para>
- Once you have successfully extracted the Wine source code
- tree, change to the main directory of it and then run (as
- user):
- </para>
- <screen>
- <prompt>$ </prompt><userinput>./tools/wineinstall</userinput>
- </screen>
- <para>
- Doing so will compile Wine, install Wine and configure the
- Wine environment (either by providing access to a Windows
- partition or by creating a properly configured no-windows
- directory environment).
- </para>
-
- </sect2>
-<!--
- Commenting out until winecfg doesn't actually do something.
- <sect2 id="config-helper-winecfg">
- <title>winecfg</title>
- <para>
- <command>winecfg</command> is a small graphical configuration tool
- residing as <filename>programs/winecfg</filename> in a Wine
- source code tree. It is a Winelib app making use of standard
- Win32 GUI controls to easily customize entries in a Wine
- configuration file.
- </para>
- </sect2>
--->
- </sect1>
-
- <sect1 id="config-verify">
- <title>Verification of correct configuration</title>
-
- <para>
- TODO: After you have finished configuring Wine you can verify
- your Wine configuration by running winecfg.
- This functionality will be added to winecfg
- in the near future.
- </para>
- <para>
- Please check out the
- configuration documentation below to find out more about Wine's
- configuration, or proceed to the <link linkend="bugs">Troubleshooting
- chapter</link>.
- </para>
- </sect1>
-
- <sect1 id="config-file">
- <title>The Wine Configuration File</title>
<para>
- This section is meant to contain both an easy step-by-step introduction
- to the Wine configuration file (for new Wine users)
- and a complete reference to all Wine configuration file settings (for
- advanced users).
- </para>
-
- <sect2>
- <title>Configuration File Introduction</title>
+ Most of the most common configuration changes can be done with the
+ Winecfg tool. We'll go through an easy, step-by-step introduction
+ to Winecfg and outline the options available.
+ In the next section we'll go over more advanced changes you can make
+ using regedit as well as provide a complete reference to all Wine
+ configuration settings. Finally, some things you might want to
+ configure fall out of the scope of Winecfg and regedit, and we'll
+ go over those.
+ </para>
+ <sect1 id="using-winecfg">
+ <title>Using Winecfg</title>
+ <para>
+ In the past, Wine used a special configuration file that could be
+ found in <filename>~/.wine/config</filename>. If you are still using
+ a version of Wine that references this file (older than June, 2005)
+ you should upgrade before doing anything else. All settings are now
+ stored directly in the registry and accessed by Wine when it starts.
+ </para>
+ <para>
+ Winecfg should have been installed on your computer along with the
+ rest of the Wine programs. If you can't figure out how to start it,
+ try running the command:
+ <prompt>$ </prompt><userinput>/usr/local/bin/winecfg</userinput>
+ </para>
<para>
- The Wine configuration file is the central file to store
- configuration settings for Wine.
- This file (which is called <filename>config</filename>)
- can be found in the sub directory <filename>.wine/</filename>
- of your user's home directory
- (directory <filename>/home/user/</filename>). In other words, the Wine
- configuration file is <filename>~/.wine/config</filename>.
- Note that since the Wine configuration file is a part of the
- Wine registry file system, this file also
- <emphasis>requires</emphasis> a correct "WINE REGISTRY
- Version 2" header line to be recognized properly, just like
- all other Wine registry text files (just in case you decided
- to write your own registry file from scratch and wonder why
- Wine keeps rejecting it).
+ or possibly just:
+ <prompt>$ </prompt><userinput>winecfg</userinput>
</para>
<para>
- The settings available in the configuration file include:
+ When the program starts you'll notice there are tabs along the top
+ of the window for:
<itemizedlist>
<listitem>
<para>
- Directory settings
+ Applications
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Libraries
</para>
</listitem>
<listitem>
<para>
- Port settings
+ Graphics
</para>
</listitem>
<listitem>
<para>
- The Wine look and feel
+ Appearance
</para>
</listitem>
<listitem>
<para>
- Wine's DLL usage
+ Drives
</para>
</listitem>
<listitem>
<para>
- Wine's multimedia drivers and DLL configuration
+ Audio
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ About
</para>
</listitem>
</itemizedlist>
</para>
+ <para>
+ Changing settings in the
+ <emphasis>Applications</emphasis> and <emphasis>Libraries</emphasis>
+ tab will have the most impact on getting an application to run. The
+ other settings focus on getting Wine itself to behave the way
+ you want it to.
+ </para>
+ <para>
+ Note: The Applications, Libraries, and Graphics tabs are linked
+ together! If you have Default Settings selected under Applications,
+ all of the changes made within the Libraries and Graphics tabs will
+ be changed for all applications. If you've configured a specfic
+ application under the Applications tab and have it selected, then
+ any changes made in Libraries or Graphics will affect only that
+ application. This allows for custom settings for specific
+ applications.
+ </para>
+ <sect2 id="config-windows-versions">
+ <title>Application Settings</title>
+ <para>
+ Wine has the ability to mimic the behavior of different versions of
+ Windows. In general, the biggest difference is whether Wine
+ behaves as a Win9x version or an NT version. Some applications
+ require a specific behavior in order to function and changing
+ this setting may cause a buggy app to work. Recently Wine's
+ default Windows version has changed to Windows 2000. It's known
+ that many applications will perform better if you choose Windows
+ 98.
+ </para>
+ <para>
+ Within the tab you'll notice there is a
+ <emphasis>Default Settings</emphasis> entry. If you select that
+ you'll see the current default <emphasis>Windows Version</emphasis>
+ for all applications. A troublesome application
+ is best configured separately from the Default Settings. To do that:
+ <orderedlist>
+ <listitem>
+ <para>
+ Click on the <emphasis>Add application</emphasis> button.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Browse until you locate the .exe
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ After it's been added you can choose the specific Windows
+ version Wine will emulate for that application.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
</sect2>
-
<sect2>
- <title>Creating Or Modifying The Configuration File</title>
+ <title>Libraries Settings</title>
<para>
- If you just installed Wine for the first time and want to
- finish Wine installation by configuring it now, then you could
- use our sample configuration file <filename>config</filename>
- (which can be found in the directory
- <filename>documentation/samples/</filename> of the Wine source
- code directory) as a base for adapting the Wine configuration
- file to the settings you want.
- First, I should mention that you should not forget to make
- sure that any previous configuration file at
- <filename>~/.wine/config</filename> has been safely moved out
- of the way instead of simply overwriting it when you will now
- copy over the sample configuration file.
+ Likewise, some applications require specific libraries in order
+ to run. Wine reproduces the Windows system libraries (so-called
+ native DLL's) with completely custom versions designed to
+ function exactly the same way but without requiring licenses
+ from Microsoft. Wine has many known deficiencies in it's
+ built-in versions, but in many instances the functionality
+ is sufficient. Using only builtin DLL's ensures that your
+ system is Microsoft-free. However, Wine has the ability to
+ load native Windows DLL's.
</para>
- <para>
- If you don't have a pre-existing configuration file and thus
- need to copy over our sample configuration file to the
- standard Wine configuration file location, do in a
- <glossterm>terminal</glossterm>:
- <screen>
- <prompt>$ </><userinput>mkdir ~/.wine/</>
- <prompt>$ </><userinput>cp <replaceable>dir_to_wine_source_code</replaceable>/documentation/samples/config ~/.wine/config</>
- </screen>
- Otherwise, simply use the already existing configuration file
- at <filename>~/.wine/config</filename>.
- </para>
- <para>
- Now you can start adapting the configuration file's settings with an
- <glossterm>editor</glossterm> according to the documentation
- below.
- Note that you should <emphasis>only</emphasis> change
- configuration file settings if wineserver is not running (in
- other words: if your user doesn't have a Wine session running),
- otherwise Wine won't use them - and even worse, wineserver will
- overwrite them with the old settings once wineserver quits!!
- </para>
- </sect2>
-
- <sect2 id="config-file-how">
- <title>What Does It Contain?</title>
-
- <para>
- Let's start by giving an overview of which sections a
- configuration file may contain, and whether the inclusion of
- the respective section is <emphasis>needed</emphasis> or only <emphasis>recommended</emphasis> ("recmd").
- </para>
-
- <informaltable frame="all">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Section Name</entry>
- <entry>Needed?</entry>
- <entry>What it Does</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>[wine]</entry>
- <entry>yes</entry>
- <entry>General settings for Wine</entry>
- </row>
- <row>
- <entry>[DllOverrides]</entry>
- <entry>recmd</entry>
- <entry>Overrides defaults for DLL loading</entry>
- </row>
- <row>
- <entry>[x11drv]</entry>
- <entry>recmd</entry>
- <entry>Graphics driver settings</entry>
- </row>
- <row>
- <entry>[fonts]</entry>
- <entry>yes</entry>
- <entry>Font appearance and recognition</entry>
- </row>
- <row>
- <entry>[ppdev]</entry>
- <entry>no</entry>
- <entry>Parallelport emulation</entry>
- </row>
- <row>
- <entry>[spooler]</entry>
- <entry>no</entry>
- <entry>Print spooling</entry>
- </row>
- <row>
- <entry>[ports]</entry>
- <entry>no</entry>
- <entry>Direct port access</entry>
- </row>
- <row>
- <entry>[Debug]</entry>
- <entry>no</entry>
- <entry>What to do with certain debug messages</entry>
- </row>
- <row>
- <entry>[Registry]</entry>
- <entry>no</entry>
- <entry>Specifies locations of windows registry files</entry>
- </row>
- <row>
- <entry>[programs]</entry>
- <entry>no</entry>
- <entry>Programs to be run automatically</entry>
- </row>
- <row>
- <entry>[Console]</entry>
- <entry>no</entry>
- <entry>Console settings</entry>
- </row>
- <row>
- <entry>[Clipboard]</entry>
- <entry>no</entry>
- <entry>Interaction for Wine and X11 clipboard</entry>
- </row>
- <row>
- <entry>[afmdirs]</entry>
- <entry>no</entry>
- <entry>Postscript driver settings</entry>
- </row>
- <row>
- <entry>[WinMM]</entry>
- <entry>yes</entry>
- <entry>Multimedia settings</entry>
- </row>
- <row>
- <entry>[AppDefaults]</entry>
- <entry>no</entry>
- <entry>Overwrite the settings of previous sections for special programs</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- Now let's explain the configuration file sections in a
- detailed way.
- </para>
-
- <sect3 id="config-wine">
- <title>The [wine] Section </title>
- <para>
- The [wine] section of the configuration file contains basic settings for Wine.
- </para>
- <para>
- <programlisting>
-"Windows" = "c:\\windows"
-"ShowDirSymlinks" = "1"
-"ShowDotFiles" = "1"
- </programlisting>
- For a detailed description of drive layer configuration and
- the meaning of these parameters, please look at the <link
- linkend="config-drive-main">Disc Drives, Serial and Parallel
- Ports section</link>.
- </para>
- <para>
- <programlisting>"GraphicsDriver" = "x11drv|ttydrv"</programlisting>
- Sets the graphics driver to use for Wine output.
- x11drv is for X11 output, ttydrv is for text console output.
- WARNING: if you use ttydrv here, then you won't be able to run
- a lot of Windows GUI programs (ttydrv is still pretty "broken"
- at running graphical apps). Thus this option is mainly interesting
- for e.g. embedded use of Wine in web server scripts.
- Note that ttydrv is still very lacking, so if it doesn't work,
- resort to using "xvfb", a virtual X11 server.
- Another way to run Wine without display would be to run X11
- via Xvnc, then connect to that VNC display using xvncviewer
- (that way you're still able to connect to your app and
- configure it if need be).
- </para>
- <para>
- <programlisting>"Printer" = "off|on"</programlisting> Tells wine
- whether to allow printing via printer drivers to work.
- This option isn't needed for our built-in psdrv printer driver
- at all.
- Using these things are pretty alpha, so you might want to
- watch out. Some people might find it useful, however. If
- you're not planning to work on printing via windows printer
- drivers, don't even add this to your wine configuration file
- (It probably isn't already in it).
- Check out the [spooler] and [parallelports] sections too.
- </para>
- <para>
- <programlisting>"ShellLinker" = "wineshelllink"</programlisting>
- This setting specifies the shell linker script to use for setting
- up Windows icons in e.g. KDE or Gnome that are given by programs
- making use of appropriate shell32.dll functionality to create
- icons on the desktop/start menu during installation.
- </para>
- <para>
- <programlisting>"SymbolTableFile" = "wine.sym"</programlisting>
- Sets up the symbol table file for the wine debugger. You
- probably don't need to fiddle with this. May be useful if
- your wine is stripped.
- </para>
- </sect3>
-
- <sect3 id="config-dlloverrides">
- <title>The [DllOverrides] Section</title>
- <para>
- The format for this section is the same for each line:
- <programlisting>&lt;DLL>{,&lt;DLL>,&lt;DLL>...} = &lt;FORM>{,&lt;FORM>,&lt;FORM>...}</programlisting>
- For example, to load built-in KERNEL pair (case doesn't
- matter here):
- <programlisting>"kernel,kernel32" = "builtin"</programlisting>
- To load the native COMMDLG pair, but if that doesn't work
- try built-in:
- <programlisting>"commdlg,comdlg32" = "native, builtin"</programlisting>
- To load the native COMCTL32:
- <programlisting>"comctl32" = "native"</programlisting>
- Here is a good generic setup (As it is defined in config
- that was included with your wine package):
- <programlisting>
-[DllOverrides]
-"rpcrt4" = "builtin, native"
-"oleaut32" = "builtin, native"
-"ole32" = "builtin, native"
-"commdlg" = "builtin, native"
-"comdlg32" = "builtin, native"
-"ver" = "builtin, native"
-"version" = "builtin, native"
-"shell" = "builtin, native"
-"shell32" = "builtin, native"
-"shfolder" = "builtin, native"
-"shlwapi" = "builtin, native"
-"shdocvw" = "builtin, native"
-"lzexpand" = "builtin, native"
-"lz32" = "builtin, native"
-"comctl32" = "builtin, native"
-"commctrl" = "builtin, native"
-"advapi32" = "builtin, native"
-"crtdll" = "builtin, native"
-"mpr" = "builtin, native"
-"winspool.drv" = "builtin, native"
-"ddraw" = "builtin, native"
-"dinput" = "builtin, native"
-"dsound" = "builtin, native"
-"opengl32" = "builtin, native"
-"msvcrt" = "native, builtin"
-"msvideo" = "builtin, native"
-"msvfw32" = "builtin, native"
-"mcicda.drv" = "builtin, native"
-"mciseq.drv" = "builtin, native"
-"mciwave.drv" = "builtin, native"
-"mciavi.drv" = "native, builtin"
-"mcianim.drv" = "native, builtin"
-"msacm.drv" = "builtin, native"
-"msacm" = "builtin, native"
-"msacm32" = "builtin, native"
-"midimap.drv" = "builtin, native"
-; you can specify programs too
-"notepad.exe" = "native, builtin"
-; default for all other DLLs
-"*" = "native, builtin"
- </programlisting>
- </para>
- <note>
- <para>
- If loading of the libraries that are listed first fails,
- wine will just go on by using the second or third option.
- </para>
- </note>
- </sect3>
-
- <sect3 id="config-fonts">
- <title>The [fonts] Section</title>
- <para>
- This section sets up wine's font handling.
- </para>
- <para>
- <programlisting>"Resolution" = "96"</programlisting>
- Since the way X handles fonts is different from the way
- Windows does, wine uses a special mechanism to deal with
- them. It must scale them using the number defined in the
- "Resolution" setting. 60-120 are reasonable values, 96 is
- a nice in the middle one. If you have the real windows
- fonts available , this parameter will not be as
- important. Of course, it's always good to get your X fonts
- working acceptably in wine.
- </para>
- <para>
- <programlisting>"Default" = "-adobe-times-"</programlisting>
- The default font wine uses. Fool around with it if you'd like.
- </para>
- <para>
- OPTIONAL:
- </para>
- <para>
- The <literal>Alias</literal> setting allows you to map an X font to a font
- used in wine. This is good for apps that need a special font you don't have,
- but a good replacement exists. The syntax is like so:
- <programlisting>"AliasX" = "[Fake windows name],[Real X name]"&lt;,optional "masking" section></programlisting>
- Pretty straightforward. Replace "AliasX" with "Alias0",
- then "Alias1" and so on. The fake windows name is the name
- that the font will be under a windows app in wine. The
- real X name is the font name as seen by X (Run
- "xfontsel"). The optional "masking" section allows you to
- utilize the fake windows name you define. If it is not
- used, then wine will just try to extract the fake windows
- name itself and not use the value you enter.
- </para>
- <para>
- Here is an example of an alias without masking. The font will show up in windows
- apps as "Google".
- <programlisting>"Alias0" = "Foo,--google-"</programlisting>
- Here is an example with masking enabled. The font will show up as "Foo" in
- windows apps.
- <programlisting>"Alias1" = "Foo,--google-,subst"</programlisting>
- For more information check out the <link linkend="config-fonts-main">Fonts</link>
- chapter.
- </para>
- </sect3>
-
- <sect3 id="config-io">
- <title>The [spooler] and [ports] Sections</title>
- <para>
- The [spooler] section will inform wine where to spool
- print jobs. Use this if you want to try printing. Wine
- docs claim that spooling is "rather primitive" at this
- time, so it won't work perfectly. <emphasis>It is optional.</emphasis> The only
- setting you use in this section works to map a port (LPT1,
- for example) to a file or a command. Here is an example,
- mapping LPT1 to the file <filename>out.ps</filename>:
- <programlisting>"LPT1:" = "out.ps"</programlisting>
- The following command maps printing jobs to LPT1 to the
- command <command>lpr</command>. Notice the |:
- <programlisting>"LPT1:" = "|lpr"</programlisting>
- The [ports] section is usually useful only for people who
- need direct port access for programs requiring dongles or
- scanners. <emphasis>If you don't need it, don't use
- it!</emphasis>
- </para>
- <para>
- <programlisting>"read" = "0x779,0x379,0x280-0x2a0"</programlisting>
- Gives direct read access to those IO's.
- </para>
- <para>
- <programlisting>"write" = "0x779,0x379,0x280-0x2a0"</programlisting>
- Gives direct write access to those IO's. It's probably a
- good idea to keep the values of the
- <literal>read</literal> and <literal>write</literal>
- settings the same. This stuff will only work when you're
- root.
- </para>
- </sect3>
-
- <sect3 id="config-debug-etc">
- <title>The [Debug], [Registry], and [programs] Sections</title>
- <para>
- [Debug] is used to include or exclude debug messages, and to
- output them to a file. The latter is rarely used. <emphasis>These
- are all optional and you probably don't need to add or
- remove anything in this section to your config.</emphasis> (In extreme
- cases you may want to use these options to manage the amount
- of information generated by <parameter>WINEDEBUG=+relay
- </parameter> )
- </para>
- <para>
- <programlisting>"File" = "/blanco"</programlisting>
- Sets the logfile for wine. Set to CON to log to standard out.
- <emphasis>This is rarely used.</emphasis>
- </para>
- <para>
- <programlisting>"SpyExclude" = "WM_SIZE;WM_TIMER;"</programlisting>
- Excludes debug messages about <constant>WM_SIZE</constant>
- and <constant>WM_TIMER</constant> in the logfile.
- </para>
- <para>
- <programlisting>"SpyInclude" = "WM_SIZE;WM_TIMER;"</programlisting>
- Includes debug messages about <constant>WM_SIZE</constant>
- and <constant>WM_TIMER</constant> in the logfile.
- </para>
- <para>
- <programlisting>"RelayInclude" = "user32.CreateWindowA;comctl32.*"</programlisting>
- Include only the listed functions in a
- <parameter>WINEDEBUG=+relay</parameter> trace. This entry is
- ignored if there is a <parameter>RelayExclude</parameter> entry.
- </para>
- <para>
- <programlisting>"RelayExclude" = "RtlEnterCriticalSection;RtlLeaveCriticalSection"</programlisting>
- Exclude the listed functions in a
- <parameter>WINEDEBUG=+relay</parameter> trace. This entry
- overrides any settings in a <parameter>RelayInclude</parameter>
- entry. If neither entry is present then the trace includes
- everything.
- </para>
- <para>
- In both entries the functions may be specified either as a
- function name or as a module and function. In this latter
- case specify an asterisk for the function name to include/exclude
- all functions in the module.
- </para>
- <para>
- [Registry] can be used to tell wine where your old windows
- registry files exist. This section is completely optional
- and useless to people using wine without an existing
- windows installation.
- </para>
- <para>
- <programlisting>"UserFileName" = "/dirs/to/user.reg"</programlisting>
- The location of your old <filename>user.reg</filename> file.
- </para>
- <para>
- [programs] can be used to say what programs run under
- special conditions.
- </para>
- <para>
- <programlisting>"Default" = "/program/to/execute.exe"</programlisting>
- Sets the program to be run if wine is started without specifying a program.
- </para>
- <para>
- <programlisting>"Startup" = "/program/to/execute.exe"</programlisting>
- Sets the program to automatically be run at startup every time.
- </para>
- </sect3>
-
- <sect3 id="config-winmm">
- <title>The [WinMM] Section</title>
- <para>
- [WinMM] is used to define which multimedia drivers have to be loaded. Since
- those drivers may depend on the multimedia interfaces available on your system
- (OSS, ALSA... to name a few), it's needed to be able to configure which driver
- has to be loaded.
- </para>
-
- <para>
- The content of the section looks like:
- <programlisting>
-[WinMM]
-"Drivers" = "wineoss.drv"
-"WaveMapper" = "msacm.drv"
-"MidiMapper" = "midimap.drv"
- </programlisting>
- All the keys must be defined:
- <itemizedlist>
- <listitem>
- <para>
- The "Drivers" key is a ';' separated list of modules name, each of
- them containing a low level driver. All those drivers will be loaded
- when MMSYSTEM/WINMM is started and will provide their inner features.
- </para>
- </listitem>
- <listitem>
- <para>
- The "WaveMapper" represents the name of the module containing the Wave
- Mapper driver. Only one wave mapper can be defined in the system.
- </para>
- </listitem>
- <listitem>
- <para>
- The "MidiMapper" represents the name of the module containing the MIDI
- Mapper driver. Only one MIDI mapper can be defined in the system.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect3>
-
- <sect3 id="config-network">
- <title>The [Network] Section</title>
- <para>
- [Network] contains settings related to
- networking. Currently there is only one value that can be set.
- </para>
- <variablelist>
- <varlistentry>
- <term>UseDnsComputerName</term>
- <listitem>
- <para>
- A boolean setting (default: <literal>Y</literal>)
- that affects the way Wine sets the computer name. The computer
- name in the Windows world is the so-called <emphasis>NetBIOS name</emphasis>.
- It is contained in the <varname>ComputerName</varname> in the registry entry
- <varname>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ComputerName\ComputerName</varname>.
- </para>
- <para>
- If this option is set to "Y" or missing, Wine will set the
- NetBIOS name to the Unix host name of your computer, if
- necessary truncated to 31 characters. The Unix hostname is the output
- of the shell command <command>hostname</command>, up to but not
- including the first dot ('.'). Among other things, this means that
- Windows programs running under Wine cannot change the NetBIOS computer name.
- </para>
- <para>
- If this option is set to "N", Wine will use the registry value above
- to set the NetBIOS name. Only if the registry entry doesn't exist (usually
- only during the first wine startup) it will use the Unix hostname as
- usual. Windows programs can change the NetBIOS name. The change
- will be effective after a "reboot", i.e. after restarting Wine.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
-
- <sect3 id="config-appdefaults">
- <title>The [AppDefaults] Section</title>
- <para>
- The section is used to overwrite certain settings of this file for a
- special program with different settings.
- [AppDefaults] is not the real name of the section. The real name
- consists of the leading word AppDefaults followed by the name
- of the executable the section is valid for.
- The end of the section name is the name of the
- corresponding "standard" section of the configuration file
- that should have some of its settings overwritten with the
- program specific settings you define.
- The three parts of the section name are separated by two backslashes.
- </para>
- <para>
- Currently wine supports overriding selected settings within
- the sections [DllOverrides], [x11drv], [version] and [dsound] only.
- </para>
+ <sect3>
+ <title>DLL Overrides</title>
<para>
- Here is an example that overrides the normal settings for a
- program:
- <programlisting>
-;; default settings
-[x11drv]
-"Managed" = "Y"
-"Desktop" = "N"
-
-;; run install in desktop mode
-[AppDefaults\\install.exe\\x11drv]
-"Managed" = "N"
-"Desktop" = "800x600"
- </programlisting>
- </para>
- </sect3>
+ It's not always possible to run an application on builtin
+ DLL's. Sometimes native DLL's simply work better. After
+ you've located a native DLL on a Windows system, you'll
+ need to place it in suitable place for Wine to find it
+ and then configure it to be used. Generally the place
+ you need to put it is in the directory you've configured
+ to be <filename>c:\windows\system</filename> (more on that in
+ the drives section). There are four DLL's you should never
+ try to use the native versions of:
+ <filename>kernel32.dll</filename>,
+ <filename>gdi32.dll</filename>,
+ <filename>user32.dll</filename>,
+ and <filename>ntdll.dll</filename>. These libraries require
+ low-level Windows kernel access that simply doesn't exist
+ within Wine.
+ </para>
+ <para>
+ With that in mind, once you've copied the DLL you just need to
+ tell Wine to try to use it. You can configure Wine to choose
+ between native and builtin DLL's at two different levels.
+ If you have <emphasis>Default Settings</emphasis> selected
+ in the <emphasis>Applications</emphasis> tab, the changes you
+ make will affect all applications. Or, you can override the
+ global settings on a per-application level by adding and
+ selecting an application in the <emphasis>Applications</emphasis>
+ tab.
+ </para>
+ <para>
+ To add an override for FOO.DLL, enter "FOO" into the box
+ labeled <emphasis>New override for library:</emphasis> and
+ click on the <emphasis>Add</emphasis> button. To change how
+ the DLL behaves, select it within the <emphasis>Existing
+ overrides:</emphasis> box and choose <emphasis>Edit</emphasis>.
+ By default the new load order will be native Windows libraries
+ before Wine's own builtin ones (<emphasis>Native then
+ Builtin</emphasis>). You can also choose native only, builtin
+ only, or disable it altogether.
+ </para>
+ </sect3>
+ <sect3>
+ <title>Notes About System DLL's</title>
+ <para>
+ The Wine team has determined that it is necessary to create fake DLL
+ files to trick many programs 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 c:\windows\system directory
+ to make the program think it's there, and Wine's built-in DLL will
+ be loaded when the program actually asks for it. (Unfortunately,
+ tools/wineinstall 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>
+ 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
+ copy 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>
+ </sect3>
+ <sect3>
+ <title>Missing DLL's</title>
+ <para>
+ In case Wine complains about a missing DLL, you should check whether
+ this file is a publicly available DLL or a custom DLL belonging
+ to your program (by searching for its name on the internet).
+ After you've located the DLL, you need to make sure Wine is able to
+ use it. DLLs usually get loaded in the following order:
+ <orderedlist>
+ <listitem>
+ <para>
+ The directory the program was started from.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The current directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Windows system directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Windows directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The PATH variable directories.
+ </para>
+ </listitem>
+ </orderedlist>
+ In short: either put the required DLL into your program
+ directory (might be ugly), or put it into the Windows system
+ directory. Also, if possible you probably shouldn't use NT-based
+ native DLLs, since Wine's NT API support is somewhat weaker than
+ its Win9x API support (possibly leading to even worse compatibility
+ with NT DLLs than with a no-windows setup!).
+ </para>
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>Graphics Settings</title>
+ <para>
+ There are basically five different graphics settings you
+ can configure. For most people the defaults are fine.
+ </para>
+ <para>
+ The first is the "screen color depth" and
+ represents the number of colors that can be displayed on the
+ screen. Older graphics cards had a hard time displaying a
+ full-range of colors and for them it's useful to be able to
+ specify an "8-bit" display. Modern video cards, namely anything
+ with over 8MB of memory, have no problem using a full 24 or 32-bit
+ depth.
+ </para>
+ <para>
+ The next few settings primarily affect games and are somewhat
+ self-explanatory. You can prevent the mouse from leaving the
+ window of a DirectX program (i.e. a game.) and the default is
+ to have that box checked. There's lots of
+ reasons you might want to do that, not the least of which
+ includes it's easier to play the game if the cursor is
+ confined to a smaller area. The other reason to turn this
+ option on is for more precise control of the mouse - Wine
+ warps the location of the mouse to mimic the way Windows
+ works. Similarly, "desktop double buffering" allows for
+ smoother updates to the screen, which games can benefit from,
+ and the default is to leave it turned on. The tradeoff is
+ increased memory use.
+ </para>
+ <para>
+ You may find it helpful to <emphasis>Emulate a virtual
+ desktop</emphasis>.
+ In this case, all programs will run in a separate window. You
+ may find this useful as a way to test buggy games that change
+ (possibly unsuccessfully) the screen resolution. Confining them
+ to a window can allow for more control over them at the possible
+ expense of decreased usability. Sizes you might want to try are
+ 640x480 (the default) or 800x600.
+ </para>
+ <para>
+ Finally, you can configure some Direct3D settings. For the
+ most part these settings are detected automatically, but you
+ can force them to behave in a specific manner. Some games
+ attempt to probe the underlying system to see if it supports
+ specific features. By turning these off Wine won't report
+ the ability to render games in a certain way. It may lead
+ to the game running faster at the expense of the quality of
+ the graphics or the game may not run at all.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Drive Settings</title>
+ <para>
+ Windows requires a fairly rigid drive configuration that Wine
+ imitates. Most people are familiar with the standard notation
+ of the "A:" drive representing the floppy disk, the "C:"
+ drive representing the primary system disk, etc. Wine uses
+ the same concept and maps those drives to the underlying native
+ filesystem.
+ </para><para>
+ Wine's drive configuration is relatively simple.
+ In Winecfg under the <emphasis>Drives</emphasis> tab you'll
+ see buttons to add and remove available drives.
+ When you choose to add a drive, a new entry will be made
+ and a default drive mapping will appear. You can change where
+ this drives points to by changing what's in the
+ <emphasis>Path:</emphasis> box. If you're unsure of the
+ exact path you can choose "Browse" to search for it.
+ Removing a drive is as easy as selecting the drive and
+ clicking "Remove".
+ </para><para>
+ Winecfg has the ability to automatically detect the drives
+ available on your system. It's recommended you try this
+ before attempting to configure drives manually. Simply
+ click on the <emphasis>Autodetect</emphasis> button to
+ have Wine search for drives on your system.
+ </para><para>
+ You may be interested in configuring your drive settings
+ outside of Winecfg, in which case you're in luck because it's
+ quite easy. All of the drive settings reside in a special
+ directory, <filename>~/.wine/dosdevices</filename>. Each "drive"
+ is simply a link to where it actually resides. Wine automatically
+ sets up two drives the first time you run Wine:
+ </para>
+ <programlisting>
+ $ ls -la ~/.wine/dosdevices/
+ lrwxrwxrwx 1 wineuser wineuser 10 Jul 23 15:12 c: -> ../drive_c
+ lrwxrwxrwx 1 wineuser wineuser 1 Jul 23 15:12 z: -> /
+ </programlisting>
+ <para>
+ To add another drive, for example your CD-ROM, just create a new
+ link pointing to it:
+ <prompt>$ </prompt>
+ <userinput>ln -s /mnt/cdrom ~/.wine/dosdevices/d:</userinput>
+ Take note of the DOS-style naming convention used for links -
+ the format is a letter followed by a colon, such as "a:". So,
+ if the link to your c: drive points to
+ <filename> ~/.wine/drive_c</filename>, you
+ can interpret references to <filename>c:\windows\system</filename>
+ to mean <filename> ~/.wine/drive_c/windows/system</filename>.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Audio Settings</title>
+ <para>
+ Wine can work with quite a few different audio subsystems
+ which you can choose under the "Audio" tab. The
+ "Autodetect" button can figure it all out for you, or you can
+ manually select a driver. Older
+ Linux distributions using the 2.4 kernel or earlier typically
+ use the "OSS" driver. Newer 2.6 kernels have switched to "ALSA".
+ If you're using KDE, regardless of the kernel, you can probably
+ also use "aRts". If you're using GNOME you can probably use
+ EsounD. The OSS and ALSA audio drivers get the most testing, so
+ it's recommended you stick with them if possible.
+ If you need to use "Jack" or "NAS" you probably already know why.
+ </para>
+ <para>
+ DirectSound settings are primarily used by games. You can
+ choose what level of hardware acceleration you'd like, but
+ for most people "Full" is fine.
+ </para>
</sect2>
-
- <sect2 id="config-trouble">
- <title>What If It Doesn't Work?</title>
- <para>
- There is always a chance that things will go wrong. If the
- unthinkable happens, report the problem to
- <ulink url="http://bugs.winehq.org/">Wine Bugzilla</ulink>,
- try the newsgroup
- <systemitem>comp.emulators.ms-windows.wine</systemitem>,
- or the IRC channel <systemitem>#WineHQ</systemitem> found on
- irc.freenode.net, or connected servers.
- Make sure that you have looked over this document thoroughly,
- and have also read:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <filename>README</filename>
- </para>
- </listitem>
- <listitem>
- <para>
- <filename>http://www.winehq.org/trouble/</filename>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- If indeed it looks like you've done your research, be
- prepared for helpful suggestions. If you haven't, brace
- yourself for heaving flaming.
+ <sect2>
+ <title>Appearance</title>
+ <para>
+ Wine can load Windows themes if you have them available. While
+ this certainly isn't necessary in order to use Wine or applications,
+ it does allow you to customize the look and feel of a program. Wine
+ supports the newer MSStyles typ of themese. Unlike the older Microsoft
+ Plus! style themes, the uxtheme engine supports special .msstyles files
+ that can retheme all of the Windows controls. This is more or less the
+ same kind of theming that modern Linux desktops have supported for
+ years. If you'd like to try this out:
+ <orderedlist>
+ <listitem>
+ <para>
+ Download a Windows XP theme. Be sure it contains a .msstyles
+ file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create a set of new directories in your fake Windows drive:
+ <prompt>$ </prompt>
+ <userinput>mkdir -p ~/.wine/drive_c/windows/Resources/themes/name-of-your-theme</userinput>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Move the .msstyles to that new name-of-your-theme directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Use the new Appearance tab of winecfg to select the new theme.
+ </para>
+ </listitem>
+ </orderedlist>
</para>
</sect2>
</sect1>
-
- <sect1 id="config-drive-main">
- <title>Disc Drives, Serial and Parallel Ports</title>
- <sect2>
- <title>Extremely Important Prerequisites</title>
- <para>
- If you're planning to include access to a CD-ROM drive in your Wine
- configuration on Linux, then <emphasis>make sure</emphasis> to add
- the <quote>unhide</quote> mount option to the CD-ROM file system
- entry in <filename>/etc/fstab</filename>, e.g.:
- <programlisting>/dev/cdrom /cdrom iso9660 ro,noauto,users,unhide 0 0</programlisting>
- Several Windows program setup CD-ROMs or other CD-ROMs chose
- to do such braindamaged things as marking very important setup
- helper files on the CD-ROM as <quote>hidden</quote>.
- That's no problem on Windows, since the Windows CD-ROM driver by
- default displays even files that are supposed to be
- <quote>hidden</quote>. But on Linux, which chose to
- <emphasis>hide</emphasis> <quote>hidden</quote> files on CD by
- default, this is <emphasis>FATAL</emphasis>!
- (the programs will simply abort with an <quote>installation file not found</quote> or similar error)
- Thus you should never forget to add this setting.
- </para>
+ <sect1 id="using-regedit">
+ <title>Using the Registry and Regedit</title>
+ <para>
+ All of the settings you change in Winecfg, with exception of
+ the drive settings, are ultimately stored in the registry.
+ In Windows, this is a central repository for the configuration
+ of applications and the operating system. Likewise, Wine
+ implements a registry and some settings not found in Winecfg
+ can be changed within it. (There's actually more of a chance
+ you'll need to dip into the registry to change an applications'
+ settings than Wine itself.)
+ </para>
+ <para>
+ Now, the fact that Wine itself uses the registry to store settings
+ has been controversial. Some people argue that it's too much like
+ Windows. To counter this, there's several things to consider.
+ First, it's impossible to avoid implementing a registry simply
+ because applications expect to be able to store their settings there.
+ In order for Wine to store and access settings in a separate
+ configuration file would require a separate set of code to basically
+ do the same thing as the Win32 API's Wine already implements.
+ Finally, unlike Windows, the Wine registry is written in plain text
+ and can be changed using your favorite text editor. While most sane
+ system administrators (and Wine developers) curse madly at the twisted
+ nature of the Windows registry, it is still necessary for Wine to
+ support it somehow.
+ </para>
+ <sect2>
+ <title>Registry Structure</title>
+ <para>
+ Okay.. with that out of the way, let's dig into the registry a bit
+ to see how it's laid out. The Windows registry is an elaborate tree
+ structure, and not even most Windows programmers are fully aware of
+ how the registry is laid out, with its different "hives" and numerous
+ links between them; a full coverage is out of the scope of
+ this document. But here are the basic registry keys you might
+ need to know about for now:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>HKEY_LOCAL_MACHINE</term>
+ <listitem>
+ <para>
+ This fundamental root key (in win9x it's stored in the
+ hidden file <filename>system.dat</filename>) contains
+ everything pertaining to the current Windows
+ installation. This is often abbreviated HKLM.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>HKEY_USERS</term>
+ <listitem>
+ <para>
+ This fundamental root key (in win9x it's stored in the
+ hidden file <filename>user.dat</filename>) contains
+ configuration data for every user of the installation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>HKEY_CLASSES_ROOT</term>
+ <listitem>
+ <para>
+ This is a link to HKEY_LOCAL_MACHINE\Software\Classes.
+ It contains data describing things like file
+ associations, OLE document handlers, and COM classes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>HKEY_CURRENT_USER</term>
+ <listitem>
+ <para>
+ This is a link to HKEY_USERS\your_username, i.e., your
+ personal configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect2>
-
<sect2>
- <title>Short Introduction</title>
+ <title>Registry Files</title>
<para>
- Windows applications refer to disc drives by letters such as
- <filename>A:</filename>, <filename>B:</filename> and
- <filename>C:</filename>, and to serial and parallel ports by names
- such as <filename>COM1</filename>: and <filename>LPT1:</filename>.
+ Now, what you're probably wondering is how that translates
+ into Wine's structure. The registry layout described above
+ actually lives in four different files within each user's
+ ~/.wine directory:
</para>
+ <variablelist>
+ <varlistentry>
+ <term><filename>system.reg</filename></term>
+ <listitem>
+ <para>
+ This file contains HKEY_LOCAL_MACHINE.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>user.reg</filename></term>
+ <listitem>
+ <para>
+ This file contains HKEY_CURRENT_USER.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>userdef.reg</filename></term>
+ <listitem>
+ <para>
+ This file co