                              Wine Documentation                               
Prev                                                                       Next
-------------------------------------------------------------------------------

Chapter 4. Configuring Wine

Setting up config files, etc.

4.1. General Configuration

Copyright 1999 Adam Sacarny <magicbox@bestweb.net>

(Extracted from wine/documentation/config)

4.1.1. The Wine Config File

The Wine config file stores various settings for Wine. These include:

  * Drives and Information about them
   
  * Directory Settings
   
  * Port Settings
   
  * The Wine look and feel
   
  * Wine's DLL Usage
   
  * Wine's Multimedia drivers and DLL configuration
   
4.1.2. How Do I Make One?

This section will guide you through the process of making a config file. Take a
look at the file <dirs to wine>/documentation/samples/config. It is organized
by section.

+-----------------------------------------------------------------------------+
|Section Name   |Needed?|What it Does                                         |
|---------------+-------+-----------------------------------------------------|
|[Drive X]      |yes    |Sets up drives recognized by wine                    |
|---------------+-------+-----------------------------------------------------|
|[wine]         |yes    |Settings for wine directories                        |
|---------------+-------+-----------------------------------------------------|
|[DllDefaults]  |recmd  |Defaults for loading DLL's                           |
|---------------+-------+-----------------------------------------------------|
|[DllPairs]     |recmd  |Sanity checkers for DLL's                            |
|---------------+-------+-----------------------------------------------------|
|[DllOverrides] |recmd  |Overides defaults for DLL loading                    |
|---------------+-------+-----------------------------------------------------|
|[x11drv]       |recmd  |Graphic driver settings                              |
|---------------+-------+-----------------------------------------------------|
|[fonts]        |yes    |Font appearance and recognition                      |
|---------------+-------+-----------------------------------------------------|
|[serialports]  |no     |COM ports seen by wine                               |
|---------------+-------+-----------------------------------------------------|
|[parallelports]|no     |LPT ports seen by wine                               |
|---------------+-------+-----------------------------------------------------|
|[ppdev]        |no     |Parallelport emulation                               |
|---------------+-------+-----------------------------------------------------|
|[spooler]      |no     |Print spooling                                       |
|---------------+-------+-----------------------------------------------------|
|[ports]        |no     |Direct port access                                   |
|---------------+-------+-----------------------------------------------------|
|[spy]          |no     |What to do with certain debug messages               |
|---------------+-------+-----------------------------------------------------|
|[Registry]     |no     |Specifies locations of windows registry files        |
|---------------+-------+-----------------------------------------------------|
|[tweak.layout] |recmd  |Appearance of wine                                   |
|---------------+-------+-----------------------------------------------------|
|[programs]     |no     |Programs to be run automatically                     |
|---------------+-------+-----------------------------------------------------|
|[Console]      |no     |Console settings                                     |
|---------------+-------+-----------------------------------------------------|
|[Clipboard]    |no     |Interaction for wine and X11 clipboard               |
|---------------+-------+-----------------------------------------------------|
|[afmdirs]      |no     |Postscript driver settings                           |
|---------------+-------+-----------------------------------------------------|
|[WinMM]        |yes    |Multimedia settings                                  |
|---------------+-------+-----------------------------------------------------|
|[AppDefaults]  |no     |Overwrite the settings of previous sections for      |
|               |       |special programs                                     |
+-----------------------------------------------------------------------------+

4.1.2.1. The [Drive X] Section

It should be pretty self explanatory, but here is an in-depth tutorial about
them. There are up to 6 lines for each drive in Wine.

[Drive X]
The above line begins the section for a drive whose letter is X.

Path=/dir/to/path
This path is where the drive will begin. When Wine is browsing in drive X, it
will see the files that are in the directory /dir/to/path. Don't forget to
leave off the trailing slash!

