Removed useless #ifdef WINELIB.
[wine/gsoc_dplay.git] / documentation / configuring.sgml
blob72d9e642b3f44b4fdb1a75c77d1feea03c2cee67
1 <chapter id="config-wine-main">
2 <title>Configuring Wine</title>
3 <para>
4 Now that you hopefully managed to successfully install
5 the Wine program files,
6 this chapter will tell you how to configure the Wine environment
7 properly to run your Windows programs.
8 </para>
9 <para>
10 First, we'll give you an overview about which kinds of
11 configuration and program execution aspects a fully configured
12 Windows environment has to fulfill in order to ensure that many
13 Windows programs run successfully without encountering any
14 misconfigured or missing items.
15 Next, we'll show you which easy helper programs exist
16 to enable even novice users to complete the Wine environment
17 configuration in a fast and easy way.
18 The next section will explain the purpose of the Wine configuration file,
19 and we'll list all of its settings.
20 After that, the next section will detail the most important and
21 unfortunately most difficult configuration part:
22 how to configure the file system and DOS drive environment that
23 Windows programs need.
24 In the last step we'll tell you how to establish a working Windows
25 registry base.
26 Finally, the remaining parts of this chapter contain descriptions
27 of specific Wine configuration items that might also be
28 of interest to you.
29 </para>
31 <sect1 id="config-requirements-windows" xreflabel="--Installing Section--">
32 <title>What are the requirements of a fully working Windows environment?</title>
34 <para>
35 A Windows installation is a very complex structure. It consists of
36 many different parts with very different functionality.
37 We'll try to outline the most important aspects of it.
38 </para>
40 <itemizedlist>
41 <listitem>
42 <para>
43 Registry. Many keys are supposed to exist and contain
44 meaningful data, even in a newly-installed Windows.
45 </para>
46 </listitem>
47 <listitem>
48 <para>
49 Directory structure. Applications expect to find and/or
50 install things in specific predetermined locations. Most
51 of these directories are expected to exist. But unlike
52 Unix directory structures, most of these locations are
53 not hardcoded, and can be queried via the Windows API
54 and the registry. This places additional requirements on
55 a Wine installation.
56 </para>
57 </listitem>
58 <listitem>
59 <para>
60 System DLLs. In Windows, these usually reside in the
61 <filename>system</filename> (or
62 <filename>system32</filename>) directory. Some Windows
63 programs check for their existence in these
64 directories before attempting to load them. While Wine
65 is able to load its own internal DLLs
66 (<filename>.so</filename> files) when the program
67 asks for a DLL, Wine does not simulate the presence of
68 non-existent files.
69 </para>
70 </listitem>
71 </itemizedlist>
73 <para>
74 While the users are of course free to set up everything
75 themselves, the Wine team will make the automated Wine source
76 installation script, <filename>tools/wineinstall</filename>,
77 do everything we find necessary to do; running the
78 conventional <userinput>configure && make depend && make && make
79 install</userinput> cycle is thus not recommended, unless
80 you know what you're doing. At the moment,
81 <filename>tools/wineinstall</filename> is able to create a
82 configuration file, install the registry, and create the
83 directory structure itself.
84 </para>
86 </sect1>
88 <sect1 id="config-helper-programs">
89 <title>Easy configuration helper programs</title>
91 <para>
92 Managing the Wine configuration file settings can be a
93 difficult task, sometimes too difficult for some people.
94 That's why there are some helper applications for easily setting up an
95 initial wine configuration file with useful default settings.
96 </para>
98 <sect2 id="config-helper-winesetuptk">
99 <title>WineSetupTk</title>
100 <para>
101 WineSetupTk is a graphical Wine configuration tool with
102 incredibly easy handling of Wine configuration issues, to be
103 used for configuring the Wine environment after having
104 installed the Wine files.
105 It has been written by CodeWeavers in 2000 as part of a host
106 of other efforts to make Wine more desktop oriented.
107 </para>
108 <para>
109 If you're using Debian, simply install the winesetuptk
110 package (as root):
111 </para>
112 <screen>
113 <prompt># </prompt><userinput>apt-get install winesetuptk</userinput>
114 </screen>
115 <para>
116 If you're using another distribution, search for the package on
117 the net.
118 </para>
119 </sect2>
121 <sect2 id="config-helper-wineinstall">
122 <title>wineinstall</title>
123 <para>
124 <command>wineinstall</command> is a small configuration tool
125 residing as <filename>tools/wineinstall</filename> in a Wine
126 source code tree. It has been written to allow for an easy
127 and complete compilation/installation of Wine source code for
128 people who don't bother with reading heaps of very valuable
129 and informative documentation ;-)
130 </para>
131 <para>
132 Once you have successfully extracted the Wine source code
133 tree, change to the main directory of it and then run (as
134 user):
135 </para>
136 <screen>
137 <prompt>$ </prompt><userinput>./tools/wineinstall</userinput>
138 </screen>
139 <para>
140 Doing so will compile Wine, install Wine and configure the
141 Wine environment (either by providing access to a Windows
142 partition or by creating a properly configured no-windows
143 directory environment).
144 </para>
145 </sect2>
147 <sect2 id="config-helper-winecfg">
148 <title>winecfg</title>
149 <para>
150 <command>winecfg</command> is a small graphical configuration tool
151 residing as <filename>programs/winecfg</filename> in a Wine
152 source code tree. It is a Winelib app making use of standard
153 Win32 GUI controls to easily customize entries in a Wine
154 configuration file.
155 </para>
156 </sect2>
157 </sect1>
159 <sect1 id="config-verify">
160 <title>Verification of correct configuration</title>
162 <para>
163 After you finished configuring Wine, you may run a Perl
164 script called <command>winecheck</command>, to be found
165 in Wine's tools/ directory. It tries to check your
166 configuration's correctness by checking for some popular
167 problems.
169 The latest version can always be found at
170 <ulink url="http://home.arcor.de/andi.mohr/download/winecheck">http://home.arcor.de/andi.mohr/download/winecheck</ulink>.
172 To run it, run in a <glossterm>terminal</glossterm> in the Wine source tree directory:
173 </para>
174 <screen>
175 <prompt>$ </><userinput>cd tools</>
176 <prompt>$ </><userinput>perl ./winecheck</>
177 </screen>
178 <para>
179 The winecheck output will be a percentage score indicating Wine
180 configuration correctness.
181 Note that winecheck is only alpha, so it's not very complete or
182 100% accurate.
183 </para>
185 <para>
186 If this yields a "good" percentage score, then you can consider
187 your Wine installation to be finished successfully:
188 Congratulations!
189 Otherwise (or if there are still some configuration problems
190 that <command>winecheck</command> doesn't catch properly), please check out the
191 configuration documentation below to find out more about some
192 parts, or proceed to the <link linkend="bugs">Troubleshooting
193 chapter</link>.
194 </para>
195 </sect1>
197 <sect1 id="config-file">
198 <title>The Wine Configuration File</title>
199 <para>
200 This section is meant to contain both an easy step-by-step introduction
201 to the Wine configuration file (for new Wine users)
202 and a complete reference to all Wine configuration file settings (for
203 advanced users).
204 </para>
206 <sect2>
207 <title>Configuration File Introduction</title>
208 <para>
209 The Wine configuration file is the central file to store
210 configuration settings for Wine.
211 This file (which is called <filename>config</filename>)
212 can be found in the sub directory <filename>.wine/</filename>
213 of your user's home directory
214 (directory <filename>/home/user/</filename>). In other words, the Wine
215 configuration file is <filename>~/.wine/config</filename>.
216 Note that since the Wine configuration file is a part of the
217 Wine registry file system, this file also
218 <emphasis>requires</emphasis> a correct "WINE REGISTRY
219 Version 2" header line to be recognized properly, just like
220 all other Wine registry text files (just in case you decided
221 to write your own registry file from scratch and wonder why
222 Wine keeps rejecting it).
223 </para>
224 <para>
225 The settings available in the configuration file include:
226 <itemizedlist>
227 <listitem>
228 <para>
229 Drives and information about them
230 </para>
231 </listitem>
232 <listitem>
233 <para>
234 Directory settings
235 </para>
236 </listitem>
237 <listitem>
238 <para>
239 Port settings
240 </para>
241 </listitem>
242 <listitem>
243 <para>
244 The Wine look and feel
245 </para>
246 </listitem>
247 <listitem>
248 <para>
249 Wine's DLL usage
250 </para>
251 </listitem>
252 <listitem>
253 <para>
254 Wine's multimedia drivers and DLL configuration
255 </para>
256 </listitem>
257 </itemizedlist>
258 </para>
259 </sect2>
261 <sect2>
262 <title>Creating Or Modifying The Configuration File</title>
263 <para>
264 If you just installed Wine for the first time and want to
265 finish Wine installation by configuring it now, then you could
266 use our sample configuration file <filename>config</filename>
267 (which can be found in the directory
268 <filename>documentation/samples/</filename> of the Wine source
269 code directory) as a base for adapting the Wine configuration
270 file to the settings you want.
271 First, I should mention that you should not forget to make
272 sure that any previous configuration file at
273 <filename>~/.wine/config</filename> has been safely moved out
274 of the way instead of simply overwriting it when you will now
275 copy over the sample configuration file.
276 </para>
277 <para>
278 If you don't have a pre-existing configuration file and thus
279 need to copy over our sample configuration file to the
280 standard Wine configuration file location, do in a
281 <glossterm>terminal</glossterm>:
282 <screen>
283 <prompt>$ </><userinput>mkdir ~/.wine/</>
284 <prompt>$ </><userinput>cp <replaceable>dir_to_wine_source_code</replaceable>/documentation/samples/config ~/.wine/config</>
285 </screen>
286 Otherwise, simply use the already existing configuration file
287 at <filename>~/.wine/config</filename>.
288 </para>
289 <para>
290 Now you can start adapting the configuration file's settings with an
291 <glossterm>editor</glossterm> according to the documentation
292 below.
293 Note that you should <emphasis>only</emphasis> change
294 configuration file settings if wineserver is not running (in
295 other words: if your user doesn't have a Wine session running),
296 otherwise Wine won't use them - and even worse, wineserver will
297 overwrite them with the old settings once wineserver quits!!
298 </para>
299 </sect2>
301 <sect2 id="config-file-how">
302 <title>What Does It Contain?</title>
304 <para>
305 Let's start by giving an overview of which sections a
306 configuration file may contain, and whether the inclusion of
307 the respective section is <emphasis>needed</emphasis> or only <emphasis>recommended</emphasis> ("recmd").
308 </para>
310 <informaltable frame="all">
311 <tgroup cols="3">
312 <thead>
313 <row>
314 <entry>Section Name</entry>
315 <entry>Needed?</entry>
316 <entry>What it Does</entry>
317 </row>
318 </thead>
319 <tbody>
320 <row>
321 <entry>[Drive x]</entry>
322 <entry>yes</entry>
323 <entry>Sets up drive mappings to be used by Wine</entry>
324 </row>
325 <row>
326 <entry>[wine]</entry>
327 <entry>yes</entry>
328 <entry>General settings for Wine</entry>
329 </row>
330 <row>
331 <entry>[DllDefaults]</entry>
332 <entry>recmd</entry>
333 <entry>Defaults for loading DLL's</entry>
334 </row>
335 <row>
336 <entry>[DllPairs]</entry>
337 <entry>recmd</entry>
338 <entry>Sanity checkers for DLL's</entry>
339 </row>
340 <row>
341 <entry>[DllOverrides]</entry>
342 <entry>recmd</entry>
343 <entry>Overrides defaults for DLL loading</entry>
344 </row>
345 <row>
346 <entry>[x11drv]</entry>
347 <entry>recmd</entry>
348 <entry>Graphics driver settings</entry>
349 </row>
350 <row>
351 <entry>[fonts]</entry>
352 <entry>yes</entry>
353 <entry>Font appearance and recognition</entry>
354 </row>
355 <row>
356 <entry>[serialports]</entry>
357 <entry>no</entry>
358 <entry>COM ports seen by Wine</entry>
359 </row>
360 <row>
361 <entry>[parallelports]</entry>
362 <entry>no</entry>
363 <entry>LPT ports seen by Wine</entry>
364 </row>
365 <row>
366 <entry>[ppdev]</entry>
367 <entry>no</entry>
368 <entry>Parallelport emulation</entry>
369 </row>
370 <row>
371 <entry>[spooler]</entry>
372 <entry>no</entry>
373 <entry>Print spooling</entry>
374 </row>
375 <row>
376 <entry>[ports]</entry>
377 <entry>no</entry>
378 <entry>Direct port access</entry>
379 </row>
380 <row>
381 <entry>[Debug]</entry>
382 <entry>no</entry>
383 <entry>What to do with certain debug messages</entry>
384 </row>
385 <row>
386 <entry>[Registry]</entry>
387 <entry>no</entry>
388 <entry>Specifies locations of windows registry files</entry>
389 </row>
390 <row>
391 <entry>[tweak.layout]</entry>
392 <entry>recmd</entry>
393 <entry>Appearance of Wine</entry>
394 </row>
395 <row>
396 <entry>[programs]</entry>
397 <entry>no</entry>
398 <entry>Programs to be run automatically</entry>
399 </row>
400 <row>
401 <entry>[Console]</entry>
402 <entry>no</entry>
403 <entry>Console settings</entry>
404 </row>
405 <row>
406 <entry>[Clipboard]</entry>
407 <entry>no</entry>
408 <entry>Interaction for Wine and X11 clipboard</entry>
409 </row>
410 <row>
411 <entry>[afmdirs]</entry>
412 <entry>no</entry>
413 <entry>Postscript driver settings</entry>
414 </row>
415 <row>
416 <entry>[WinMM]</entry>
417 <entry>yes</entry>
418 <entry>Multimedia settings</entry>
419 </row>
420 <row>
421 <entry>[AppDefaults]</entry>
422 <entry>no</entry>
423 <entry>Overwrite the settings of previous sections for special programs</entry>
424 </row>
425 </tbody>
426 </tgroup>
427 </informaltable>
429 <para>
430 Now let's explain the configuration file sections in a
431 detailed way.
432 </para>
434 <sect3>
435 <title>The [Drive x] Sections</title>
436 <para>
437 For a detailed description of these configuration file
438 sections which are used to set up DOS drive mappings to Unix
439 directory space, please look at the <link
440 linkend="config-drive-sections">Wine file system layer
441 configuration section</link>.
442 </para>
443 </sect3>
445 <sect3 id="config-wine">
446 <title>The [wine] Section </title>
447 <para>
448 The [wine] section of the configuration file contains all kinds
449 of general settings for Wine.
450 </para>
451 <para>
452 <programlisting>
453 "Windows" = "c:\\windows"
454 "System" = "c:\\windows\\system"
455 "Temp" = "c:\\temp"
456 "Path" = "c:\\windows;c:\\windows\\system;c:\\blanco"
457 "ShowDirSymlinks" = "1"
458 </programlisting>
459 For a detailed description of drive layer configuration and
460 the meaning of these parameters, please look at the <link
461 linkend="config-drive-main">Wine file system layer
462 configuration section</link>.
463 </para>
464 <para>
465 <programlisting>"GraphicsDriver" = "x11drv|ttydrv"</programlisting>
466 Sets the graphics driver to use for Wine output.
467 x11drv is for X11 output, ttydrv is for text console output.
468 WARNING: if you use ttydrv here, then you won't be able to run
469 a lot of Windows GUI programs (ttydrv is still pretty "broken"
470 at running graphical apps). Thus this option is mainly interesting
471 for e.g. embedded use of Wine in web server scripts.
472 Note that ttydrv is still very lacking, so if it doesn't work,
473 resort to using "xvfb", a virtual X11 server.
474 Another way to run Wine without display would be to run X11
475 via Xvnc, then connect to that VNC display using xvncviewer
476 (that way you're still able to connect to your app and
477 configure it if need be).
478 </para>
479 <para>
480 <programlisting>"Printer" = "off|on"</programlisting> Tells wine
481 whether to allow printing via printer drivers to work.
482 This option isn't needed for our built-in psdrv printer driver
483 at all.
484 Using these things are pretty alpha, so you might want to
485 watch out. Some people might find it useful, however. If
486 you're not planning to work on printing via windows printer
487 drivers, don't even add this to your wine configuration file
488 (It probably isn't already in it).
489 Check out the [spooler] and [parallelports] sections too.
490 </para>
491 <para>
492 <programlisting>"ShellLinker" = "wineshelllink"</programlisting>
493 This setting specifies the shell linker script to use for setting
494 up Windows icons in e.g. KDE or Gnome that are given by programs
495 making use of appropriate shell32.dll functionality to create
496 icons on the desktop/start menu during installation.
497 </para>
498 <para>
499 <programlisting>"SymbolTableFile" = "wine.sym"</programlisting>
500 Sets up the symbol table file for the wine debugger. You
501 probably don't need to fiddle with this. May be useful if
502 your wine is stripped.
503 </para>
504 </sect3>
506 <sect3 id="config-dlldefaults">
507 <title>The [DllDefaults] Section</title>
508 <para>
509 These settings provide wine's default handling of DLL loading.
510 </para>
511 <para>
512 <programlisting>"DefaultLoadOrder" =" native, builtin"</programlisting>
513 This setting is a comma-delimited list of the order in
514 which to attempt loading DLLs. If the first option fails,
515 it will try the second, and so on. The order specified
516 above is probably the best in most conditions.
517 </para>
518 </sect3>
520 <sect3>
521 <title>The [DllPairs] Section</title>
522 <para>
523 At one time, there was a section called [DllPairs] in the
524 default configuration file, but this has been obsoleted
525 because the pairing information has now been embedded into
526 Wine itself. (The purpose of this section was merely to be
527 able to issue warnings if the user attempted to pair
528 codependent 16-bit/32-bit DLLs of different types.) If you
529 still have this in your <filename>~/.wine/.config</filename> or
530 <filename>wine.conf</filename>, you may safely delete it.
531 </para>
532 </sect3>
534 <sect3 id="config-dlloverrides">
535 <title>The [DllOverrides] Section</title>
536 <para>
537 The format for this section is the same for each line:
538 <programlisting>&lt;DLL>{,&lt;DLL>,&lt;DLL>...} = &lt;FORM>{,&lt;FORM>,&lt;FORM>...}</programlisting>
539 For example, to load built-in KERNEL pair (case doesn't
540 matter here):
541 <programlisting>"kernel,kernel32" = "builtin"</programlisting>
542 To load the native COMMDLG pair, but if that doesn't work
543 try built-in:
544 <programlisting>"commdlg,comdlg32" = "native, builtin"</programlisting>
545 To load the native COMCTL32:
546 <programlisting>"comctl32" = "native"</programlisting>
547 Here is a good generic setup (As it is defined in config
548 that was included with your wine package):
549 <programlisting>
550 [DllOverrides]
551 "rpcrt4" = "builtin, native"
552 "oleaut32" = "builtin, native"
553 "ole32" = "builtin, native"
554 "commdlg" = "builtin, native"
555 "comdlg32" = "builtin, native"
556 "ver" = "builtin, native"
557 "version" = "builtin, native"
558 "shell" = "builtin, native"
559 "shell32" = "builtin, native"
560 "shfolder" = "builtin, native"
561 "shlwapi" = "builtin, native"
562 "shdocvw" = "builtin, native"
563 "lzexpand" = "builtin, native"
564 "lz32" = "builtin, native"
565 "comctl32" = "builtin, native"
566 "commctrl" = "builtin, native"
567 "advapi32" = "builtin, native"
568 "crtdll" = "builtin, native"
569 "mpr" = "builtin, native"
570 "winspool.drv" = "builtin, native"
571 "ddraw" = "builtin, native"
572 "dinput" = "builtin, native"
573 "dsound" = "builtin, native"
574 "opengl32" = "builtin, native"
575 "msvcrt" = "native, builtin"
576 "msvideo" = "builtin, native"
577 "msvfw32" = "builtin, native"
578 "mcicda.drv" = "builtin, native"
579 "mciseq.drv" = "builtin, native"
580 "mciwave.drv" = "builtin, native"
581 "mciavi.drv" = "native, builtin"
582 "mcianim.drv" = "native, builtin"
583 "msacm.drv" = "builtin, native"
584 "msacm" = "builtin, native"
585 "msacm32" = "builtin, native"
586 "midimap.drv" = "builtin, native"
587 ; you can specify programs too
588 "notepad.exe" = "native, builtin"
589 ; default for all other DLLs
590 "*" = "native, builtin"
591 </programlisting>
592 </para>
593 <note>
594 <para>
595 If loading of the libraries that are listed first fails,
596 wine will just go on by using the second or third option.
597 </para>
598 </note>
599 </sect3>
601 <sect3 id="config-fonts">
602 <title>The [fonts] Section</title>
603 <para>
604 This section sets up wine's font handling.
605 </para>
606 <para>
607 <programlisting>"Resolution" = "96"</programlisting>
608 Since the way X handles fonts is different from the way
609 Windows does, wine uses a special mechanism to deal with
610 them. It must scale them using the number defined in the
611 "Resolution" setting. 60-120 are reasonable values, 96 is
612 a nice in the middle one. If you have the real windows
613 fonts available , this parameter will not be as
614 important. Of course, it's always good to get your X fonts
615 working acceptably in wine.
616 </para>
617 <para>
618 <programlisting>"Default" = "-adobe-times-"</programlisting>
619 The default font wine uses. Fool around with it if you'd like.
620 </para>
621 <para>
622 OPTIONAL:
623 </para>
624 <para>
625 The <literal>Alias</literal> setting allows you to map an X font to a font
626 used in wine. This is good for apps that need a special font you don't have,
627 but a good replacement exists. The syntax is like so:
628 <programlisting>"AliasX" = "[Fake windows name],[Real X name]"&lt;,optional "masking" section></programlisting>
629 Pretty straightforward. Replace "AliasX" with "Alias0",
630 then "Alias1" and so on. The fake windows name is the name
631 that the font will be under a windows app in wine. The
632 real X name is the font name as seen by X (Run
633 "xfontsel"). The optional "masking" section allows you to
634 utilize the fake windows name you define. If it is not
635 used, then wine will just try to extract the fake windows
636 name itself and not use the value you enter.
637 </para>
638 <para>
639 Here is an example of an alias without masking. The font will show up in windows
640 apps as "Google".
641 <programlisting>"Alias0" = "Foo,--google-"</programlisting>
642 Here is an example with masking enabled. The font will show up as "Foo" in
643 windows apps.
644 <programlisting>"Alias1" = "Foo,--google-,subst"</programlisting>
645 For more information check out the <link linkend="config-fonts-main">Fonts</link>
646 chapter.
647 </para>
648 </sect3>
650 <sect3 id="config-io">
651 <title>The [serialports], [parallelports], [spooler], and [ports] Sections</title>
652 <para>
653 Even though it sounds like a lot of sections, these are
654 all closely related. They are all for communications and
655 parallel ports.
656 </para>
657 <para>
658 The [serialports] section tells wine what serial ports it
659 is allowed to use.
660 <programlisting>"ComX" = "/dev/ttySY"</programlisting>
661 Replace <literal>X</literal> with the number of the COM
662 port in Windows (1-8) and <literal>Y</literal> with the
663 number of it in <literal>X</literal> (Usually the number
664 of the port in Windows minus 1). <literal>ComX</literal>
665 can actually equal any device
666 (<medialabel>/dev/modem</medialabel> is acceptable). It is
667 not always necessary to define any COM ports (An optional
668 setting). Here is an example:
669 <programlisting>"Com1" = "/dev/ttyS0"</programlisting>
670 Use as many of these as you like in the section to define
671 all of the COM ports you need.
672 </para>
673 <para>
674 The [parallelports] section sets up any parallel ports
675 that will be allowed access under wine.
676 <programlisting>"LptX" = "/dev/lpY"</programlisting>
677 Sounds familiar? Syntax is just like the COM port setting.
678 Replace <literal>X</literal> with a value from 1-4 as it
679 is in Windows and <literal>Y</literal> with a value from
680 0-3 (<literal>Y</literal> is usually the value in windows
681 minus 1, just like for COM ports). You don't always need
682 to define a parallel port (AKA, it's optional). As with
683 the other section, LptX can equal any device (Maybe
684 <medialabel>/dev/printer</medialabel>). Here is an
685 example: <programlisting>"Lpt1" = "/dev/lp0"</programlisting>
686 The [spooler] section will inform wine where to spool
687 print jobs. Use this if you want to try printing. Wine
688 docs claim that spooling is "rather primitive" at this
689 time, so it won't work perfectly. <emphasis>It is optional.</emphasis> The only
690 setting you use in this section works to map a port (LPT1,
691 for example) to a file or a command. Here is an example,
692 mapping LPT1 to the file <filename>out.ps</filename>:
693 <programlisting>"LPT1:" = "out.ps"</programlisting>
694 The following command maps printing jobs to LPT1 to the
695 command <command>lpr</command>. Notice the |:
696 <programlisting>"LPT1:" = "|lpr"</programlisting>
697 The [ports] section is usually useful only for people who
698 need direct port access for programs requiring dongles or
699 scanners. <emphasis>If you don't need it, don't use
700 it!</emphasis>
701 </para>
702 <para>
703 <programlisting>"read" = "0x779,0x379,0x280-0x2a0"</programlisting>
704 Gives direct read access to those IO's.
705 </para>
706 <para>
707 <programlisting>"write" = "0x779,0x379,0x280-0x2a0"</programlisting>
708 Gives direct write access to those IO's. It's probably a
709 good idea to keep the values of the
710 <literal>read</literal> and <literal>write</literal>
711 settings the same. This stuff will only work when you're
712 root.
713 </para>
714 </sect3>
716 <sect3 id="config-debug-etc">
717 <title>The [Debug], [Registry], [tweak.layout], and [programs] Sections</title>
718 <para>
719 [Debug] is used to include or exclude debug messages, and to
720 output them to a file. The latter is rarely used. <emphasis>These
721 are all optional and you probably don't need to add or
722 remove anything in this section to your config.</emphasis> (In extreme
723 cases you may want to use these options to manage the amount
724 of information generated by the <parameter>--debugmsg +relay
725 </parameter> option.)
726 </para>
727 <para>
728 <programlisting>"File" = "/blanco"</programlisting>
729 Sets the logfile for wine. Set to CON to log to standard out.
730 <emphasis>This is rarely used.</emphasis>
731 </para>
732 <para>
733 <programlisting>"SpyExclude" = "WM_SIZE;WM_TIMER;"</programlisting>
734 Excludes debug messages about <constant>WM_SIZE</constant>
735 and <constant>WM_TIMER</constant> in the logfile.
736 </para>
737 <para>
738 <programlisting>"SpyInclude" = "WM_SIZE;WM_TIMER;"</programlisting>
739 Includes debug messages about <constant>WM_SIZE</constant>
740 and <constant>WM_TIMER</constant> in the logfile.
741 </para>
742 <para>
743 <programlisting>"RelayInclude" = "user32.CreateWindowA;comctl32.*"</programlisting>
744 Include only the listed functions in a
745 <parameter>--debugmsg +relay</parameter> trace. This entry is
746 ignored if there is a <parameter>RelayExclude</parameter> entry.
747 </para>
748 <para>
749 <programlisting>"RelayExclude" = "RtlEnterCriticalSection;RtlLeaveCriticalSection"</programlisting>
750 Exclude the listed functions in a
751 <parameter>--debugmsg +relay</parameter> trace. This entry
752 overrides any settings in a <parameter>RelayInclude</parameter>
753 entry. If neither entry is present then the trace includes
754 everything.
755 </para>
756 <para>
757 In both entries the functions may be specified either as a
758 function name or as a module and function. In this latter
759 case specify an asterisk for the function name to include/exclude
760 all functions in the module.
761 </para>
762 <para>
763 [Registry] can be used to tell wine where your old windows
764 registry files exist. This section is completely optional
765 and useless to people using wine without an existing
766 windows installation.
767 </para>
768 <para>
769 <programlisting>"UserFileName" = "/dirs/to/user.reg"</programlisting>
770 The location of your old <filename>user.reg</filename> file.
771 </para>
772 <para>
773 [tweak.layout] is devoted to wine's look. There is only
774 one setting for it.
775 </para>
776 <para>
777 <programlisting>"WineLook" = "win31|win95|win98"</programlisting>
778 Will change the look of wine from Windows 3.1 to Windows 95.
779 The <literal>win98</literal> setting behaves
780 just like <literal>win95</literal> most of the time.
781 </para>
782 <para>
783 [programs] can be used to say what programs run under
784 special conditions.
785 </para>
786 <para>
787 <programlisting>"Default" = "/program/to/execute.exe"</programlisting>
788 Sets the program to be run if wine is started without specifying a program.
789 </para>
790 <para>
791 <programlisting>"Startup" = "/program/to/execute.exe"</programlisting>
792 Sets the program to automatically be run at startup every time.
793 </para>
794 </sect3>
796 <sect3 id="config-winmm">
797 <title>The [WinMM] Section</title>
798 <para>
799 [WinMM] is used to define which multimedia drivers have to be loaded. Since
800 those drivers may depend on the multimedia interfaces available on your system
801 (OSS, ALSA... to name a few), it's needed to be able to configure which driver
802 has to be loaded.
803 </para>
805 <para>
806 The content of the section looks like:
807 <programlisting>
808 [WinMM]
809 "Drivers" = "wineoss.drv"
810 "WaveMapper" = "msacm.drv"
811 "MidiMapper" = "midimap.drv"
812 </programlisting>
813 All the keys must be defined:
814 <itemizedlist>
815 <listitem>
816 <para>
817 The "Drivers" key is a ';' separated list of modules name, each of
818 them containing a low level driver. All those drivers will be loaded
819 when MMSYSTEM/WINMM is started and will provide their inner features.
820 </para>
821 </listitem>
822 <listitem>
823 <para>
824 The "WaveMapper" represents the name of the module containing the Wave
825 Mapper driver. Only one wave mapper can be defined in the system.
826 </para>
827 </listitem>
828 <listitem>
829 <para>
830 The "MidiMapper" represents the name of the module containing the MIDI
831 Mapper driver. Only one MIDI mapper can be defined in the system.
832 </para>
833 </listitem>
834 </itemizedlist>
835 </para>
836 </sect3>
838 <sect3 id="config-network">
839 <title>The [Network] Section</title>
840 <para>
841 [Network] contains settings related to
842 networking. Currently there is only one value that can be set.
843 </para>
844 <variablelist>
845 <varlistentry>
846 <term>UseDnsComputerName</term>
847 <listitem>
848 <para>
849 A boolean setting (default: <literal>Y</literal>)
850 that affects the way Wine sets the computer name. The computer
851 name in the Windows world is the so-called <emphasis>NetBIOS name</emphasis>.
852 It is contained in the <varname>ComputerName</varname> in the registry entry
853 <varname>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ComputerName\ComputerName</varname>.
854 </para>
855 <para>
856 If this option is set to "Y" or missing, Wine will set the
857 NetBIOS name to the Unix host name of your computer, if
858 necessary truncated to 31 characters. The Unix hostname is the output
859 of the shell command <command>hostname</command>, up to but not
860 including the first dot ('.'). Among other things, this means that
861 Windows programs running under Wine cannot change the NetBIOS computer name.
862 </para>
863 <para>
864 If this option is set to "N", Wine will use the registry value above
865 to set the NetBIOS name. Only if the registry entry doesn't exist (usually
866 only during the first wine startup) it will use the Unix hostname as
867 usual. Windows programs can change the NetBIOS name. The change
868 will be effective after a "reboot", i.e. after restarting Wine.
869 </para>
870 </listitem>
871 </varlistentry>
872 </variablelist>
873 </sect3>
875 <sect3 id="config-appdefaults">
876 <title>The [AppDefaults] Section</title>
877 <para>
878 The section is used to overwrite certain settings of this file for a
879 special program with different settings.
880 [AppDefaults] is not the real name of the section. The real name
881 consists of the leading word AppDefaults followed by the name
882 of the executable the section is valid for.
883 The end of the section name is the name of the
884 corresponding "standard" section of the configuration file
885 that should have some of its settings overwritten with the
886 program specific settings you define.
887 The three parts of the section name are separated by two backslashes.
888 </para>
889 <para>
890 Currently wine supports overriding selected settings within
891 the sections [DllOverrides], [x11drv], [version] and [dsound] only.
892 </para>
893 <para>
894 Here is an example that overrides the normal settings for a
895 program:
896 <programlisting>
897 ;; default settings
898 [x11drv]
899 "Managed" = "Y"
900 "Desktop" = "N"
902 ;; run install in desktop mode
903 [AppDefaults\\install.exe\\x11drv]
904 "Managed" = "N"
905 "Desktop" = "800x600"
906 </programlisting>
907 </para>
908 </sect3>
909 </sect2>
911 <sect2 id="config-trouble">
912 <title>What If It Doesn't Work?</title>
913 <para>
914 There is always a chance that things will go wrong. If the
915 unthinkable happens, report the problem to
916 <ulink url="http://bugs.winehq.org/">Wine Bugzilla</ulink>,
917 try the newsgroup
918 <systemitem>comp.emulators.ms-windows.wine</systemitem>,
919 or the IRC channel <systemitem>#WineHQ</systemitem> found on
920 irc.freenode.net, or connected servers.
921 Make sure that you have looked over this document thoroughly,
922 and have also read:
923 </para>
924 <itemizedlist>
925 <listitem>
926 <para>
927 <filename>README</filename>
928 </para>
929 </listitem>
930 <listitem>
931 <para>
932 <filename>http://www.winehq.org/trouble/</filename>
933 </para>
934 </listitem>
935 </itemizedlist>
936 <para>
937 If indeed it looks like you've done your research, be
938 prepared for helpful suggestions. If you haven't, brace
939 yourself for heaving flaming.
940 </para>
941 </sect2>
942 </sect1>
944 <sect1 id="config-drive-main">
945 <title>The Wine File System And Drive Layer</title>
946 <sect2>
947 <title>Extremely Important Prerequisites</title>
948 <para>
949 If you're planning to include access to a CD-ROM drive in your Wine
950 configuration on Linux, then <emphasis>make sure</emphasis> to add
951 the <quote>unhide</quote> mount option to the CD-ROM file system
952 entry in <filename>/etc/fstab</filename>, e.g.:
953 <programlisting>/dev/cdrom /cdrom iso9660 ro,noauto,users,unhide 0 0</programlisting>
954 Several Windows program setup CD-ROMs or other CD-ROMs chose
955 to do such braindamaged things as marking very important setup
956 helper files on the CD-ROM as <quote>hidden</quote>.
957 That's no problem on Windows, since the Windows CD-ROM driver by
958 default displays even files that are supposed to be
959 <quote>hidden</quote>. But on Linux, which chose to
960 <emphasis>hide</emphasis> <quote>hidden</quote> files on CD by
961 default, this is <emphasis>FATAL</emphasis>!
962 (the programs will simply abort with an <quote>installation file not found</quote> or similar error)
963 Thus you should never forget to add this setting.
964 </para>
965 </sect2>
967 <sect2>
968 <title>Short Introduction</title>
969 <para>
970 Wine emulates drives by placing their virtual drive roots to
971 user-configurable points in the Unix filesystem, so it's your
972 choice where <medialabel>C:</medialabel>'s root should be
973 (<filename>tools/wineinstall</filename> will even ask you). If
974 you choose, say, <filename>~/wine</filename> (or, in other
975 words, <filename>/home/user/wine</filename>, since "~"
976 indicates the home directory of a user), as the root of your
977 virtual drive <medialabel>C:</medialabel>, then you'd put this
978 into your Wine configuration file:
979 </para>
981 <programlisting>
982 [Drive C]
983 "Path" = "%HOME%/wine"
984 "Type" = "hd"
985 "Label" = "MS-DOS"
986 "Filesystem" = "win95"
987 </programlisting>
989 <para>
990 With this configuration, what windows apps think of as
991 "c:\windows\system" would map to
992 <filename>/home/user/wine/windows/system</filename> in the UNIX
993 filesystem. Note that you need to specify
994 <literal>"Filesystem" = "win95"</literal>,
995 <emphasis>not</emphasis>
996 <literal>"Filesystem" = "unix"</literal>, to make Wine simulate a
997 Windows compatible (case insensitive) filesystem, otherwise
998 most apps won't work.
999 </para>
1000 </sect2>
1002 <sect2 id="config-drive-dir">
1003 <title>Windows Directory Structure</title>
1004 <para>
1005 Here's the fundamental layout that Windows programs and
1006 installers expect and that we thus need to configure properly
1007 in Wine. Without it, they seldomly operate correctly. If you
1008 intend to use a no-windows environment (not using an existing
1009 Windows partition), then it is recommended to use either
1010 <command>WineSetupTk</command>'s or
1011 <command>wineinstall</command>'s capabilities to create an
1012 initial windows directory tree, since creating a directory
1013 structure manually is tiresome and error-prone.
1014 </para>
1016 <programlisting>
1017 C:\ Root directory of primary disk drive
1018 Windows\ Windows directory, containing .INI files,
1019 accessories, etc.
1020 System\ Win3.x/95/98/ME directory for common DLLs
1021 WinNT/2000 directory for common 16-bit DLLs
1022 System32\ WinNT/2000 directory for common 32-bit DLLs
1023 Start Menu\ Program launcher directory structure
1024 Programs\ Program launcher links (.LNK files) to programs
1025 Program Files\ Application binaries (.EXE and .DLL files)
1026 </programlisting>
1027 </sect2>
1029 <sect2 id="config-drive-sections">
1030 <title>The [Drive x] Sections</title>
1031 <para>
1032 These sections are supposed to make certain Unix
1033 directory locations accessible to Wine as a DOS/Windows drive
1034 (drive 'x:') and thus accessible to Windows programs
1035 under the drive name you specified.
1036 Every DOS/Windows program sort of expects at least a C:
1037 drive (and sometimes also an A: floppy drive), so your
1038 configuration file should at least contain the corresponding
1039 sections, [Drive C] and [Drive A].
1040 You need to decide on whether you want to use an existing Windows
1041 partition as the C drive or whether you want to create your own
1042 Wine drive C directory tree somewhere (take care about
1043 permissions!).
1044 Each drive section may specify up to 6 different settings
1045 as explained below.
1046 </para>
1047 <para>
1048 <programlisting>[Drive x]</programlisting>
1049 The above line begins the section for a drive whose letter is x
1050 (DOS notation: drive 'x:').
1051 You could e.g. create an equivalent to a drive 'C:'
1052 under DOS/Windows by using a [Drive C] section name.
1053 Note that the drive letter is case insensitive.
1054 </para>
1055 <para>
1056 <programlisting>"Path" = "/dir/to/path"</programlisting>
1057 This specifies the directory where the drive will begin.
1058 When Wine is browsing in drive x, it will be able
1059 to see the files that are in the directory
1060 <filename>/dir/to/path</filename> and below.
1061 (note that symlinks to directories won't get included!
1062 see "<link linkend="dirsymlinks">ShowDirSymlinks</link>"
1063 configuration setting)
1064 You can also make use of environment variables like $HOME here,
1065 an example for using a <filename>mywinedrive</filename>
1066 directory in your home dir would be
1067 <programlisting>"Path" = "%HOME%/mywinedrive"</programlisting>,
1068 but don't forget to put it as a DOS environment variable,
1069 ie surrounded by '%' signs rather than preceded by a '$'.
1070 Don't forget to leave off the trailing slash!
1071 </para>
1072 <para>
1073 <programlisting>"Type" = "hd|cdrom|network|floppy"</programlisting>
1074 Sets up the type of drive Wine will see it as. Type must
1075 equal one of the four <literal>floppy</literal>,
1076 <literal>hd</literal>, <literal>cdrom</literal>, or
1077 <literal>network</literal>. They are self-explanatory.
1078 (The |'s mean "Type = '&lt;one of the options&gt;'".)
1079 Usually, you choose "hd" for a drive ("hd" is default anyway).
1080 For a home directory entry, it makes sense to choose
1081 "network" sometimes, since some home directories are being
1082 exported over the network via NFS and thus can have slow response
1083 times.
1084 </para>
1085 <para>
1086 <programlisting>"Label" = "blah"</programlisting>
1087 Defines the drive label. Generally only needed
1088 for programs that look for a special CD-ROM.
1089 The label may be up to 11 characters.
1090 Note that the preferred way of managing labels and serial numbers
1091 of CD-ROMs and floppies is to give Wine raw device access for
1092 reading these on a per-CD case (see "Device" below) instead of
1093 hardcoding one specific "Label".
1094 </para>
1095 <para>
1096 <programlisting>"Serial" = "deadbeef"</programlisting>
1097 Tells Wine the serial number of the drive. A few programs with
1098 intense protection for pirating might need this, but otherwise
1099 it's not needed. Up to 8 characters and hexadecimal.
1100 Using a "Device" entry instead of hardcoding the "Serial" probably
1101 is a smarter choice.
1102 </para>
1103 <para>
1104 <programlisting>"Filesystem" = "win95|unix|msdos"</programlisting>
1105 Sets up the way Wine looks at files on the drive.
1106 This setting controls the file name lookup and mapping of
1107 Wine to existing file systems on your PC, it does
1108 <emphasis>not</emphasis> tell anything about the filesystem
1109 used itself.
1110 </para>
1112 <variablelist>
1113 <varlistentry>
1114 <term><literal>win95</literal></term>
1115 <listitem>
1116 <para>
1117 Case insensitive. Alike to Windows 9x/NT 4. This is
1118 the long filename filesystem you are probably used
1119 to working with. The filesystem behavior of choice for most
1120 programs to be run under wine. <emphasis>Probably the one
1121 you want!</emphasis>
1122 </para>
1123 </listitem>
1124 </varlistentry>
1125 <varlistentry>
1126 <term><literal>unix</literal></term>
1127 <listitem>
1128 <para>
1129 Case sensitive. This filesystem has almost no use
1130 (Windows apps expect case insensitive filenames),
1131 except maybe for Winelib applications.
1132 Try it if you dare, but win95 is a much better
1133 and always recommended choice.
1134 </para>
1135 </listitem>
1136 </varlistentry>
1137 <varlistentry>
1138 <term><literal>msdos</literal></term>
1139 <listitem>
1140 <para>
1141 Case insensitive filesystem. Alike to DOS and
1142 Windows 3.x. <literal>8.3</literal> is the maximum
1143 length of files (eightdot.123) - longer ones will be
1144 truncated.
1145 <note>
1146 <para>
1147 This is a <emphasis>very bad choice</emphasis> if
1148 you plan on running apps that use long filenames.
1149 win95 should work fine with apps that were designed
1150 to run under the msdos system. In other words, you
1151 might not want to use this.
1152 </para>
1153 </note>
1154 </para>
1155 </listitem>
1156 </varlistentry>
1157 </variablelist>
1159 <programlisting>"Device" = "/dev/xx"</programlisting>
1160 <para>
1161 Needed for raw device access and <link linkend="config-drive-cdrom-labels">label and serial number reading</link>.
1162 Use this <emphasis>only</emphasis> for floppy and cdrom devices. Using it on
1163 Extended2 or other Unix file systems can have dire results
1164 (when a windows app tries to do a lowlevel write,
1165 they do it in a FAT way -- FAT format is completely different from
1166 any Unix file system).
1167 Also, make sure that you have proper permissions to this device
1168 file.
1169 </para>
1170 <note>
1171 <para>
1172 This setting is not really important; almost all apps
1173 will have no problem if it remains unspecified. For
1174 CD-ROMs it's quite useful in order to get automatic label
1175 detection, though. If you are unsure about specifying
1176 device names, just leave out this setting for your
1177 drives.
1178 </para>
1179 </note>
1180 <para>
1181 Here are a few sample entries:
1182 <programlisting>
1183 Here is a setup for Drive C, a generic hard drive:
1184 [Drive C]
1185 "Path" = "/dosc"
1186 "Type" = "hd"
1187 "Label" = "Hard Drive"
1188 "Filesystem" = "win95"
1189 This is a setup for Drive E, a generic CD-ROM drive:
1190 [Drive E]
1191 "Path" = "/mnt/cdrom"
1192 "Type" = "cdrom"
1193 "Label" = "Total Annihilation"
1194 "Filesystem" = "win95"
1195 "Device" = "/dev/cdrom"
1196 And here is a setup for Drive A, a generic floppy drive:
1197 [Drive A]
1198 "Type" = "floppy"
1199 "Path" = "/mnt/floppy"
1200 "Label" = "Floppy Drive"
1201 "Serial" = "87654321"
1202 "Filesystem" = "win95"
1203 "Device" = "/dev/fd0"
1204 </programlisting>
1205 </para>
1206 </sect2>
1208 <sect2>
1209 <title>File system settings in the [wine] section</title>
1210 <para>
1211 <programlisting>"Windows" = "c:\\windows"</programlisting>
1212 This tells Wine and Windows programs where the
1213 <filename>Windows</filename> directory is. It is
1214 recommended to have this directory somewhere on your
1215 configured <medialabel>C</medialabel> drive, and it's also
1216 recommended to just call the directory "windows" (this is
1217 the default setup on Windows, and some stupid programs
1218 might rely on this). So in case you chose a "Windows"
1219 setting of "c:\\windows" and you chose to set up a drive C
1220 e.g. at <filename>/usr/local/wine_c</filename>, the
1221 corresponding directory would be
1222 <filename>/usr/local/wine_c/windows</filename>. Make one
1223 if you don't already have one. <emphasis>No trailing slash</emphasis> (<emphasis>not</emphasis>
1224 <filename>C:\\windows\</filename>)! Write access strongly
1225 recommended, as Windows programs always assume write access
1226 to the Windows directory!
1227 </para>
1228 <para>
1229 <programlisting>"System" = "c:\\windows\\system"</programlisting>
1230 This sets up where the windows system files are. The Windows
1231 system directory should reside below the directory used for the
1232 <literal>Windows</literal> setting.
1233 Thus when using the example above, the system directory would be
1234 <filename>/usr/local/wine_c/windows/system</filename>.
1235 Again, no trailing slash, and write access!
1236 </para>
1237 <para>
1238 <programlisting>"Temp" = "c:\\temp"</programlisting> This should
1239 be the directory you want your temp files stored in,
1240 /usr/local/wine_c/temp in our example.
1241 Again, no trailing slash, and <emphasis>write
1242 access</emphasis>!!
1243 </para>
1244 <para>
1245 <programlisting>"Path" = "c:\\windows;c:\\windows\\system;c:\\blanco"</programlisting>
1246 Behaves like the <envar>PATH</envar> setting on UNIX
1247 boxes. When wine is run like <userinput>wine
1248 sol.exe</userinput>, if <filename>sol.exe</filename>
1249 resides in a directory specified in the
1250 <literal>Path</literal> setting, wine will run it (Of
1251 course, if <filename>sol.exe</filename> resides in the
1252 current directory, wine will run that one). Make sure it
1253 always has your <filename>windows</filename> directory and
1254 system directory (For this setup, it must have
1255 <filename>"c:\\windows;c:\\windows\\system"</filename>).
1256 </para>
1257 <para id="dirsymlinks">
1258 <programlisting>"ShowDirSymlinks" = "1"</programlisting>
1259 Wine doesn't pass directory symlinks to Windows programs by
1260 default, as doing so may crash some programs that do
1261 recursive lookups of whole subdirectory trees
1262 whenever a directory symlink points back to itself or one of its
1263 parent directories.
1264 That's why we disallowed the use of directory symlinks
1265 and added this setting to reenable ("1") this functionality.
1266 If you <emphasis>really</emphasis> need Wine to take into
1267 account symlinked directories, then reenable it, but
1268 <emphasis>be prepared for crashes</emphasis> in certain
1269 Windows programs when using the above method! (in other words:
1270 enabling it is certainly not recommended)
1271 </para>
1272 </sect2>
1274 <sect2>
1275 <title>More detailed explanation about file system differences</title>
1276 <para>
1277 Windows uses a different (and inferior) way than Unix to describe the
1278 location of files in a computer. Thus Windows programs also expect
1279 to find this different way supported by the system.
1280 Since we intend to run Windows programs on
1281 a Unix system, we're in trouble, as we need to translate
1282 between these different file access techniques.
1283 </para>
1284 <para>
1285 Windows uses drive letters to describe drives or
1286 any other form of storage media and to access files on them.
1287 For example, common drive names are
1288 <filename>C:</filename> for the main Windows system partition
1289 on the first harddisk and <filename>A:</filename> for the
1290 first floppy drive.
1291 Also, Windows uses <filename>\</filename> (backslash) as the
1292 directory separator sign, whereas Unix uses
1293 <filename>/</filename> (slash).
1294 Thus, an example document on the first data partition in
1295 Windows might be accessed by the name of
1296 <filename>D:\mywork\mydocument.txt</filename>.
1297 </para>
1298 <para>
1299 So much for the Windows way of doing things.
1300 </para>
1301 <para>
1302 Well, the problem is, in Unix there is no such thing as
1303 <quote>drive letters</quote>. Instead, Unix chose to go the
1304 much better way of having one single uniform directory tree
1305 (starting with the root directory
1306 <filename>/</filename>), which has various storage devices
1307 such as e.g. harddisk partitions appended at various directory
1308 locations within the tree (an example would be
1309 <filename>/data1/mywork</filename>, which is the first data
1310 partition mounted/attached to a directory called data1 in the
1311 root directory <filename>/</filename>; mywork is a sub
1312 directory of the data partition file system that's mounted
1313 under <filename>/data1</filename>).
1314 In Unix, the Windows example document mentioned above could e.g.
1315 be accessed by the name of
1316 <filename>/data1/mywork/mydocument.txt</filename>,
1317 provided that the administrator decided to mount (attach) the first
1318 data partition at the directory /data1 inside the Unix
1319 directory tree. Note that in Unix, the administrator can
1320 <emphasis>choose</emphasis> any custom partition location he
1321 wants (here, <filename>/data1</filename>), whereas in Windows the system
1322 <emphasis>selects</emphasis> any drive letter it deems
1323 suitable for the first data partition (here,
1324 <filename>D:</filename>), and, even worse, if there is some
1325 change in partition order, Windows automatically
1326 <emphasis>changes</emphasis> the drive letter, and you might
1327 suddenly find yourself with a first data partition at drive
1328 letter <filename>E:</filename>, with all the file naming and
1329 referencing confusion that entails. Thus, the Windows way of
1330 using ever-changing drive letters is <emphasis>clearly
1331 inferior</emphasis> to the Unix way of assigning
1332 <emphasis>fixed</emphasis> directory tree locations for every
1333 data storage medium.
1334 As we'll see soon, fortunately this Windows limitation of
1335 changing drive letters doesn't affect us in Wine at all, since
1336 we can properly map <emphasis>never-changing</emphasis> drive letters to <emphasis>fixed</emphasis> locations inside the Unix directory tree (and even if the location of the respective Unix directory changes, we can still simply update the Wine drive mapping to reflect the updated location and at the same time keep the original drive letter).
1337 </para>
1338 <para>
1339 OK, now that we know some theory about Windows and Unix drive
1340 and filename mapping, it's probably time to ask how Wine
1341 achieves the magic of mapping a Unix directory location to a
1342 Windows drive...
1343 </para>
1344 <para>
1345 Wine chose to do the following:
1346 In Wine, you don't assign some real physical storage medium
1347 (such as a harddisk partition or similar) to each drive letter
1348 mapping entry.
1349 Instead, you choose certain sub directory trees inside the Unix
1350 directory tree (that starts with <filename>/</filename>) that
1351 you would like to assign a drive letter to.
1352 </para>
1353 <para>
1354 Note that for every Unix sub directory tree that you intend to
1355 start Windows programs in, it is <emphasis>absolutely
1356 required</emphasis> to have a Wine drive mapping entry:
1357 </para>
1358 <para>
1359 For example, if you had a publicly writable <quote>Windows
1360 directory space</quote> under <filename>/usr/mywine</filename>, then in order to be
1361 able to access this sub directory tree from Wine, you should
1362 have a drive mapping entry that maps a certain drive letter
1363 (for example, let's take drive letter <filename>P:</filename>)
1364 either to <filename>/usr/mywine</filename> or <filename>/usr</filename> (to also access any directories belonging to the parent directory) or <filename>/</filename> (to also access any directory whatsoever on this system by this drive letter mapping). The DOS drive/directory location to access files in <filename>/usr/mywine</filename> <emphasis>in Wine</emphasis> in these configuration cases would then be <filename>P:\</filename> or <filename>P:\mywine</filename> or <filename>P:\usr\mywine</filename>, respectively.
1365 </para>
1366 </sect2>
1368 <sect2 id="config-no-windows">
1369 <title>Installing Wine Without Windows</title>
1371 <para>
1372 A major goal of Wine is to allow users to run Windows programs
1373 without having to install Windows on their machine. Wine
1374 implements the functionality of the main DLLs usually
1375 provided with Windows. Therefore, once Wine is finished, you
1376 will not need to have Windows installed to use Wine.
1377 </para>
1378 <para>
1379 Wine has already made enough progress that it may be possible
1380 to run your target programs without Windows installed. If
1381 you want to try it, follow these steps:
1382 </para>
1384 <orderedlist>
1385 <listitem>
1386 <para>
1387 Point <medialabel>[Drive C]</medialabel> in
1388 <filename>~/.wine/config</filename> to the directory where you want
1389 <filename>C:</filename> to be. Refer to the wine.conf man page
1390 for more information.
1391 The directory to be used for emulating a C: drive will be
1392 the base directory for some Windows specific directories
1393 created below.
1394 Remember to use
1395 <userinput>"Filesystem" = "win95"</userinput>!
1396 </para>
1397 </listitem>
1398 <listitem>
1399 <para>
1400 Within the directory to be used for C:, create empty
1401 <filename>windows</filename>,
1402 <filename>windows/system</filename>,
1403 <filename>windows/Start Menu</filename>, and
1404 <filename>windows/Start Menu/Programs</filename>
1405 directories. Do not point Wine to a
1406 <filename>Windows</filename> directory full of old
1407 installations and a messy registry. (Wine creates a
1408 special registry in your <filename >home</filename>
1409 directory, in <filename>$HOME/.wine/*.reg</filename>.
1410 Perhaps you have to remove these files).
1411 In one line:
1412 mkdir -p windows windows/system windows/Start\ Menu windows/Start\ Menu/Programs
1413 </para>
1414 </listitem>
1415 <listitem>
1416 <para>
1417 Run and/or install your programs.
1418 </para>
1419 </listitem>
1420 </orderedlist>
1422 <para>
1423 Because Wine is not yet complete, some programs will work
1424 better with native Windows DLLs than with Wine's
1425 replacements. Wine has been designed to make this possible.
1426 Here are some tips by Juergen Schmied (and others) on how to
1427 proceed. This assumes that your
1428 <filename>C:\windows</filename> directory in the configuration
1429 file does not point to a native Windows installation but is in
1430 a separate Unix file system. (For instance, <quote>C:\windows</quote> is
1431 really subdirectory <quote>windows</quote> located in
1432 <quote>/home/ego/wine/drives/c</quote>).
1433 </para>
1435 <itemizedlist>
1436 <listitem>
1437 <para>
1438 Run the program with <parameter>--debugmsg
1439 +loaddll</parameter> to find out which files are
1440 needed. Copy the required DLLs one by one to the
1441 <filename>C:\windows\system</filename> directory. Do not
1442 copy KERNEL/KERNEL32, GDI/GDI32, USER/USER32 or NTDLL. These
1443 implement the core functionality of the Windows API, and
1444 the Wine internal versions must be used.
1445 </para>
1446 </listitem>
1447 <listitem>
1448 <para>
1449 Edit the <quote>[DllOverrides]</quote> section of
1450 <filename>~/.wine/config</filename> to specify
1451 <quote>native</quote> before <quote>builtin</quote> for
1452 the Windows DLLs you want to use. For more information
1453 about this, see the Wine manpage.
1454 </para>
1455 </listitem>
1456 <listitem>
1457 <para>
1458 Note that some network DLLs are not needed even though
1459 Wine is looking for them. The Windows
1460 <filename>MPR.DLL</filename> currently does not work; you
1461 must use the internal implementation.
1462 </para>
1463 </listitem>
1464 <listitem>
1465 <para>
1466 Copy SHELL.DLL/SHELL32.DLL, COMMDLG.DLL/COMDLG32.DLL
1467 and COMMCTRL.DLL/COMCTL32.DLL
1468 only as pairs to your Wine directory (these DLLs are
1469 <quote>clean</quote> to use). Make sure you have these
1470 specified in the <quote>[DllPairs]</quote> section of
1471 <filename>~/.wine/config</filename>.
1472 </para>
1473 </listitem>
1474 <listitem>
1475 <para>
1476 Be consistent: Use only DLLs from the same Windows version
1477 together.
1478 </para>
1479 </listitem>
1480 <listitem>
1481 <para>
1482 Put <filename>regedit.exe</filename> in the
1483 <filename>C:\windows</filename> directory.
1484 (<application>Office 95</application> imports a
1485 <filename>*.reg</filename> file when it runs with an empty
1486 registry, don't know about
1487 <application>Office 97</application>).
1488 As of now, it might not be necessary any more to use
1489 regedit.exe, since Wine has its own regedit Winelib
1490 application now.
1491 </para>
1492 </listitem>
1493 <listitem>
1494 <para>
1495 Also add <filename>winhelp.exe</filename> and
1496 <filename>winhlp32.exe</filename> if you want to be able
1497 to browse through your programs' help function
1498 (or in case Wine's winhelp implementation in programs/winhelp/
1499 is not good enough, for example).
1500 </para>
1501 </listitem>
1502 </itemizedlist>
1503 </sect2>
1505 <sect2 id="config-with-windows">
1506 <title>Installing Wine Using An Existing Windows Partition As Base</title>
1507 <para>
1508 Some people intend to use the data of an existing Windows partition
1509 with Wine in order to gain some better compatibility or to run already
1510 installed programs in a setup as original as possible.
1511 Note that many Windows programs assume that they have full write
1512 access to all windows directories.
1514 This means that you either have to configure the Windows
1515 partition mount point for write permission by your Wine user
1516 (see <link linkend="config-drive-vfat">Dealing with FAT/VFAT partitions</link>
1517 on how to do that), or you'll have to copy over (some parts of) the Windows
1518 partition content to a directory of a Unix partition and make
1519 sure this directory structure is writable by your user.
1520 We <emphasis>HIGHLY DISCOURAGE</emphasis> people from directly using a Windows partition with
1521 write access as a base for Wine!! (some programs, notably
1522 Explorer, corrupt large parts of the Windows partition in case
1523 of an incorrect setup; you've been warned).
1524 Not to mention that NTFS write support in Linux is still very
1525 experimental and <emphasis>dangerous</emphasis> (in case you're using an NT-based
1526 Windows version using the NTFS file system).
1527 Thus we advise you to go the Unix directory way.
1528 </para>
1529 </sect2>
1531 <sect2 id="config-drive-vfat">
1532 <title>Dealing With FAT/VFAT Partitions</title>
1533 <para>
1534 This document describes how FAT and
1535 VFAT file system permissions work in Linux
1536 with a focus on configuring them for Wine.
1537 </para>
1539 <sect3>
1540 <title>Introduction</title>
1541 <para>
1542 Linux is able to access DOS and Windows file systems using
1543 either the FAT (older 8.3 DOS filesystems) or VFAT (newer
1544 Windows 95 or later long filename filesystems) modules.
1545 Mounted FAT or VFAT filesystems provide the primary means
1546 for which existing programs and their data are accessed
1547 through Wine for dual boot (Linux + Windows) systems.
1548 </para>
1549 <para>
1550 Wine maps mounted FAT filesystems, such as
1551 <filename>/c</filename>, to driver letters, such as
1552 <quote>c:</quote>, as indicated by the
1553 <filename>~/.wine/config</filename> file. The following excerpt
1554 from a <filename>~/.wine/config</filename> file does this:
1555 </para>
1556 <programlisting>
1557 [Drive C]
1558 "Path" = "/c"
1559 "Type" = "hd"
1560 </programlisting>
1561 <para>
1562 Although VFAT filesystems are preferable to FAT filesystems
1563 for their long filename support, the term <quote>FAT</quote>
1564 will be used throughout the remainder of this document to
1565 refer to FAT filesystems and their derivatives. Also,
1566 <quote>/c</quote> will be used as the FAT mount point in
1567 examples throughout this document.
1568 </para>
1569 <para>
1570 Most modern Linux distributions either detect or allow
1571 existing FAT file systems to be configured so that they can be
1572 mounted, in a location such as <filename>/c</filename>,
1573 either persistently (on bootup) or on an as needed basis. In
1574 either case, by default, the permissions will probably be
1575 configured so that they look like:
1576 </para>
1577 <screen>
1578 <prompt>~></prompt><userinput>cd /c</userinput>
1579 <prompt>/c></prompt><userinput>ls -l</userinput>
1580 <computeroutput>-rwxr-xr-x 1 root root 91 Oct 10 17:58 autoexec.bat
1581 -rwxr-xr-x 1 root root 245 Oct 10 17:58 config.sys
1582 drwxr-xr-x 41 root root 16384 Dec 30 1998 windows</computeroutput>
1583 </screen>
1584 <para>
1585 where all the files are owned by "root", are in the "root"
1586 group and are only writable by "root"
1587 (<literal>755</literal> permissions). This is restrictive in
1588 that it requires that Wine be run as root in order for
1589 programs to be able to write to any part of the
1590 filesystem.
1591 </para>
1592 <para>
1593 There are three major approaches to overcoming the restrictive
1594 permissions mentioned in the previous paragraph:
1595 </para>
1596 <orderedlist>
1597 <listitem>
1598 <para>
1599 Run <application>Wine</application> as root
1600 </para>
1601 </listitem>
1602 <listitem>
1603 <para>
1604 Mount the FAT filesystem with less restrictive
1605 permissions
1606 </para>
1607 </listitem>
1608 <listitem>
1609 <para>
1610 Shadow the FAT filesystem by completely or partially
1611 copying it
1612 </para>
1613 </listitem>
1614 </orderedlist>
1615 <para>
1616 Each approach will be discussed in the following sections.
1617 </para>
1618 </sect3>
1620 <sect3>
1621 <title>Running Wine as root</title>
1622 <para>
1623 Running Wine as root is the easiest and most thorough way of giving
1624 programs that Wine runs unrestricted access to FAT files systems.
1625 Running wine as root also allows programs to do things unrelated
1626 to FAT filesystems, such as listening to ports that are less than
1627 1024. Running Wine as root is dangerous since there is no limit to
1628 what the program can do to the system, so it's <emphasis>HIGHLY DISCOURAGED</emphasis>.
1629 </para>
1630 </sect3>
1632 <sect3>
1633 <title>Mounting FAT filesystems</title>
1634 <para>
1635 The FAT filesystem can be mounted with permissions less restrictive
1636 than the default. This can be done by either changing the user that
1637 mounts the FAT filesystem or by explicitly changing the permissions
1638 that the FAT filesystem is mounted with. The permissions are
1639 inherited from the process that mounts the FAT filesystem. Since the
1640 process that mounts the FAT filesystem is usually a startup script
1641 running as root the FAT filesystem inherits root's permissions. This
1642 results in the files on the FAT filesystem having permissions similar
1643 to files created by root. For example:
1644 </para>
1645 <screen>
1646 <prompt>~></prompt><userinput>whoami</userinput>
1647 <computeroutput>root</computeroutput>
1648 <prompt>~></prompt><userinput>touch root_file</userinput>
1649 <prompt>~></prompt><userinput>ls -l root_file</userinput>
1650 <computeroutput></computeroutput>-rw-r--r-- 1 root root 0 Dec 10 00:20 root_file
1651 </screen>
1652 <para>
1653 which matches the owner, group and permissions of files seen
1654 on the FAT filesystem except for the missing 'x's. The
1655 permissions on the FAT filesystem can be changed by changing
1656 root's umask (unset permissions bits). For example:
1657 </para>
1658 <screen>
1659 <prompt>~></prompt><userinput>umount /c</userinput>
1660 <prompt>~></prompt><userinput>umask</userinput>
1661 <computeroutput>022</computeroutput>
1662 <prompt>~></prompt><userinput>umask 073</userinput>
1663 <prompt>~></prompt><userinput>mount /c</userinput>
1664 <prompt>~></prompt><userinput>cd /c</userinput>
1665 <prompt>/c></prompt><userinput>ls -l</userinput>
1666 <computeroutput>-rwx---r-- 1 root root 91 Oct 10 17:58 autoexec.bat
1667 -rwx---r-- 1 root root 245 Oct 10 17:58 config.sys
1668 drwx---r-- 41 root root 16384 Dec 30 1998 windows</computeroutput>
1669 </screen>
1670 <para>
1671 Mounting the FAT filesystem with a umask of
1672 <literal>000</literal> gives all users complete control over
1673 it. Explicitly specifying the permissions of the FAT
1674 filesystem when it is mounted provides additional control.
1675 There are three mount options that are relevant to FAT
1676 permissions: <literal>uid</literal>, <literal>gid</literal>
1677 and <literal>umask</literal>. They can each be specified
1678 when the filesystem is manually mounted. For example:
1679 </para>
1680 <screen>
1681 <prompt>~></prompt><userinput>umount /c</userinput>
1682 <prompt>~></prompt><userinput>mount -o uid=500 -o gid=500 -o umask=002 /c</userinput>
1683 <prompt>~></prompt><userinput>cd /c</userinput>
1684 <prompt>/c></prompt><userinput>ls -l</userinput>
1685 <computeroutput>-rwxrwxr-x 1 sle sle 91 Oct 10 17:58 autoexec.bat
1686 -rwxrwxr-x 1 sle sle 245 Oct 10 17:58 config.sys
1687 drwxrwxr-x 41 sle sle 16384 Dec 30 1998 windows</computeroutput>
1688 </screen>
1689 <para>
1690 which gives "sle" complete control over
1691 <filename>/c</filename>. The options listed above can be
1692 made permanent by adding them to the
1693 <filename>/etc/fstab</filename> file:
1694 </para>
1695 <screen>
1696 <prompt>~></prompt><userinput>grep /c /etc/fstab</userinput>
1697 <computeroutput>/dev/hda1 /c vfat uid=500,gid=500,umask=002,exec,dev,suid,rw 1 1</computeroutput>
1698 </screen>
1699 <para>
1700 Note that the umask of <literal>002</literal> is common in
1701 the user private group file permission scheme. On FAT file
1702 systems this umask assures that all files are fully
1703 accessible by all users in the specified user group
1704 (<literal>gid</literal>).
1705 </para>
1706 </sect3>
1708 <sect3>
1709 <title>Shadowing FAT filesystems</title>
1710 <para>
1711 Shadowing provides a finer granularity of control. Parts of
1712 the original FAT filesystem can be copied so that the
1713 program can safely work with those copied parts while
1714 the program continues to directly read the remaining
1715 parts. This is done with symbolic links. For example,
1716 consider a system where a program named
1717 <application>AnApp</application> must be able to read and
1718 write to the <filename>c:\windows</filename> and
1719 <filename>c:\AnApp</filename> directories as well as have
1720 read access to the entire FAT filesystem. On this system
1721 the FAT filesystem has default permissions which should not
1722 be changed for security reasons or can not be changed due to
1723 lack of root access. On this system a shadow directory
1724 might be set up in the following manner:
1725 </para>
1726 <screen>
1727 <prompt>~></prompt><userinput>cd /</userinput>
1728 <prompt>/></prompt><userinput>mkdir c_shadow</userinput>
1729 <prompt>/></prompt><userinput>cd c_shadow</userinput>
1730 <prompt>/c_shadow></prompt><userinput>ln -s /c_/* .</userinput>
1731 <prompt>/c_shadow></prompt><userinput>rm windows AnApp</userinput>
1732 <prompt>/c_shadow></prompt><userinput>cp -R /c_/{windows,AnApp} .</userinput>
1733 <prompt>/c_shadow></prompt><userinput>chmod -R 777 windows AnApp</userinput>
1734 <prompt>/c_shadow></prompt><userinput>perl -p -i -e 's|/c$|/c_shadow|g' ~/.wine/config</userinput>
1735 </screen>
1736 <para>
1737 The above gives everyone complete read and write access to
1738 the <filename>windows</filename> and
1739 <filename>AnApp</filename> directories while only root has
1740 write access to all other directories.
1741 </para>
1742 </sect3>
1743 </sect2>
1745 <sect2 id="config-drive-cdrom-labels">
1747 <title>Drive labels and serial numbers</title>
1748 <para>
1749 Until now, your only possibility of specifying drive volume
1750 labels and serial numbers was to set them manually in the wine
1751 configuration file. By now, wine can read them directly from the
1752 device as well. This may be useful for many Win 9x games or
1753 for setup programs distributed on CD-ROMs that check for
1754 volume label.
1755 </para>
1757 <sect3>
1758 <title>What's Supported?</title>
1760 <informaltable frame="all">
1761 <tgroup cols="3">
1762 <thead>
1763 <row>
1764 <entry>File System</entry>
1765 <entry>Types</entry>
1766 <entry>Comment</entry>
1767 </row>
1768 </thead>
1769 <tbody>
1770 <row>
1771 <entry>FAT systems</entry>
1772 <entry>hd, floppy</entry>
1773 <entry>reads labels and serial numbers</entry>
1774 </row>
1775 <row>
1776 <entry>ISO9660</entry>
1777 <entry>cdrom</entry>
1778 <entry>reads labels and serial numbers (not mixed-mode CDs yet!)</entry>
1779 </row>
1780 </tbody>
1781 </tgroup>
1782 </informaltable>
1784 </sect3>
1786 <sect3>
1787 <title>How To Set Up?</title>
1788 <para>
1789 Reading labels and serial numbers just works automatically
1790 if you specify a <literal>"Device" =</literal> line in the
1791 [Drive x] section in your <filename>~/.wine/config</filename>.
1792 Note that the device has to exist and must be accessible by the user
1793 running Wine if you do this, though.
1794 </para>
1795 <para>
1796 If you don't want to read labels and serial numbers directly from
1797 the device, then you should give fixed
1798 <literal>"Label" =</literal> or <literal>"Serial" =</literal>
1799 entries in <filename>~/.wine/config</filename>, as Wine returns
1800 these entries instead if no device is given. If they don't
1801 exist, then Wine will return default values (label
1802 <literal>Drive X</literal> and serial
1803 <literal>12345678</literal>).
1804 </para>
1805 <para>
1806 If you want to give a <literal>"Device" =</literal> entry
1807 <emphasis>only</emphasis> for drive raw sector accesses,
1808 but not for reading the volume info from the device (i.e. you want
1809 a <emphasis>fixed</emphasis>, preconfigured label), you need
1810 to specify <literal>"ReadVolInfo" = "0"</literal> to tell Wine
1811 to skip the volume reading.
1812 </para>
1813 </sect3>
1815 <sect3>
1816 <title>Examples</title>
1817 <para>
1818 Here's a simple example of CD-ROM and floppy; labels will be
1819 read from the device on both CD-ROM and floppy; serial
1820 numbers on floppy only:
1821 </para>
1822 <programlisting>
1823 [Drive A]
1824 "Path" = "/mnt/floppy"
1825 "Type" = "floppy"
1826 "Device" = "/dev/fd0"
1827 "Filesystem" = "msdos"
1829 [Drive R]
1830 "Path" = "/mnt/cdrom"
1831 "Type" = "cdrom"
1832 "Device" = "/dev/hda1"
1833 "Filesystem" = "win95"
1834 </programlisting>
1835 <para>
1836 Here's an example of overriding the CD-ROM label:
1837 </para>
1838 <programlisting>
1839 [Drive J]
1840 "Path" = "/mnt/cdrom"
1841 "Type" = "cdrom"
1842 "Label" = "X234GCDSE"
1843 ; note that the device isn't really needed here as we have a fixed label
1844 "Device" = "/dev/cdrom"
1845 "Filesystem" = "msdos"
1846 </programlisting>
1847 </sect3>
1849 <sect3>
1850 <title>Todo / Open Issues</title>
1851 <itemizedlist>
1852 <listitem> <para>
1853 The CD-ROM label can be read only if the data track of
1854 the disk resides in the first track and the cdrom is
1855 iso9660.
1856 </para> </listitem>
1857 <listitem> <para>
1858 Better checking for FAT superblock (it now checks only
1859 one byte). </para>
1860 </listitem>
1861 <listitem> <para>
1862 Support for labels/serial nums WRITING.
1863 </para> </listitem>
1864 <listitem> <para>
1865 Can the label be longer than 11 chars? (iso9660 has 32
1866 chars).
1867 </para> </listitem>
1868 <listitem> <para>
1869 What about reading ext2 volume label? ....
1870 </para> </listitem>
1871 </itemizedlist>
1872 </sect3>
1873 </sect2>
1874 </sect1>
1876 &registry;
1878 <sect1 id="config-dll">
1879 <title>DLL configuration</title>
1881 <sect2>
1882 <title>Introduction</title>
1883 <para>
1884 If your programs don't work as expected, then it's often because one
1885 DLL or another is failing. This can often be resolved by changing
1886 certain DLLs from Wine built-in to native Windows DLL file and vice
1887 versa.
1888 </para>
1889 <para>
1890 A very useful help to find out which DLLs are loaded as built-in and
1891 which are loaded as native Windows file can be the debug channel
1892 loaddll, activated via the Wine command line parameter
1893 <command>--debugmsg +loaddll</command>.
1894 </para>
1895 </sect2>
1897 <sect2>
1898 <!-- FIXME intro!!! -->
1899 <title>Introduction To DLL Sections</title>
1900 <para>
1901 There are a few things you will need to know before
1902 configuring the DLL sections in your wine configuration
1903 file.
1904 </para>
1905 <sect3>
1906 <title>Windows DLL Pairs</title>
1907 <para>
1908 Most windows DLL's have a win16 (Windows 3.x) and win32
1909 (Windows 9x/NT) form. The combination of the win16 and
1910 win32 DLL versions are called the "DLL pair". This is a
1911 list of the most common pairs:
1912 </para>
1914 <informaltable>
1915 <tgroup cols="3">
1916 <thead>
1917 <row>
1918 <entry>Win16</entry>
1919 <entry>Win32</entry>
1920 <entry>
1921 Native
1922 <footnote>
1923 <para>
1924 Is it possible to use native DLL with wine?
1925 (See next section)
1926 </para>
1927 </footnote>
1928 </entry>
1929 </row>
1930 </thead>
1931 <tbody>
1932 <row>
1933 <entry>KERNEL</entry>
1934 <entry>KERNEL32</entry>
1935 <entry>No!</entry>
1936 </row>
1937 <row>
1938 <entry>USER</entry>
1939 <entry>USER32</entry>
1940 <entry>No!</entry>
1941 </row>
1942 <row>
1943 <entry>SHELL</entry>
1944 <entry>SHELL32</entry>
1945 <entry>Yes</entry>
1946 </row>
1947 <row>
1948 <entry>GDI</entry>
1949 <entry>GDI32</entry>
1950 <entry>No!</entry>
1951 </row>
1952 <row>
1953 <entry>COMMDLG</entry>
1954 <entry>COMDLG32</entry>
1955 <entry>Yes</entry>
1956 </row>
1957 <row>
1958 <entry>VER</entry>
1959 <entry>VERSION</entry>
1960 <entry>Yes</entry>
1961 </row>
1962 </tbody>
1963 </tgroup>
1964 </informaltable>
1965 </sect3>
1967 <sect3>
1968 <title>Different Forms Of DLL's</title>
1969 <para>
1970 There are a few different forms of DLL's wine can load:
1971 <variablelist>
1972 <varlistentry>
1973 <term>native</term>
1974 <listitem><para>
1975 The DLL's that are included with windows. Many
1976 windows DLL's can be loaded in their native
1977 form. Many times these native versions work
1978 better than their non-Microsoft equivalent --
1979 other times they don't.
1980 </para></listitem>
1981 </varlistentry>
1982 <varlistentry>
1983 <term>builtin</term>
1984 <listitem><para>
1985 The most common form of DLL loading. This is
1986 what you will use if the DLL is too system-specific
1987 or error-prone in native form (KERNEL for example),
1988 you don't have the native DLL, or you just want to be
1989 Microsoft-free.
1990 </para></listitem>
1991 </varlistentry>
1992 <varlistentry>
1993 <term>so</term>
1994 <listitem><para>
1995 Native ELF libraries. Has been deprecated, ignored.
1996 </para></listitem>
1997 </varlistentry>
1998 <varlistentry>
1999 <term>elfdll</term>
2000 <listitem><para>
2001 ELF encapsulated windows DLL's.
2002 No longer used, ignored.
2003 </para></listitem>
2004 </varlistentry>
2005 </variablelist>
2006 </para>
2007 </sect3>
2008 </sect2>
2010 <sect2 id="config-dll-overrides">
2011 <title>DLL Overrides</title>
2013 <para>
2014 The wine configuration file directives [DllDefaults]
2015 and [DllOverrides] are the subject of some confusion. The
2016 overall purpose of most of these directives are clear enough,
2017 though - given a choice, should Wine use its own built-in
2018 DLLs, or should it use <filename>.DLL</filename> files found
2019 in an existing Windows installation? This document explains
2020 how this feature works.
2021 </para>
2023 <sect3>
2024 <title>DLL types</title>
2025 <variablelist>
2026 <varlistentry>
2027 <term>native</term>
2028 <listitem> <para>
2029 A "native" DLL is a <filename>.DLL</filename> file
2030 written for the real Microsoft Windows.
2031 </para> </listitem>
2032 </varlistentry>
2033 <varlistentry>
2034 <term>builtin</term>
2035 <listitem> <para>
2036 A "built-in" DLL is a Wine DLL. These can either be a
2037 part of <filename>libwine.so</filename>, or more
2038 recently, in a special <filename>.so</filename> file
2039 that Wine is able to load on demand.
2040 </para> </listitem>
2041 </varlistentry>
2042 </variablelist>
2043 </sect3>
2045 <sect3>
2046 <title>The [DllDefaults] section</title>
2047 <variablelist>
2048 <varlistentry>
2049 <term>DefaultLoadOrder</term>
2050 <listitem> <para>
2051 This specifies in what order Wine should search for
2052 available DLL types, if the DLL in question was not
2053 found in the [DllOverrides] section.
2054 </para> </listitem>
2055 </varlistentry>
2056 </variablelist>
2057 </sect3>
2059 <sect3>
2060 <title>The [DllPairs] section</title>
2061 <para>
2062 At one time, there was a section called [DllPairs] in the
2063 default configuration file, but this has been obsoleted
2064 because the pairing information has now been embedded into
2065 Wine itself. (The purpose of this section was merely to be
2066 able to issue warnings if the user attempted to pair
2067 codependent 16-bit/32-bit DLLs of different types.) If you
2068 still have this in your <filename>~/.wine/config</filename> or
2069 <filename>wine.conf</filename>, you may safely delete it.
2070 </para>
2071 </sect3>
2073 <sect3>
2074 <title>The [DllOverrides] section</title>
2075 <para>
2076 This section specifies how you want specific DLLs to be
2077 handled, in particular whether you want to use "native" DLLs
2078 or not, if you have some from a real Windows configuration.
2079 Because built-ins do not mix seamlessly with native DLLs yet,
2080 certain DLL dependencies may be problematic, but workarounds
2081 exist in Wine for many popular DLL configurations. Also see
2082 WWN's [16]Status Page to figure out how well your favorite
2083 DLL is implemented in Wine.
2084 </para>
2085 <para>
2086 It is of course also possible to override these settings by
2087 explicitly using Wine's <parameter>--dll</parameter>
2088 command-line option (see the man page for details). Some
2089 hints for choosing your optimal configuration (listed by
2090 16/32-bit DLL pair):
2091 </para>
2092 <variablelist>
2093 <varlistentry>
2094 <term>krnl386, kernel32</term>
2095 <listitem> <para>
2096 Native versions of these will never work, so don't try. Leave
2097 at <literal>builtin</literal>.
2098 </para> </listitem>
2099 </varlistentry>
2100 <varlistentry>
2101 <term>gdi, gdi32</term>
2102 <listitem> <para>
2103 Graphics Device Interface. No effort has been made at trying to
2104 run native GDI. Leave at <literal>builtin</literal>.
2105 </para> </listitem>
2106 </varlistentry>
2107 <varlistentry>
2108 <term>user, user32</term>
2109 <listitem> <para>
2110 Window management and standard controls. It was
2111 possible to use Win95's <literal>native</literal>
2112 versions at some point (if all other DLLs that depend
2113 on it, such as comctl32 and comdlg32, were also run
2114 <literal>native</literal>). However, this is no longer
2115 possible after the Address Space Separation, so leave
2116 at <literal>builtin</literal>.
2117 </para> </listitem>
2118 </varlistentry>
2119 <varlistentry>
2120 <term>ntdll</term>
2121 <listitem> <para>
2122 NT kernel API. Although badly documented, the
2123 <literal>native</literal> version of this will never
2124 work. Leave at <literal>builtin</literal>.
2125 </para> </listitem>
2126 </varlistentry>
2127 <varlistentry>
2128 <term>w32skrnl</term>
2129 <listitem> <para>
2130 Win32s (for Win3.x). The <literal>native</literal>
2131 version will probably never work. Leave at
2132 <literal>builtin</literal>.
2133 </para> </listitem>
2134 </varlistentry>
2135 <varlistentry>
2136 <term>wow32</term>
2137 <listitem> <para>
2138 Win16 support library for NT. The
2139 <literal>native</literal> version will probably never
2140 work. Leave at <literal>builtin</literal>.
2141 </para> </listitem>
2142 </varlistentry>
2143 <varlistentry>
2144 <term>system</term>
2145 <listitem> <para>
2146 Win16 kernel stuff. Will never work
2147 <literal>native</literal>. Leave at
2148 <literal>builtin</literal>.
2149 </para> </listitem>
2150 </varlistentry>
2151 <varlistentry>
2152 <term>display</term>
2153 <listitem> <para>
2154 Display driver. Definitely leave at <literal>builtin</literal>.
2155 </para> </listitem>
2156 </varlistentry>
2157 <varlistentry>
2158 <term>toolhelp</term>
2159 <listitem> <para>
2160 Tool helper routines. This is rarely a source of problems.
2161 Leave at <literal>builtin</literal>.
2162 </para> </listitem>
2163 </varlistentry>
2164 <varlistentry>
2165 <term>ver, version</term>
2166 <listitem> <para>
2167 Versioning. Seldom useful to mess with.
2168 </para> </listitem>
2169 </varlistentry>
2170 <varlistentry>
2171 <term>advapi32</term>
2172 <listitem> <para>
2173 Registry and security features. Trying the
2174 <literal>native</literal> version of this may or may
2175 not work.
2176 </para> </listitem>
2177 </varlistentry>
2178 <varlistentry>
2179 <term>commdlg, comdlg32</term>
2180 <listitem> <para>
2181 Common Dialogs, such as color picker, font dialog,
2182 print dialog, open/save dialog, etc. It is safe to try
2183 <literal>native</literal>.
2184 </para> </listitem>
2185 </varlistentry>
2186 <varlistentry>
2187 <term>commctrl, comctl32</term>
2188 <listitem> <para>
2189 Common Controls. This is toolbars, status bars, list controls,
2190 the works. It is safe to try <literal>native</literal>.
2191 </para> </listitem>
2192 </varlistentry>
2193 <varlistentry>
2194 <term>shell, shell32</term>
2195 <listitem> <para>
2196 Shell interface (desktop, filesystem, etc). Being one of the
2197 most undocumented pieces of Windows, you may have luck with the
2198 <literal>native</literal> version, should you need it.
2199 </para> </listitem>
2200 </varlistentry>
2201 <varlistentry>
2202 <term>winsock, wsock32</term>
2203 <listitem> <para>
2204 Windows Sockets. The <literal>native</literal> version
2205 will not work under Wine, so leave at
2206 <literal>builtin</literal>.
2207 </para> </listitem>
2208 </varlistentry>
2209 <varlistentry>
2210 <term>icmp</term>
2211 <listitem> <para>
2212 ICMP routines for wsock32. As with wsock32, leave at
2213 <literal>builtin</literal>.
2214 </para> </listitem>
2215 </varlistentry>
2216 <varlistentry>
2217 <term>mpr</term>
2218 <listitem> <para>
2219 The <literal>native</literal> version may not work due
2220 to thunking issues. Leave at
2221 <literal>builtin</literal>.
2222 </para> </listitem>
2223 </varlistentry>
2224 <varlistentry>
2225 <term>lzexpand, lz32</term>
2226 <listitem> <para>
2227 Lempel-Ziv decompression. Wine's
2228 <literal>builtin</literal> version ought to work fine.
2229 </para> </listitem>
2230 </varlistentry>
2231 <varlistentry>
2232 <term>winaspi, wnaspi32</term>
2233 <listitem> <para>
2234 Advanced SCSI Peripheral Interface. The
2235 <literal>native</literal> version will probably never
2236 work. Leave at <literal>builtin</literal>.
2237 </para> </listitem>
2238 </varlistentry>
2239 <varlistentry>
2240 <term>crtdll</term>
2241 <listitem> <para>
2242 C Runtime library. The <literal>native</literal>
2243 version will easily work better than Wine's on this
2244 one.
2245 </para> </listitem>
2246 </varlistentry>
2247 <varlistentry>
2248 <term>winspool.drv</term>
2249 <listitem> <para>
2250 Printer spooler. You are not likely to have more luck
2251 with the <literal>native</literal> version.
2252 </para> </listitem>
2253 </varlistentry>
2254 <varlistentry>
2255 <term>ddraw</term>
2256 <listitem> <para>
2257 DirectDraw/Direct3D. Since Wine does not implement the
2258 DirectX HAL, the <literal>native</literal> version
2259 will not work at this time.
2260 </para> </listitem>
2261 </varlistentry>
2262 <varlistentry>
2263 <term>dinput</term>
2264 <listitem> <para>
2265 DirectInput. Running this <literal>native</literal>
2266 may or may not work.
2267 </para> </listitem>
2268 </varlistentry>
2269 <varlistentry>
2270 <term>dsound</term>
2271 <listitem> <para>
2272 DirectSound. It may be possible to run this
2273 <literal>native</literal>, but don't count on it.
2274 </para> </listitem>
2275 </varlistentry>
2276 <varlistentry>
2277 <term>dplay/dplayx</term>
2278 <listitem> <para>
2279 DirectPlay. The <literal>native</literal> version
2280 ought to work best on this, if at all.
2281 </para> </listitem>
2282 </varlistentry>
2283 <varlistentry>
2284 <term>mmsystem, winmm</term>
2285 <listitem> <para>
2286 Multimedia system. The <literal>native</literal>
2287 version is not likely to work. Leave at
2288 <literal>builtin</literal>.
2289 </para> </listitem>
2290 </varlistentry>
2291 <varlistentry>
2292 <term>msacm, msacm32</term>
2293 <listitem> <para>
2294 Audio Compression Manager. The
2295 <literal>builtin</literal> version works best, if you
2296 set msacm.drv to the same.
2297 </para> </listitem>
2298 </varlistentry>
2299 <varlistentry>
2300 <term>msvideo, msvfw32</term>
2301 <listitem> <para>
2302 Video for Windows. It is safe (and recommended) to try
2303 <literal>native</literal>.
2304 </para> </listitem>
2305 </varlistentry>
2306 <varlistentry>
2307 <term>mcicda.drv</term>
2308 <listitem> <para>
2309 CD Audio MCI driver.
2310 </para> </listitem>
2311 </varlistentry>
2312 <varlistentry>
2313 <term>mciseq.drv</term>
2314 <listitem> <para>
2315 MIDI Sequencer MCI driver (<filename>.MID</filename>
2316 playback).
2317 </para> </listitem>
2318 </varlistentry>
2319 <varlistentry>
2320 <term>mciwave.drv</term>
2321 <listitem> <para>
2322 Wave audio MCI driver (<filename>.WAV</filename> playback).
2323 </para> </listitem>
2324 </varlistentry>
2325 <varlistentry>
2326 <term>mciavi.drv</term>
2327 <listitem> <para>
2328 AVI MCI driver (<filename>.AVI</filename> video
2329 playback). Best to use <literal>native</literal>.
2330 </para> </listitem>
2331 </varlistentry>
2332 <varlistentry>
2333 <term>mcianim.drv</term>
2334 <listitem> <para>
2335 Animation MCI driver.
2336 </para> </listitem>
2337 </varlistentry>
2338 <varlistentry>
2339 <term>msacm.drv</term>
2340 <listitem> <para>
2341 Audio Compression Manager. Set to same as msacm32.
2342 </para> </listitem>
2343 </varlistentry>
2344 <varlistentry>
2345 <term>midimap.drv</term>
2346 <listitem> <para>
2347 MIDI Mapper.
2348 </para> </listitem>
2349 </varlistentry>
2350 <varlistentry>
2351 <term>wprocs</term>
2352 <listitem> <para>
2353 This is a pseudo-DLL used by Wine for thunking
2354 purposes. A <literal>native</literal> version of this
2355 doesn't exist.
2356 </para> </listitem>
2357 </varlistentry>
2358 </variablelist>
2359 </sect3>
2360 </sect2>
2362 <sect2 id="config-system-dlls">
2363 <title>System DLLs</title>
2364 <para>
2365 The Wine team has determined that it is necessary to create
2366 fake DLL files to trick many programs that check for
2367 file existence to determine whether a particular feature
2368 (such as Winsock and its TCP/IP networking) is available. If
2369 this is a problem for you, you can create empty files in the
2370 configured <filename>c:\windows\system</filename> directory
2371 to make the program think it's there, and Wine's built-in DLL
2372 will be loaded when the program actually asks for it.
2373 (Unfortunately, <filename>tools/wineinstall</filename> does
2374 not create such empty files itself.)
2375 </para>
2376 <para>
2377 Applications sometimes also try to inspect the version
2378 resources from the physical files (for example, to determine
2379 the DirectX version). Empty files will not do in this case,
2380 it is rather necessary to install files with complete
2381 version resources. This problem is currently being worked
2382 on. In the meantime, you may still need to grab some real
2383 DLL files to fool these apps with.
2384 </para>
2385 <para>
2386 And there are of course DLLs that wine does not currently
2387 implement very well (or at all). If you do not have a real
2388 Windows you can steal necessary DLLs from, you can always
2389 get some from one of the Windows DLL archive sites
2390 that can be found via internet search engine.
2391 Please make sure to obey any licenses on the DLLs you fetch...
2392 (some are redistributable, some aren't).
2393 </para>
2394 </sect2>
2396 <sect2 id="config-dll-missing">
2397 <title>Missing DLLs</title>
2399 <para>
2400 In case Wine complains about a missing DLL, you should check whether
2401 this file is a publicly available DLL or a custom DLL belonging
2402 to your program (by searching for its name on the internet).
2403 If you managed to get hold of the DLL, then you should make sure
2404 that Wine is able to find and load it.
2405 DLLs usually get loaded according to the mechanism of the
2406 SearchPath() function.
2407 This function searches directories in the following order:
2409 <orderedlist>
2410 <listitem>
2411 <para>
2412 The directory the program was started from.
2413 </para>
2414 </listitem>
2415 <listitem>
2416 <para>
2417 The current directory.
2418 </para>
2419 </listitem>
2420 <listitem>
2421 <para>
2422 The Windows system directory.
2423 </para>
2424 </listitem>
2425 <listitem>
2426 <para>
2427 The Windows directory.
2428 </para>
2429 </listitem>
2430 <listitem>
2431 <para>
2432 The PATH variable directories.
2433 </para>
2434 </listitem>
2435 </orderedlist>
2437 In short: either put the required DLL into your program
2438 directory (might be ugly), or usually put it into the Windows system
2439 directory. Just find out its directory by having a look at the Wine
2440 configuration file variable "System" (which indicates the location of the
2441 Windows system directory) and the associated drive entry.
2442 Note that you probably shouldn't use NT-based native DLLs,
2443 since Wine's NT API support is somewhat weaker than its Win9x
2444 API support (thus leading to even worse compatibility with NT DLLs
2445 than with a no-windows setup!), so better use Win9x native DLLs
2446 instead or no native DLLs at all.
2447 </para>
2448 </sect2>
2450 <sect2 id="config-dll-windows">
2451 <title>Fetching native DLLs from a Windows CD</title>
2453 <para>
2454 The Linux <command>cabextract</command> utility can be used to
2455 extract native Windows .dll files from .cab files that are to be
2456 found on many Windows installation CDs.
2457 </para>
2458 </sect2>
2459 </sect1>
2461 <sect1 id="config-graphics-driver">
2462 <title>Configuring the graphics driver (x11drv, ttydrv etc.)</title>
2464 <para>
2465 Wine currently supports several different display subsystems
2466 (graphics / text) that are available on various operating
2467 systems today.
2468 For each of these, Wine implements its own interfacing driver.
2469 This section explains how to select one of these drivers
2470 and how to further configure the respective driver.
2471 Once you're finished with that, you can consider your Wine installation
2472 to be finished.
2473 </para>
2475 <para>
2476 The display drivers currently implemented in Wine are:
2477 x11drv, which is used for interfacing to X11 graphics
2478 (the one you'll most likely want to use) and ttydrv
2479 (used for text mode console apps mainly that don't really need
2480 any graphics output).
2481 Once you have decided which display driver to use, it is chosen
2482 with the <literal>GraphicsDriver</literal> option in the
2483 [wine] section of <filename>~/.wine/config</filename>.
2484 </para>
2486 <sect2>
2487 <title>Configuring the x11drv graphics driver</title>
2489 <sect3>
2490 <title>x11drv modes of operation</title>
2492 <para>
2493 The x11drv driver consists of two conceptually distinct
2494 pieces, the graphics driver (GDI part), and the windowing
2495 driver (USER part). Both of these are linked into the
2496 <filename>libx11drv.so</filename> module, though (which you
2497 load with the <literal>GraphicsDriver</literal> option). In
2498 Wine, running on X11, the graphics driver must draw on
2499 drawables (window interiors) provided by the windowing
2500 driver. This differs a bit from the Windows model, where the
2501 windowing system creates and configures device contexts
2502 controlled by the graphics driver, and programs are
2503 allowed to hook into this relationship anywhere they like.
2504 Thus, to provide any reasonable tradeoff between
2505 compatibility and usability, the x11drv has three different
2506 modes of operation.
2507 </para>
2509 <variablelist>
2510 <varlistentry>
2511 <term>Managed</term>
2512 <listitem>
2513 <para>
2514 The default. Specified by using the <literal>Managed</literal>
2515 wine configuration file option (see below).
2516 Ordinary top-level frame windows with thick borders,
2517 title bars, and system menus will be managed by your
2518 window manager. This lets these programs integrate
2519 better with the rest of your desktop, but may not
2520 always work perfectly (a rewrite of this mode of
2521 operation, to make it more robust and less patchy, is
2522 currently being done, though, and it's planned to be
2523 finished before the Wine 1.0 release).
2524 </para>
2525 </listitem>
2526 </varlistentry>
2527 <varlistentry>
2528 <term>Unmanaged / Normal</term>
2529 <listitem>
2530 <para>
2531 Window manager independent (any running
2532 window manager is ignored completely). Window
2533 decorations (title bars, borders, etc) are drawn by
2534 Wine to look and feel like the real Windows. This is
2535 compatible with programs that depend on being able
2536 to compute the exact sizes of any such decorations, or
2537 that want to draw their own.
2538 Unmanaged mode is only used if both Managed and Desktop
2539 are set to disabled.
2540 </para>
2541 </listitem>
2542 </varlistentry>
2543 <varlistentry>
2544 <term>Desktop-in-a-Box</term>
2545 <listitem>
2546 <para>
2547 Specified by using the <literal>Desktop</literal>
2548 wine configuration file option (see below).
2549 (adding a geometry, e.g. <literal>800x600</literal>
2550 for a such-sized desktop, or
2551 even <literal>800x600+0+0</literal> to
2552 automatically position the desktop at the upper-left
2553 corner of the display). This is the mode most
2554 compatible with the Windows model. All program
2555 windows will just be Wine-drawn windows inside the
2556 Wine-provided desktop window (which will itself be
2557 managed by your window manager), and Windows
2558 programs can roam freely within this virtual
2559 workspace and think they own it all, without
2560 disturbing your other X apps.
2561 Note: currently there's one desktop window for every
2562 program; this will be fixed at some time.
2563 </para>
2564 </listitem>
2565 </varlistentry>
2566 </variablelist>
2567 </sect3>
2569 <sect3>
2570 <title>The [x11drv] section</title>
2572 <variablelist>
2573 <varlistentry>
2574 <term>Managed</term>
2575 <listitem>
2576 <para>
2577 Wine can let frame windows be managed by your window
2578 manager. This option specifies whether you want that
2579 by default.
2580 </para>
2581 </listitem>
2582 </varlistentry>
2583 <varlistentry>
2584 <term>Desktop</term>
2585 <listitem>
2586 <para>
2587 Creates a main desktop window of a specified size
2588 to display all Windows programs in.
2589 The size argument could e.g. be "800x600".
2590 </para>
2591 </listitem>
2592 </varlistentry>
2593 <varlistentry>
2594 <term>DXGrab</term>
2595 <listitem>
2596 <para>
2597 If you don't use DGA, you may want an alternative
2598 means to convince the mouse cursor to stay within the
2599 game window. This option does that. Of course, as with
2600 DGA, if Wine crashes, you're in trouble (although not
2601 as badly as in the DGA case, since you can still use
2602 the keyboard to get out of X).
2603 </para>
2604 </listitem>
2605 </varlistentry>
2606 <varlistentry>
2607 <term>UseDGA</term>
2608 <listitem>
2609 <para>
2610 This specifies whether you want DirectDraw to use
2611 XFree86's <firstterm>Direct Graphics
2612 Architecture</firstterm> (DGA), which is able to
2613 take over the entire display and run the game
2614 full-screen at maximum speed. (With DGA1 (XFree86
2615 3.x), you still have to configure the X server to the
2616 game's requested bpp first, but with DGA2 (XFree86
2617 4.x), runtime depth-switching may be possible,
2618 depending on your driver's capabilities.) But be aware
2619 that if Wine crashes while in DGA mode, it may not be
2620 possible to regain control over your computer without
2621 rebooting. DGA normally requires either root
2622 privileges or read/write access to
2623 <filename>/dev/mem</filename>.
2624 </para>
2625 </listitem>
2626 </varlistentry>
2627 <varlistentry>
2628 <term>DesktopDoubleBuffered</term>
2629 <listitem>
2630 <para>
2631 Applies only if you use the
2632 <parameter>--desktop</parameter> command-line option
2633 to run in a desktop window. Specifies whether to
2634 create the desktop window with a double-buffered
2635 visual, something most OpenGL games need to run
2636 correctly.
2637 </para>
2638 </listitem>
2639 </varlistentry>
2640 <varlistentry>
2641 <term>AllocSystemColors</term>
2642 <listitem>
2643 <para>
2644 Applies only if you have a palette-based display, i.e.
2645 if your X server is set to a depth of 8bpp, and if you
2646 haven't requested a private color map. It specifies
2647 the maximum number of shared colormap cells (palette
2648 entries) Wine should occupy. The higher this value,
2649 the less colors will be available to other
2650 programs.
2651 </para>
2652 </listitem>
2653 </varlistentry>
2654 <varlistentry>
2655 <term>PrivateColorMap</term>
2656 <listitem>
2657 <para>
2658 Applies only if you have a palette-based display, i.e.
2659 if your X server is set to a depth of 8bpp. It
2660 specifies that you don't want to use the shared color
2661 map, but a private color map, where all 256 colors are
2662 available. The disadvantage is that Wine's private
2663 color map is only seen while the mouse pointer is
2664 inside a Wine window, so psychedelic flashing and
2665 funky colors will become routine if you use the mouse
2666 a lot.
2667 </para>
2668 </listitem>
2669 </varlistentry>
2670 <varlistentry>
2671 <term>Synchronous</term>
2672 <listitem>
2673 <para>
2674 To be used for debugging X11 operations.
2675 If Wine crashes with an X11 error, then you should enable
2676 Synchronous mode to disable X11 request caching in order
2677 to make sure that the X11 error happens directly after
2678 the corresponding X11 call in the log file appears.
2679 Will slow down X11 output!
2680 </para>
2681 </listitem>
2682 </varlistentry>
2683 <varlistentry>
2684 <term>ScreenDepth</term>
2685 <listitem>
2686 <para>
2687 Applies only to multi-depth displays. It specifies
2688 which of the available depths Wine should use (and
2689 tell Windows apps about).
2690 </para>
2691 </listitem>
2692 </varlistentry>
2693 <varlistentry>
2694 <term>Display</term>
2695 <listitem>
2696 <para>
2697 This specifies which X11 display to use, and if
2698 specified, will override the
2699 <envar>DISPLAY</envar> environment variable.
2700 </para>
2701 </listitem>
2702 </varlistentry>
2703 <varlistentry>
2704 <term>PerfectGraphics</term>
2705 <listitem>
2706 <para>
2707 This option only determines whether fast X11 routines
2708 or exact Wine routines will be used for certain ROP
2709 codes in blit operations. Most users won't notice any
2710 difference.
2711 </para>
2712 </listitem>
2713 </varlistentry>
2714 </variablelist>
2715 </sect3>
2716 </sect2>
2718 <sect2>
2719 <title>Configuring the ttydrv graphics driver</title>
2720 <para>
2721 Currently, the ttydrv doesn't have any special configuration
2722 options to set in the configuration file.
2723 </para>
2724 </sect2>
2726 </sect1>
2728 <sect1 id="config-windows-versions">
2730 <title>Setting the Windows and DOS version value</title>
2732 <para>
2733 The windows and DOS version value a program gets e.g. by calling the
2734 Windows function GetVersion() plays a very important role:
2735 If your Wine installation for whatever reason fails to provide
2736 to your program the correct version value that it expects,
2737 then the program might assume some very bad things and fail (in
2738 the worst case even silently!).
2740 Fortunately Wine contains some more or less intelligent Windows
2741 version guessing algorithm that will try to guess the Windows
2742 version a program might expect and pass that one on to the
2743 program.
2745 Thus you should <emphasis>not</emphasis> lightly configure a version value, as this will be a "forced" value and thus turn out to be rather harmful to proper operation. In other words: only explicitly set a Windows version value in case Wine's own version detection was unable to provide the correct Windows version and the program fails.
2746 </para>
2748 <sect2>
2749 <title>How to configure the Windows and DOS version value Wine
2750 should return</title>
2752 <para>
2753 The version values can be configured in the wine configuration file in
2754 the [Version] section.
2755 </para>
2757 <variablelist>
2758 <varlistentry>
2759 <term>"Windows" = "&lt;version string&gt;"</term>
2760 <listitem>
2761 <para>
2762 default: none; chosen by semi-intelligent detection
2763 mechanism based on DLL environment.
2764 Used to specify which Windows version to return to
2765 programs (forced value, overrides standard detection
2766 mechanism!). Valid settings are e.g. "win31", "win95",
2767 "win98", "win2k", "winxp".
2768 Also valid as an
2769 <link linkend="config-appdefaults">AppDefaults</link>
2770 setting (recommended/preferred use).
2771 </para>
2772 </listitem>
2773 </varlistentry>
2774 <varlistentry>
2775 <term>"DOS"="&lt;version string&gt;"</term>
2776 <listitem>
2777 <para>
2778 Used to specify the DOS version that should be returned
2779 to programs. Only takes effect in case Wine acts as
2780 "win31" Windows version! Common DOS version settings
2781 include 6.22, 6.20, 6.00, 5.00, 4.00, 3.30, 3.10.
2782 Also valid as an
2783 <link linkend="config-appdefaults">AppDefaults</link>
2784 setting (recommended/preferred use).
2785 </para>
2786 </listitem>
2787 </varlistentry>
2788 </variablelist>
2789 </sect2>
2790 </sect1>
2792 &fonts;
2793 &printing;
2795 <sect1 id="config-win95look">
2796 <title>Win95/98 Look And Feel</title>
2797 <para>
2798 Instead of compiling Wine for Win3.1 vs. Win95 using
2799 <constant>#define</constant> switches, the code now looks in a
2800 special [Tweak.Layout] section of
2801 <filename>~/.wine/config</filename> for a
2802 <literal>"WineLook" = "Win95"</literal> or
2803 <literal>"WineLook" = "Win98"</literal> entry.
2804 </para>
2805 <para>
2806 A few new sections and a number of entries have been added to
2807 the <filename>~/.wine/config</filename> file -- these are for
2808 debugging the Win95 tweaks only and may be removed in a future
2809 release! These entries/sections are:
2810 </para>
2811 <programlisting>
2812 [Tweak.Fonts]
2813 "System.Height" = "&lt;point size>" # Sets the height of the system typeface
2814 "System.Bold" = "[true|false]" # Whether the system font should be boldfaced
2815 "System.Italic" = "[true|false]" # Whether the system font should be italicized
2816 "System.Underline" = "[true|false]" # Whether the system font should be underlined
2817 "System.StrikeOut" = "[true|false]" # Whether the system font should be struck out
2818 "OEMFixed.xxx" # Same parameters for the OEM fixed typeface
2819 "AnsiFixed.xxx" # Same parameters for the Ansi fixed typeface
2820 "AnsiVar.xxx" # Same parameters for the Ansi variable typeface
2821 "SystemFixed.xxx" # Same parameters for the System fixed typeface
2823 [Tweak.Layout]
2824 "WineLook" = "[Win31|Win95|Win98]" # Changes Wine's look and feel
2825 </programlisting>
2826 </sect1>
2828 <sect1 id="config-keyboard">
2829 <title>Keyboard</title>
2831 <para>
2832 Wine now needs to know about your keyboard layout. This
2833 requirement comes from a need from many apps to have the
2834 correct scancodes available, since they read these directly,
2835 instead of just taking the characters returned by the X
2836 server. This means that Wine now needs to have a mapping from
2837 X keys to the scancodes these programs expect.
2838 </para>
2839 <para>
2840 On startup, Wine will try to recognize the active X layout by
2841 seeing if it matches any of the defined tables. If it does,
2842 everything is alright. If not, you need to define it.
2843 </para>
2844 <para>
2845 To do this, open the file
2846 <filename>dlls/x11drv/keyboard.c</filename> and take a look
2847 at the existing tables. Make a backup copy of it, especially
2848 if you don't use CVS.
2849 </para>
2850 <para>
2851 What you really would need to do, is find out which scancode
2852 each key needs to generate. Find it in the
2853 <function>main_key_scan</function> table, which looks like
2854 this:
2855 </para>
2856 <programlisting>
2857 static const int main_key_scan[MAIN_LEN] =
2859 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
2860 0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,
2861 0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,
2862 0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B,
2863 0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
2864 0x56 /* the 102nd key (actually to the right of l-shift) */
2866 </programlisting>
2867 <para>
2868 Next, assign each scancode the characters imprinted on the
2869 keycaps. This was done (sort of) for the US 101-key keyboard,
2870 which you can find near the top in
2871 <filename>keyboard.c</filename>. It also shows that if there
2872 is no 102nd key, you can skip that.
2873 </para>
2874 <para>
2875 However, for most international 102-key keyboards, we have
2876 done it easy for you. The scancode layout for these already
2877 pretty much matches the physical layout in the
2878 <function>main_key_scan</function>, so all you need to do is
2879 to go through all the keys that generate characters on your
2880 main keyboard (except spacebar), and stuff those into an
2881 appropriate table. The only exception is that the 102nd key,
2882 which is usually to the left of the first key of the last line
2883 (usually <keycap>Z</keycap>), must be placed on a separate
2884 line after the last line.
2885 </para>
2886 <para>
2887 For example, my Norwegian keyboard looks like this
2888 </para>
2889 <screen>
2890 § ! " # ¤ % & / ( ) = ? ` Back-
2891 | 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
2893 Tab Q W E R T Y U I O P Ã… ^
2894 ¨~
2895 Enter
2896 Caps A S D F G H J K L Ø Æ *
2897 Lock '
2899 Sh- > Z X C V B N M ; : _ Shift
2900 ift &lt; , . -
2902 Ctrl Alt Spacebar AltGr Ctrl
2903 </screen>
2904 <para>
2905 Note the 102nd key, which is the <keycap>&lt;></keycap> key, to
2906 the left of <keycap>Z</keycap>. The character to the right of
2907 the main character is the character generated by
2908 <keycap>AltGr</keycap>.
2909 </para>
2910 <para>
2911 This keyboard is defined as follows:
2912 </para>
2913 <programlisting>
2914 static const char main_key_NO[MAIN_LEN][4] =
2916 "|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´",
2917 "qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~",
2918 "aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*",
2919 "zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_",
2920 "&lt;>"
2922 </programlisting>
2923 <para>
2924 Except that " and \ needs to be quoted with a backslash, and
2925 that the 102nd key is on a separate line, it's pretty
2926 straightforward.
2927 </para>
2928 <para>
2929 After you have written such a table, you need to add it to the
2930 <function>main_key_tab[]</function> layout index table. This
2931 will look like this:
2932 </para>
2933 <programlisting>
2934 static struct {
2935 WORD lang, ansi_codepage, oem_codepage;
2936 const char (*key)[MAIN_LEN][4];
2937 } main_key_tab[]={
2940 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &amp;main_key_NO},
2942 </programlisting>
2943 <para>
2944 After you have added your table, recompile Wine and test that
2945 it works. If it fails to detect your table, try running
2946 </para>
2947 <screen>
2948 wine --debugmsg +key,+keyboard >& key.log
2949 </screen>
2950 <para>
2951 and look in the resulting <filename>key.log</filename> file to
2952 find the error messages it gives for your layout.
2953 </para>
2954 <para>
2955 Note that the <constant>LANG_*</constant> and
2956 <constant>SUBLANG_*</constant> definitions are in
2957 <filename>include/winnls.h</filename>, which you might need to
2958 know to find out which numbers your language is assigned, and
2959 find it in the debugmsg output. The numbers will be
2960 <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
2961 the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
2962 <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
2963 <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
2964 could look for <literal>0414</literal> in the debugmsg output
2965 to find out why my keyboard won't detect.
2966 </para>
2967 <para>
2968 Once it works, submit it to the Wine project. If you use CVS,
2969 you will just have to do
2970 </para>
2971 <screen>
2972 cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
2973 </screen>
2974 <para>
2975 from your main Wine directory, then submit
2976 <filename>layout.diff</filename> to
2977 <email>wine-patches@winehq.org</email> along with a brief note
2978 of what it is.
2979 </para>
2980 <para>
2981 If you don't use CVS, you need to do
2982 </para>
2983 <screen>
2984 diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
2985 </screen>
2986 <para>
2987 and submit it as explained above.
2988 </para>
2989 <para>
2990 If you did it right, it will be included in the next Wine
2991 release, and all the troublesome programs (especially
2992 remote-control programs) and games that use scancodes will
2993 be happily using your keyboard layout, and you won't get those
2994 annoying fixme messages either.
2995 </para>
2996 <para>
2997 Good luck.
2998 </para>
2999 </sect1>
3001 <sect1 id="config-scsi-support">
3002 <title>SCSI Support</title>
3003 <para>
3004 This file describes setting up the Windows ASPI interface.
3005 </para>
3007 <para>
3008 <warning><title>Warning/Warning/Warning!!!!!!</title>
3009 <para>This may trash your system if used incorrectly. It may
3010 even trash your system when used <emphasis>correctly</>!
3011 </para>
3012 </warning>
3013 </para>
3015 <para>
3016 Now that I have said that. ASPI is a direct link to SCSI devices from
3017 windows programs. ASPI just forwards the SCSI commands that programs send
3018 to it to the SCSI bus.
3019 </para>
3020 <para>
3021 If you use the wrong SCSI device in your setup file, you can send
3022 completely bogus commands to the wrong device - An example would be
3023 formatting your hard drives (assuming the device gave you permission -
3024 if you're running as root, all bets are off).
3025 </para>
3026 <para>
3027 So please make sure that <emphasis>all</emphasis> SCSI devices not needed by the program
3028 have their permissions set as restricted as possible!
3029 </para>
3031 <para>
3032 Cookbook for setting up scanner: (At least how mine is to work)
3033 (well, for other devices such as CD burners, MO drives, ..., too)
3034 </para>
3036 <sect2>
3037 <title>Windows requirements</title>
3038 <orderedlist>
3039 <listitem>
3040 <para>
3041 The scanner software needs to use the "Adaptec"
3042 compatible drivers (ASPI). At least with Mustek, they
3043 allow you the choice of using the built-in card or the
3044 "Adaptec (AHA)" compatible drivers. This will not work
3045 any other way. Software that accesses the scanner via a
3046 DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM]
3047 </para>
3048 </listitem>
3049 <listitem>
3050 <para>
3051 You probably need a real windows install of the software
3052 to set the LUN's/SCSI id's up correctly. I'm not exactly
3053 sure.
3054 </para>
3055 </listitem>
3056 </orderedlist>
3057 </sect2>
3059 <sect2>
3060 <title>Linux requirements</title>
3061 <orderedlist>
3062 <listitem>
3063 <para>
3064 Your SCSI card must be supported under Linux. This will
3065 not work with an unknown SCSI card. Even for cheap'n
3066 crappy "scanner only" controllers some special Linux
3067 drivers exist on the net.
3068 If you intend to use your IDE device, you need to use the
3069 ide-scsi emulation.
3070 Read
3071 <ulink url="http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html">
3072 http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html</ulink>
3073 for ide-scsi setup instructions.
3074 </para>
3075 </listitem>
3076 <listitem>
3077 <para>
3078 Compile generic SCSI drivers into your kernel.
3079 </para>
3080 </listitem>
3081 <listitem>
3082 <para>
3083 This seems to be not required any more for newer (2.2.x) kernels:
3084 Linux by default uses smaller SCSI buffers than Windows.
3085 There is a kernel build define <literal>SG_BIG_BUFF</literal> (in
3086 <filename>sg.h</filename>) that is by default set too
3087 low. The SANE project recommends
3088 <literal>130560</literal> and this seems to work just
3089 fine. This does require a kernel rebuild.
3090 </para>
3091 </listitem>
3092 <listitem>
3093 <para>
3094 Make the devices for the scanner (generic SCSI devices)
3095 - look at the SCSI programming HOWTO at
3096 <ulink url="http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html">
3097 http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html</ulink>
3098 for device numbering.
3099 </para>
3100 </listitem>
3101 <listitem>
3102 <para>
3103 I would recommend making the scanner device writable by
3104 a group. I made a group called
3105 <literal>scanner</literal> and added myself to it.
3106 Running as root increases your risk of sending bad SCSI
3107 commands to the wrong device. With a regular user, you
3108 are better protected.
3109 </para>
3110 </listitem>
3111 <listitem>
3112 <para>
3113 For Win32 software (WNASPI32), Wine has auto-detection in place.
3114 For Win16 software (WINASPI), you need to add a SCSI device entry
3115 for your particular scanner to ~/.wine/config. The format is
3116 <literal>[scsi cCtTdD]</literal> where
3117 <literal>"C" = "controller"</literal>,
3118 <literal>"T" = "target"</literal>, <literal>D=LUN</literal>
3119 </para>
3120 <para>
3121 For example, I set mine up as controller <literal>0</literal>,
3122 Target <literal>6</literal>, LUN <literal>0</literal>.
3123 <programlisting>
3124 [scsi c0t6d0]
3125 "Device" = "/dev/sgi"
3126 </programlisting>
3127 Yours will vary with your particular SCSI setup.
3128 </para>
3129 </listitem>
3130 </orderedlist>
3131 </sect2>
3133 <sect2>
3134 <title>General Information</title>
3135 <para>
3136 The mustek scanner I have was shipped with a package
3137 "ipplus". This program uses the TWAIN driver specification
3138 to access scanners.
3139 </para>
3140 <para>
3141 (TWAIN MANAGER)
3142 </para>
3143 <para>
3144 <programlisting>
3145 ipplus.exe &lt;-&gt; (TWAIN INTERFACE) &lt;-&gt; (TWAIN DATA SOURCE.ASPI) -&gt; WINASPI
3146 </programlisting>
3147 </para>
3148 </sect2>
3150 <sect2>
3151 <title>NOTES/BUGS</title>
3152 <para>
3153 The biggest drawback is that it only works under Linux at the moment.
3154 </para>
3155 <para>
3156 The ASPI code has only been tested with:
3157 </para>
3158 <itemizedlist>
3159 <listitem>
3160 <para>
3161 a Mustek 800SP with a Buslogic controller under Linux [BM]
3162 </para>
3163 </listitem>
3164 <listitem>
3165 <para>
3166 a Siemens Nixdorf 9036 with Adaptec AVA-1505 under Linux
3167 accessed via DOSASPI. Note that I had color problems,
3168 though (barely readable result) [AM]
3169 </para>
3170 </listitem>
3171 <listitem>
3172 <para>
3173 a Fujitsu M2513A MO drive (640MB) using generic SCSI
3174 drivers. Formatting and ejecting worked perfectly.
3175 Thanks to Uwe Bonnes for access to the hardware! [AM]
3176 </para>
3177 </listitem>
3178 </itemizedlist>
3179 <para>
3180 I make no warranty to the ASPI code. It makes my scanner
3181 work. Your devices may explode. I have no way of determining
3182 this. I take zero responsibility!
3183 </para>
3184 </sect2>
3185 </sect1>
3187 <sect1 id="config-odbc">
3188 <title>Using ODBC</title>
3189 <para>
3190 This section describes how ODBC works within Wine and how to configure
3191 it to do what you want (if it can do what you want).
3192 </para>
3193 <para>
3194 The ODBC system within Wine, as with the printing system, is designed
3195 to hook across to the Unix system at a high level. Rather than
3196 ensuring that all the windows code works under wine it uses a suitable
3197 Unix ODBC provider, such as UnixODBC. Thus if you configure Wine to
3198 use the built-in odbc32.dll, that Wine DLL will interface to your
3199 Unix ODBC package and let that do the work, whereas if you configure
3200 Wine to use the native odbc32.dll it will try to use the native
3201 ODBC32 drivers etc.
3202 </para>
3203 <sect2>
3204 <title>Using a Unix ODBC system with Wine</title>
3205 <para>
3206 The first step in using a Unix ODBC system with Wine is, of course,
3207 to get the Unix ODBC system working itself. This may involve
3208 downloading code or RPMs etc. There are several Unix ODBC systems
3209 available; the one the author is used to is unixODBC (with the
3210 IBM DB2 driver). Typically such systems will include a tool, such
3211 as <command>isql</command>, which will allow you to access the data from the command
3212 line so that you can check that the system is working.
3213 </para>
3214 <para>
3215 The next step is to hook the Unix ODBC library to the wine built-in
3216 odbc32 DLL. The built-in odbc32 (currently) looks to the
3217 environment variable <emphasis>LIB_ODBC_DRIVER_MANAGER</emphasis>
3218 for the name of the ODBC library. For example in the author's
3219 .bashrc file is the line:
3220 </para>
3221 <programlisting>
3222 export LIB_ODBC_DRIVER_MANAGER=/usr/lib/libodbc.so.1.0.0
3223 </programlisting>
3224 <para>
3225 If that environment variable is not set then it looks for a
3226 library called libodbc.so and so you can add a symbolic link to
3227 equate that to your own library. For example as root you could
3228 run the commands:
3229 </para>
3230 <screen>
3231 <prompt># </prompt><userinput>ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so</userinput>
3232 <prompt># </prompt><userinput>/sbin/ldconfig</userinput>
3233 </screen>
3234 <para>
3235 The last step in configuring this is to ensure that Wine is set up
3236 to run the built-in version of odbc32.dll, by modifying the DLL
3237 configuration. This built-in DLL merely acts as a stub between the
3238 calling code and the Unix ODBC library.
3239 </para>
3240 <para>
3241 If you have any problems then you can use the debugmsg channel
3242 odbc32 to trace what is happening. One word of warning. Some
3243 programs actually cheat a little and bypass the ODBC library. For
3244 example the Crystal Reports engine goes to the registry to check on
3245 the DSN. The fix for this is documented at unixODBC's site where
3246 there is a section on using unixODBC with Wine.
3247 </para>
3248 </sect2>
3249 <sect2>
3250 <title>Using Windows ODBC drivers</title>
3251 <para>
3252 Does anyone actually have any experience of this and anything to
3253 add?
3254 </para>
3255 </sect2>
3256 </sect1>
3258 </chapter>
3260 <!-- Keep this comment at the end of the file
3261 Local variables:
3262 mode: sgml
3263 sgml-parent-document:("wine-user.sgml" "set" "book" "chapter" "")
3264 End: