Moved system metrics definitions to winuser.h.
[wine] / 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