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 Adam Sacarny (magicbox@bestweb.net)
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 all are 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 Seem farmiliar? 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 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> Make sure that you have
820 looked over this document thoroughly, and have also read:
824 <para><filename>README</filename></para>
827 <para><filename>documentation/bugreports</filename></para>
831 <filename>http://www.westfalen.de/witch/wine-HOWTO.txt</filename>
832 (Optional but recommended)
837 If indeed it looks like you've done your research, be
838 prepared for helpful suggestions. If you haven't, brace
839 yourself for heaving flaming.
844 <sect1 id="win95look">
845 <title>Win95/98 Look</title>
850 (Extracted from <filename>wine/documentation/win95look</filename>)
853 Win95/Win98 interface code is being introduced.
856 Instead of compiling Wine for Win3.1 vs. Win95 using
857 <constant>#define</constant> switches, the code now looks in a
858 special [Tweak.Layout] section of
859 <filename>wine.conf</filename> for a
860 <literal>WineLook=Win95</literal> or
861 <literal>WineLook=Win98</literal> entry.
864 A few new sections and a number of entries have been added to
865 the <filename>wine.conf file</filename> -- these are for
866 debugging the Win95 tweaks only and may be removed in a future
867 release! These entries/sections are:
871 System.Height=<point size> # Sets the height of the system typeface
872 System.Bold=[true|false] # Whether the system font should be boldfaced
873 System.Italic=[true|false] # Whether the system font should be italicized
874 System.Underline=[true|false] # Whether the system font should be underlined
875 System.StrikeOut=[true|false] # Whether the system font should be struck out
876 OEMFixed.xxx # Same parameters for the OEM fixed typeface
877 AnsiFixed.xxx # Same parameters for the Ansi fixed typeface
878 AnsiVar.xxx # Same parameters for the Ansi variable typeface
879 SystemFixed.xxx # Same parameters for the System fixed typeface
882 WineLook=[Win31|Win95|Win98] # Changes Wine's look and feel
887 <title>Configuring the x11drv Driver</title>
893 (Extracted from <filename>wine/documentation/x11drv</filename>)
897 Most Wine users run Wine under the windowing system known as
898 X11. During most of Wine's history, this was the only display
899 driver available, but in recent years, parts of Wine has been
900 reorganized to allow for other display drivers (although the
901 only alternative currently available is Patrik Stridvall's
902 ncurses-based ttydrv, which he claims works for displaying
903 calc.exe). The display driver is chosen with the
904 <literal>GraphicsDriver</literal> option in the [wine] section
905 of <filename>wine.conf</filename> or
906 <filename>.winerc</filename>, but I will only cover the x11drv
907 driver in this article.
911 <title>x11drv modes of operation</title>
914 The x11drv driver consists of two conceptually distinct
915 pieces, the graphics driver (GDI part), and the windowing
916 driver (USER part). Both of these are linked into the
917 <filename>libx11drv.so</filename> module, though (which you
918 load with the <literal>GraphicsDriver</literal> option). In
919 Wine, running on X11, the graphics driver must draw on
920 drawables (window interiors) provided by the windowing
921 driver. This differs a bit from the Windows model, where the
922 windowing system creates and configures device contexts
923 controlled by the graphics driver, and applications are
924 allowed to hook into this relationship anywhere they like.
925 Thus, to provide any reasonable tradeoff between
926 compatibility and usability, the x11drv has three different
932 <term>Unmanaged/Normal</term>
935 The default. Window-manager-independent (any running
936 window manager is ignored completely). Window
937 decorations (title bars, borders, etc) are drawn by
938 Wine to look and feel like the real Windows. This is
939 compatible with applications that depend on being able
940 to compute the exact sizes of any such decorations, or
941 that want to draw their own.
949 Specified by using the
950 <parameter>--managed</parameter> command-line option
951 or the <literal>Managed</literal>
952 <filename>wine.conf</filename> option (see below).
953 Ordinary top-level frame windows with thick borders,
954 title bars, and system menus will be managed by your
955 window manager. This lets these applications integrate
956 better with the rest of your desktop, but may not
957 always work perfectly. (A rewrite of this mode of
958 operation, to make it more robust and less patchy, is
959 highly desirable, though, and is planned to be done
960 before the Wine 1.0 release.)
965 <term>Desktop-in-a-Box</term>
968 Specified by using the
969 <parameter>--desktop</parameter> command-line option
970 (with a geometry, e.g. <parameter>--desktop
971 800x600</parameter> for a such-sized desktop, or
972 even <parameter>--desktop 800x600+0+0</parameter> to
973 automatically position the desktop at the upper-left
974 corner of the display). This is the mode most
975 compatible with the Windows model. All application
976 windows will just be Wine-drawn windows inside the
977 Wine-provided desktop window (which will itself be
978 managed by your window manager), and Windows
979 applications can roam freely within this virtual
980 workspace and think they own it all, without
981 disturbing your other X apps.
989 <title>The [x11drv] section</title>
993 <term>AllocSystemColors</term>
996 Applies only if you have a palette-based display, i.e.
997 if your X server is set to a depth of 8bpp, and if you
998 haven't requested a private color map. It specifies
999 the maximum number of shared colormap cells (palette
1000 entries) Wine should occupy. The higher this value,
1001 the less colors will be available to other
1007 <term>PrivateColorMap</term>
1010 Applies only if you have a palette-based display, i.e.
1011 if your X server is set to a depth of 8bpp. It
1012 specifies that you don't want to use the shared color
1013 map, but a private color map, where all 256 colors are
1014 available. The disadvantage is that Wine's private
1015 color map is only seen while the mouse pointer is
1016 inside a Wine window, so psychedelic flashing and
1017 funky colors will become routine if you use the mouse
1023 <term>PerfectGraphics</term>
1026 This option only determines whether fast X11 routines
1027 or exact Wine routines will be used for certain ROP
1028 codes in blit operations. Most users won't notice any
1034 <term>ScreenDepth</term>
1037 Applies only to multi-depth displays. It specifies
1038 which of the available depths Wine should use (and
1039 tell Windows apps about).
1044 <term>Display</term>
1047 This specifies which X11 display to use, and if
1048 specified, will override both the
1049 <envar>DISPLAY</envar> environment variable and the
1050 <parameter>--display</parameter> command-line option.
1055 <term>Managed</term>
1058 Wine can let frame windows be managed by your window
1059 manager. This option specifies whether you want that
1068 This specifies whether you want DirectDraw to use
1069 XFree86's <firstterm>Direct Graphics
1070 Architecture</firstterm> (DGA), which is able to
1071 take over the entire display and run the game
1072 full-screen at maximum speed. (With DGA1 (XFree86
1073 3.x), you still have to configure the X server to the
1074 game's requested bpp first, but with DGA2 (XFree86
1075 4.x), runtime depth-switching may be possible,
1076 depending on your driver's capabilities.) But be aware
1077 that if Wine crashes while in DGA mode, it may not be
1078 possible to regain control over your computer without
1079 rebooting. DGA normally requires either root
1080 privileges or read/write access to
1081 <filename>/dev/mem</filename>.
1086 <term>UseXShm</term>
1089 If you don't want DirectX to use DGA, you can at least
1090 use X Shared Memory extensions (XShm). It is much
1091 slower than DGA, since the app doesn't have direct
1092 access to the physical frame buffer, but using shared
1093 memory to draw the frame is at least faster than
1094 sending the data through the standard X11 socket, even
1095 though Wine's XShm support is still known to crash
1104 If you don't use DGA, you may want an alternative
1105 means to convince the mouse cursor to stay within the
1106 game window. This option does that. Of course, as with
1107 DGA, if Wine crashes, you're in trouble (although not
1108 as badly as in the DGA case, since you can still use
1109 the keyboard to get out of X).
1114 <term>DesktopDoubleBuffered</term>
1117 Applies only if you use the
1118 <parameter>--desktop</parameter> command-line option
1119 to run in a desktop window. Specifies whether to
1120 create the desktop window with a double-buffered
1121 visual, something most OpenGL games need to run
1132 <sect1 id="cdrom-labels">
1136 <firstname>Petr</firstname>
1137 <surname>Tomasek</surname>
1139 <address><email><tomasek@etf.cuni.cz></email></address>
1141 <contrib>Nov 14 1999</contrib>
1144 <firstname>Andreas</firstname>
1145 <surname>Mohr</surname>
1147 <address><email><a.mohr@mailto.de></email></address>
1149 <contrib>Jan 25 2000</contrib>
1154 <title>Drive labels and serial numbers with wine</title>
1156 by Petr Tomasek <tomasek@etf.cuni.cz>
1160 changes by Andreas Mohr <a.mohr@mailto.de>
1164 (Extracted from <filename>wine/documentation/cdrom-labels</filename>)
1167 Until now, your only possibility of specifying drive volume
1168 labels and serial numbers was to set them manually in the wine
1169 config file. By now, wine can read them directly from the
1170 device as well. This may be useful for many Win 9x games or
1171 for setup programs distributed on CD-ROMs that check for
1176 <title>What's Supported?</title>
1178 <informaltable frame="all">
1182 <entry>File System</entry>
1183 <entry>Types</entry>
1184 <entry>Comment</entry>
1189 <entry>FAT systems</entry>
1190 <entry>hd, floppy</entry>
1191 <entry>reads labels and serial numbers</entry>
1194 <entry>ISO9660</entry>
1195 <entry>cdrom</entry>
1196 <entry>reads labels only</entry>
1205 <title>How To Set Up?</title>
1207 Reading labels and serial numbers just works automagically
1208 if you specify a <literal>Device=</literal> line in the
1209 [Drive X] section in your <filename>wine.conf</filename>.
1210 Note that the device has to exist and must be accessible if
1211 you do this, though.
1214 If you don't do that, then you should give fixed
1215 <literal>Label=</literal> or <literal>Serial=</literal>
1216 entries in <filename>wine.conf</filename>, as Wine returns
1217 these entries instead if no device is given. If they don't
1218 exist, then Wine will return default values (label
1219 <literal>Drive X</literal> and serial
1220 <literal>12345678</literal>).
1223 If you want to give a <literal>Device=</literal> entry
1224 *only* for drive raw sector accesses, but not for reading
1225 the volume info from the device (i.e. you want a
1226 <emphasis>fixed</emphasis>, preconfigured label), you need
1227 to specify <literal>ReadVolInfo=0</literal> to tell Wine to
1228 skip the volume reading.
1233 <title>EXAMPLES</title>
1235 Here's a simple example of cdrom and floppy; labels will be
1236 read from the device on both cdrom and floppy; serial
1237 numbers on floppy only:
1253 Here's an example of overriding the CD-ROM label:
1260 ; note that the device isn't really needed here as we have a fixed label
1267 <title>Todo / Open Issues</title>
1270 The cdrom label can be read only if the data track of
1271 the disk resides in the first track and the cdrom is
1275 Better checking for FAT superblock (it now checks only
1279 Support for labels/serial nums WRITING.
1282 Can the label be longer than 11 chars? (iso9660 has 32
1286 What about reading ext2 volume label? ....
1292 <sect1 id="dll-overrides">
1293 <title>Dll Overrides</title>
1295 <para>by Ove Kaaven <ovek@arcticnet.no></para>
1297 (Extracted from <filename>wine/documentation/dll-overrides</filename>)
1301 The <filename>wine.conf</filename> directives [DllDefaults]
1302 and [DllOverrides] are the subject of some confusion. The
1303 overall purpose of most of these directives are clear enough,
1304 though - given a choice, should Wine use its own built-in
1305 DLLs, or should it use <filename>.DLL</filename> files found
1306 in an existing Windows installation? This document explains
1307 how this feature works.
1311 <title>DLL types</title>
1316 A "native" DLL is a <filename>.DLL</filename> file
1317 written for the real Microsoft Windows.
1321 <term>builtin</term>
1323 A "builtin" DLL is a Wine DLL. These can either be a
1324 part of <filename>libwine.so</filename>, or more
1325 recently, in a special <filename>.so</filename> file
1326 that Wine is able to load on demand.
1332 An "elfdll" is a Wine <filename>.so</filename> file
1333 with a special Windows-like file structure that is as
1334 close to Windows as possible, and that can also
1335 seamlessly link dynamically with "native" DLLs, by
1336 using special ELF loader and linker tricks. Bertho
1337 Stultiens did some work on this, but this feature has
1338 not yet been merged back into Wine (because of
1339 political reasons and lack of time), so this DLL type
1340 does not exist in the official Wine at this time. In
1341 the meantime, the "builtin" DLL type gained some of
1342 the features of elfdlls (such as dynamic loading), so
1343 it's possible that "elfdll" functionality will be
1344 folded into "builtin" at some point.
1350 A native Unix <filename>.so</filename> file, with
1351 calling convention conversion thunks generated on the
1352 fly as the library is loaded. This is mostly useful
1353 for libraries such as "glide" that has exactly the
1354 same API on both Windows and Unix.
1361 <title>The [DllDefaults] section</title>
1364 <term>EXTRA_LD_LIBRARY_PATH</term>
1366 This specifies the location of the Wine's DLL
1367 <filename>.so</filename> files. Wine will search this
1368 path when trying to locate a DLL of the type
1369 <literal>builtin</literal> or
1370 <literal>elfdll</literal>. (This does not apply to
1371 <filename>libwine.so</filename>, since
1372 <filename>libwine.so</filename> is not a DLL in this
1377 <term>DefaultLoadOrder</term>
1379 This specifies in what order Wine should search for
1380 available DLL types, if the DLL in question was not
1381 found in the [DllOverrides] section.
1388 <title>The [DllPairs] section</title>
1390 At one time, there was a section called [DllPairs] in the
1391 default configuration file, but this has been obsoleted
1392 because the pairing information has now been embedded into
1393 Wine itself. (The purpose of this section was merely to be
1394 able to issue warnings if the user attempted to pair
1395 codependent 16-bit/32-bit DLLs of different types.) If you
1396 still have this in your <filename>wine.conf</filename> or
1397 <filename>.winerc</filename>, you may safely delete it.
1402 <title>The [DllOverrides] section</title>
1404 This section specifies how you want specific DLLs to be
1405 handled, in particular whether you want to use "native" DLLs
1406 or not, if you have some from a real Windows configuration.
1407 Because builtins do not mix seamlessly with native DLLs yet,
1408 certain DLL dependencies may be problematic, but workarounds
1409 exist in Wine for many popular DLL configurations. Also see
1410 WWN's [16]Status Page to figure out how well your favorite
1411 DLL is implemented in Wine.
1414 It is of course also possible to override these settings by
1415 explictly using Wine's <parameter>--dll</parameter>
1416 command-line option (see the man page for details). Some
1417 hints for choosing your optimal configuration (listed by
1418 16/32-bit DLL pair):
1422 <term>krnl386, kernel32</term>
1424 Native versions of these will never work, so don't try. Leave
1425 at <literal>builtin</literal>.
1429 <term>gdi, gdi32</term>
1431 Graphics Device Interface. No effort has been made at trying to
1432 run native GDI. Leave at <literal>builtin</literal>.
1436 <term>user, user32</term>
1438 Window management and standard controls. It was
1439 possible to use Win95's <literal>native</literal>
1440 versions at some point (if all other DLLs that depend
1441 on it, such as comctl32 and comdlg32, were also run
1442 <literal>native</literal>). However, this is no longer
1443 possible after the Address Space Separation, so leave
1444 at <literal>builtin</literal>.
1450 NT kernel API. Although badly documented, the
1451 <literal>native</literal> version of this will never
1452 work. Leave at <literal>builtin</literal>.
1456 <term>w32skrnl</term>
1458 Win32s (for Win3.x). The <literal>native</literal>
1459 version will probably never work. Leave at
1460 <literal>builtin</literal>.
1466 Win16 support library for NT. The
1467 <literal>native</literal> version will probably never
1468 work. Leave at <literal>builtin</literal>.
1474 Win16 kernel stuff. Will never work
1475 <literal>native</literal>. Leave at
1476 <literal>builtin</literal>.
1480 <term>display</term>
1482 Display driver. Definitely leave at <literal>builtin</literal>.
1486 <term>toolhelp</term>
1488 Tool helper routines. This is rarely a source of problems.
1489 Leave at <literal>builtin</literal>.
1493 <term>ver, version</term>
1495 Versioning. Seldom useful to mess with.
1499 <term>advapi32</term>
1501 Registry and security features. Trying the
1502 <literal>native</literal> version of this may or may
1507 <term>commdlg, comdlg32</term>
1509 Common Dialogs, such as color picker, font dialog,
1510 print dialog, open/save dialog, etc. It is safe to try
1511 <literal>native</literal>.
1515 <term>commctrl, comctl32</term>
1517 Common Controls. This is toolbars, status bars, list controls,
1518 the works. It is safe to try <literal>native</literal>.
1522 <term>shell, shell32</term>
1524 Shell interface (desktop, filesystem, etc). Being one of the
1525 most undocumented pieces of Windows, you may have luck with the
1526 <literal>native</literal> version, should you need it.
1530 <term>winsock, wsock32</term>
1532 Windows Sockets. The <literal>native</literal> version
1533 will not work under Wine, so leave at
1534 <literal>builtin</literal>.
1540 ICMP routines for wsock32. As with wsock32, leave at
1541 <literal>builtin</literal>.
1547 The <literal>native</literal> version may not work due
1548 to thunking issues. Leave at
1549 <literal>builtin</literal>.
1553 <term>lzexpand, lz32</term>
1555 Lempel-Ziv decompression. Wine's
1556 <literal>builtin</literal> version ought to work fine.
1560 <term>winaspi, wnaspi32</term>
1562 Advanced SCSI Peripheral Interface. The
1563 <literal>native</literal> version will probably never
1564 work. Leave at <literal>builtin</literal>.
1570 C Runtime library. The <literal>native</literal>
1571 version will easily work better than Wine's on this
1576 <term>winspool.drv</term>
1578 Printer spooler. You are not likely to have more luck
1579 with the <literal>native</literal> version.
1585 DirectDraw/Direct3D. Since Wine does not implement the
1586 DirectX HAL, the <literal>native</literal> version
1587 will not work at this time.
1593 DirectInput. Running this <literal>native</literal>
1594 may or may not work.
1600 DirectSound. It may be possible to run this
1601 <literal>native</literal>, but don't count on it.
1605 <term>dplay/dplayx</term>
1607 DirectPlay. The <literal>native</literal> version
1608 ought to work best on this, if at all.
1612 <term>mmsystem, winmm</term>
1614 Multimedia system. The <literal>native</literal>
1615 version is not likely to work. Leave at
1616 <literal>builtin</literal>.
1620 <term>msacm, msacm32</term>
1622 Audio Compression Manager. The
1623 <literal>builtin</literal> version works best, if you
1624 set msacm.drv to the same.
1628 <term>msvideo, msvfw32</term>
1630 Video for Windows. It is safe (and recommended) to try
1631 <literal>native</literal>.
1635 <term>mcicda.drv</term>
1637 CD Audio MCI driver.
1641 <term>mciseq.drv</term>
1643 MIDI Sequencer MCI driver (<filename>.MID</filename>
1648 <term>mciwave.drv</term>
1650 Wave audio MCI driver (<filename>.WAV</filename> playback).
1654 <term>mciavi.drv</term>
1656 AVI MCI driver (<filename>.AVI</filename> video
1657 playback). Best to use <literal>native</literal>.
1661 <term>mcianim.drv</term>
1663 Animation MCI driver.
1667 <term>msacm.drv</term>
1669 Audio Compression Manager. Set to same as msacm32.
1673 <term>midimap.drv</term>
1681 This is a pseudo-DLL used by Wine for thunking
1682 purposes. A <literal>native</literal> version of this
1690 <sect1 id="keyboard">
1691 <title>Keyboard</title>
1693 <para>by Ove Kaaven <ovek@arcticnet.no></para>
1695 (Extracted from <filename>wine/documentation/keyboard</filename>)
1699 Wine now needs to know about your keyboard layout. This
1700 requirement comes from a need from many apps to have the
1701 correct scancodes available, since they read these directly,
1702 instead of just taking the characters returned by the X
1703 server. This means that Wine now needs to have a mapping from
1704 X keys to the scancodes these applications expect.
1707 On startup, Wine will try to recognize the active X layout by
1708 seeing if it matches any of the defined tables. If it does,
1709 everything is alright. If not, you need to define it.
1712 To do this, open the file
1713 <filename>windows/x11drv/keyboard.c</filename> and take a look
1714 at the existing tables. Make a backup copy of it, especially
1715 if you don't use CVS.
1718 What you really would need to do, is find out which scancode
1719 each key needs to generate. Find it in the
1720 <function>main_key_scan</function> table, which looks like
1724 static const int main_key_scan[MAIN_LEN] =
1726 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
1727 0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,
1728 0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,
1729 0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B,
1730 0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
1731 0x56 /* the 102nd key (actually to the right of l-shift) */
1735 Next, assign each scancode the characters imprinted on the
1736 keycaps. This was done (sort of) for the US 101-key keyboard,
1737 which you can find near the top in
1738 <filename>keyboard.c</filename>. It also shows that if there
1739 is no 102nd key, you can skip that.
1742 However, for most international 102-key keyboards, we have
1743 done it easy for you. The scancode layout for these already
1744 pretty much matches the physical layout in the
1745 <function>main_key_scan</function>, so all you need to do is
1746 to go through all the keys that generate characters on your
1747 main keyboard (except spacebar), and stuff those into an
1748 appropriate table. The only exception is that the 102nd key,
1749 which is usually to the left of the first key of the last line
1750 (usually <keycap>Z</keycap>), must be placed on a separate
1751 line after the last line.
1754 For example, my Norwegian keyboard looks like this
1757 § ! " # ¤ % & / ( ) = ? ` Back-
1758 | 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
1760 Tab Q W E R T Y U I O P Å ^
1763 Caps A S D F G H J K L Ø Æ *
1766 Sh- > Z X C V B N M ; : _ Shift
1769 Ctrl Alt Spacebar AltGr Ctrl
1772 Note the 102nd key, which is the <keycap><></keycap> key, to
1773 the left of <keycap>Z</keycap>. The character to the right of
1774 the main character is the character generated by
1775 <keycap>AltGr</keycap>.
1778 This keyboard is defined as follows:
1781 static const char main_key_NO[MAIN_LEN][4] =
1783 "|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´",
1784 "qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~",
1785 "aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*",
1786 "zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_",
1791 Except that " and \ needs to be quoted with a backslash, and
1792 that the 102nd key is on a separate line, it's pretty
1796 After you have written such a table, you need to add it to the
1797 <function>main_key_tab[]</function> layout index table. This
1798 will look like this:
1802 WORD lang, ansi_codepage, oem_codepage;
1803 const char (*key)[MAIN_LEN][4];
1807 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
1811 After you have added your table, recompile Wine and test that
1812 it works. If it fails to detect your table, try running
1815 wine --debugmsg +key,+keyboard >& key.log
1818 and look in the resulting <filename>key.log</filename> file to
1819 find the error messages it gives for your layout.
1822 Note that the <constant>LANG_*</constant> and
1823 <constant>SUBLANG_*</constant> definitions are in
1824 <filename>include/winnls.h</filename>, which you might need to
1825 know to find out which numbers your language is assigned, and
1826 find it in the debugmsg output. The numbers will be
1827 <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
1828 the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
1829 <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
1830 <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
1831 could look for <literal>0414</literal> in the debugmsg output
1832 to find out why my keyboard won't detect.
1835 Once it works, submit it to the Wine project. If you use CVS,
1836 you will just have to do
1839 cvs -z3 diff -u windows/x11drv/keyboard.c > layout.diff
1842 from your main Wine directory, then submit
1843 <filename>layout.diff</filename> to
1844 <email>wine-patches@winehq.com</email> along with a brief note
1848 If you don't use CVS, you need to do
1851 diff -u the_backup_file_you_made windows/x11drv/keyboard.c > layout.diff
1854 and submit it as explained above.
1857 If you did it right, it will be included in the next Wine
1858 release, and all the troublesome applications (especially
1859 remote-control applications) and games that use scancodes will
1860 be happily using your keyboard layout, and you won't get those
1861 annoying fixme messages either.
1869 <!-- Keep this comment at the end of the file
1872 sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
projects / wine / blob