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).
Parts taken from the former file wine/documentation/config, Copyright 1999 Adam Sacarny <magicbox@bestweb.net>
The Wine configuration file is the central file to store configuration settings for Wine. This file (which is called config) can be found in the sub directory .wine/ of your user's home directory (directory /home/user/). In other words, the Wine configuration file is ~/.wine/config. Note that since the Wine configuration file is a part of the Wine registry file system, this file also requires 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).
The settings available in the configuration file 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
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 config (which can be found in the directory documentation/samples/ 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 ~/.wine/config has been safely moved out of the way instead of simply overwriting it when you will now copy over the sample configuration file.
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 terminal:
$ mkdir ~/.wine/ $ cp dir_to_wine_source_code/documentation/samples/config ~/.wine/config |
Now you can start adapting the configuration file's settings with an editor according to the documentation below. Note that you should only 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!!
Let's start by giving an overview of which sections a configuration file may contain, and whether the inclusion of the respective section is needed or only recommended ("recmd").
Section Name | Needed? | What it Does |
---|---|---|
[Drive x] | yes | Sets up drive mappings to be used by Wine |
[wine] | yes | General settings for Wine |
[DllDefaults] | recmd | Defaults for loading DLL's |
[DllPairs] | recmd | Sanity checkers for DLL's |
[DllOverrides] | recmd | Overrides defaults for DLL loading |
[x11drv] | recmd | Graphics 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 |
[Debug] | 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 |
Now let's explain the configuration file sections in a detailed way.
For a detailed description of these configuration file sections which are used to set up DOS drive mappings to Unix directory space, please look at the Wine file system layer configuration section.
The [wine] section of the configuration file contains all kinds of general settings for Wine.
"Windows" = "c:\\windows" "System" = "c:\\windows\\system" "Temp" = "c:\\temp" "Path" = "c:\\windows;c:\\windows\\system;c:\\blanco" "ShowDirSymlinks" = "1" |
"GraphicsDriver" = "x11drv|ttydrv" |
"Printer" = "off|on" |
"ShellLinker" = "wineshelllink" |
"SymbolTableFile" = "wine.sym" |
These settings provide wine's default handling of DLL loading.
"DefaultLoadOrder" =" native, 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.
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/.config or wine.conf, you may safely delete it.
The format for this section is the same for each line:
<DLL>{,<DLL>,<DLL>...} = <FORM>{,<FORM>,<FORM>...} |
For example, to load built-in KERNEL pair (case doesn't matter here):
"kernel,kernel32" = "builtin" |
To load the native COMMDLG pair, but if that doesn't work try built-in:
"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] "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" |
Note: If loading of the libraries that are listed first fails, wine will just go on by using the second or third option.
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-" |
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".
"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 information check out the Fonts chapter.
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/ttySY" |
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/ttyS0" |
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" |
"write" = "0x779,0x379,0x280-0x2a0" |
[Debug] 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. (In extreme cases you may want to use these options to manage the amount of information generated by the --debugmsg +relay option.)
"File" = "/blanco" |
"SpyExclude" = "WM_SIZE;WM_TIMER;" |
"SpyInclude" = "WM_SIZE;WM_TIMER;" |
"RelayInclude" = "user32.CreateWindowA;comctl32.*" |
"RelayExclude" = "RtlEnterCriticalSection;RtlLeaveCriticalSection" |
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.
[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" |
[tweak.layout] is devoted to wine's look. There is only one setting for it.
"WineLook" = "win31|win95|win98" |
[programs] can be used to say what programs run under special conditions.
"Default" = "/program/to/execute.exe" |
"Startup" = "/program/to/execute.exe" |
[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.
The content of the section looks like:
[WinMM] "Drivers" = "wineoss.drv" "WaveMapper" = "msacm.drv" "MidiMapper" = "midimap.drv" |
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.
[Network] contains settings related to networking. Currently there is only one value that can be set.
A boolean setting (default: Y) that affects the way Wine sets the computer name. The computer name in the Windows world is the so-called NetBIOS name. It is contained in the ComputerName in the registry entry HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ComputerName\ComputerName.
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 hostname, 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.
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.
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.
Currently wine supports overriding selected settings within the sections [DllOverrides], [x11drv], [version] and [dsound] only.
Here is an example that overrides 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" |
There is always a chance that things will go wrong. If the unthinkable happens, report the problem to Wine Bugzilla, try the newsgroup comp.emulators.ms-windows.wine, or the IRC channel #WineHQ found on irc.freenode.net, or connected servers. Make sure that you have looked over this document thoroughly, and have also read:
README
http://www.winehq.org/trouble/
If indeed it looks like you've done your research, be prepared for helpful suggestions. If you haven't, brace yourself for heaving flaming.