1 <chapter id=
"configuring">
2 <title>Configuring Wine
</title>
3 <para>Setting up config files, etc.
</para>
6 <title>General Configuration
</title>
8 Copyright
1999 &name-adam-sacarny;
<email>&email-adam-sacarny;
</email>
11 (Extracted from
<filename>wine/documentation/config
</filename>)
15 <title>The Wine Config File
</title>
17 The Wine config file stores various settings for Wine. These include:
21 Drives and Information about them
36 The Wine look and feel
49 <title>How Do I Make One?
</title>
51 This section will guide you through the process of making a
52 config file. Take a look at the file
<filename><dirs to
53 wine
>/documentation/samples/config
</filename>. It is organized by section.
56 <informaltable frame=
"all">
60 <entry>Section Name
</entry>
61 <entry>Needed?
</entry>
62 <entry>What it Does
</entry>
67 <entry>[Drive X]
</entry>
69 <entry>Sets up drives recognized by wine
</entry>
74 <entry>Settings for wine directories
</entry>
77 <entry>[DllDefaults]
</entry>
79 <entry>Defaults for loading DLL's
</entry>
82 <entry>[DllPairs]
</entry>
84 <entry>Sanity checkers for DLL's
</entry>
87 <entry>[DllOverrides]
</entry>
89 <entry>Overides defaults for DLL loading
</entry>
92 <entry>[options]
</entry>
94 <entry>No one seems to know
</entry>
97 <entry>[fonts]
</entry>
99 <entry>Font appearance and recognition
</entry>
102 <entry>[serialports]
</entry>
104 <entry>COM ports seen by wine
</entry>
107 <entry>[parallelports]
</entry>
109 <entry>LPT ports seen by wine
</entry>
112 <entry>[spooler]
</entry>
114 <entry>Print spooling
</entry>
117 <entry>[ports]
</entry>
119 <entry>Direct port access
</entry>
124 <entry>What to do with certain debug messages
</entry>
127 <entry>[Registry]
</entry>
129 <entry>Specifies locations of windows registry files
</entry>
132 <entry>[tweak.layout]
</entry>
134 <entry>Appearance of wine
</entry>
137 <entry>[programs]
</entry>
139 <entry>Programs to be run automatically
</entry>
142 <entry>[Console]
</entry>
144 <entry>Console settings
</entry>
151 <title>The [Drive X] Section
</title>
153 It should be pretty self explanatory, but here is an
154 in-depth tutorial about them. There are up to
6 lines for
158 <programlisting>[Drive X]
</programlisting>
159 The above line begins the section for a drive whose letter is X.
162 <programlisting>Path=/dir/to/path
</programlisting> This
163 path is where the drive will begin. When Wine is browsing
164 in drive X, it will see the files that are in the
165 directory
<filename>/dir/to/path
</filename>. Don't forget
166 to leave off the trailing slash!
170 "Type" =
"floppy|hd|cdrom|network" <--- the |'s mean
"Type = "<one of the options
>"
174 Sets up the type of drive Wine will see it as. Type must
175 equal one of the four <literal>floppy</literal>,
176 <literal>hd</literal>, <literal>cdrom</literal>, or
177 <literal>network</literal>. They are self-explanatory.
180 <programlisting>"Label
" = "blah
"</programlisting> Defines the
181 drive label. Generally only needed for programs that look
182 for a special CD-ROM. Info on finding the lable is in
183 <literal><dirs to wine>/documentation/cdrom-labels</literal>.
184 The label may be up to 11 characters.
187 <programlisting>"Serial
" = "deadbeef
"</programlisting>
188 Tells Wine the serial number of the drive. A few programs with
189 intense protection for pirating might need this, but otherwise
190 don't use it. Up to 8 characters and hexadecimal.
193 <programlisting>"Filesystem
" = "msdos|win95|unix
"</programlisting>
194 Sets up the way Wine looks at files on the drive.
199 <term><literal>msdos</literal></term>
202 Case insensitive filesystem. Alike to DOS and
203 Windows 3.x. <literal>8.3</literal> is the maximum
204 length of files (eightdot.123) - longer ones will be
205 truncated. (NOTE: this is a very bad choice if you
206 plan on running apps that use long filenames. win95
207 should work fine with apps that were designed to run
208 under the msdos system. In other words, you might
209 not want to use this.)
214 <term><literal>win95</literal></term>
217 Case insensitive. Alike to Windows 9x/NT 4. This is
218 the long filename filesystem you are probably used
219 to working with. The filesystem of choice for most
220 applications to be run under wine. PROBABLY THE ONE
226 <term><literal>unix</literal></term>
229 Case sensitive. This filesystem has almost no use
230 (Windows apps expect case insensitive filenames).
231 Try it if you dare, but win95 is a much better
238 <programlisting>"Device
" = "/dev/xx
"</programlisting>
240 Use this ONLY for floppy and cdrom devices. Using it on
241 Extended2 partitions can have dire results (when a windows
242 app tries to do a lowlevel write, they do it in a FAT way
243 -- FAT does not mix with Extended2).
247 This setting is not really important; almost all apps
248 will have no problem if it remains unspecified. For
249 CD-ROMs you might want to add it to get automatic label
250 detection, though. If you are unsure about specifying
251 device names, just leave out this setting for your
256 Here is a setup for Drive X, a generic hard drive:
261 "Label
" = "Hard Drive
"
262 "Filesystem
" = "win95
"
263 This is a setup for Drive X, a generic CD-ROM drive:
267 "Label
" = "Total Annihilation
"
268 "Filesystem
" = "win95
"
269 "Device
" = "/dev/hdc
"
270 And here is a setup for Drive X, a generic floppy drive:
273 "Path
" = "/mnt/floppy
"
274 "Label
" = "Floppy Drive
"
275 "Serial
" = "87654321"
276 "Filesystem
" = "win95
"
277 "Device
" = "/dev/fd0
"
283 <title>The [wine] Section </title>
285 The [wine] section of the configuration file contains
286 information wine uses for directories. When specifying the
287 directories for the settings, make them as they would
288 appear in wine. If your drive <medialabel>C</medialabel>
289 has a path of <filename>/dos</filename>, and your
290 <filename>windows</filename> directory is located in
291 <filename>/dos/windows</filename>, then use:
292 <programlisting>"Windows
" = "c:\\windows
"</programlisting>
295 This sets up the <filename>windows</filename> directory.
296 Make one if you don't already have one. NO TRAILING SLASH
297 (NOT <filename>C:\\windows\</filename>)!
300 <programlisting>"System
" = "c:\\windows\\system
"</programlisting>
301 This sets up where the windows system files are. Should
302 reside in the directory used for the
303 <literal>Windows</literal> setting. If you don't have
304 <filename>windows</filename> then this is where the system
305 files will go. Again, NO TRAILING SLASH!
308 <programlisting>"Temp
" = "c:\\temp
"</programlisting> This should
309 be the directory you want your temp files stored in. YOU
310 MUST HAVE WRITE ACCESS TO IT.
314 "Path
" = "c:\\windows;c:\\windows\\system;c:\\blanco
"
318 Behaves like the <envar>PATH</envar> setting on UNIX
319 boxes. When wine is run like <userinput>wine
320 sol.exe</userinput>, if <filename>sol.exe</filename>
321 resides in a directory specified in the
322 <literal>Path</literal> setting, wine will run it (Of
323 course, if <filename>sol.exe</filename> resides in the
324 current directory, wine will run that one). Make sure it
325 always has your <filename>windows</filename> directory and
326 system directory (For this setup, it must have
327 <filename>"c:\\windows;c:\\windows\\system
"</filename>).
330 <programlisting>"SymbolTableFile
" = "wine.sym
"</programlisting>
331 Sets up the symbol table file for the wine debugger. You
332 probably don't need to fiddle with this. May be useful if
333 your wine is stripped.
336 <programlisting>"printer
" = "off|on
"</programlisting> Tells wine
337 whether to allow printer drivers and printing to work.
338 Using these things are pretty alpha, so you might want to
339 watch out. Some people might find it useful, however. If
340 you're not planning on working on printing, don't even add
341 this to your <filename>~/.wine/config</filename> (It probably
342 isn't already in it). Check out the [spooler] and
343 [parallelports] sections too.
348 <title>Introduction To DLL Sections</title>
350 There are a few things you will need to know before
351 configuring the DLL sections in your wine configuration
355 <title>Windows DLL Pairs</title>
357 Most windows DLL's have a win16 (Windows 3.x) and win32
358 (Windows 9x/NT) form. The combination of the win16 and
359 win32 DLL versions are called the "DLL pair
". This is a
360 list of the most common pairs:
373 Is it possible to use native dll with wine?
382 <entry>KERNEL</entry>
383 <entry>KERNEL32</entry>
388 <entry>USER32</entry>
393 <entry>SHELL32</entry>
402 <entry>COMMDLG</entry>
403 <entry>COMDLG32</entry>
408 <entry>VERSION</entry>
417 <title>Different Forms Of DLL's</title>
419 There are a few different forms of DLL's wine can load:
424 The DLL's that are included with windows. Many
425 windows DLL's can be loaded in their native
426 form. Many times these native versions work
427 better than their non-Microsoft equivalent --
428 other times they don't.
434 ELF encapsulated windows DLL's. This is currently
435 experimental (Not working yet).
441 Native ELF libraries. Will not work yet.
447 The most common form of DLL loading. This is
448 what you will use if the DLL is error-prone in
449 native form (KERNEL for example), you don't have
450 the native DLL, or you just want to be
460 <title>The [DllDefaults] Section</title>
462 These settings provide wine's default handling of DLL loading.
465 <programlisting>"DefaultLoadOrder
" =" native, so, builtin
"</programlisting>
468 This setting is a comma-delimited list of which order to
469 attempt loading DLL's. If the first option fails, it will
470 try the second, and so on. The order specified above is
471 probably the best in most conditions.
476 <title>The [DllPairs] Section</title>
478 At one time, there was a section called [DllPairs] in the
479 default configuration file, but this has been obsoleted
480 because the pairing information has now been embedded into
481 Wine itself. (The purpose of this section was merely to be
482 able to issue warnings if the user attempted to pair
483 codependent 16-bit/32-bit DLLs of different types.) If you
484 still have this in your <filename>wine.conf</filename> or
485 <filename>~/.wine/config</filename>, you may safely delete it.
488 <title>The [DllOverrides] Section</title>
490 The format for this section is the same for each line:
492 <DLL>{,<DLL>,<DLL>...} = <FORM>{,<FORM>,<FORM>...}
496 For example, to load builtin KERNEL pair (case doesn't
499 "kernel,kernel32
" = "builtin
"
503 To load the native COMMDLG pair, but if that doesn't work
506 "commdlg,comdlg32
" = "native,builtin
"
510 To load the native COMCTL32:
512 "comctl32
" = "native
"
516 Here is a good generic setup (As it is defined in config
517 that was included with your wine package):
520 "commdlg
" = "builtin, native
"
521 "comdlg32
" = "builtin, native
"
522 "ver
" = "builtin, native
"
523 "version
" = "builtin, native
"
524 "shell
" = "builtin, native
"
525 "shell32
" = "builtin, native
"
526 "lzexpand
" = "builtin, native
"
527 "lz32
" = "builtin, native
"
528 "comctl32
" = "builtin, native
"
529 "commctrl
" = "builtin, native
"
530 "wsock32
" = "builtin
"
531 "winsock
" = "builtin
"
532 "advapi32
" = "builtin, native
"
533 "crtdll
" = "builtin, native
"
534 "mpr
" = "builtin, native
"
535 "winspool.drv
" = "builtin, native
"
536 "ddraw
" = "builtin, native
"
537 "dinput
" = "builtin, native
"
538 "dsound
" = "builtin, native
"
539 "mmsystem
" = "builtin
"
541 "msvcrt
" = "native, builtin
"
542 "msvideo
" = "builtin, native
"
543 "msvfw32
" = "builtin, native
"
544 "mcicda.drv
" = "builtin, native
"
545 "mciseq.drv
" = "builtin, native
"
546 "mciwave.drv
" = "builtin, native
"
547 "mciavi.drv
" = "native, builtin
"
548 "mcianim.drv
" = "native, builtin
"
549 "msacm.drv
" = "builtin, native
"
550 "msacm
" = "builtin, native
"
551 "msacm32
" = "builtin, native
"
552 "midimap.drv
" = "builtin, native
"
553 "wnaspi32
" = "builtin
"
559 You see that elfdll or so is the first option for a few
560 of these dll's. This will fail for you, but you won't
561 notice it as wine will just use the second or third
568 <title>The [options] Section</title>
570 No one seems to know what this section is...
574 "AllocSystemColors
" = "100"
576 System colors to allocate? Just leave it at 100.
581 <title>The [fonts] Section</title>
583 This section sets up wine's font handling.
586 <programlisting>"Resolution
" = "96"</programlisting>
589 Since the way X handles fonts is different from the way
590 Windows does, wine uses a special mechanism to deal with
591 them. It must scale them using the number defined in the
592 "Resolution
" setting. 60-120 are reasonable values, 96 is
593 a nice in the middle one. If you have the real windows
594 fonts available (<filename><dirs to
595 wine>/documentation/ttfserver</filename> and
596 <filename>fonts</filename>), this parameter will not be as
597 important. Of course, it's always good to get your X fonts
598 working acceptably in wine.
601 <programlisting>"Default
" = "-adobe-times-
"</programlisting>
602 The default font wine uses. Fool around with it if you'd like.
608 The <literal>Alias</literal> setting allows you to map an X font to a font
609 used in wine. This is good for apps that need a special font you don't have,
610 but a good replacement exists. The syntax is like so:
612 "AliasX
" = "[Fake windows name],[Real X name]
"<,optional "masking
" section>
616 Pretty straightforward. Replace "AliasX
" with "Alias0
",
617 then "Alias1
" and so on. The fake windows name is the name
618 that the font will be under a windows app in wine. The
619 real X name is the font name as seen by X (Run
620 "xfontsel
"). The optional "masking
" section allows you to
621 utilize the fake windows name you define. If it is not
622 used, then wine will just try to extract the fake windows
623 name itself and not use the value you enter.
626 Here is an example of an alias without masking. The font will show up in windows
627 apps as "Google
". When defining an alias in a config file, forget about my
628 comment text (The "<-- blah
" stuff)
630 "Alias0
" = "Foo,--google-
" <
634 Here is an example with masking enabled. The font will show up as "Foo
" in
637 "Alias1
" = "Foo,--google-,subst
"
641 For more info check out <filename><dirs to wine>/documentation/fonts</filename>
646 <title>The [serialports], [parallelports], [spooler], and [ports] Sections</title>
648 Even though it sounds like a lot of sections, these are
649 all closely related. They are all for communications and
653 The [serialports] section tells wine what serial ports it
655 <programlisting>"ComX
" = "/dev/cuaY
"</programlisting>
658 Replace <literal>X</literal> with the number of the COM
659 port in Windows (1-8) and <literal>Y</literal> with the
660 number of it in <literal>X</literal> (Usually the number
661 of the port in Windows minus 1). <literal>ComX</literal>
662 can actually equal any device
663 (<medialabel>/dev/modem</medialabel> is acceptable). It is
664 not always necessary to define any COM ports (An optional
665 setting). Here is an example:
666 <programlisting>"Com1
" = "/dev/cua0
"</programlisting>
669 Use as many of these as you like in the section to define
670 all of the COM ports you need.
673 The [parallelports] section sets up any parallel ports
674 that will be allowed access under wine.
675 <programlisting>"LptX
" = "/dev/lpY
"</programlisting>
678 Sounds familiar? Syntax is just like the COM port setting.
679 Replace <literal>X</literal> with a value from 1-4 as it
680 is in Windows and <literal>Y</literal> with a value from
681 0-3 (<literal>Y</literal> is usually the value in windows
682 minus 1, just like for COM ports). You don't always need
683 to define a parallel port (AKA, it's optional). As with
684 the other section, LptX can equal any device (Maybe
685 <medialabel>/dev/printer</medialabel>). Here is an
686 example: <programlisting>"Lpt1
" = "/dev/lp0
"</programlisting>
689 The [spooler] section will inform wine where to spool
690 print jobs. Use this if you want to try printing. Wine
691 docs claim that spooling is "rather primitive
" at this
692 time, so it won't work perfectly. IT IS OPTIONAL. The only
693 setting you use in this section works to map a port (LPT1,
694 for example) to a file or a command. Here is an example,
695 mapping LPT1 to the file <filename>out.ps</filename>:
696 <programlisting>"LPT1:
" = "out.ps
"</programlisting>
699 The following command maps printing jobs to LPT1 to the
700 command <command>lpr</command>. Notice the |:
701 <programlisting>"LPT1:
" = "|lpr
"</programlisting>
704 The [ports] section is usually useful only for people who
705 need direct port access for programs requiring dongles or
706 scanners. IF YOU DON'T NEED IT, DON'T USE IT!
709 <programlisting>"read
" = "0x779,
0x379,
0x280-
0x2a0"</programlisting>
710 Gives direct read access to those IO's.
713 <programlisting>"write
" = "0x779,
0x379,
0x280-
0x2a0"</programlisting>
714 Gives direct write access to those IO's. It's probably a
715 good idea to keep the values of the
716 <literal>read</literal> and <literal>write</literal>
717 settings the same. This stuff will only work when you're
723 <title>The [spy], [Registry], [tweak.layout], and [programs] Sections</title>
725 [spy] is used to include or exclude debug messages, and to
726 output them to a file. The latter is rarely used. THESE
727 ARE ALL OPTIONAL AND YOU PROBABLY DON'T NEED TO ADD OR
728 REMOVE ANYTHING IN THIS SECTION TO YOUR CONFIG.
731 <programlisting>"File
" = "/blanco
"</programlisting>
732 Sets the logfile for wine. Set to CON to log to standard out.
736 <programlisting>"Exclude
" = "WM_SIZE;WM_TIMER;
"</programlisting>
737 Excludes debug messages about <constant>WM_SIZE</constant>
738 and <constant>WM_TIMER</constant> in the logfile.
741 <programlisting>"Include
" = "WM_SIZE;WM_TIMER;
"</programlisting>
742 Includes debug messages about <constant>WM_SIZE</constant>
743 and <constant>WM_TIMER</constant> in the logfile.
746 [Registry] can be used to tell wine where your old windows
747 registry files exist. This section is completely optional
748 and useless to people using wine without an existing
749 windows installation.
752 <programlisting>"UserFileName
" = "/dirs/to/user.reg
"</programlisting>
753 The location of your old <filename>user.reg</filename> file.
756 [tweak.layout] is devoted to wine's look. There is only
760 <programlisting>"WineLook
" = "win31|win95|win98
"</programlisting>
761 Will change the look of wine from Windows 3.1 to Windows 95.
762 The <literal>win98</literal> setting behaves
763 just like <literal>win95</literal> most of the time.
766 [programs] can be used to say what programs run under
770 <programlisting>"Default
" = "/program/to/execute.exe
"</programlisting>
771 Sets the program to be run if wine is started without specifying a program.
774 <programlisting>"Startup
" = "/program/to/execute.exe
"</programlisting>
775 Sets the program to automatically be run at startup every time.
781 <title>Where Do I Put It?</title>
783 The wine config file can go in two places.
787 <term><filename>/usr/local/etc/wine.conf</filename></term>
789 A systemwide config file, used for anyone who doesn't
790 have their own. NOTE: this file is currently unused as a
791 new global configuration mechanism is not in place at this
796 <term><filename>$HOME/.wine/config</filename></term>
798 Your own config file, that only is used for your user.
803 So copy your version of the <filename>wine.conf</filename> file to
804 <filename>/usr/local/etc/wine.conf</filename> or
805 <filename>$HOME/.wine/config</filename> for wine to recognize
811 <title>What If It Doesn't Work?</title>
813 There is always a chance that things will go wrong. If the
814 unthinkable happens, try the newsgroup,
815 <systemitem>comp.emulators.ms-windows.wine</systemitem>,
816 or the IRCnet channel <systemitem>#WineHQ</systemitem> found on
817 irc.stealth.net:6668, or connected servers.
818 Make sure that you have looked over this document thoroughly,
823 <para><filename>README</filename></para>
827 <filename>http://www.la-sorciere.de/wine/index.html</filename>
828 (optional but recommended)
833 If indeed it looks like you've done your research, be
834 prepared for helpful suggestions. If you haven't, brace
835 yourself for heaving flaming.
840 <sect1 id="win95look
">
841 <title>Win95/98 Look</title>
843 Written by &name-david-cuthbert; <email>&email-david-cuthbert;</email>
846 (Extracted from <filename>wine/documentation/win95look</filename>)
849 Win95/Win98 interface code is being introduced.
852 Instead of compiling Wine for Win3.1 vs. Win95 using
853 <constant>#define</constant> switches, the code now looks in a
854 special [Tweak.Layout] section of
855 <filename>~/.wine/config</filename> for a
856 <literal>"WineLook
" = "Win95
"</literal> or
857 <literal>"WineLook
" = "Win98
"</literal> entry.
860 A few new sections and a number of entries have been added to
861 the <filename>~/.wine/config</filename> file -- these are for
862 debugging the Win95 tweaks only and may be removed in a future
863 release! These entries/sections are:
867 "System.Height
" = "<point size
>" # Sets the height of the system typeface
868 "System.Bold
" = "[true|false]
" # Whether the system font should be boldfaced
869 "System.Italic
" = "[true|false]
" # Whether the system font should be italicized
870 "System.Underline
" = "[true|false]
" # Whether the system font should be underlined
871 "System.StrikeOut
" = "[true|false]
" # Whether the system font should be struck out
872 "OEMFixed.xxx
" # Same parameters for the OEM fixed typeface
873 "AnsiFixed.xxx
" # Same parameters for the Ansi fixed typeface
874 "AnsiVar.xxx
" # Same parameters for the Ansi variable typeface
875 "SystemFixed.xxx
" # Same parameters for the System fixed typeface
878 "WineLook
" = "[Win31|Win95|Win98]
" # Changes Wine's look and feel
883 <title>Configuring the x11drv Driver</title>
886 Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
889 (Extracted from <filename>wine/documentation/cdrom-labels</filename>)
893 Most Wine users run Wine under the windowing system known as
894 X11. During most of Wine's history, this was the only display
895 driver available, but in recent years, parts of Wine has been
896 reorganized to allow for other display drivers (although the
897 only alternative currently available is Patrik Stridvall's
898 ncurses-based ttydrv, which he claims works for displaying
899 calc.exe). The display driver is chosen with the
900 <literal>GraphicsDriver</literal> option in the [wine] section
901 of <filename>~/.wine/config</filename>, but I will only cover the
902 x11drv driver in this article.
906 <title>x11drv modes of operation</title>
909 The x11drv driver consists of two conceptually distinct
910 pieces, the graphics driver (GDI part), and the windowing
911 driver (USER part). Both of these are linked into the
912 <filename>libx11drv.so</filename> module, though (which you
913 load with the <literal>GraphicsDriver</literal> option). In
914 Wine, running on X11, the graphics driver must draw on
915 drawables (window interiors) provided by the windowing
916 driver. This differs a bit from the Windows model, where the
917 windowing system creates and configures device contexts
918 controlled by the graphics driver, and applications are
919 allowed to hook into this relationship anywhere they like.
920 Thus, to provide any reasonable tradeoff between
921 compatibility and usability, the x11drv has three different
927 <term>Unmanaged/Normal</term>
930 The default. Window-manager-independent (any running
931 window manager is ignored completely). Window
932 decorations (title bars, borders, etc) are drawn by
933 Wine to look and feel like the real Windows. This is
934 compatible with applications that depend on being able
935 to compute the exact sizes of any such decorations, or
936 that want to draw their own.
944 Specified by using the
945 <parameter>--managed</parameter> command-line option
946 or the <literal>Managed</literal>
947 <filename>wine.conf</filename> option (see below).
948 Ordinary top-level frame windows with thick borders,
949 title bars, and system menus will be managed by your
950 window manager. This lets these applications integrate
951 better with the rest of your desktop, but may not
952 always work perfectly. (A rewrite of this mode of
953 operation, to make it more robust and less patchy, is
954 highly desirable, though, and is planned to be done
955 before the Wine 1.0 release.)
960 <term>Desktop-in-a-Box</term>
963 Specified by using the
964 <parameter>--desktop</parameter> command-line option
965 (with a geometry, e.g. <parameter>--desktop
966 800x600</parameter> for a such-sized desktop, or
967 even <parameter>--desktop 800x600+0+0</parameter> to
968 automatically position the desktop at the upper-left
969 corner of the display). This is the mode most
970 compatible with the Windows model. All application
971 windows will just be Wine-drawn windows inside the
972 Wine-provided desktop window (which will itself be
973 managed by your window manager), and Windows
974 applications can roam freely within this virtual
975 workspace and think they own it all, without
976 disturbing your other X apps.
984 <title>The [x11drv] section</title>
988 <term>AllocSystemColors</term>
991 Applies only if you have a palette-based display, i.e.
992 if your X server is set to a depth of 8bpp, and if you
993 haven't requested a private color map. It specifies
994 the maximum number of shared colormap cells (palette
995 entries) Wine should occupy. The higher this value,
996 the less colors will be available to other
1002 <term>PrivateColorMap</term>
1005 Applies only if you have a palette-based display, i.e.
1006 if your X server is set to a depth of 8bpp. It
1007 specifies that you don't want to use the shared color
1008 map, but a private color map, where all 256 colors are
1009 available. The disadvantage is that Wine's private
1010 color map is only seen while the mouse pointer is
1011 inside a Wine window, so psychedelic flashing and
1012 funky colors will become routine if you use the mouse
1018 <term>PerfectGraphics</term>
1021 This option only determines whether fast X11 routines
1022 or exact Wine routines will be used for certain ROP
1023 codes in blit operations. Most users won't notice any
1029 <term>ScreenDepth</term>
1032 Applies only to multi-depth displays. It specifies
1033 which of the available depths Wine should use (and
1034 tell Windows apps about).
1039 <term>Display</term>
1042 This specifies which X11 display to use, and if
1043 specified, will override both the
1044 <envar>DISPLAY</envar> environment variable and the
1045 <parameter>--display</parameter> command-line option.
1050 <term>Managed</term>
1053 Wine can let frame windows be managed by your window
1054 manager. This option specifies whether you want that
1063 This specifies whether you want DirectDraw to use
1064 XFree86's <firstterm>Direct Graphics
1065 Architecture</firstterm> (DGA), which is able to
1066 take over the entire display and run the game
1067 full-screen at maximum speed. (With DGA1 (XFree86
1068 3.x), you still have to configure the X server to the
1069 game's requested bpp first, but with DGA2 (XFree86
1070 4.x), runtime depth-switching may be possible,
1071 depending on your driver's capabilities.) But be aware
1072 that if Wine crashes while in DGA mode, it may not be
1073 possible to regain control over your computer without
1074 rebooting. DGA normally requires either root
1075 privileges or read/write access to
1076 <filename>/dev/mem</filename>.
1081 <term>UseXShm</term>
1084 If you don't want DirectX to use DGA, you can at least
1085 use X Shared Memory extensions (XShm). It is much
1086 slower than DGA, since the app doesn't have direct
1087 access to the physical frame buffer, but using shared
1088 memory to draw the frame is at least faster than
1089 sending the data through the standard X11 socket, even
1090 though Wine's XShm support is still known to crash
1099 If you don't use DGA, you may want an alternative
1100 means to convince the mouse cursor to stay within the
1101 game window. This option does that. Of course, as with
1102 DGA, if Wine crashes, you're in trouble (although not
1103 as badly as in the DGA case, since you can still use
1104 the keyboard to get out of X).
1109 <term>DesktopDoubleBuffered</term>
1112 Applies only if you use the
1113 <parameter>--desktop</parameter> command-line option
1114 to run in a desktop window. Specifies whether to
1115 create the desktop window with a double-buffered
1116 visual, something most OpenGL games need to run
1127 <sect1 id="cdrom-labels
">
1131 <firstname>Petr</firstname>
1132 <surname>Tomasek</surname>
1134 <address><email>&email-petr-tomasek;</email></address>
1136 <contrib>Nov 14 1999</contrib>
1139 <firstname>Andreas</firstname>
1140 <surname>Mohr</surname>
1142 <address><email>&email-andreas-mohr;</email></address>
1144 <contrib>Jan 25 2000</contrib>
1149 <title>Drive labels and serial numbers with wine</title>
1151 Written by &name-petr-tomasek; <email>&email-petr-tomasek;</email>
1155 Changes by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
1159 (Extracted from <filename>wine/documentation/cdrom-labels</filename>)
1162 Until now, your only possibility of specifying drive volume
1163 labels and serial numbers was to set them manually in the wine
1164 config file. By now, wine can read them directly from the
1165 device as well. This may be useful for many Win 9x games or
1166 for setup programs distributed on CD-ROMs that check for
1171 <title>What's Supported?</title>
1173 <informaltable frame="all
">
1177 <entry>File System</entry>
1178 <entry>Types</entry>
1179 <entry>Comment</entry>
1184 <entry>FAT systems</entry>
1185 <entry>hd, floppy</entry>
1186 <entry>reads labels and serial numbers</entry>
1189 <entry>ISO9660</entry>
1190 <entry>cdrom</entry>
1191 <entry>reads labels only</entry>
1200 <title>How To Set Up?</title>
1202 Reading labels and serial numbers just works automagically
1203 if you specify a <literal>Device=</literal> line in the
1204 [Drive X] section in your <filename>~/.wine/config</filename>.
1205 Note that the device has to exist and must be accessible if
1206 you do this, though.
1209 If you don't do that, then you should give fixed
1210 <literal>"Label
" =</literal> or <literal>"Serial
" =</literal>
1211 entries in <filename>~./wine/config</filename>, as Wine returns
1212 these entries instead if no device is given. If they don't
1213 exist, then Wine will return default values (label
1214 <literal>Drive X</literal> and serial
1215 <literal>12345678</literal>).
1218 If you want to give a <literal>"Device
" =</literal> entry
1219 <emphasis>only</emphasis> for drive raw sector accesses,
1220 but not for reading the volume info from the device (i.e. you want
1221 a <emphasis>fixed</emphasis>, preconfigured label), you need
1222 to specify <literal>"ReadVolInfo
" = "0"</literal> to tell Wine
1223 to skip the volume reading.
1228 <title>EXAMPLES</title>
1230 Here's a simple example of cdrom and floppy; labels will be
1231 read from the device on both cdrom and floppy; serial
1232 numbers on floppy only:
1236 "Path
" = "/mnt/floppy
"
1238 "Device
" = "/dev/fd0
"
1239 "Filesystem
" = "msdos
"
1242 "Path
" = "/mnt/cdrom
"
1244 "Device
" = "/dev/hda1
"
1245 "Filesystem
" = "win95
"
1248 Here's an example of overriding the CD-ROM label:
1252 "Path
" = "/mnt/cdrom
"
1254 "Label
" = "X234GCDSE
"
1255 ; note that the device isn't really needed here as we have a fixed label
1256 "Device
" = "/dev/cdrom
"
1257 "Filesystem
" = "msdos
"
1262 <title>Todo / Open Issues</title>
1265 The cdrom label can be read only if the data track of
1266 the disk resides in the first track and the cdrom is
1270 Better checking for FAT superblock (it now checks only
1274 Support for labels/serial nums WRITING.
1277 Can the label be longer than 11 chars? (iso9660 has 32
1281 What about reading ext2 volume label? ....
1287 <sect1 id="dll-overrides
">
1288 <title>Dll Overrides</title>
1291 Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1294 (Extracted from <filename>wine/documentation/dll-overrides</filename>)
1298 The <filename>wine.conf</filename> directives [DllDefaults]
1299 and [DllOverrides] are the subject of some confusion. The
1300 overall purpose of most of these directives are clear enough,
1301 though - given a choice, should Wine use its own built-in
1302 DLLs, or should it use <filename>.DLL</filename> files found
1303 in an existing Windows installation? This document explains
1304 how this feature works.
1308 <title>DLL types</title>
1313 A "native
" DLL is a <filename>.DLL</filename> file
1314 written for the real Microsoft Windows.
1318 <term>builtin</term>
1320 A "builtin
" DLL is a Wine DLL. These can either be a
1321 part of <filename>libwine.so</filename>, or more
1322 recently, in a special <filename>.so</filename> file
1323 that Wine is able to load on demand.
1329 An "elfdll
" is a Wine <filename>.so</filename> file
1330 with a special Windows-like file structure that is as
1331 close to Windows as possible, and that can also
1332 seamlessly link dynamically with "native
" DLLs, by
1333 using special ELF loader and linker tricks. Bertho
1334 Stultiens did some work on this, but this feature has
1335 not yet been merged back into Wine (because of
1336 political reasons and lack of time), so this DLL type
1337 does not exist in the official Wine at this time. In
1338 the meantime, the "builtin
" DLL type gained some of
1339 the features of elfdlls (such as dynamic loading), so
1340 it's possible that "elfdll
" functionality will be
1341 folded into "builtin
" at some point.
1347 A native Unix <filename>.so</filename> file, with
1348 calling convention conversion thunks generated on the
1349 fly as the library is loaded. This is mostly useful
1350 for libraries such as "glide
" that have exactly the
1351 same API on both Windows and Unix.
1358 <title>The [DllDefaults] section</title>
1361 <term>DefaultLoadOrder</term>
1363 This specifies in what order Wine should search for
1364 available DLL types, if the DLL in question was not
1365 found in the [DllOverrides] section.
1372 <title>The [DllPairs] section</title>
1374 At one time, there was a section called [DllPairs] in the
1375 default configuration file, but this has been obsoleted
1376 because the pairing information has now been embedded into
1377 Wine itself. (The purpose of this section was merely to be
1378 able to issue warnings if the user attempted to pair
1379 codependent 16-bit/32-bit DLLs of different types.) If you
1380 still have this in your <filename>wine.conf</filename> or
1381 <filename>~/.wine/config</filename>, you may safely delete it.
1386 <title>The [DllOverrides] section</title>
1388 This section specifies how you want specific DLLs to be
1389 handled, in particular whether you want to use "native
" DLLs
1390 or not, if you have some from a real Windows configuration.
1391 Because builtins do not mix seamlessly with native DLLs yet,
1392 certain DLL dependencies may be problematic, but workarounds
1393 exist in Wine for many popular DLL configurations. Also see
1394 WWN's [16]Status Page to figure out how well your favorite
1395 DLL is implemented in Wine.
1398 It is of course also possible to override these settings by
1399 explictly using Wine's <parameter>--dll</parameter>
1400 command-line option (see the man page for details). Some
1401 hints for choosing your optimal configuration (listed by
1402 16/32-bit DLL pair):
1406 <term>krnl386, kernel32</term>
1408 Native versions of these will never work, so don't try. Leave
1409 at <literal>builtin</literal>.
1413 <term>gdi, gdi32</term>
1415 Graphics Device Interface. No effort has been made at trying to
1416 run native GDI. Leave at <literal>builtin</literal>.
1420 <term>user, user32</term>
1422 Window management and standard controls. It was
1423 possible to use Win95's <literal>native</literal>
1424 versions at some point (if all other DLLs that depend
1425 on it, such as comctl32 and comdlg32, were also run
1426 <literal>native</literal>). However, this is no longer
1427 possible after the Address Space Separation, so leave
1428 at <literal>builtin</literal>.
1434 NT kernel API. Although badly documented, the
1435 <literal>native</literal> version of this will never
1436 work. Leave at <literal>builtin</literal>.
1440 <term>w32skrnl</term>
1442 Win32s (for Win3.x). The <literal>native</literal>
1443 version will probably never work. Leave at
1444 <literal>builtin</literal>.
1450 Win16 support library for NT. The
1451 <literal>native</literal> version will probably never
1452 work. Leave at <literal>builtin</literal>.
1458 Win16 kernel stuff. Will never work
1459 <literal>native</literal>. Leave at
1460 <literal>builtin</literal>.
1464 <term>display</term>
1466 Display driver. Definitely leave at <literal>builtin</literal>.
1470 <term>toolhelp</term>
1472 Tool helper routines. This is rarely a source of problems.
1473 Leave at <literal>builtin</literal>.
1477 <term>ver, version</term>
1479 Versioning. Seldom useful to mess with.
1483 <term>advapi32</term>
1485 Registry and security features. Trying the
1486 <literal>native</literal> version of this may or may
1491 <term>commdlg, comdlg32</term>
1493 Common Dialogs, such as color picker, font dialog,
1494 print dialog, open/save dialog, etc. It is safe to try
1495 <literal>native</literal>.
1499 <term>commctrl, comctl32</term>
1501 Common Controls. This is toolbars, status bars, list controls,
1502 the works. It is safe to try <literal>native</literal>.
1506 <term>shell, shell32</term>
1508 Shell interface (desktop, filesystem, etc). Being one of the
1509 most undocumented pieces of Windows, you may have luck with the
1510 <literal>native</literal> version, should you need it.
1514 <term>winsock, wsock32</term>
1516 Windows Sockets. The <literal>native</literal> version
1517 will not work under Wine, so leave at
1518 <literal>builtin</literal>.
1524 ICMP routines for wsock32. As with wsock32, leave at
1525 <literal>builtin</literal>.
1531 The <literal>native</literal> version may not work due
1532 to thunking issues. Leave at
1533 <literal>builtin</literal>.
1537 <term>lzexpand, lz32</term>
1539 Lempel-Ziv decompression. Wine's
1540 <literal>builtin</literal> version ought to work fine.
1544 <term>winaspi, wnaspi32</term>
1546 Advanced SCSI Peripheral Interface. The
1547 <literal>native</literal> version will probably never
1548 work. Leave at <literal>builtin</literal>.
1554 C Runtime library. The <literal>native</literal>
1555 version will easily work better than Wine's on this
1560 <term>winspool.drv</term>
1562 Printer spooler. You are not likely to have more luck
1563 with the <literal>native</literal> version.
1569 DirectDraw/Direct3D. Since Wine does not implement the
1570 DirectX HAL, the <literal>native</literal> version
1571 will not work at this time.
1577 DirectInput. Running this <literal>native</literal>
1578 may or may not work.
1584 DirectSound. It may be possible to run this
1585 <literal>native</literal>, but don't count on it.
1589 <term>dplay/dplayx</term>
1591 DirectPlay. The <literal>native</literal> version
1592 ought to work best on this, if at all.
1596 <term>mmsystem, winmm</term>
1598 Multimedia system. The <literal>native</literal>
1599 version is not likely to work. Leave at
1600 <literal>builtin</literal>.
1604 <term>msacm, msacm32</term>
1606 Audio Compression Manager. The
1607 <literal>builtin</literal> version works best, if you
1608 set msacm.drv to the same.
1612 <term>msvideo, msvfw32</term>
1614 Video for Windows. It is safe (and recommended) to try
1615 <literal>native</literal>.
1619 <term>mcicda.drv</term>
1621 CD Audio MCI driver.
1625 <term>mciseq.drv</term>
1627 MIDI Sequencer MCI driver (<filename>.MID</filename>
1632 <term>mciwave.drv</term>
1634 Wave audio MCI driver (<filename>.WAV</filename> playback).
1638 <term>mciavi.drv</term>
1640 AVI MCI driver (<filename>.AVI</filename> video
1641 playback). Best to use <literal>native</literal>.
1645 <term>mcianim.drv</term>
1647 Animation MCI driver.
1651 <term>msacm.drv</term>
1653 Audio Compression Manager. Set to same as msacm32.
1657 <term>midimap.drv</term>
1665 This is a pseudo-DLL used by Wine for thunking
1666 purposes. A <literal>native</literal> version of this
1674 <sect1 id="keyboard
">
1675 <title>Keyboard</title>
1678 Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1681 (Extracted from <filename>wine/documentation/keyboard</filename>)
1685 Wine now needs to know about your keyboard layout. This
1686 requirement comes from a need from many apps to have the
1687 correct scancodes available, since they read these directly,
1688 instead of just taking the characters returned by the X
1689 server. This means that Wine now needs to have a mapping from
1690 X keys to the scancodes these applications expect.
1693 On startup, Wine will try to recognize the active X layout by
1694 seeing if it matches any of the defined tables. If it does,
1695 everything is alright. If not, you need to define it.
1698 To do this, open the file
1699 <filename>windows/x11drv/keyboard.c</filename> and take a look
1700 at the existing tables. Make a backup copy of it, especially
1701 if you don't use CVS.
1704 What you really would need to do, is find out which scancode
1705 each key needs to generate. Find it in the
1706 <function>main_key_scan</function> table, which looks like
1710 static const int main_key_scan[MAIN_LEN] =
1712 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
1713 0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,
1714 0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,
1715 0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B,
1716 0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
1717 0x56 /* the 102nd key (actually to the right of l-shift) */
1721 Next, assign each scancode the characters imprinted on the
1722 keycaps. This was done (sort of) for the US 101-key keyboard,
1723 which you can find near the top in
1724 <filename>keyboard.c</filename>. It also shows that if there
1725 is no 102nd key, you can skip that.
1728 However, for most international 102-key keyboards, we have
1729 done it easy for you. The scancode layout for these already
1730 pretty much matches the physical layout in the
1731 <function>main_key_scan</function>, so all you need to do is
1732 to go through all the keys that generate characters on your
1733 main keyboard (except spacebar), and stuff those into an
1734 appropriate table. The only exception is that the 102nd key,
1735 which is usually to the left of the first key of the last line
1736 (usually <keycap>Z</keycap>), must be placed on a separate
1737 line after the last line.
1740 For example, my Norwegian keyboard looks like this
1743 § ! " # ¤ % & / ( ) = ? ` Back-
1744 |
1 2@
3£
4$
5 6 7{
8[
9]
0} + \´ space
1746 Tab Q W E R T Y U I O P Å ^
1749 Caps A S D F G H J K L Ø Æ *
1752 Sh-
> Z X C V B N M ; : _ Shift
1755 Ctrl Alt Spacebar AltGr Ctrl
1758 Note the
102nd key, which is the
<keycap><></keycap> key, to
1759 the left of
<keycap>Z
</keycap>. The character to the right of
1760 the main character is the character generated by
1761 <keycap>AltGr
</keycap>.
1764 This keyboard is defined as follows:
1767 static const char main_key_NO[MAIN_LEN][
4] =
1769 "|§",
"1!",
"2\"@
","3#£
","4¤$
","5%
","6&
","7/{
","8([
","9)]
","0=}
","+?
","\\´
",
1770 "qQ
","wW
","eE
","rR
","tT
","yY
","uU
","iI
","oO
","pP
","åÅ
","¨^~
",
1771 "aA
","sS
","dD
","fF
","gG
","hH
","jJ
","kK
","lL
","øØ
","æÆ
","'*
",
1772 "zZ
","xX
","cC
","vV
","bB
","nN
","mM
",",;
",".:
","-_
",
1777 Except that " and \ needs to be quoted with a backslash, and
1778 that the
102nd key is on a separate line, it's pretty
1782 After you have written such a table, you need to add it to the
1783 <function>main_key_tab[]
</function> layout index table. This
1784 will look like this:
1788 WORD lang, ansi_codepage, oem_codepage;
1789 const char (*key)[MAIN_LEN][
4];
1793 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT),
1252,
865,
&main_key_NO},
1797 After you have added your table, recompile Wine and test that
1798 it works. If it fails to detect your table, try running
1801 wine --debugmsg +key,+keyboard
>& key.log
1804 and look in the resulting
<filename>key.log
</filename> file to
1805 find the error messages it gives for your layout.
1808 Note that the
<constant>LANG_*
</constant> and
1809 <constant>SUBLANG_*
</constant> definitions are in
1810 <filename>include/winnls.h
</filename>, which you might need to
1811 know to find out which numbers your language is assigned, and
1812 find it in the debugmsg output. The numbers will be
1813 <literal>(SUBLANG *
0x400 + LANG)
</literal>, so, for example
1814 the combination
<literal>LANG_NORWEGIAN (
0x14)
</literal> and
1815 <literal>SUBLANG_DEFAULT (
0x1)
</literal> will be (in hex)
1816 <literal>14 +
1*
400 =
414</literal>, so since I'm Norwegian, I
1817 could look for
<literal>0414</literal> in the debugmsg output
1818 to find out why my keyboard won't detect.
1821 Once it works, submit it to the Wine project. If you use CVS,
1822 you will just have to do
1825 cvs -z3 diff -u windows/x11drv/keyboard.c
> layout.diff
1828 from your main Wine directory, then submit
1829 <filename>layout.diff
</filename> to
1830 <email>wine-patches@winehq.com
</email> along with a brief note
1834 If you don't use CVS, you need to do
1837 diff -u the_backup_file_you_made windows/x11drv/keyboard.c
> layout.diff
1840 and submit it as explained above.
1843 If you did it right, it will be included in the next Wine
1844 release, and all the troublesome applications (especially
1845 remote-control applications) and games that use scancodes will
1846 be happily using your keyboard layout, and you won't get those
1847 annoying fixme messages either.
1855 <!-- Keep this comment at the end of the file
1858 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")