documentation/config

   1 Copyright 1999 Adam Sacarny (magicbox@bestweb.net)
   2 1. WHAT IS THE WINE CONFIG FILE?
   3
   4 The Wine config file stores various settings for Wine. These include:
   5         Drives and Information about them
   6         Directory Settings
   7         Port Settings
   8         The Wine look and feel
   9         Wine's DLL Usage
  10
  11 2. HOW DO I MAKE ONE?
  12
  13 This section will guide you through the process of making a config file. Take a
  14 look at the file <dirs to wine>/wine.ini
  15 It is organized by section.
  16
  17
  18      Name        | Needed? | What it does
  19 ----------------------------------------------------------------
  20 [Drive X]        | yes     | Sets up drives recognized by wine
  21 [wine]           | yes     | Settings for wine directories
  22 [DllDefaults]    | recmd   | Defaults for loading DLL's
  23 [DllPairs]       | recmd   | Sanity checkers for DLL's
  24 [DllOverrides]   | recmd   | Overides defaults for DLL loading
  25 [options]        | no      | No one seems to know
  26 [fonts]          | yes     | Font appearance and recognition
  27 [serialports]    | no      | COM ports seen by wine
  28 [parallelports]  | no      | LPT ports seen by wine
  29 [spooler]        | no      | Print spooling
  30 [ports]          | no      | Direct port access
  31 [spy]            | no      | What to do with certain debug messages
  32 [Registry]       | no      | Specifies locations of windows registry files
  33 [tweak.layout]   | recmd   | Appearance of wine
  34 [programs]       | no      | Programs to be run automatically
  35 [Console]        | no      | Console settings
  36 Recmd-Recommended
  37 2.1 THE [Drive X] SECTION
  38 It should be pretty self explanatory, but here is an in-depth tutorial about
  39 them.
  40 There are up to 6 lines for each drive in Wine.
  41
  42 [Drive X]
  43
  44 The above line begins the section for a drive whose letter is X.
  45
  46 Path=/dir/to/path
  47
  48 This path is where the drive will begin. When Wine is browsing in drive X, it
  49 will see the files that are in the directory "/dir/to/path". Don't forget to
  50 leave off the trailing slash!
  51
  52 Type=floppy|hd|cdrom|network <--- the |'s mean Type=<one of the options>
  53
  54 Sets up the type of drive Wine will see it as. Type must equal one of the four
  55 "floppy", "hd", "cdrom", or "network". They are self-explanatory.
  56
  57 Label=blah
  58
  59 Defines the drive label. Generally only needed for programs that look for a
  60 special CD-ROM. Info on finding the lable is in <dirs to
  61 wine>/documentation/cdrom-labels. The label may be up to 11 characters.
  62
  63 Serial=deadbeef
  64
  65 Tells Wine the serial number of the drive. A few programs with intense
  66 protection for pirating might need this, but otherwise don't use it. Up to 8
  67 characters and hexadecimal.
  68
  69 Filesystem=msdos|win95|unix
  70
  71 Sets up the way Wine looks at files on the drive.
  72
  73         msdos -> Case insensitive filesystem. Alike to DOS and Windows 3.x.
  74         8.3 is the maximum length of files (eightdot.123) - longer ones will be
  75         truncated. (NOTE: this is a very bad choice if you plan on running apps
  76         that use long filenames. win95 should work fine with apps that were
  77         designed to run under the msdos system. In other words, you might not
  78         want to use this.)
  79
  80         win95 -> Case insensitive. Alike to Windows 9x/NT 4. This is the long
  81         filename filesystem you are probably used to working with. The
  82         filesystem of choice for most applications to be run under wine.
  83         PROBABLY THE ONE YOU WANT
  84
  85         unix  -> Case sensitive. This filesystem has almost no use (Windows apps
  86         expect case insensitive filenames). Try it if you dare, but win95 is a
  87         much better choice.
  88
  89 Device=/dev/xx
  90
  91 Use this ONLY for floppy and cdrom devices. Using it on Extended2 partitions can
  92 have dire results (When a windows app tries to do a lowlevel write, they do it
  93 in a FAT way -- FAT does not mix with Extended2). Currently, it is useless when
  94 used on cdrom's, however functionality could be implemented later to allow wine
  95 to automatically find the cdrom label.
  96 NOTE: This setting is not terribly important, almost all apps will have no
  97 problem if it remains unspecified. If you are unsure about specifying device
  98 names, just leave out this setting for your drives.
  99
 100 Here is a setup for Drive X, a generic hard drive:
 101 [Drive X]
 102 Path=/dos-a
 103 Type=hd
 104 Label=Hard Drive
 105 Filesystem=win95
 106 This is a setup for Drive X, a generic CD-ROM drive:
 107 [Drive X]
 108 Path=/dos-d
 109 Type=cdrom
 110 Label=Total Annihilation
 111 Filesystem=win95
 112 Device=/dev/hdc
 113 And here is a setup for Drive X, a generic floppy drive:
 114 [Drive X]
 115 Type=floppy
 116 Path=/mnt/floppy
 117 Label=Floppy Drive
 118 Serial=87654321
 119 Filesystem=win95
 120 Device=/dev/fd0
 121
 122 2.2 THE [wine] SECTION
 123
 124 The [wine] section of the configuration file contains information wine uses for
 125 directories. When specifying the directories for the settings, make them as they
 126 would appear in wine. If your drive C has a Path of /dos, and your windows
 127 directory is located in /dos/windows, Windows=c:\windows.
 128
 129 Windows=c:\windows
 130
 131 Sets up the windows directory. Make one if you don't have windows. NO TRAILING
 132 SLASH (NOT C:\windows\)!
 133
 134 System=c:\windows\system
 135
 136 Sets up where the windows system files are. Should reside in the directory used
 137 for the "Windows" setting. If you don't have windows then this is where the
 138 system files will go. NO TRAILING SLASH!
 139
 140 Temp=c:\temp
 141
 142 This should be the directory you want your temp files stored in. YOU MUST HAVE
 143 WRITE ACCESS TO IT.
 144
 145 Path=c:\windows;c:\windows\system;c:\blanco
 146
 147 Behaves like the PATH setting on unix boxes. When wine is run like "wine
 148 sol.exe", if sol.exe resides in a directory specified in the "Path" setting,
 149 wine will run it (Of course, if sol.exe resides in the current directory, wine
 150 will run that one). Make sure it always has your windows directory and system
 151 directory (For this setup, it must have c:\windows;c:\windows\system).
 152
 153 SymbolTableFile=wine.sym
 154
 155 Sets up the symbol table file for the wine debugger. You probably don't need to
 156 fiddle with this. May be useful if your wine is stripped.
 157
 158 printer=off|on
 159
 160 Tells wine whether to allow printer drivers and printing to work. Using these
 161 things are pretty alpha, so you might want to watch out. Some people might find
 162 it useful, however. If you're not planning on working on printing, don't even
 163 add this to your wine.ini (It probably isn't already in it). Check out the
 164 [spooler] and [parallelports] sections too.
 165
 166 2.3 INTRODUCTION TO DLL SECTIONS
 167
 168 There are a few things you will need to know before configuring the DLL sections
 169 in your wine configuration file.
 170
 171         2.3.1 WINDOWS DLL PAIRS
 172
 173         Most windows DLL's have a win16 (Windows 3.x) and win32 (Windows 9x/NT)
 174         form.  The combination of the win16 and win32 DLL versions are called
 175         the "DLL pair". This is a list of the most common pairs:
 176            Win16   |   Win32   | Native*
 177         -----------------------------
 178         KERNEL     | KERNEL32  | No!
 179         USER       | USER32    | No!
 180         SHELL      | SHELL32   | Yes
 181         GDI        | GDI32     | No!
 182         COMMDLG    | COMDLG32  | Yes
 183         VER        | VERSION   | Yes
 184         *-Is it possible to use native dll with wine?(See next section)
 185
 186         2.3.2 DIFFERENT FORMS OF DLL'S
 187
 188         There are a few different forms of DLL's wine can load:
 189                 native -> The DLL's that are included with windows. Many windows
 190                 DLL's can be loaded in their native form. Many times these
 191                 native versions work better than their non-Microsoft equivalent
 192                 -- other times they don't.
 193                 elfdll -> ELF encapsulated windows DLL's. This is currently
 194                 experimental (Not working yet).
 195                 so -> Native ELF libraries. Will not work yet.
 196                 builtin -> The most common form of DLL loading. This is what you
 197                 will use if the DLL is error-prone in native form (KERNEL for
 198                 example), you don't have the native DLL, or you just want to be
 199                 Microsoft-free.
 200
 201 2.4 THE [DllDefaults] SECTION
 202
 203 These settings provide wine's default handling of DLL loading.
 204
 205 EXTRA_LD_LIBRARY_PATH=/dirs
 206
 207 The directory specified here is appended to the normal search path for certain
 208 forms of DLL's (elfdll and .so).
 209
 210 DefaultLoadOrder = native, elfdll, so, builtin
 211
 212 This setting is a comma-delimited list of which order to attempt loading DLL's.
 213 If the first option fails, it will try the second, and so on. The order
 214 specified above is probably the best in most conditions.
 215
 216 2.5 THE [DllPairs] SECTION
 217
 218 This section is optional, but strongly recommended. If you try to use native
 219 SHELL32, but builtin SHELL, you could have some big problems (native and
 220 builtin/so/elfdll do certain things in different ways). Using different forms of
 221 a pair is a *very*, **very** bad idea. By specifying DLL pairs here, wine will
 222 print out a message if you use different forms of a pair.
 223 You shouldn't need to change anything in this section, the following should work
 224 fine in all cases:
 225
 226 [DllPairs]
 227 kernel  = kernel32
 228 gdi     = gdi32
 229 user    = user32
 230 commdlg = comdlg32
 231 commctrl= comctl32
 232 ver     = version
 233 shell   = shell32
 234 lzexpand= lz32
 235 winsock = wsock32
 236
 237 2.6 THE [DllOverrides] SECTION
 238
 239 The format for this section is the same for each line:
 240
 241 <DLL>{,<DLL>,<DLL>...} = <FORM>{,<FORM>,<FORM>...}
 242
 243 For example, to load builtin KERNEL pair (Case doesn't matter here):
 244
 245 kernel,kernel32 = builtin
 246
 247 To load the native COMMDLG pair, but if that doesn't work try builtin:
 248
 249 commdlg,comdlg32 = native,builtin
 250
 251 To load the native COMCTL32:
 252
 253 comctl32 = native
 254
 255 Here is a good generic setup (As it is defined in wine.ini that was included
 256 with your wine package):
 257
 258 [DllOverrides]
 259 kernel32, gdi32, user32 = builtin
 260 kernel, gdi, user       = builtin
 261 toolhelp                = builtin
 262 comdlg32, commdlg       = elfdll, builtin, native
 263 version, ver            = elfdll, builtin, native
 264 shell32, shell          = builtin, native
 265 lz32, lzexpand          = builtin, native
 266 commctrl, comctl32      = builtin, native
 267 wsock32, winsock        = builtin
 268 advapi32, crtdll, ntdll = builtin, native
 269 mpr, winspool           = builtin, native
 270 ddraw, dinput, dsound   = builtin, native
 271 winmm, w32skrnl, msvfw32= builtin
 272 wnaspi32, wow32         = builtin
 273 system, display, wprocs = builtin
 274 wineps                  = builtin
 275
 276 NOTE: You see that elfdll or so is the first option for a few of these dll's.
 277 This will fail for you, but you won't notice it as wine will just use the second
 278 or third option.
 279
 280 2.7 THE [options] SECTION
 281
 282 No one seems to know what this section is...
 283
 284 AllocSystemColors=100
 285
 286 System colors to allocate? Just leave it at 100.
 287
 288 2.8 THE [fonts] SECTION
 289
 290 This section sets up wine's font handling.
 291
 292 Resolution = 96
 293
 294 Since the way X handles fonts is different from the way Windows does, wine uses
 295 a special mechanism to deal with them. It must scale them using the number
 296 defined in the "Resolution" setting. 60-120 are reasonable values, 96 is a nice
 297 in the middle one. If you have the real windows fonts available (<dirs to
 298 wine>/documentation/ttfserver and fonts), this parameter will not be as
 299 important. Of course, it's always good to get your X fonts working acceptably in
 300 wine.
 301
 302 Default = -adobe-times-
 303
 304 The default font wine uses. Fool around with it if you'd like.
 305
 306 OPTIONAL:
 307
 308 The "Alias" setting allows you to map an X font to a font used in wine. This is
 309 good for apps that need a special font you don't have, but a good replacement
 310 exists. The syntax is like so:
 311
 312 AliasX = [Fake windows name],[Real X name]<,optional "masking" section>
 313
 314 Pretty straightforward. Replace "AliasX" with "Alias0", then "Alias1" and so on.
 315 The fake windows name is the name that the font will be under a windows app in
 316 wine. The real X name is the font name as seen by X (Run "xfontsel").
 317 The optional "masking" section allows you to utilize the fake windows name you
 318 define. If it is not used, then wine will just try to extract the fake windows
 319 name itself and not use the value you enter.
 320
 321 Here is an example of an alias without masking. The font will show up in windows
 322 apps as "Google". When defining an alias in a config file, forget about my
 323 comment text (The "<-- blah" stuff)
 324
 325 Alias0 = Foo,--google-      <-- Note the no spaces after the " = ". Important!
 326
 327 Here is an example with masking enabled. The font will show up as "Foo" in
 328 windows apps.
 329
 330 Alias1 = Foo,--google-,subst
 331
 332 For more info check out <dirs to wine>/documentation/fonts
 333
 334 2.9 THE [serialports], [parallelports], [spooler], AND [ports] SECTIONS
 335
 336 Even though it sounds like a lot of sections, these are all closely related.
 337 They all are for communications and parallel ports.
 338
 339 The [serialports] section tells wine what serial ports it is allowed to use.
 340
 341 ComX=/dev/cuaY
 342
 343 Replace X with the number of the COM port in Windows (1-8) and Y with the
 344 number of it in X (Usually the number of the port in Windows minus 1). ComX can
 345 actually equal any device (/dev/modem is acceptable). It is not always necessary
 346 to define any COM ports (An optional setting). Here is an example:
 347
 348 Com1=/dev/cua0
 349
 350 Use as many of these as you like in the section to define all of the COM ports
 351 you need.
 352
 353 The [parallelports] section sets up any parallel ports that will be allowed
 354 access under wine.
 355
 356 LptX=/dev/lpY
 357
 358 Seem farmiliar? Syntax is just like the COM port setting. Replace X with a value
 359 from 1-4 as it is in Windows and Y with a value from 0-3 (Y is usually the value
 360 in windows minus 1, just like for COM ports). You don't always need to define a
 361 parallel port (AKA, it's optional). As with the other section, LptX can equal
 362 any device (Maybe /dev/printer). Here is an example:
 363
 364 Lpt1=/dev/lp0
 365
 366 The [spooler] section will inform wine where to spool print jobs. Use this if
 367 you want to try printing. Wine docs claim that spooling is "rather primitive" at
 368 this time, so it won't work perfectly. IT IS OPTIONAL
 369 The only setting you use in this section works to map a port (LPT1, for example)
 370 to a file or a command. Here is an example, mapping LPT1 to the file "out.ps":
 371
 372 LPT1:=out.ps
 373
 374 The following command maps printing jobs to LPT1 to the command "lpr". Notice
 375 the |:
 376
 377 LPT1:=|lpr
 378
 379 The [ports] section is usually useful only for people who need direct port
 380 access for programs requiring dongles or scanners. IF YOU DON'T NEED IT, DON'T
 381 USE IT!
 382
 383 read=0x779,0x379,0x280-0x2a0
 384
 385 Gives direct read access to those IO's.
 386
 387 write=0x779,0x379,0x280-0x2a0
 388
 389 Gives direct write access to those IO's. It probably a good idea to keep the
 390 values of the "read" and "write" settings the same. This stuff will only work
 391 when you're root.
 392
 393 2.10 THE [spy], [Registry], [tweak.layout], and [programs] SECTIONS
 394
 395 [spy] is used to Include or exclude debug messages, and to output them to a
 396 file. The latter is rarely used. THESE ARE ALL OPTIONAL AND YOU PROBABLY DON'T
 397 NEED TO ADD OR REMOVE ANYTHING IN THIS SECTION TO YOUR CONFIG.
 398
 399 File=/blanco
 400
 401 Sets the logfile for wine. Set to CON to log to standard out. THIS IS RARELY
 402 USED
 403
 404 Exclude=WM_SIZE;WM_TIMER;
 405
 406 Excludes debug messages about WM_SIZE and WM_TIMER in the logfile.
 407
 408 Include=WM_SIZE;WM_TIMER;
 409
 410 Includes debug messages about WM_SIZE and WM_TIMER in the logfile.
 411
 412 [Registry] can be used to tell wine where your old windows registry files exist. This
 413 section is completely optional and useless to people using wine without an existing
 414 windows installation.
 415
 416 UserFileName=/dirs/to/user.reg
 417
 418 The location of your old user.reg file.
 419
 420 LocalMachineFileName=/dirs/to/system.reg
 421
 422 The location of your old system.reg file.
 423
 424 [tweak.layout] is devoted to wine's look. There is only one setting for it.
 425
 426 WineLook=win31|win95|win98
 427
 428 Will change the look of wine from Windows 3.1 to Windows 95. "win98" behaves
 429 just like "win95" most of the time.
 430
 431 [programs] can be used to say what programs run under special conditions.
 432
 433 Default=/program/to/execute.exe
 434
 435 Sets the program to be run if wine is started without specifying a program.
 436
 437 Startup=/program/to/execute.exe
 438
 439 Sets the program to automatically be run at startup every time.
 440
 441 3. WHERE DO I PUT IT?
 442
 443 The wine config file can go in two places.
 444
 445         /usr/local/etc/wine.conf <--- A systemwide config file, used for anyone
 446         who doesn't have their own.
 447         $HOME/.winerc <--- Your own config file, that only is used for your
 448         user.
 449
 450 So copy the file you made to be the wine.conf to /usr/local/etc/wine.conf or
 451 $HOME/.winerc for wine to recognize it.
 452
 453 4. WHAT IF IT DOESN'T WORK?
 454
 455 There is always a chance that things will go wrong. If the unthinkable happens,
 456 try the newsgroup, comp.emulators.ms-windows.wine
 457 Make sure that you have looked over this document thoroughly, and have also
 458 read:
 459 README
 460 documentation/bugreports
 461 http://www.westfalen.de/witch/wine-HOWTO.txt (Optional but recommended)
 462 If indeed it looks like you've done your research, be prepared for helpful
 463 suggestions. If you haven't, brace yourself for heaving flaming.
 464