| blob | 21950a7fd978d2003df0939e2e12065ea47de0f6 |
7 <para>
9 </para>
10 <para>
12 </para>
14 <sect2>
16 <para>
17 The Wine config file stores various settings for Wine. These include:
18 <itemizedlist>
19 <listitem>
20 <para>
21 Drives and Information about them
22 </para>
23 </listitem>
24 <listitem>
25 <para>
26 Directory Settings
27 </para>
28 </listitem>
29 <listitem>
30 <para>
31 Port Settings
32 </para>
33 </listitem>
34 <listitem>
35 <para>
36 The Wine look and feel
37 </para>
38 </listitem>
39 <listitem>
40 <para>
41 Wine's DLL Usage
42 </para>
43 </listitem>
44 <listitem>
45 <para>
46 Wine's Multimedia drivers and DLL configuration
47 </para>
48 </listitem>
49 </itemizedlist>
50 </para>
51 </sect2>
53 <sect2>
55 <para>
56 This section will guide you through the process of making a
59 </para>
63 <thead>
64 <row>
68 </row>
69 </thead>
70 <tbody>
71 <row>
75 </row>
76 <row>
80 </row>
81 <row>
85 </row>
86 <row>
90 </row>
91 <row>
95 </row>
96 <row>
100 </row>
101 <row>
105 </row>
106 <row>
110 </row>
111 <row>
115 </row>
116 <row>
120 </row>
121 <row>
125 </row>
126 <row>
130 </row>
131 <row>
135 </row>
136 <row>
140 </row>
141 <row>
145 </row>
146 <row>
150 </row>
151 </tbody>
152 </tgroup>
153 </informaltable>
155 <sect3>
157 <para>
158 It should be pretty self explanatory, but here is an
159 in-depth tutorial about them. There are up to 6 lines for
160 each drive in Wine.
161 </para>
162 <para>
164 The above line begins the section for a drive whose letter is X.
165 </para>
166 <para>
168 path is where the drive will begin. When Wine is browsing
169 in drive X, it will see the files that are in the
171 to leave off the trailing slash!
172 </para>
173 <para>
175 Sets up the type of drive Wine will see it as. Type must
179 (The |'s mean "Type = '<one of the options>'".)
180 </para>
181 <para>
183 drive label. Generally only needed for programs that look
184 for a special CD-ROM. Info on finding the lable is in
186 The label may be up to 11 characters.
187 </para>
188 <para>
190 Tells Wine the serial number of the drive. A few programs with
191 intense protection for pirating might need this, but otherwise
192 don't use it. Up to 8 characters and hexadecimal.
193 </para>
194 <para>
196 Sets up the way Wine looks at files on the drive.
197 </para>
199 <variablelist>
200 <varlistentry>
202 <listitem>
203 <para>
204 Case insensitive filesystem. Alike to DOS and
206 length of files (eightdot.123) - longer ones will be
207 truncated. (NOTE: this is a very bad choice if you
208 plan on running apps that use long filenames. win95
209 should work fine with apps that were designed to run
210 under the msdos system. In other words, you might
211 not want to use this.)
212 </para>
213 </listitem>
214 </varlistentry>
215 <varlistentry>
217 <listitem>
218 <para>
220 the long filename filesystem you are probably used
221 to working with. The filesystem of choice for most
222 applications to be run under wine. PROBABLY THE ONE
223 YOU WANT!
224 </para>
225 </listitem>
226 </varlistentry>
227 <varlistentry>
229 <listitem>
230 <para>
231 Case sensitive. This filesystem has almost no use
232 (Windows apps expect case insensitive filenames).
233 Try it if you dare, but win95 is a much better
234 choice.
235 </para>
236 </listitem>
237 </varlistentry>
238 </variablelist>
241 <para>
242 Use this ONLY for floppy and cdrom devices. Using it on
243 Extended2 partitions can have dire results (when a windows
244 app tries to do a lowlevel write, they do it in a FAT way
245 -- FAT does not mix with Extended2).
246 </para>
247 <note>
248 <para>
249 This setting is not really important; almost all apps
250 will have no problem if it remains unspecified. For
251 CD-ROMs you might want to add it to get automatic label
252 detection, though. If you are unsure about specifying
253 device names, just leave out this setting for your
254 drives.
255 </para>
256 </note>
257 <para>
258 Here is a setup for Drive X, a generic hard drive:
259 <programlisting>
260 [Drive X]
265 This is a setup for Drive X, a generic CD-ROM drive:
266 [Drive X]
272 And here is a setup for Drive X, a generic floppy drive:
273 [Drive X]
280 </programlisting>
281 </para>
282 </sect3>
284 <sect3>
286 <para>
287 The [wine] section of the configuration file contains all kinds
288 of general settings for Wine. When specifying the directories
289 for the directory related settings, make them as they would
295 </para>
296 <para>
298 Make one if you don't already have one. NO TRAILING SLASH
300 </para>
301 <para>
303 This sets up where the windows system files are. Should
304 reside in the directory used for the
307 files will go. Again, NO TRAILING SLASH!
308 </para>
309 <para>
311 be the directory you want your temp files stored in. YOU
312 MUST HAVE WRITE ACCESS TO IT.
313 </para>
314 <para>
315 <programlisting>
317 </programlisting>
318 </para>
319 <para>
321 boxes. When wine is run like <userinput>wine
323 resides in a directory specified in the
326 current directory, wine will run that one). Make sure it
328 system directory (For this setup, it must have
330 </para>
331 <para>
333 Sets the graphics driver to use for Wine output.
334 x11drv is for X11 output, ttydrv is for text console output.
335 WARNING: if you use ttydrv here, then you won't be able to run
336 any Windows GUI programs. Thus this option is mainly interesting
337 for e.g. embedded use of Wine in web server scripts.
338 </para>
339 <para>
341 whether to allow printing via printer drivers to work.
342 This option isn't needed for our builtin psdrv printer driver
343 at all.
344 Using these things are pretty alpha, so you might want to
345 watch out. Some people might find it useful, however. If
346 you're not planning on working on printing via windows printer
347 drivers, don't even add this to your wine config file
348 (It probably isn't already in it).
349 Check out the [spooler] and [parallelports] sections too.
350 </para>
351 <para>
353 This setting specifies the shell linker script to use for setting
354 up Windows icons in e.g. KDE or Gnome that are given by programs
355 making use of appropriate shell32.dll functionality to create
356 icons on the desktop/start menu during installation.
357 </para>
358 <para>
360 Wine doesn't pass directory symlinks to Windows programs by
361 default, as doing so may crash some programs that do
362 recursive lookups of whole subdirectory trees
363 whenever a directory symlink points back to itself or one of its
364 parent directories.
365 That's why we disallowed the use of directory symlinks
366 and added this setting to reenable ("1") this functionality.
367 </para>
368 <para>
370 Sets up the symbol table file for the wine debugger. You
371 probably don't need to fiddle with this. May be useful if
372 your wine is stripped.
373 </para>
374 </sect3>
376 <sect3>
378 <para>
379 There are a few things you will need to know before
380 configuring the DLL sections in your wine configuration
381 file.
382 </para>
383 <sect4>
385 <para>
386 Most windows DLL's have a win16 (Windows 3.x) and win32
387 (Windows 9x/NT) form. The combination of the win16 and
388 win32 DLL versions are called the "DLL pair". This is a
389 list of the most common pairs:
390 </para>
392 <informaltable>
394 <thead>
395 <row>
398 <entry>
399 Native
400 <footnote>
401 <para>
402 Is it possible to use native dll with wine?
403 (See next section)
404 </para>
405 </footnote>
406 </entry>
407 </row>
408 </thead>
409 <tbody>
410 <row>
414 </row>
415 <row>
419 </row>
420 <row>
424 </row>
425 <row>
429 </row>
430 <row>
434 </row>
435 <row>
439 </row>
440 </tbody>
441 </tgroup>
442 </informaltable>
443 </sect4>
445 <sect4>
447 <para>
448 There are a few different forms of DLL's wine can load:
449 <variablelist>
450 <varlistentry>
452 <listitem><para>
453 The DLL's that are included with windows. Many
454 windows DLL's can be loaded in their native
455 form. Many times these native versions work
456 better than their non-Microsoft equivalent --
457 other times they don't.
458 </para></listitem>
459 </varlistentry>
460 <varlistentry>
462 <listitem><para>
463 ELF encapsulated windows DLL's. This is currently
464 experimental (Not working yet).
465 </para></listitem>
466 </varlistentry>
467 <varlistentry>
469 <listitem><para>
470 Native ELF libraries. Will not work yet.
471 </para></listitem>
472 </varlistentry>
473 <varlistentry>
475 <listitem><para>
476 The most common form of DLL loading. This is
477 what you will use if the DLL is error-prone in
478 native form (KERNEL for example), you don't have
479 the native DLL, or you just want to be
480 Microsoft-free.
481 </para></listitem>
482 </varlistentry>
483 </variablelist>
484 </para>
485 </sect4>
486 </sect3>
488 <sect3>
490 <para>
491 These settings provide wine's default handling of DLL loading.
492 </para>
493 <para>
495 </para>
496 <para>
497 This setting is a comma-delimited list of the order in
498 which to attempt loading DLLs. If the first option fails,
499 it will try the second, and so on. The order specified
500 above is probably the best in most conditions.
501 </para>
502 </sect3>
504 <sect3>
506 <para>
507 At one time, there was a section called [DllPairs] in the
508 default configuration file, but this has been obsoleted
509 because the pairing information has now been embedded into
510 Wine itself. (The purpose of this section was merely to be
511 able to issue warnings if the user attempted to pair
515 </para>
516 </sect3>
518 <sect3>
520 <para>
521 The format for this section is the same for each line:
522 <programlisting>
524 </programlisting>
525 </para>
526 <para>
527 For example, to load builtin KERNEL pair (case doesn't
528 matter here):
529 <programlisting>
531 </programlisting>
532 </para>
533 <para>
534 To load the native COMMDLG pair, but if that doesn't work
535 try builtin:
536 <programlisting>
538 </programlisting>
539 </para>
540 <para>
541 To load the native COMCTL32:
542 <programlisting>
544 </programlisting>
545 </para>
546 <para>
547 Here is a good generic setup (As it is defined in config
548 that was included with your wine package):
549 <programlisting>
550 [DllOverrides]
586 </programlisting>
587 </para>
588 <note>
589 <para>
590 You see that elfdll or so is the first option for a few
591 of these dll's. This will fail for you, but you won't
592 notice it as wine will just use the second or third
593 option.
594 </para>
595 </note>
596 </sect3>
598 <sect3>
600 <para>
601 This section sets up wine's font handling.
602 </para>
603 <para>
605 </para>
606 <para>
607 Since the way X handles fonts is different from the way
608 Windows does, wine uses a special mechanism to deal with
609 them. It must scale them using the number defined in the
611 a nice in the middle one. If you have the real windows
615 important. Of course, it's always good to get your X fonts
616 working acceptably in wine.
617 </para>
618 <para>
620 The default font wine uses. Fool around with it if you'd like.
621 </para>
622 <para>
623 OPTIONAL:
624 </para>
625 <para>
627 used in wine. This is good for apps that need a special font you don't have,
628 but a good replacement exists. The syntax is like so:
629 <programlisting>
631 </programlisting>
632 </para>
633 <para>
635 then "Alias1" and so on. The fake windows name is the name
636 that the font will be under a windows app in wine. The
637 real X name is the font name as seen by X (Run
639 utilize the fake windows name you define. If it is not
640 used, then wine will just try to extract the fake windows
641 name itself and not use the value you enter.
642 </para>
643 <para>
644 Here is an example of an alias without masking. The font will show up in windows
645 apps as "Google". When defining an alias in a config file, forget about my
646 comment text (The "<-- blah" stuff)
647 <programlisting>
649 </programlisting>
650 </para>
651 <para>
652 Here is an example with masking enabled. The font will show up as "Foo" in
653 windows apps.
654 <programlisting>
656 </programlisting>
657 </para>
658 <para>
660 </para>
661 </sect3>
663 <sect3>
665 <para>
666 Even though it sounds like a lot of sections, these are
667 all closely related. They are all for communications and
668 parallel ports.
669 </para>
670 <para>
671 The [serialports] section tells wine what serial ports it
672 is allowed to use.
674 </para>
675 <para>
680 can actually equal any device
682 not always necessary to define any COM ports (An optional
683 setting). Here is an example:
685 </para>
686 <para>
687 Use as many of these as you like in the section to define
688 all of the COM ports you need.
689 </para>
690 <para>
691 The [parallelports] section sets up any parallel ports
692 that will be allowed access under wine.
694 </para>
695 <para>
696 Sounds familiar? Syntax is just like the COM port setting.
700 minus 1, just like for COM ports). You don't always need
701 to define a parallel port (AKA, it's optional). As with
702 the other section, LptX can equal any device (Maybe
705 </para>
706 <para>
707 The [spooler] section will inform wine where to spool
708 print jobs. Use this if you want to try printing. Wine
709 docs claim that spooling is "rather primitive" at this
710 time, so it won't work perfectly. IT IS OPTIONAL. The only
711 setting you use in this section works to map a port (LPT1,
712 for example) to a file or a command. Here is an example,
715 </para>
716 <para>
717 The following command maps printing jobs to LPT1 to the
720 </para>
721 <para>
722 The [ports] section is usually useful only for people who
723 need direct port access for programs requiring dongles or
724 scanners. IF YOU DON'T NEED IT, DON'T USE IT!
725 </para>
726 <para>
728 Gives direct read access to those IO's.
729 </para>
730 <para>
732 Gives direct write access to those IO's. It's probably a
733 good idea to keep the values of the
735 settings the same. This stuff will only work when you're
736 root.
737 </para>
738 </sect3>
740 <sect3>
742 <para>
743 [spy] is used to include or exclude debug messages, and to
744 output them to a file. The latter is rarely used. THESE
745 ARE ALL OPTIONAL AND YOU PROBABLY DON'T NEED TO ADD OR
746 REMOVE ANYTHING IN THIS SECTION TO YOUR CONFIG.
747 </para>
748 <para>
750 Sets the logfile for wine. Set to CON to log to standard out.
751 THIS IS RARELY USED.
752 </para>
753 <para>
757 </para>
758 <para>
762 </para>
763 <para>
764 [Registry] can be used to tell wine where your old windows
765 registry files exist. This section is completely optional
766 and useless to people using wine without an existing
767 windows installation.
768 </para>
769 <para>
772 </para>
773 <para>
774 [tweak.layout] is devoted to wine's look. There is only
775 one setting for it.
776 </para>
777 <para>
782 </para>
783 <para>
784 [programs] can be used to say what programs run under
785 special conditions.
786 </para>
787 <para>
789 Sets the program to be run if wine is started without specifying a program.
790 </para>
791 <para>
793 Sets the program to automatically be run at startup every time.
794 </para>
795 </sect3>
797 <sect3>
799 <para>
800 [WinMM] is used to define which multimedia drivers have to be loaded. Since
801 those drivers may depend on the multimedia interfaces available on your sustem
802 (OSS, Alsa... to name a few), it's needed to be able to configure which driver
803 has to be loaded.
804 </para>
806 <para>
807 The content of the section looks like:
808 <programlisting>
809 [WinMM]
813 </programlisting>
814 All the keys must be defined:
815 <itemizedlist>
816 <listitem>
817 <para>
818 The "Drivers" key is a ';' separated list of modules name, each of
819 them containing a low level driver. All those drivers will be loaded
820 when MMSYSTEM/WINMM is started and will provide their inner features.
821 </para>
822 </listitem>
823 <listitem>
824 <para>
825 The "WaveMapper" represents the name of the module containing the Wave
826 Mapper driver. Only one wave mapper can be defined in the system.
827 </para>
828 </listitem>
829 <listitem>
830 <para>
831 The "MidiMapper" represents the name of the module containing the Midi
832 Mapper driver. Only one Midi mapper can be defined in the system.
833 </para>
834 </listitem>
835 </itemizedlist>
836 </para>
837 </sect3>
838 </sect2>
840 <sect2>
842 <para>
843 The wine config file can go in two places.
844 </para>
845 <variablelist>
846 <varlistentry>
848 <listitem><para>
849 A systemwide config file, used for anyone who doesn't
850 have their own. NOTE: this file is currently unused as a
851 new global configuration mechanism is not in place at this
852 time
853 </para></listitem>
854 </varlistentry>
855 <varlistentry>
857 <listitem><para>
858 Your own config file, that only is used for your user.
859 </para></listitem>
860 </varlistentry>
861 </variablelist>
862 <para>
866 it.
867 </para>
868 </sect2>
870 <sect2>
872 <para>
873 There is always a chance that things will go wrong. If the
874 unthinkable happens, try the newsgroup,
877 irc.stealth.net:6668, or connected servers.
878 Make sure that you have looked over this document thoroughly,
879 and have also read:
880 </para>
881 <itemizedlist>
882 <listitem>
884 </listitem>
885 <listitem>
886 <para>
888 (optional but recommended)
889 </para>
890 </listitem>
891 </itemizedlist>
892 <para>
893 If indeed it looks like you've done your research, be
894 prepared for helpful suggestions. If you haven't, brace
895 yourself for heaving flaming.
896 </para>
897 </sect2>
898 </sect1>
902 <para>
904 </para>
905 <para>
907 </para>
908 <para>
909 Win95/Win98 interface code is being introduced.
910 </para>
911 <para>
912 Instead of compiling Wine for Win3.1 vs. Win95 using
914 special [Tweak.Layout] section of
918 </para>
919 <para>
920 A few new sections and a number of entries have been added to
922 debugging the Win95 tweaks only and may be removed in a future
923 release! These entries/sections are:
924 </para>
925 <programlisting>
926 [Tweak.Fonts]
932 "OEMFixed.xxx" # Same parameters for the OEM fixed typeface
933 "AnsiFixed.xxx" # Same parameters for the Ansi fixed typeface
934 "AnsiVar.xxx" # Same parameters for the Ansi variable typeface
935 "SystemFixed.xxx" # Same parameters for the System fixed typeface
937 [Tweak.Layout]
939 </programlisting>
940 </sect1>
945 <para>
947 </para>
948 <para>
950 </para>
952 <para>
953 Most Wine users run Wine under the windowing system known as
954 X11. During most of Wine's history, this was the only display
955 driver available, but in recent years, parts of Wine has been
956 reorganized to allow for other display drivers (although the
957 only alternative currently available is Patrik Stridvall's
958 ncurses-based ttydrv, which he claims works for displaying
959 calc.exe). The display driver is chosen with the
962 x11drv driver in this article.
963 </para>
965 <sect2>
968 <para>
969 <!-- FIXME: This is outdated -->
970 Note: This is now all done in the config file. Needs an update...
971 </para>
973 <para>
974 The x11drv driver consists of two conceptually distinct
975 pieces, the graphics driver (GDI part), and the windowing
976 driver (USER part). Both of these are linked into the
979 Wine, running on X11, the graphics driver must draw on
980 drawables (window interiors) provided by the windowing
981 driver. This differs a bit from the Windows model, where the
982 windowing system creates and configures device contexts
983 controlled by the graphics driver, and applications are
984 allowed to hook into this relationship anywhere they like.
985 Thus, to provide any reasonable tradeoff between
986 compatibility and usability, the x11drv has three different
987 modes of operation.
988 </para>
990 <variablelist>
991 <varlistentry>
993 <listitem>
994 <para>
995 The default. Window-manager-independent (any running
996 window manager is ignored completely). Window
997 decorations (title bars, borders, etc) are drawn by
998 Wine to look and feel like the real Windows. This is
999 compatible with applications that depend on being able
1000 to compute the exact sizes of any such decorations, or
1001 that want to draw their own.
1002 </para>
1003 </listitem>
1004 </varlistentry>
1005 <varlistentry>
1007 <listitem>
1008 <para>
1009 Specified by using the
1013 Ordinary top-level frame windows with thick borders,
1014 title bars, and system menus will be managed by your
1015 window manager. This lets these applications integrate
1016 better with the rest of your desktop, but may not
1017 always work perfectly. (A rewrite of this mode of
1018 operation, to make it more robust and less patchy, is
1019 highly desirable, though, and is planned to be done
1020 before the Wine 1.0 release.)
1021 </para>
1022 </listitem>
1023 </varlistentry>
1024 <varlistentry>
1026 <listitem>
1027 <para>
1028 Specified by using the
1030 (with a geometry, e.g. <parameter>--desktop
1033 automatically position the desktop at the upper-left
1034 corner of the display). This is the mode most
1035 compatible with the Windows model. All application
1036 windows will just be Wine-drawn windows inside the
1037 Wine-provided desktop window (which will itself be
1038 managed by your window manager), and Windows
1039 applications can roam freely within this virtual
1040 workspace and think they own it all, without
1041 disturbing your other X apps.
1042 </para>
1043 </listitem>
1044 </varlistentry>
1045 </variablelist>
1046 </sect2>
1048 <sect2>
1051 <variablelist>
1052 <varlistentry>
1054 <listitem>
1055 <para>
1056 Applies only if you have a palette-based display, i.e.
1057 if your X server is set to a depth of 8bpp, and if you
1058 haven't requested a private color map. It specifies
1059 the maximum number of shared colormap cells (palette
1060 entries) Wine should occupy. The higher this value,
1061 the less colors will be available to other
1062 applications.
1063 </para>
1064 </listitem>
1065 </varlistentry>
1066 <varlistentry>
1068 <listitem>
1069 <para>
1070 Applies only if you have a palette-based display, i.e.
1071 if your X server is set to a depth of 8bpp. It
1072 specifies that you don't want to use the shared color
1073 map, but a private color map, where all 256 colors are
1074 available. The disadvantage is that Wine's private
1075 color map is only seen while the mouse pointer is
1076 inside a Wine window, so psychedelic flashing and
1077 funky colors will become routine if you use the mouse
1078 a lot.
1079 </para>
1080 </listitem>
1081 </varlistentry>
1082 <varlistentry>
1084 <listitem>
1085 <para>
1086 This option only determines whether fast X11 routines
1087 or exact Wine routines will be used for certain ROP
1088 codes in blit operations. Most users won't notice any
1089 difference.
1090 </para>
1091 </listitem>
1092 </varlistentry>
1093 <varlistentry>
1095 <listitem>
1096 <para>
1097 Applies only to multi-depth displays. It specifies
1098 which of the available depths Wine should use (and
1099 tell Windows apps about).
1100 </para>
1101 </listitem>
1102 </varlistentry>
1103 <varlistentry>
1105 <listitem>
1106 <para>
1107 This specifies which X11 display to use, and if
1108 specified, will override both the
1111 </para>
1112 </listitem>
1113 </varlistentry>
1114 <varlistentry>
1116 <listitem>
1117 <para>
1118 Wine can let frame windows be managed by your window
1119 manager. This option specifies whether you want that
1120 by default.
1121 </para>
1122 </listitem>
1123 </varlistentry>
1124 <varlistentry>
1126 <listitem>
1127 <para>
1128 This specifies whether you want DirectDraw to use
1129 XFree86's <firstterm>Direct Graphics
1130 Architecture</firstterm> (DGA), which is able to
1131 take over the entire display and run the game
1132 full-screen at maximum speed. (With DGA1 (XFree86
1133 3.x), you still have to configure the X server to the
1134 game's requested bpp first, but with DGA2 (XFree86
1135 4.x), runtime depth-switching may be possible,
1136 depending on your driver's capabilities.) But be aware
1137 that if Wine crashes while in DGA mode, it may not be
1138 possible to regain control over your computer without
1139 rebooting. DGA normally requires either root
1140 privileges or read/write access to
1142 </para>
1143 </listitem>
1144 </varlistentry>
1145 <varlistentry>
1147 <listitem>
1148 <para>
1149 If you don't want DirectX to use DGA, you can at least
1150 use X Shared Memory extensions (XShm). It is much
1151 slower than DGA, since the app doesn't have direct
1152 access to the physical frame buffer, but using shared
1153 memory to draw the frame is at least faster than
1154 sending the data through the standard X11 socket, even
1155 though Wine's XShm support is still known to crash
1156 sometimes.
1157 </para>
1158 </listitem>
1159 </varlistentry>
1160 <varlistentry>
1162 <listitem>
1163 <para>
1164 If you don't use DGA, you may want an alternative
1165 means to convince the mouse cursor to stay within the
1166 game window. This option does that. Of course, as with
1167 DGA, if Wine crashes, you're in trouble (although not
1168 as badly as in the DGA case, since you can still use
1169 the keyboard to get out of X).
1170 </para>
1171 </listitem>
1172 </varlistentry>
1173 <varlistentry>
1175 <listitem>
1176 <para>
1177 Applies only if you use the
1179 to run in a desktop window. Specifies whether to
1180 create the desktop window with a double-buffered
1181 visual, something most OpenGL games need to run
1182 correctly.
1183 </para>
1184 </listitem>
1185 </varlistentry>
1186 <varlistentry>
1188 <listitem>
1189 <para>
1190 <!-- FIXME: To be documented -->
1191 To be documented...
1192 </para>
1193 </listitem>
1194 </varlistentry>
1195 <varlistentry>
1197 <listitem>
1198 <para>
1199 <!-- FIXME: To be documented -->
1200 To be documented...
1201 </para>
1202 </listitem>
1203 </varlistentry>
1204 <varlistentry>
1206 <listitem>
1207 <para>
1208 <!-- FIXME: To be documented -->
1209 To be documented...
1210 </para>
1211 </listitem>
1212 </varlistentry>
1213 </variablelist>
1214 </sect2>
1215 </sect1>
1217 ®istry;
1220 <sect1info>
1221 <authorgroup>
1222 <author>
1225 <affiliation>
1227 </affiliation>
1229 </author>
1230 <author>
1233 <affiliation>
1235 </affiliation>
1237 </author>
1238 </authorgroup>
1239 </sect1info>
1242 <para>
1244 Nov 14 1999
1245 </para>
1246 <para>
1248 Jan 25 2000
1249 </para>
1250 <para>
1252 </para>
1253 <para>
1254 Until now, your only possibility of specifying drive volume
1255 labels and serial numbers was to set them manually in the wine
1256 config file. By now, wine can read them directly from the
1257 device as well. This may be useful for many Win 9x games or
1258 for setup programs distributed on CD-ROMs that check for
1259 volume label.
1260 </para>
1262 <sect2>
1267 <thead>
1268 <row>
1272 </row>
1273 </thead>
1274 <tbody>
1275 <row>
1279 </row>
1280 <row>
1284 </row>
1285 </tbody>
1286 </tgroup>
1287 </informaltable>
1289 </sect2>
1291 <sect2>
1293 <para>
1294 Reading labels and serial numbers just works automagically
1297 Note that the device has to exist and must be accessible if
1298 you do this, though.
1299 </para>
1300 <para>
1301 If you don't do that, then you should give fixed
1304 these entries instead if no device is given. If they don't
1305 exist, then Wine will return default values (label
1308 </para>
1309 <para>
1312 but not for reading the volume info from the device (i.e. you want
1315 to skip the volume reading.
1316 </para>
1317 </sect2>
1319 <sect2>
1321 <para>
1322 Here's a simple example of cdrom and floppy; labels will be
1323 read from the device on both cdrom and floppy; serial
1324 numbers on floppy only:
1325 </para>
1326 <screen>
1327 [Drive A]
1333 [Drive R]
1338 </screen>
1339 <para>
1340 Here's an example of overriding the CD-ROM label:
1341 </para>
1342 <screen>
1343 [Drive J]
1347 ; note that the device isn't really needed here as we have a fixed label
1350 </screen>
1351 </sect2>
1353 <sect2>
1355 <itemizedlist>
1356 <listitem> <para>
1357 The cdrom label can be read only if the data track of
1358 the disk resides in the first track and the cdrom is
1359 iso9660.
1360 </para> </listitem>
1361 <listitem> <para>
1362 Better checking for FAT superblock (it now checks only
1363 one byte). </para>
1364 </listitem>
1365 <listitem> <para>
1366 Support for labels/serial nums WRITING.
1367 </para> </listitem>
1368 <listitem> <para>
1370 chars).
1371 </para> </listitem>
1372 <listitem> <para>
1373 What about reading ext2 volume label? ....
1374 </para> </listitem>
1375 </itemizedlist>
1376 </sect2>
1377 </sect1>
1382 <para>
1384 </para>
1385 <para>
1387 </para>
1389 <para>
1391 and [DllOverrides] are the subject of some confusion. The
1392 overall purpose of most of these directives are clear enough,
1393 though - given a choice, should Wine use its own built-in
1395 in an existing Windows installation? This document explains
1396 how this feature works.
1397 </para>
1399 <sect2>
1401 <variablelist>
1402 <varlistentry>
1404 <listitem> <para>
1406 written for the real Microsoft Windows.
1407 </para> </listitem>
1408 </varlistentry>
1409 <varlistentry>
1411 <listitem> <para>
1412 A "builtin" DLL is a Wine DLL. These can either be a
1415 that Wine is able to load on demand.
1416 </para> </listitem>
1417 </varlistentry>
1418 <varlistentry>
1420 <listitem> <para>
1422 with a special Windows-like file structure that is as
1423 close to Windows as possible, and that can also
1424 seamlessly link dynamically with "native" DLLs, by
1425 using special ELF loader and linker tricks. Bertho
1426 Stultiens did some work on this, but this feature has
1427 not yet been merged back into Wine (because of
1428 political reasons and lack of time), so this DLL type
1429 does not exist in the official Wine at this time. In
1430 the meantime, the "builtin" DLL type gained some of
1431 the features of elfdlls (such as dynamic loading), so
1432 it's possible that "elfdll" functionality will be
1433 folded into "builtin" at some point.
1434 </para> </listitem>
1435 </varlistentry>
1436 <varlistentry>
1438 <listitem> <para>
1440 calling convention conversion thunks generated on the
1441 fly as the library is loaded. This is mostly useful
1442 for libraries such as "glide" that have exactly the
1443 same API on both Windows and Unix.
1444 </para> </listitem>
1445 </varlistentry>
1446 </variablelist>
1447 </sect2>
1449 <sect2>
1451 <variablelist>
1452 <varlistentry>
1454 <listitem> <para>
1455 This specifies in what order Wine should search for
1456 available DLL types, if the DLL in question was not
1457 found in the [DllOverrides] section.
1458 </para> </listitem>
1459 </varlistentry>
1460 </variablelist>
1461 </sect2>
1463 <sect2>
1465 <para>
1466 At one time, there was a section called [DllPairs] in the
1467 default configuration file, but this has been obsoleted
1468 because the pairing information has now been embedded into
1469 Wine itself. (The purpose of this section was merely to be
1470 able to issue warnings if the user attempted to pair
1474 </para>
1475 </sect2>
1477 <sect2>
1479 <para>
1480 This section specifies how you want specific DLLs to be
1481 handled, in particular whether you want to use "native" DLLs
1482 or not, if you have some from a real Windows configuration.
1483 Because builtins do not mix seamlessly with native DLLs yet,
1484 certain DLL dependencies may be problematic, but workarounds
1485 exist in Wine for many popular DLL configurations. Also see
1486 WWN's [16]Status Page to figure out how well your favorite
1487 DLL is implemented in Wine.
1488 </para>
1489 <para>
1490 It is of course also possible to override these settings by
1492 command-line option (see the man page for details). Some
1493 hints for choosing your optimal configuration (listed by
1495 </para>
1496 <variablelist>
1497 <varlistentry>
1499 <listitem> <para>
1500 Native versions of these will never work, so don't try. Leave
1502 </para> </listitem>
1503 </varlistentry>
1504 <varlistentry>
1506 <listitem> <para>
1507 Graphics Device Interface. No effort has been made at trying to
1509 </para> </listitem>
1510 </varlistentry>
1511 <varlistentry>
1513 <listitem> <para>
1514 Window management and standard controls. It was
1516 versions at some point (if all other DLLs that depend
1517 on it, such as comctl32 and comdlg32, were also run
1519 possible after the Address Space Separation, so leave
1521 </para> </listitem>
1522 </varlistentry>
1523 <varlistentry>
1525 <listitem> <para>
1526 NT kernel API. Although badly documented, the
1529 </para> </listitem>
1530 </varlistentry>
1531 <varlistentry>
1533 <listitem> <para>
1535 version will probably never work. Leave at
1537 </para> </listitem>
1538 </varlistentry>
1539 <varlistentry>
1541 <listitem> <para>
1542 Win16 support library for NT. The
1545 </para> </listitem>
1546 </varlistentry>
1547 <varlistentry>
1549 <listitem> <para>
1550 Win16 kernel stuff. Will never work
1553 </para> </listitem>
1554 </varlistentry>
1555 <varlistentry>
1557 <listitem> <para>
1559 </para> </listitem>
1560 </varlistentry>
1561 <varlistentry>
1563 <listitem> <para>
1564 Tool helper routines. This is rarely a source of problems.
1566 </para> </listitem>
1567 </varlistentry>
1568 <varlistentry>
1570 <listitem> <para>
1571 Versioning. Seldom useful to mess with.
1572 </para> </listitem>
1573 </varlistentry>
1574 <varlistentry>
1576 <listitem> <para>
1577 Registry and security features. Trying the
1579 not work.
1580 </para> </listitem>
1581 </varlistentry>
1582 <varlistentry>
1584 <listitem> <para>
1585 Common Dialogs, such as color picker, font dialog,
1586 print dialog, open/save dialog, etc. It is safe to try
1588 </para> </listitem>
1589 </varlistentry>
1590 <varlistentry>
1592 <listitem> <para>
1593 Common Controls. This is toolbars, status bars, list controls,
1595 </para> </listitem>
1596 </varlistentry>
1597 <varlistentry>
1599 <listitem> <para>
1600 Shell interface (desktop, filesystem, etc). Being one of the
1601 most undocumented pieces of Windows, you may have luck with the
1603 </para> </listitem>
1604 </varlistentry>
1605 <varlistentry>
1607 <listitem> <para>
1609 will not work under Wine, so leave at
1611 </para> </listitem>
1612 </varlistentry>
1613 <varlistentry>
1615 <listitem> <para>
1616 ICMP routines for wsock32. As with wsock32, leave at
1618 </para> </listitem>
1619 </varlistentry>
1620 <varlistentry>
1622 <listitem> <para>
1624 to thunking issues. Leave at
1626 </para> </listitem>
1627 </varlistentry>
1628 <varlistentry>
1630 <listitem> <para>
1631 Lempel-Ziv decompression. Wine's
1633 </para> </listitem>
1634 </varlistentry>
1635 <varlistentry>
1637 <listitem> <para>
1638 Advanced SCSI Peripheral Interface. The
1641 </para> </listitem>
1642 </varlistentry>
1643 <varlistentry>
1645 <listitem> <para>
1647 version will easily work better than Wine's on this
1648 one.
1649 </para> </listitem>
1650 </varlistentry>
1651 <varlistentry>
1653 <listitem> <para>
1654 Printer spooler. You are not likely to have more luck
1656 </para> </listitem>
1657 </varlistentry>
1658 <varlistentry>
1660 <listitem> <para>
1661 DirectDraw/Direct3D. Since Wine does not implement the
1663 will not work at this time.
1664 </para> </listitem>
1665 </varlistentry>
1666 <varlistentry>
1668 <listitem> <para>
1670 may or may not work.
1671 </para> </listitem>
1672 </varlistentry>
1673 <varlistentry>
1675 <listitem> <para>
1676 DirectSound. It may be possible to run this
1678 </para> </listitem>
1679 </varlistentry>
1680 <varlistentry>
1682 <listitem> <para>
1684 ought to work best on this, if at all.
1685 </para> </listitem>
1686 </varlistentry>
1687 <varlistentry>
1689 <listitem> <para>
1691 version is not likely to work. Leave at
1693 </para> </listitem>
1694 </varlistentry>
1695 <varlistentry>
1697 <listitem> <para>
1698 Audio Compression Manager. The
1700 set msacm.drv to the same.
1701 </para> </listitem>
1702 </varlistentry>
1703 <varlistentry>
1705 <listitem> <para>
1706 Video for Windows. It is safe (and recommended) to try
1708 </para> </listitem>
1709 </varlistentry>
1710 <varlistentry>
1712 <listitem> <para>
1713 CD Audio MCI driver.
1714 </para> </listitem>
1715 </varlistentry>
1716 <varlistentry>
1718 <listitem> <para>
1720 playback).
1721 </para> </listitem>
1722 </varlistentry>
1723 <varlistentry>
1725 <listitem> <para>
1727 </para> </listitem>
1728 </varlistentry>
1729 <varlistentry>
1731 <listitem> <para>
1734 </para> </listitem>
1735 </varlistentry>
1736 <varlistentry>
1738 <listitem> <para>
1739 Animation MCI driver.
1740 </para> </listitem>
1741 </varlistentry>
1742 <varlistentry>
1744 <listitem> <para>
1745 Audio Compression Manager. Set to same as msacm32.
1746 </para> </listitem>
1747 </varlistentry>
1748 <varlistentry>
1750 <listitem> <para>
1751 MIDI Mapper.
1752 </para> </listitem>
1753 </varlistentry>
1754 <varlistentry>
1756 <listitem> <para>
1757 This is a pseudo-DLL used by Wine for thunking
1759 doesn't exist.
1760 </para> </listitem>
1761 </varlistentry>
1762 </variablelist>
1763 </sect2>
1764 </sect1>
1769 <para>
1771 </para>
1772 <para>
1774 </para>
1776 <para>
1777 Wine now needs to know about your keyboard layout. This
1778 requirement comes from a need from many apps to have the
1779 correct scancodes available, since they read these directly,
1780 instead of just taking the characters returned by the X
1781 server. This means that Wine now needs to have a mapping from
1782 X keys to the scancodes these applications expect.
1783 </para>
1784 <para>
1785 On startup, Wine will try to recognize the active X layout by
1786 seeing if it matches any of the defined tables. If it does,
1787 everything is alright. If not, you need to define it.
1788 </para>
1789 <para>
1790 To do this, open the file
1792 at the existing tables. Make a backup copy of it, especially
1793 if you don't use CVS.
1794 </para>
1795 <para>
1796 What you really would need to do, is find out which scancode
1797 each key needs to generate. Find it in the
1799 this:
1800 </para>
1801 <programlisting>
1802 static const int main_key_scan[MAIN_LEN] =
1803 {
1804 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
1810 };
1811 </programlisting>
1812 <para>
1813 Next, assign each scancode the characters imprinted on the
1814 keycaps. This was done (sort of) for the US 101-key keyboard,
1815 which you can find near the top in
1817 is no 102nd key, you can skip that.
1818 </para>
1819 <para>
1820 However, for most international 102-key keyboards, we have
1821 done it easy for you. The scancode layout for these already
1822 pretty much matches the physical layout in the
1824 to go through all the keys that generate characters on your
1825 main keyboard (except spacebar), and stuff those into an
1826 appropriate table. The only exception is that the 102nd key,
1827 which is usually to the left of the first key of the last line
1829 line after the last line.
1830 </para>
1831 <para>
1832 For example, my Norwegian keyboard looks like this
1833 </para>
1834 <screen>
1835 § ! " # ¤ % & / ( ) = ? ` Back-
1836 | 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
1838 Tab Q W E R T Y U I O P Å ^
1839 ¨~
1840 Enter
1841 Caps A S D F G H J K L Ø Æ *
1842 Lock '
1844 Sh- > Z X C V B N M ; : _ Shift
1845 ift < , . -
1847 Ctrl Alt Spacebar AltGr Ctrl
1848 </screen>
1849 <para>
1850 Note the 102nd key, which is the <keycap><></keycap> key, to
1851 the left of <keycap>Z</keycap>. The character to the right of
1852 the main character is the character generated by
1853 <keycap>AltGr</keycap>.
1854 </para>
1855 <para>
1856 This keyboard is defined as follows:
1857 </para>
1858 <programlisting>
1859 static const char main_key_NO[MAIN_LEN][4] =
1860 {
1865 "<>"
1866 };
1867 </programlisting>
1868 <para>
1869 Except that " and \ needs to be quoted with a backslash, and
1870 that the 102nd key is on a separate line, it's pretty
1871 straightforward.
1872 </para>
1873 <para>
1874 After you have written such a table, you need to add it to the
1875 <function>main_key_tab[]</function> layout index table. This
1876 will look like this:
1877 </para>
1878 <programlisting>
1879 static struct {
1880 WORD lang, ansi_codepage, oem_codepage;
1881 const char (*key)[MAIN_LEN][4];
1882 } main_key_tab[]={
1883 ...
1884 ...
1885 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
1886 ...
1887 </programlisting>
1888 <para>
1889 After you have added your table, recompile Wine and test that
1890 it works. If it fails to detect your table, try running
1891 </para>
1892 <screen>
1893 wine --debugmsg +key,+keyboard >& key.log
1894 </screen>
1895 <para>
1896 and look in the resulting <filename>key.log</filename> file to
1897 find the error messages it gives for your layout.
1898 </para>
1899 <para>
1900 Note that the <constant>LANG_*</constant> and
1901 <constant>SUBLANG_*</constant> definitions are in
1902 <filename>include/winnls.h</filename>, which you might need to
1903 know to find out which numbers your language is assigned, and
1904 find it in the debugmsg output. The numbers will be
1905 <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
1906 the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
1907 <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
1908 <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
1909 could look for <literal>0414</literal> in the debugmsg output
1910 to find out why my keyboard won't detect.
1911 </para>
1912 <para>
1913 Once it works, submit it to the Wine project. If you use CVS,
1914 you will just have to do
1915 </para>
1916 <screen>
1917 cvs -z3 diff -u windows/x11drv/keyboard.c > layout.diff
1918 </screen>
1919 <para>
1920 from your main Wine directory, then submit
1921 <filename>layout.diff</filename> to
1922 <email>wine-patches@winehq.com</email> along with a brief note
1923 of what it is.
1924 </para>
1925 <para>
1926 If you don't use CVS, you need to do
1927 </para>
1928 <screen>
1929 diff -u the_backup_file_you_made windows/x11drv/keyboard.c > layout.diff
1930 </screen>
1931 <para>
1932 and submit it as explained above.
1933 </para>
1934 <para>
1935 If you did it right, it will be included in the next Wine
1936 release, and all the troublesome applications (especially
1937 remote-control applications) and games that use scancodes will
1938 be happily using your keyboard layout, and you won't get those
1939 annoying fixme messages either.
1940 </para>
1941 <para>
1942 Good luck.
1943 </para>
1944 </sect1>
1946 &fonts;
1947 &printing;
1949 </chapter>
1951 <!-- Keep this comment at the end of the file
1952 Local variables:
1953 mode: sgml
1955 End:
1956 -->