Moved system metrics definitions to winuser.h.

[wine] / documentation / config

Copyright 1999 Adam Sacarny (magicbox@bestweb.net)
1. WHAT IS 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

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>/wine.ini
It is organized by 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
[options]        | no      | No one seems to know
[fonts]          | yes     | Font appearance and recognition
[serialports]    | no      | COM ports seen by wine
[parallelports]  | no      | LPT ports seen by wine
[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
Recmd-Recommended
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 <--- the |'s mean Type=<one of the options>

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.

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

2.2 THE [wine] SECTION 

The [wine] section of the configuration file contains information wine uses for
directories. When specifying the directories for the 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, Windows=c:\windows.

Windows=c:\windows

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

System=c:\windows\system

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

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.

printer=off|on

Tells wine whether to allow printer drivers and printing to work. 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, don't even
add this to your wine.ini (It probably isn't already in it). Check out the
[spooler] and [parallelports] sections too.

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.

        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* 
        -----------------------------
        KERNEL     | KERNEL32  | No!
        USER       | USER32    | No!
        SHELL      | SHELL32   | Yes
        GDI        | GDI32     | No!
        COMMDLG    | COMDLG32  | Yes
        VER        | VERSION   | Yes
        *-Is it possible to use native dll with wine?(See next section)

        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.
        
2.4 THE [DllDefaults] SECTION

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

EXTRA_LD_LIBRARY_PATH=/dirs

The directory specified here is appended to the normal search path for certain
forms of DLL's (elfdll and .so).

DefaultLoadOrder = native, elfdll, so, builtin

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

2.5 THE [DllPairs] SECTION

This section is optional, but strongly recommended. If you try to use native
SHELL32, but builtin SHELL, you could have some big problems (native and
builtin/so/elfdll do certain things in different ways). Using different forms of
a pair is a *very*, **very** bad idea. By specifying DLL pairs here, wine will
print out a message if you use different forms of a pair.
You shouldn't need to change anything in this section, the following should work
fine in all cases:

[DllPairs]
kernel  = kernel32
gdi     = gdi32
user    = user32
commdlg = comdlg32
commctrl= comctl32
ver     = version
shell   = shell32
lzexpand= lz32
winsock = wsock32

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 wine.ini that was included
with your wine package):

[DllOverrides]
kernel32, gdi32, user32 = builtin
kernel, gdi, user       = builtin
toolhelp                = builtin
comdlg32, commdlg       = elfdll, builtin, native
version, ver            = elfdll, builtin, native
shell32, shell          = builtin, native
lz32, lzexpand          = builtin, native
commctrl, comctl32      = builtin, native
wsock32, winsock        = builtin
advapi32, crtdll, ntdll = builtin, native
mpr, winspool           = builtin, native
ddraw, dinput, dsound   = builtin, native
winmm, w32skrnl, msvfw32= builtin
wnaspi32, wow32         = builtin
system, display, wprocs = builtin
wineps                  = 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.

2.7 THE [options] SECTION

No one seems to know what this section is...

AllocSystemColors=100

System colors to allocate? Just leave it at 100.

2.8 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-      <-- Note the no spaces after the " = ". Important!

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

2.9 THE [serialports], [parallelports], [spooler], AND [ports] SECTIONS

Even though it sounds like a lot of sections, these are all closely related.
They all are 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

Seem farmiliar? 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 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.

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

LocalMachineFileName=/dirs/to/system.reg

The location of your old system.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. "win98" 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.

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.
        $HOME/.winerc <--- Your own config file, that only is used for your
        user. 

So copy the file you made to be the wine.conf to /usr/local/etc/wine.conf or 
$HOME/.winerc for wine to recognize it. 

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
Make sure that you have looked over this document thoroughly, and have also
read:
README
documentation/bugreports
http://www.westfalen.de/witch/wine-HOWTO.txt (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.