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