"Type" = "floppy|hd|cdrom|network"
Sets up the type of drive Wine will see it as. Type must equal one of the four
floppy, hd, cdrom, or network. They are self-explanatory. (The |'s mean "Type =
'<one of the options>'".)

"Label" = "blah"
Defines the drive label. Generally only needed for programs that look for a
special CD-ROM. Info on finding the lable is in <dirs to wine>/documentation/
cdrom-labels. The label may be up to 11 characters.

"Serial" = "deadbeef"
Tells Wine the serial number of the drive. A few programs with intense
protection for pirating might need this, but otherwise don't use it. Up to 8
characters and hexadecimal.

"Filesystem" = "msdos|win95|unix"
Sets up the way Wine looks at files on the drive.

msdos
   
    Case insensitive filesystem. Alike to DOS and Windows 3.x. 8.3 is the
    maximum length of files (eightdot.123) - longer ones will be truncated.
    (NOTE: this is a very bad choice if you plan on running apps that use long
    filenames. win95 should work fine with apps that were designed to run under
    the msdos system. In other words, you might not want to use this.)
   
win95
   
    Case insensitive. Alike to Windows 9x/NT 4. This is the long filename
    filesystem you are probably used to working with. The filesystem of choice
    for most applications to be run under wine. PROBABLY THE ONE YOU WANT!
   
unix
   
    Case sensitive. This filesystem has almost no use (Windows apps expect case
    insensitive filenames). Try it if you dare, but win95 is a much better
    choice.
   
"Device" = "/dev/xx"

Use this ONLY for floppy and cdrom devices. Using it on Extended2 partitions
can have dire results (when a windows app tries to do a lowlevel write, they do
it in a FAT way -- FAT does not mix with Extended2).

Note This setting is not really important; almost all apps will have no problem
     if it remains unspecified. For CD-ROMs you might want to add it to get    
     automatic label detection, though. If you are unsure about specifying     
     device names, just leave out this setting for your drives.                

Here is a setup for Drive X, a generic hard drive:
[Drive X]
"Path" = "/dos-a"
"Type" = "hd"
"Label" = "Hard Drive"
"Filesystem" = "win95"
This is a setup for Drive X, a generic CD-ROM drive:
[Drive X]
"Path" = "/dos-d"
"Type" = "cdrom"
"Label" = "Total Annihilation"
"Filesystem" = "win95"
"Device" = "/dev/hdc"
And here is a setup for Drive X, a generic floppy drive:
[Drive X]
"Type" = "floppy"
"Path" = "/mnt/floppy"
"Label" = "Floppy Drive"
"Serial" = "87654321"
"Filesystem" = "win95"
"Device" = "/dev/fd0"
            

4.1.2.2. The [wine] Section

The [wine] section of the configuration file contains all kinds of general
settings for Wine. When specifying the directories for the directory related
settings, make them as they would appear in wine. If your drive C has a path of
/dos, and your windows directory is located in /dos/windows, then use:
"Windows" = "c:\\windows"

This sets up the windows directory. Make one if you don't already have one. NO
TRAILING SLASH (NOT C:\\windows\)!

"System" = "c:\\windows\\system"
This sets up where the windows system files are. Should reside in the directory
used for the Windows setting. If you don't have windows then this is where the
system files will go. Again, NO TRAILING SLASH!

"Temp" = "c:\\temp"
This should be the directory you want your temp files stored in. YOU MUST HAVE
WRITE ACCESS TO IT.

"Path" = "c:\\windows;c:\\windows\\system;c:\\blanco"
            

Behaves like the PATH setting on UNIX boxes. When wine is run like wine sol.exe
, if sol.exe resides in a directory specified in the Path setting, wine will
run it (Of course, if sol.exe resides in the current directory, wine will run
that one). Make sure it always has your windows directory and system directory
(For this setup, it must have "c:\\windows;c:\\windows\\system").

"GraphicsDriver" = "x11drv|ttydrv"
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 any Windows GUI programs. Thus this option is mainly
interesting for e.g. embedded use of Wine in web server scripts.

"Printer" = "off|on"
Tells wine whether to allow printing via printer drivers to work. This option
isn't needed for our builtin 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 on working on printing via windows
printer drivers, don't even add this to your wine config file (It probably
isn't already in it). Check out the [spooler] and [parallelports] sections too.

"ShellLinker" = "wineshelllink"
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.

"ShowDirSymlinks" = "1"
Wine doesn't pass directory symlinks to Windows programs by default, as doing
so may crash some programs that do recursive lookups of whole subdirectory
trees whenever a directory symlink points back to itself or one of its parent
directories. That's why we disallowed the use of directory symlinks and added
this setting to reenable ("1") this functionality.

"SymbolTableFile" = "wine.sym"
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.

4.1.2.3. Introduction To DLL Sections

There are a few things you will need to know before configuring the DLL
sections in your wine configuration file.

4.1.2.3.1. Windows DLL Pairs

Most windows DLL's have a win16 (Windows 3.x) and win32 (Windows 9x/NT) form.
The combination of the win16 and win32 DLL versions are called the "DLL pair".
This is a list of the most common pairs:

+-----------------------------------------------------------------+
|Win16            |Win32               |Native [a]                |
|-----------------+--------------------+--------------------------|
|KERNEL           |KERNEL32            |No!                       |
|-----------------+--------------------+--------------------------|
|USER             |USER32              |No!                       |
|-----------------+--------------------+--------------------------|
|SHELL            |SHELL32             |Yes                       |
|-----------------+--------------------+--------------------------|
|GDI              |GDI32               |No!                       |
|-----------------+--------------------+--------------------------|
|COMMDLG          |COMDLG32            |Yes                       |
|-----------------+--------------------+--------------------------|
|VER              |VERSION             |Yes                       |
|-----------------------------------------------------------------|
|Notes:                                                           |
|a. Is it possible to use native dll with wine? (See next section)|
+-----------------------------------------------------------------+

4.1.2.3.2. Different Forms Of DLL's

There are a few different forms of DLL's wine can load:

native
   
    The DLL's that are included with windows. Many windows DLL's can be loaded
    in their native form. Many times these native versions work better than
    their non-Microsoft equivalent -- other times they don't.
   
elfdll
   
    ELF encapsulated windows DLL's. This is currently experimental (Not working
    yet).
   
