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>/wine.ini</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:
263 This is a setup for Drive X, a generic CD-ROM drive:
267 Label=Total Annihilation
270 And here is a setup for Drive X, a generic floppy drive:
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.ini</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>EXTRA_LD_LIBRARY_PATH=/dirs</programlisting>
468 The directory specified here is appended to the normal search
469 path for certain forms of DLL's (elfdll and .so).
472 <programlisting>DefaultLoadOrder = native, elfdll, so, builtin</programlisting>
475 This setting is a comma-delimited list of which order to
476 attempt loading DLL's. If the first option fails, it will
477 try the second, and so on. The order specified above is
478 probably the best in most conditions.
483 <title>The [DllPairs] Section</title>
485 This section is optional, but strongly recommended. If you
486 try to use native SHELL32, but builtin SHELL, you could
487 have some big problems (native and builtin/so/elfdll do
488 certain things in different ways). Using different forms
489 of a pair is a *very*, **very** bad idea. By specifying
490 DLL pairs here, wine will print out a message if you use
491 different forms of a pair. You shouldn't need to change
492 anything in this section, the following should work fine
510 <title>The [DllOverrides] Section</title>
512 The format for this section is the same for each line:
514 <DLL>{,<DLL>,<DLL>...} = <FORM>{,<FORM>,<FORM>...}
518 For example, to load builtin KERNEL pair (case doesn't
521 kernel,kernel32 = builtin
525 To load the native COMMDLG pair, but if that doesn't work
528 commdlg,comdlg32 = native,builtin
532 To load the native COMCTL32:
538 Here is a good generic setup (As it is defined in wine.ini
539 that was included with your wine package):
542 kernel32, gdi32, user32 = builtin
543 kernel, gdi, user = builtin
545 comdlg32, commdlg = elfdll, builtin, native
546 version, ver = elfdll, builtin, native
547 shell32, shell = builtin, native
548 lz32, lzexpand = builtin, native
549 commctrl, comctl32 = builtin, native
550 wsock32, winsock = builtin
551 advapi32, crtdll, ntdll = builtin, native
552 mpr, winspool = builtin, native
553 ddraw, dinput, dsound = builtin, native
554 winmm, w32skrnl, msvfw32= builtin
555 wnaspi32, wow32 = builtin
556 system, display, wprocs = builtin
562 You see that elfdll or so is the first option for a few
563 of these dll's. This will fail for you, but you won't
564 notice it as wine will just use the second or third
571 <title>The [options] Section</title>
573 No one seems to know what this section is...
577 AllocSystemColors=100
579 System colors to allocate? Just leave it at 100.
584 <title>The [fonts] Section</title>
586 This section sets up wine's font handling.
589 <programlisting>Resolution = 96</programlisting>
592 Since the way X handles fonts is different from the way
593 Windows does, wine uses a special mechanism to deal with
594 them. It must scale them using the number defined in the
595 "Resolution" setting. 60-120 are reasonable values, 96 is
596 a nice in the middle one. If you have the real windows
597 fonts available (<filename><dirs to
598 wine>/documentation/ttfserver</filename> and
599 <filename>fonts</filename>), this parameter will not be as
600 important. Of course, it's always good to get your X fonts
601 working acceptably in wine.
604 <programlisting>Default = -adobe-times-</programlisting>
605 The default font wine uses. Fool around with it if you'd like.
611 The <literal>Alias</literal> setting allows you to map an X font to a font
612 used in wine. This is good for apps that need a special font you don't have,
613 but a good replacement exists. The syntax is like so:
615 AliasX = [Fake windows name],[Real X name]<,optional "masking" section>
619 Pretty straightforward. Replace "AliasX" with "Alias0",
620 then "Alias1" and so on. The fake windows name is the name
621 that the font will be under a windows app in wine. The
622 real X name is the font name as seen by X (Run
623 "xfontsel"). The optional "masking" section allows you to
624 utilize the fake windows name you define. If it is not
625 used, then wine will just try to extract the fake windows
626 name itself and not use the value you enter.
629 Here is an example of an alias without masking. The font will show up in windows
630 apps as "Google". When defining an alias in a config file, forget about my
631 comment text (The "<-- blah" stuff)
633 Alias0 = Foo,--google- <-- Note the no spaces after the " = ". Important!
637 Here is an example with masking enabled. The font will show up as "Foo" in
640 Alias1 = Foo,--google-,subst
644 For more info check out <filename><dirs to wine>/documentation/fonts</filename>
649 <title>The [serialports], [parallelports], [spooler], and [ports] Sections</title>
651 Even though it sounds like a lot of sections, these are
652 all closely related. They are all for communications and
656 The [serialports] section tells wine what serial ports it
658 <programlisting>ComX=/dev/cuaY</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/cua0</programlisting>
672 Use as many of these as you like in the section to define
673 all of the COM ports you need.
676 The [parallelports] section sets up any parallel ports
677 that will be allowed access under wine.
678 <programlisting>LptX=/dev/lpY</programlisting>
681 Sounds familiar? Syntax is just like the COM port setting.
682 Replace <literal>X</literal> with a value from 1-4 as it
683 is in Windows and <literal>Y</literal> with a value from
684 0-3 (<literal>Y</literal> is usually the value in windows
685 minus 1, just like for COM ports). You don't always need
686 to define a parallel port (AKA, it's optional). As with
687 the other section, LptX can equal any device (Maybe
688 <medialabel>/dev/printer</medialabel>). Here is an
689 example: <programlisting>Lpt1=/dev/lp0</programlisting>
692 The [spooler] section will inform wine where to spool
693 print jobs. Use this if you want to try printing. Wine
694 docs claim that spooling is "rather primitive" at this
695 time, so it won't work perfectly. IT IS OPTIONAL. The only
696 setting you use in this section works to map a port (LPT1,
697 for example) to a file or a command. Here is an example,
698 mapping LPT1 to the file <filename>out.ps</filename>:
699 <programlisting>LPT1:=out.ps</programlisting>
702 The following command maps printing jobs to LPT1 to the
703 command <command>lpr</command>. Notice the |:
704 <programlisting>LPT1:=|lpr</programlisting>
707 The [ports] section is usually useful only for people who
708 need direct port access for programs requiring dongles or
709 scanners. IF YOU DON'T NEED IT, DON'T USE IT!
712 <programlisting>read=0x779,0x379,0x280-0x2a0</programlisting>
713 Gives direct read access to those IO's.
716 <programlisting>write=0x779,0x379,0x280-0x2a0</programlisting>
717 Gives direct write access to those IO's. It's probably a
718 good idea to keep the values of the
719 <literal>read</literal> and <literal>write</literal>
720 settings the same. This stuff will only work when you're
726 <title>The [spy], [Registry], [tweak.layout], and [programs] Sections</title>
728 [spy] is used to include or exclude debug messages, and to
729 output them to a file. The latter is rarely used. THESE
730 ARE ALL OPTIONAL AND YOU PROBABLY DON'T NEED TO ADD OR
731 REMOVE ANYTHING IN THIS SECTION TO YOUR CONFIG.
734 <programlisting>File=/blanco</programlisting>
735 Sets the logfile for wine. Set to CON to log to standard out.
739 <programlisting>Exclude=WM_SIZE;WM_TIMER;</programlisting>
740 Excludes debug messages about <constant>WM_SIZE</constant>
741 and <constant>WM_TIMER</constant> in the logfile.
744 <programlisting>Include=WM_SIZE;WM_TIMER;</programlisting>
745 Includes debug messages about <constant>WM_SIZE</constant>
746 and <constant>WM_TIMER</constant> in the logfile.
749 [Registry] can be used to tell wine where your old windows
750 registry files exist. This section is completely optional
751 and useless to people using wine without an existing
752 windows installation.
755 <programlisting>UserFileName=/dirs/to/user.reg</programlisting>
756 The location of your old <filename>user.reg</filename> file.
759 <programlisting>LocalMachineFileName=/dirs/to/system.reg</programlisting>
760 The location of your old <filename>system.reg</filename> file.
763 [tweak.layout] is devoted to wine's look. There is only
767 <programlisting>WineLook=win31|win95|win98</programlisting>
768 Will change the look of wine from Windows 3.1 to Windows 95.
769 The <literal>win98</literal> setting behaves
770 just like <literal>win95</literal> most of the time.
773 [programs] can be used to say what programs run under
777 <programlisting>Default=/program/to/execute.exe</programlisting>
778 Sets the program to be run if wine is started without specifying a program.
781 <programlisting>Startup=/program/to/execute.exe</programlisting>
782 Sets the program to automatically be run at startup every time.
788 <title>Where Do I Put It?</title>
790 The wine config file can go in two places.
794 <term><filename>/usr/local/etc/wine.conf</filename></term>
796 A systemwide config file, used for anyone who doesn't
801 <term><filename>$HOME/.winerc</filename></term>
803 Your own config file, that only is used for your user.
808 So copy your version of the <filename>wine.conf</filename> file to
809 <filename>/usr/local/etc/wine.conf</filename> or
810 <filename>$HOME/.winerc</filename> for wine to recognize it.
815 <title>What If It Doesn't Work?</title>
817 There is always a chance that things will go wrong. If the
818 unthinkable happens, try the newsgroup,
819 <systemitem>comp.emulators.ms-windows.wine</systemitem>,
820 or the IRCnet channel <systemitem>#WineHQ</systemitem>.
821 Make sure that you have looked over this document thoroughly,
826 <para><filename>README</filename></para>
830 <filename>http://www.la-sorciere.de/wine/index.html</filename>
831 (optional but recommended)
836 If indeed it looks like you've done your research, be
837 prepared for helpful suggestions. If you haven't, brace
838 yourself for heaving flaming.
843 <sect1 id="win95look">
844 <title>Win95/98 Look</title>
846 Written by &name-david-cuthbert; <email>&email-david-cuthbert;</email>
849 (Extracted from <filename>wine/documentation/win95look</filename>)
852 Win95/Win98 interface code is being introduced.
855 Instead of compiling Wine for Win3.1 vs. Win95 using
856 <constant>#define</constant> switches, the code now looks in a
857 special [Tweak.Layout] section of
858 <filename>wine.conf</filename> for a
859 <literal>WineLook=Win95</literal> or
860 <literal>WineLook=Win98</literal> entry.
863 A few new sections and a number of entries have been added to
864 the <filename>wine.conf file</filename> -- these are for
865 debugging the Win95 tweaks only and may be removed in a future
866 release! These entries/sections are:
870 System.Height=<point size> # Sets the height of the system typeface
871 System.Bold=[true|false] # Whether the system font should be boldfaced
872 System.Italic=[true|false] # Whether the system font should be italicized
873 System.Underline=[true|false] # Whether the system font should be underlined
874 System.StrikeOut=[true|false] # Whether the system font should be struck out
875 OEMFixed.xxx # Same parameters for the OEM fixed typeface
876 AnsiFixed.xxx # Same parameters for the Ansi fixed typeface
877 AnsiVar.xxx # Same parameters for the Ansi variable typeface
878 SystemFixed.xxx # Same parameters for the System fixed typeface
881 WineLook=[Win31|Win95|Win98] # Changes Wine's look and feel
886 <title>Configuring the x11drv Driver</title>
889 Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
892 (Extracted from <filename>wine/documentation/cdrom-labels</filename>)
896 Most Wine users run Wine under the windowing system known as
897 X11. During most of Wine's history, this was the only display
898 driver available, but in recent years, parts of Wine has been
899 reorganized to allow for other display drivers (although the
900 only alternative currently available is Patrik Stridvall's
901 ncurses-based ttydrv, which he claims works for displaying
902 calc.exe). The display driver is chosen with the
903 <literal>GraphicsDriver</literal> option in the [wine] section
904 of <filename>wine.conf</filename> or
905 <filename>.winerc</filename>, but I will only cover the x11drv
906 driver in this article.
910 <title>x11drv modes of operation</title>
913 The x11drv driver consists of two conceptually distinct
914 pieces, the graphics driver (GDI part), and the windowing
915 driver (USER part). Both of these are linked into the
916 <filename>libx11drv.so</filename> module, though (which you
917 load with the <literal>GraphicsDriver</literal> option). In
918 Wine, running on X11, the graphics driver must draw on
919 drawables (window interiors) provided by the windowing
920 driver. This differs a bit from the Windows model, where the
921 windowing system creates and configures device contexts
922 controlled by the graphics driver, and applications are
923 allowed to hook into this relationship anywhere they like.
924 Thus, to provide any reasonable tradeoff between
925 compatibility and usability, the x11drv has three different
931 <term>Unmanaged/Normal</term>
934 The default. Window-manager-independent (any running
935 window manager is ignored completely). Window
936 decorations (title bars, borders, etc) are drawn by
937 Wine to look and feel like the real Windows. This is
938 compatible with applications that depend on being able
939 to compute the exact sizes of any such decorations, or
940 that want to draw their own.
948 Specified by using the
949 <parameter>--managed</parameter> command-line option
950 or the <literal>Managed</literal>
951 <filename>wine.conf</filename> option (see below).
952 Ordinary top-level frame windows with thick borders,
953 title bars, and system menus will be managed by your
954 window manager. This lets these applications integrate
955 better with the rest of your desktop, but may not
956 always work perfectly. (A rewrite of this mode of
957 operation, to make it more robust and less patchy, is
958 highly desirable, though, and is planned to be done
959 before the Wine 1.0 release.)
964 <term>Desktop-in-a-Box</term>
967 Specified by using the
968 <parameter>--desktop</parameter> command-line option
969 (with a geometry, e.g. <parameter>--desktop
970 800x600</parameter> for a such-sized desktop, or
971 even <parameter>--desktop 800x600+0+0</parameter> to
972 automatically position the desktop at the upper-left
973 corner of the display). This is the mode most
974 compatible with the Windows model. All application
975 windows will just be Wine-drawn windows inside the
976 Wine-provided desktop window (which will itself be
977 managed by your window manager), and Windows
978 applications can roam freely within this virtual
979 workspace and think they own it all, without
980 disturbing your other X apps.
988 <title>The [x11drv] section</title>
992 <term>AllocSystemColors</term>
995 Applies only if you have a palette-based display, i.e.
996 if your X server is set to a depth of 8bpp, and if you
997 haven't requested a private color map. It specifies
998 the maximum number of shared colormap cells (palette
999 entries) Wine should occupy. The higher this value,
1000 the less colors will be available to other
1006 <term>PrivateColorMap</term>
1009 Applies only if you have a palette-based display, i.e.
1010 if your X server is set to a depth of 8bpp. It
1011 specifies that you don't want to use the shared color
1012 map, but a private color map, where all 256 colors are
1013 available. The disadvantage is that Wine's private
1014 color map is only seen while the mouse pointer is
1015 inside a Wine window, so psychedelic flashing and
1016 funky colors will become routine if you use the mouse
1022 <term>PerfectGraphics</term>
1025 This option only determines whether fast X11 routines
1026 or exact Wine routines will be used for certain ROP
1027 codes in blit operations. Most users won't notice any
1033 <term>ScreenDepth</term>
1036 Applies only to multi-depth displays. It specifies
1037 which of the available depths Wine should use (and
1038 tell Windows apps about).
1043 <term>Display</term>
1046 This specifies which X11 display to use, and if
1047 specified, will override both the
1048 <envar>DISPLAY</envar> environment variable and the
1049 <parameter>--display</parameter> command-line option.
1054 <term>Managed</term>
1057 Wine can let frame windows be managed by your window
1058 manager. This option specifies whether you want that
1067 This specifies whether you want DirectDraw to use
1068 XFree86's <firstterm>Direct Graphics
1069 Architecture</firstterm> (DGA), which is able to
1070 take over the entire display and run the game
1071 full-screen at maximum speed. (With DGA1 (XFree86
1072 3.x), you still have to configure the X server to the
1073 game's requested bpp first, but with DGA2 (XFree86
1074 4.x), runtime depth-switching may be possible,
1075 depending on your driver's capabilities.) But be aware
1076 that if Wine crashes while in DGA mode, it may not be
1077 possible to regain control over your computer without
1078 rebooting. DGA normally requires either root
1079 privileges or read/write access to
1080 <filename>/dev/mem</filename>.
1085 <term>UseXShm</term>
1088 If you don't want DirectX to use DGA, you can at least
1089 use X Shared Memory extensions (XShm). It is much
1090 slower than DGA, since the app doesn't have direct
1091 access to the physical frame buffer, but using shared
1092 memory to draw the frame is at least faster than
1093 sending the data through the standard X11 socket, even
1094 though Wine's XShm support is still known to crash
1103 If you don't use DGA, you may want an alternative
1104 means to convince the mouse cursor to stay within the
1105 game window. This option does that. Of course, as with
1106 DGA, if Wine crashes, you're in trouble (although not
1107 as badly as in the DGA case, since you can still use
1108 the keyboard to get out of X).
1113 <term>DesktopDoubleBuffered</term>
1116 Applies only if you use the
1117 <parameter>--desktop</parameter> command-line option
1118 to run in a desktop window. Specifies whether to
1119 create the desktop window with a double-buffered
1120 visual, something most OpenGL games need to run
1131 <sect1 id="cdrom-labels">
1135 <firstname>Petr</firstname>
1136 <surname>Tomasek</surname>
1138 <address><email>&email-petr-tomasek;</email></address>
1140 <contrib>Nov 14 1999</contrib>
1143 <firstname>Andreas</firstname>
1144 <surname>Mohr</surname>
1146 <address><email>&email-andreas-mohr;</email></address>
1148 <contrib>Jan 25 2000</contrib>
1153 <title>Drive labels and serial numbers with wine</title>
1155 Written by &name-petr-tomasek; <email>&email-petr-tomasek;</email>
1159 Changes by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
1163 (Extracted from <filename>wine/documentation/cdrom-labels</filename>)
1166 Until now, your only possibility of specifying drive volume
1167 labels and serial numbers was to set them manually in the wine
1168 config file. By now, wine can read them directly from the
1169 device as well. This may be useful for many Win 9x games or
1170 for setup programs distributed on CD-ROMs that check for
1175 <title>What's Supported?</title>
1177 <informaltable frame="all">
1181 <entry>File System</entry>
1182 <entry>Types</entry>
1183 <entry>Comment</entry>
1188 <entry>FAT systems</entry>
1189 <entry>hd, floppy</entry>
1190 <entry>reads labels and serial numbers</entry>
1193 <entry>ISO9660</entry>
1194 <entry>cdrom</entry>
1195 <entry>reads labels only</entry>
1204 <title>How To Set Up?</title>
1206 Reading labels and serial numbers just works automagically
1207 if you specify a <literal>Device=</literal> line in the
1208 [Drive X] section in your <filename>wine.conf</filename>.
1209 Note that the device has to exist and must be accessible if
1210 you do this, though.
1213 If you don't do that, then you should give fixed
1214 <literal>Label=</literal> or <literal>Serial=</literal>
1215 entries in <filename>wine.conf</filename>, as Wine returns
1216 these entries instead if no device is given. If they don't
1217 exist, then Wine will return default values (label
1218 <literal>Drive X</literal> and serial
1219 <literal>12345678</literal>).
1222 If you want to give a <literal>Device=</literal> entry
1223 <emphasis>only</emphasis> for drive raw sector accesses,
1224 but not for reading the volume info from the device (i.e. you want
1225 a <emphasis>fixed</emphasis>, preconfigured label), you need
1226 to specify <literal>ReadVolInfo=0</literal> to tell Wine to
1227 skip the volume reading.
1232 <title>EXAMPLES</title>
1234 Here's a simple example of cdrom and floppy; labels will be
1235 read from the device on both cdrom and floppy; serial
1236 numbers on floppy only:
1252 Here's an example of overriding the CD-ROM label:
1259 ; note that the device isn't really needed here as we have a fixed label
1266 <title>Todo / Open Issues</title>
1269 The cdrom label can be read only if the data track of
1270 the disk resides in the first track and the cdrom is
1274 Better checking for FAT superblock (it now checks only
1278 Support for labels/serial nums WRITING.
1281 Can the label be longer than 11 chars? (iso9660 has 32
1285 What about reading ext2 volume label? ....
1291 <sect1 id="dll-overrides">
1292 <title>Dll Overrides</title>
1295 Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1298 (Extracted from <filename>wine/documentation/dll-overrides</filename>)
1302 The <filename>wine.conf</filename> directives [DllDefaults]
1303 and [DllOverrides] are the subject of some confusion. The
1304 overall purpose of most of these directives are clear enough,
1305 though - given a choice, should Wine use its own built-in
1306 DLLs, or should it use <filename>.DLL</filename> files found
1307 in an existing Windows installation? This document explains
1308 how this feature works.
1312 <title>DLL types</title>
1317 A "native" DLL is a <filename>.DLL</filename> file
1318 written for the real Microsoft Windows.
1322 <term>builtin</term>
1324 A "builtin" DLL is a Wine DLL. These can either be a
1325 part of <filename>libwine.so</filename>, or more
1326 recently, in a special <filename>.so</filename> file
1327 that Wine is able to load on demand.
1333 An "elfdll" is a Wine <filename>.so</filename> file
1334 with a special Windows-like file structure that is as
1335 close to Windows as possible, and that can also
1336 seamlessly link dynamically with "native" DLLs, by
1337 using special ELF loader and linker tricks. Bertho
1338 Stultiens did some work on this, but this feature has
1339 not yet been merged back into Wine (because of
1340 political reasons and lack of time), so this DLL type
1341 does not exist in the official Wine at this time. In
1342 the meantime, the "builtin" DLL type gained some of
1343 the features of elfdlls (such as dynamic loading), so
1344 it's possible that "elfdll" functionality will be
1345 folded into "builtin" at some point.
1351 A native Unix <filename>.so</filename> file, with
1352 calling convention conversion thunks generated on the
1353 fly as the library is loaded. This is mostly useful
1354 for libraries such as "glide" that have exactly the
1355 same API on both Windows and Unix.
1362 <title>The [DllDefaults] section</title>
1365 <term>EXTRA_LD_LIBRARY_PATH</term>
1367 This specifies the location of the Wine's DLL
1368 <filename>.so</filename> files. Wine will search this
1369 path when trying to locate a DLL of the type
1370 <literal>builtin</literal> or
1371 <literal>elfdll</literal>. (This does not apply to
1372 <filename>libwine.so</filename>, since
1373 <filename>libwine.so</filename> is not a DLL in this
1378 <term>DefaultLoadOrder</term>
1380 This specifies in what order Wine should search for
1381 available DLL types, if the DLL in question was not
1382 found in the [DllOverrides] section.
1389 <title>The [DllPairs] section</title>
1391 At one time, there was a section called [DllPairs] in the
1392 default configuration file, but this has been obsoleted
1393 because the pairing information has now been embedded into
1394 Wine itself. (The purpose of this section was merely to be
1395 able to issue warnings if the user attempted to pair
1396 codependent 16-bit/32-bit DLLs of different types.) If you
1397 still have this in your <filename>wine.conf</filename> or
1398 <filename>.winerc</filename>, you may safely delete it.
1403 <title>The [DllOverrides] section</title>
1405 This section specifies how you want specific DLLs to be
1406 handled, in particular whether you want to use "native" DLLs
1407 or not, if you have some from a real Windows configuration.
1408 Because builtins do not mix seamlessly with native DLLs yet,
1409 certain DLL dependencies may be problematic, but workarounds
1410 exist in Wine for many popular DLL configurations. Also see
1411 WWN's [16]Status Page to figure out how well your favorite
1412 DLL is implemented in Wine.
1415 It is of course also possible to override these settings by
1416 explictly using Wine's <parameter>--dll</parameter>
1417 command-line option (see the man page for details). Some
1418 hints for choosing your optimal configuration (listed by
1419 16/32-bit DLL pair):
1423 <term>krnl386, kernel32</term>
1425 Native versions of these will never work, so don't try. Leave
1426 at <literal>builtin</literal>.
1430 <term>gdi, gdi32</term>
1432 Graphics Device Interface. No effort has been made at trying to
1433 run native GDI. Leave at <literal>builtin</literal>.
1437 <term>user, user32</term>
1439 Window management and standard controls. It was
1440 possible to use Win95's <literal>native</literal>
1441 versions at some point (if all other DLLs that depend
1442 on it, such as comctl32 and comdlg32, were also run
1443 <literal>native</literal>). However, this is no longer
1444 possible after the Address Space Separation, so leave
1445 at <literal>builtin</literal>.
1451 NT kernel API. Although badly documented, the
1452 <literal>native</literal> version of this will never
1453 work. Leave at <literal>builtin</literal>.
1457 <term>w32skrnl</term>
1459 Win32s (for Win3.x). The <literal>native</literal>
1460 version will probably never work. Leave at
1461 <literal>builtin</literal>.
1467 Win16 support library for NT. The
1468 <literal>native</literal> version will probably never
1469 work. Leave at <literal>builtin</literal>.
1475 Win16 kernel stuff. Will never work
1476 <literal>native</literal>. Leave at
1477 <literal>builtin</literal>.
1481 <term>display</term>
1483 Display driver. Definitely leave at <literal>builtin</literal>.
1487 <term>toolhelp</term>
1489 Tool helper routines. This is rarely a source of problems.
1490 Leave at <literal>builtin</literal>.
1494 <term>ver, version</term>
1496 Versioning. Seldom useful to mess with.
1500 <term>advapi32</term>
1502 Registry and security features. Trying the
1503 <literal>native</literal> version of this may or may
1508 <term>commdlg, comdlg32</term>
1510 Common Dialogs, such as color picker, font dialog,
1511 print dialog, open/save dialog, etc. It is safe to try
1512 <literal>native</literal>.
1516 <term>commctrl, comctl32</term>
1518 Common Controls. This is toolbars, status bars, list controls,
1519 the works. It is safe to try <literal>native</literal>.
1523 <term>shell, shell32</term>
1525 Shell interface (desktop, filesystem, etc). Being one of the
1526 most undocumented pieces of Windows, you may have luck with the
1527 <literal>native</literal> version, should you need it.
1531 <term>winsock, wsock32</term>
1533 Windows Sockets. The <literal>native</literal> version
1534 will not work under Wine, so leave at
1535 <literal>builtin</literal>.
1541 ICMP routines for wsock32. As with wsock32, leave at
1542 <literal>builtin</literal>.
1548 The <literal>native</literal> version may not work due
1549 to thunking issues. Leave at
1550 <literal>builtin</literal>.
1554 <term>lzexpand, lz32</term>
1556 Lempel-Ziv decompression. Wine's
1557 <literal>builtin</literal> version ought to work fine.
1561 <term>winaspi, wnaspi32</term>
1563 Advanced SCSI Peripheral Interface. The
1564 <literal>native</literal> version will probably never
1565 work. Leave at <literal>builtin</literal>.
1571 C Runtime library. The <literal>native</literal>
1572 version will easily work better than Wine's on this
1577 <term>winspool.drv</term>
1579 Printer spooler. You are not likely to have more luck
1580 with the <literal>native</literal> version.
1586 DirectDraw/Direct3D. Since Wine does not implement the
1587 DirectX HAL, the <literal>native</literal> version
1588 will not work at this time.
1594 DirectInput. Running this <literal>native</literal>
1595 may or may not work.
1601 DirectSound. It may be possible to run this
1602 <literal>native</literal>, but don't count on it.
1606 <term>dplay/dplayx</term>
1608 DirectPlay. The <literal>native</literal> version
1609 ought to work best on this, if at all.
1613 <term>mmsystem, winmm</term>
1615 Multimedia system. The <literal>native</literal>
1616 version is not likely to work. Leave at
1617 <literal>builtin</literal>.
1621 <term>msacm, msacm32</term>
1623 Audio Compression Manager. The
1624 <literal>builtin</literal> version works best, if you
1625 set msacm.drv to the same.
1629 <term>msvideo, msvfw32</term>
1631 Video for Windows. It is safe (and recommended) to try
1632 <literal>native</literal>.
1636 <term>mcicda.drv</term>
1638 CD Audio MCI driver.
1642 <term>mciseq.drv</term>
1644 MIDI Sequencer MCI driver (<filename>.MID</filename>
1649 <term>mciwave.drv</term>
1651 Wave audio MCI driver (<filename>.WAV</filename> playback).
1655 <term>mciavi.drv</term>
1657 AVI MCI driver (<filename>.AVI</filename> video
1658 playback). Best to use <literal>native</literal>.
1662 <term>mcianim.drv</term>
1664 Animation MCI driver.
1668 <term>msacm.drv</term>
1670 Audio Compression Manager. Set to same as msacm32.
1674 <term>midimap.drv</term>
1682 This is a pseudo-DLL used by Wine for thunking
1683 purposes. A <literal>native</literal> version of this
1691 <sect1 id="keyboard">
1692 <title>Keyboard</title>
1695 Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1698 (Extracted from <filename>wine/documentation/keyboard</filename>)
1702 Wine now needs to know about your keyboard layout. This
1703 requirement comes from a need from many apps to have the
1704 correct scancodes available, since they read these directly,
1705 instead of just taking the characters returned by the X
1706 server. This means that Wine now needs to have a mapping from
1707 X keys to the scancodes these applications expect.
1710 On startup, Wine will try to recognize the active X layout by
1711 seeing if it matches any of the defined tables. If it does,
1712 everything is alright. If not, you need to define it.
1715 To do this, open the file
1716 <filename>windows/x11drv/keyboard.c</filename> and take a look
1717 at the existing tables. Make a backup copy of it, especially
1718 if you don't use CVS.
1721 What you really would need to do, is find out which scancode
1722 each key needs to generate. Find it in the
1723 <function>main_key_scan</function> table, which looks like
1727 static const int main_key_scan[MAIN_LEN] =
1729 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
1730 0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,
1731 0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,
1732 0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B,
1733 0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
1734 0x56 /* the 102nd key (actually to the right of l-shift) */
1738 Next, assign each scancode the characters imprinted on the
1739 keycaps. This was done (sort of) for the US 101-key keyboard,
1740 which you can find near the top in
1741 <filename>keyboard.c</filename>. It also shows that if there
1742 is no 102nd key, you can skip that.
1745 However, for most international 102-key keyboards, we have
1746 done it easy for you. The scancode layout for these already
1747 pretty much matches the physical layout in the
1748 <function>main_key_scan</function>, so all you need to do is
1749 to go through all the keys that generate characters on your
1750 main keyboard (except spacebar), and stuff those into an
1751 appropriate table. The only exception is that the 102nd key,
1752 which is usually to the left of the first key of the last line
1753 (usually <keycap>Z</keycap>), must be placed on a separate
1754 line after the last line.
1757 For example, my Norwegian keyboard looks like this
1760 § ! " # ¤ % & / ( ) = ? ` Back-
1761 | 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
1763 Tab Q W E R T Y U I O P Å ^
1766 Caps A S D F G H J K L Ø Æ *
1769 Sh- > Z X C V B N M ; : _ Shift
1772 Ctrl Alt Spacebar AltGr Ctrl
1775 Note the 102nd key, which is the <keycap><></keycap> key, to
1776 the left of <keycap>Z</keycap>. The character to the right of
1777 the main character is the character generated by
1778 <keycap>AltGr</keycap>.
1781 This keyboard is defined as follows:
1784 static const char main_key_NO[MAIN_LEN][4] =
1786 "|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´",
1787 "qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~",
1788 "aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*",
1789 "zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_",
1794 Except that " and \ needs to be quoted with a backslash, and
1795 that the 102nd key is on a separate line, it's pretty
1799 After you have written such a table, you need to add it to the
1800 <function>main_key_tab[]</function> layout index table. This
1801 will look like this:
1805 WORD lang, ansi_codepage, oem_codepage;
1806 const char (*key)[MAIN_LEN][4];
1810 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
1814 After you have added your table, recompile Wine and test that
1815 it works. If it fails to detect your table, try running
1818 wine --debugmsg +key,+keyboard >& key.log
1821 and look in the resulting <filename>key.log</filename> file to
1822 find the error messages it gives for your layout.
1825 Note that the <constant>LANG_*</constant> and
1826 <constant>SUBLANG_*</constant> definitions are in
1827 <filename>include/winnls.h</filename>, which you might need to
1828 know to find out which numbers your language is assigned, and
1829 find it in the debugmsg output. The numbers will be
1830 <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
1831 the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
1832 <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
1833 <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
1834 could look for <literal>0414</literal> in the debugmsg output
1835 to find out why my keyboard won't detect.
1838 Once it works, submit it to the Wine project. If you use CVS,
1839 you will just have to do
1842 cvs -z3 diff -u windows/x11drv/keyboard.c > layout.diff
1845 from your main Wine directory, then submit
1846 <filename>layout.diff</filename> to
1847 <email>wine-patches@winehq.com</email> along with a brief note
1851 If you don't use CVS, you need to do
1854 diff -u the_backup_file_you_made windows/x11drv/keyboard.c > layout.diff
1857 and submit it as explained above.
1860 If you did it right, it will be included in the next Wine
1861 release, and all the troublesome applications (especially
1862 remote-control applications) and games that use scancodes will
1863 be happily using your keyboard layout, and you won't get those
1864 annoying fixme messages either.
1872 <!-- Keep this comment at the end of the file
1875 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
projects / wine / blob