so
   
    Native ELF libraries. Will not work yet.
   
builtin
   
    The most common form of DLL loading. This is what you will use if the DLL
    is error-prone in native form (KERNEL for example), you don't have the
    native DLL, or you just want to be Microsoft-free.
   
4.1.2.4. The [DllDefaults] Section

These settings provide wine's default handling of DLL loading.

"DefaultLoadOrder" =" native, so, builtin"

This setting is a comma-delimited list of the order in which to attempt loading
DLLs. If the first option fails, it will try the second, and so on. The order
specified above is probably the best in most conditions.

4.1.2.5. The [DllPairs] Section

At one time, there was a section called [DllPairs] in the default configuration
file, but this has been obsoleted because the pairing information has now been
embedded into Wine itself. (The purpose of this section was merely to be able
to issue warnings if the user attempted to pair codependent 16-bit/32-bit DLLs
of different types.) If you still have this in your wine.conf or ~/.wine/
config, you may safely delete it.

4.1.2.6. The [DllOverrides] Section

The format for this section is the same for each line:
<DLL>{,<DLL>,<DLL>...} = <FORM>{,<FORM>,<FORM>...}
            

For example, to load builtin KERNEL pair (case doesn't matter here):
"kernel,kernel32" = "builtin"
            

To load the native COMMDLG pair, but if that doesn't work try builtin:
"commdlg,comdlg32" = "native,builtin"
            

To load the native COMCTL32:
"comctl32" = "native"
            

Here is a good generic setup (As it is defined in config that was included with
your wine package):
[DllOverrides]
"commdlg"      = "builtin, native"
"comdlg32"     = "builtin, native"
"ver"          = "builtin, native"
"version"      = "builtin, native"
"shell"        = "builtin, native"
"shell32"      = "builtin, native"
"lzexpand"     = "builtin, native"
"lz32"         = "builtin, native"
"comctl32"     = "builtin, native"
"commctrl"     = "builtin, native"
"wsock32"      = "builtin"
"winsock"      = "builtin"
"advapi32"     = "builtin, native"
"crtdll"       = "builtin, native"
"mpr"          = "builtin, native"
"winspool.drv" = "builtin, native"
"ddraw"        = "builtin, native"
"dinput"       = "builtin, native"
"dsound"       = "builtin, native"
"mmsystem"     = "builtin"
"winmm"        = "builtin"
"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"
"wnaspi32"     = "builtin"
"icmp"         = "builtin"
            

Note You see that elfdll or so is the first option for a few of these dll's.   
     This will fail for you, but you won't notice it as wine will just use the 
     second or third option.                                                   

4.1.2.7. The [fonts] Section

This section sets up wine's font handling.

"Resolution" = "96"

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 (<dirs to wine>
/documentation/ttfserver and fonts), this parameter will not be as important.
Of course, it's always good to get your X fonts working acceptably in wine.

"Default" = "-adobe-times-"
The default font wine uses. Fool around with it if you'd like.

OPTIONAL:

The Alias 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:
"AliasX" = "[Fake windows name],[Real X name]"<,optional "masking" section>
            

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.

Here is an example of an alias without masking. The font will show up in
windows apps as "Google". When defining an alias in a config file, forget about
my comment text (The "<-- blah" stuff)
"Alias0" = "Foo,--google-"      <
            

Here is an example with masking enabled. The font will show up as "Foo" in
windows apps.
"Alias1" = "Foo,--google-,subst"
            

For more info check out <dirs to wine>/documentation/fonts

4.1.2.8. The [serialports], [parallelports], [spooler], and [ports] Sections

Even though it sounds like a lot of sections, these are all closely related.
They are all for communications and parallel ports.

The [serialports] section tells wine what serial ports it is allowed to use.
"ComX" = "/dev/cuaY"

Replace X with the number of the COM port in Windows (1-8) and Y with the
number of it in X (Usually the number of the port in Windows minus 1). ComX can
actually equal any device (/dev/modem is acceptable). It is not always
necessary to define any COM ports (An optional setting). Here is an example:
"Com1" = "/dev/cua0"

Use as many of these as you like in the section to define all of the COM ports
you need.

The [parallelports] section sets up any parallel ports that will be allowed
access under wine.
"LptX" = "/dev/lpY"

Sounds familiar? Syntax is just like the COM port setting. Replace X with a
value from 1-4 as it is in Windows and Y with a value from 0-3 (Y is usually
the value in windows minus 1, just like for COM ports). You don't always need
to define a parallel port (AKA, it's optional). As with the other section, LptX
can equal any device (Maybe /dev/printer). Here is an example:
"Lpt1" = "/dev/lp0"

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. IT IS OPTIONAL. 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 out.ps:
"LPT1:" = "out.ps"

The following command maps printing jobs to LPT1 to the command lpr. Notice the
|:
"LPT1:" = "|lpr"

The [ports] section is usually useful only for people who need direct port
access for programs requiring dongles or scanners. IF YOU DON'T NEED IT, DON'T
USE IT!

"read" = "0x779,0x379,0x280-0x2a0"
Gives direct read access to those IO's.

"write" = "0x779,0x379,0x280-0x2a0"
Gives direct write access to those IO's. It's probably a good idea to keep the
values of the read and write settings the same. This stuff will only work when
you're root.

4.1.2.9. The [spy], [Registry], [tweak.layout], and [programs] Sections

[spy] is used to include or exclude debug messages, and to output them to a
file. The latter is rarely used. THESE ARE ALL OPTIONAL AND YOU PROBABLY DON'T
NEED TO ADD OR REMOVE ANYTHING IN THIS SECTION TO YOUR CONFIG.

"File" = "/blanco"
Sets the logfile for wine. Set to CON to log to standard out. THIS IS RARELY
USED.

"Exclude" = "WM_SIZE;WM_TIMER;"
Excludes debug messages about WM_SIZE and WM_TIMER in the logfile.

"Include" = "WM_SIZE;WM_TIMER;"
Includes debug messages about WM_SIZE and WM_TIMER in the logfile.

[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.

"UserFileName" = "/dirs/to/user.reg"
The location of your old user.reg file.

[tweak.layout] is devoted to wine's look. There is only one setting for it.

"WineLook" = "win31|win95|win98"
Will change the look of wine from Windows 3.1 to Windows 95. The win98 setting
behaves just like win95 most of the time.

[programs] can be used to say what programs run under special conditions.

"Default" = "/program/to/execute.exe"
Sets the program to be run if wine is started without specifying a program.

"Startup" = "/program/to/execute.exe"
Sets the program to automatically be run at startup every time.

4.1.2.10. The [WinMM] Section

[WinMM] is used to define which multimedia drivers have to be loaded. Since
those drivers may depend on the multimedia interfaces available on your sustem
(OSS, Alsa... to name a few), it's needed to be able to configure which driver
has to be loaded.

The content of the section looks like:
 
[WinMM]
"Drivers" = "wineoss.drv"
"WaveMapper" = "msacm.drv"
"MidiMapper" = "midimap.drv"
            
All the keys must be defined:

  * 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.
   
  * The "WaveMapper" represents the name of the module containing the Wave
    Mapper driver. Only one wave mapper can be defined in the system.
   
  * The "MidiMapper" represents the name of the module containing the Midi
    Mapper driver. Only one Midi mapper can be defined in the system.
   
4.1.2.11. The [AppDefaults] Section

The section is used to overwrite the setting 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 section of the configuration file its values should be overwritten with
different settings. The three parts of the section name are separated by two
backslashes.

Currently wine supports only overwriting the sections [DllOverrides] and
[x11drv].

Here is an example that overwrites the normal settings for a program:
 
;; default settings
[x11drv]
"Managed" = "Y"
"Desktop" = "N"

;; run install in desktop mode
[AppDefaults\\install.exe\\x11drv]
"Managed" = "N"
"Desktop" = "800x600"
            

4.1.3. Where Do I Put It?

The wine config file can go in two places.

/usr/local/etc/wine.conf
   
    A systemwide config file, used for anyone who doesn't have their own. NOTE:
    this file is currently unused as a new global configuration mechanism is
    not in place at this time
   
$HOME/.wine/config
   
    Your own config file, that only is used for your user.
   
So copy your version of the wine.conf file to /usr/local/etc/wine.conf or $HOME
/.wine/config for wine to recognize it.

4.1.4. What If It Doesn't Work?

There is always a chance that things will go wrong. If the unthinkable happens,
try the newsgroup, comp.emulators.ms-windows.wine, or the IRCnet channel #
WineHQ found on irc.stealth.net:6668, or connected servers. Make sure that you
have looked over this document thoroughly, and have also read:

  * README
   
  * http://www.la-sorciere.de/wine/index.html (optional but recommended)
   
If indeed it looks like you've done your research, be prepared for helpful
suggestions. If you haven't, brace yourself for heaving flaming.

-------------------------------------------------------------------------------
Prev                                 Home                                  Next
SCSI Support                          Up                          Win95/98 Look
