| blob | a6496db9bb090776b356c037b2cfbad467288988 |
3 <para>
4 Now that you hopefully managed to successfully install
5 the Wine program files,
6 this chapter will tell you how to configure the Wine environment
7 properly to run your Windows programs.
8 </para>
9 <para>
10 First, we'll give you an overview about which kinds of
11 configuration and program execution aspects a fully configured
12 Windows environment has to fulfill in order to ensure that many
13 Windows programs run successfully without encountering any
14 misconfigured or missing items.
15 Next, we'll show you which easy helper programs exist
16 to enable even novice users to complete the Wine environment
17 configuration in a fast and easy way.
18 The next section will explain the purpose of the Wine configuration file,
19 and we'll list all of its settings.
20 After that, the next section will detail the most important and
21 unfortunately most difficult configuration part:
22 how to configure the file system and DOS drive environment that
23 Windows programs need.
24 In the last step we'll tell you how to establish a working Windows
25 registry base.
26 Finally, the remaining parts of this chapter contain descriptions
27 of specific Wine configuration items that might also be
28 of interest to you.
29 </para>
34 <para>
35 Formerly a part of: "WWN #52 Feature: Replacing Windows".
37 </para>
39 <para>
40 A Windows installation is a very complex structure. It consists of
41 many different parts with very different functionality.
42 We'll try to outline the most important aspects of it.
43 </para>
45 <itemizedlist>
46 <listitem>
47 <para>
48 Registry. Many keys are supposed to exist and contain
49 meaningful data, even in a newly-installed Windows.
50 </para>
51 </listitem>
52 <listitem>
53 <para>
54 Directory structure. Applications expect to find and/or
55 install things in specific predetermined locations. Most
56 of these directories are expected to exist. But unlike
57 Unix directory structures, most of these locations are
58 not hardcoded, and can be queried via the Windows API
59 and the registry. This places additional requirements on
60 a Wine installation.
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 System DLLs. In Windows, these usually reside in the
68 programs check for their existence in these
69 directories before attempting to load them. While Wine
70 is able to load its own internal DLLs
72 asks for a DLL, Wine does not simulate the existence of
73 nonexisting files.
74 </para>
75 </listitem>
76 </itemizedlist>
78 <para>
79 While the users are of course free to set up everything
80 themselves, the Wine team will make the automated Wine source
82 do everything we find necessary to do; running the
83 conventional <userinput>configure && make depend && make && make
84 install</userinput> cycle is thus not recommended, unless
85 you know what you're doing. At the moment,
87 configuration file, install the registry, and create the
88 directory structure itself.
89 </para>
91 </sect1>
96 <para>
97 Managing the Wine configuration file settings can be a
98 difficult task, sometimes too difficult for some people.
99 That's why there are some helper applications for easily setting up an
100 initial wine configuration file with useful default settings.
101 </para>
105 <para>
106 WineSetupTk is a graphical Wine configuration tool with
107 incredibly easy handling of Wine configuration issues, to be
108 used for configuring the Wine environment after having
109 installed the Wine files.
110 It has been written by CodeWeavers in 2000 as part of a host
111 of other efforts to make Wine more desktop oriented.
112 </para>
113 <para>
114 If you're using Debian, simply install the winesetuptk
115 package (as root):
116 </para>
117 <screen>
119 </screen>
120 <para>
121 If you're using another distribution, search for the package on
122 the net.
123 </para>
124 </sect2>
128 <para>
131 source code tree. It has been written to allow for an easy
132 and complete compilation/installation of Wine source code for
133 people who don't bother with reading heaps of very valuable
134 and informative documentation ;-)
135 </para>
136 <para>
137 Once you have successfully extracted the Wine source code
138 tree, change to the main directory of it and then run (as
139 user):
140 </para>
141 <screen>
143 </screen>
144 <para>
145 Doing so will compile Wine, install Wine and configure the
146 Wine environment (either by providing access to a Windows
147 partition or by creating a properly configured no-windows
148 directory environment).
149 </para>
150 </sect2>
154 <para>
157 source code tree. It is a Winelib app making use of standard
158 Win32 GUI controls to easily customize entries in a Wine
159 configuration file.
160 </para>
161 </sect2>
162 </sect1>
167 <para>
168 After you finished configuring Wine, you may run a Perl
170 in Wine's tools/ directory. It tries to check your
171 configuration's correctness by checking for some popular
172 problems.
174 The latest version can always be found at
175 <ulink url="http://home.arcor.de/andi.mohr/download/winecheck">http://home.arcor.de/andi.mohr/download/winecheck</ulink>.
178 </para>
179 <screen>
182 </screen>
183 <para>
184 The winecheck output will be a percentage score indicating Wine
185 configuration correctness.
186 Note that winecheck is only alpha, so it's not very complete or
187 100% accurate.
188 </para>
190 <para>
191 If this yields a "good" percentage score, then you can consider
192 your Wine installation to be finished successfully:
193 Congratulations!
194 Otherwise (or if there are still some configuration problems
196 configuration documentation below to find out more about some
198 chapter</link>.
199 </para>
200 </sect1>
204 <para>
205 This section is meant to contain both an easy step-by-step introduction
206 to the Wine configuration file (for new Wine users)
207 and a complete reference to all Wine configuration file settings (for
208 advanced users).
209 </para>
210 <para>
213 </para>
215 <sect2>
217 <para>
218 The Wine configuration file is the central file to store
219 configuration settings for Wine.
222 of your user's home directory
225 </para>
226 <para>
227 The settings available in the configuration file include:
228 <itemizedlist>
229 <listitem>
230 <para>
231 Drives and information about them
232 </para>
233 </listitem>
234 <listitem>
235 <para>
236 Directory settings
237 </para>
238 </listitem>
239 <listitem>
240 <para>
241 Port settings
242 </para>
243 </listitem>
244 <listitem>
245 <para>
246 The Wine look and feel
247 </para>
248 </listitem>
249 <listitem>
250 <para>
251 Wine's DLL usage
252 </para>
253 </listitem>
254 <listitem>
255 <para>
256 Wine's multimedia drivers and DLL configuration
257 </para>
258 </listitem>
259 </itemizedlist>
260 </para>
261 </sect2>
263 <sect2>
265 <para>
266 If you just installed Wine for the first time and want to
267 finish Wine installation by configuring it now, then you could
269 (which can be found in the directory
271 code directory) as a base for adapting the Wine configuration
272 file to the settings you want.
273 First, I should mention that you should not forget to make
274 sure that any previous configuration file at
276 of the way instead of simply overwriting it when you will now
277 copy over the sample configuration file.
278 </para>
279 <para>
280 If you don't have a pre-existing configuration file and thus
281 need to copy over our sample configuration file to the
282 standard Wine configuration file location, do in a
284 <screen>
286 <prompt>$ </><userinput>cp <replaceable>dir_to_wine_source_code</replaceable>/documentation/samples/config ~/.wine/config</>
287 </screen>
288 Otherwise, simply use the already existing configuration file
290 </para>
291 <para>
292 Now you can start adapting the configuration file's settings with an
294 below.
296 configuration file settings if wineserver is not running (in
297 other words: if your user doesn't have a Wine session running),
298 otherwise Wine won't use them - and even worse, wineserver will
299 overwrite them with the old settings once wineserver quits!!
300 </para>
301 </sect2>
306 <para>
307 Let's start by giving an overview of which sections a
308 configuration file may contain, and whether the inclusion of
309 the respective section is <emphasis>needed</emphasis> or only <emphasis>recommended</emphasis> ("recmd").
310 </para>
314 <thead>
315 <row>
319 </row>
320 </thead>
321 <tbody>
322 <row>
326 </row>
327 <row>
331 </row>
332 <row>
336 </row>
337 <row>
341 </row>
342 <row>
346 </row>
347 <row>
351 </row>
352 <row>
356 </row>
357 <row>
361 </row>
362 <row>
366 </row>
367 <row>
371 </row>
372 <row>
376 </row>
377 <row>
381 </row>
382 <row>
386 </row>
387 <row>
391 </row>
392 <row>
396 </row>
397 <row>
401 </row>
402 <row>
406 </row>
407 <row>
411 </row>
412 <row>
416 </row>
417 <row>
421 </row>
422 <row>
426 </row>
427 </tbody>
428 </tgroup>
429 </informaltable>
431 <para>
432 Now let's explain the configuration file sections in a
433 detailed way.
434 </para>
436 <sect3>
438 <para>
439 For a detailed description of these configuration file
440 sections which are used to set up DOS drive mappings to Unix
441 directory space, please look at the <link
443 configuration section</link>.
444 </para>
445 </sect3>
449 <para>
450 The [wine] section of the configuration file contains all kinds
451 of general settings for Wine.
452 </para>
453 <para>
454 <programlisting>
460 </programlisting>
461 For a detailed description of drive layer configuration and
462 the meaning of these parameters, please look at the <link
464 configuration section</link>.
465 </para>
466 <para>
468 Sets the graphics driver to use for Wine output.
469 x11drv is for X11 output, ttydrv is for text console output.
470 WARNING: if you use ttydrv here, then you won't be able to run
471 a lot of Windows GUI programs (ttydrv is still pretty "broken"
472 at running graphical apps). Thus this option is mainly interesting
473 for e.g. embedded use of Wine in web server scripts.
474 Note that ttydrv is still very lacking, so if it doesn't work,
475 resort to using "xvfb", a virtual X11 server.
476 Another way to run Wine without display would be to run X11
477 via Xvnc, then connect to that VNC display using xvncviewer
478 (that way you're still able to connect to your app and
479 configure it if need be).
480 </para>
481 <para>
483 whether to allow printing via printer drivers to work.
484 This option isn't needed for our built-in psdrv printer driver
485 at all.
486 Using these things are pretty alpha, so you might want to
487 watch out. Some people might find it useful, however. If
488 you're not planning to work on printing via windows printer
489 drivers, don't even add this to your wine configuration file
490 (It probably isn't already in it).
491 Check out the [spooler] and [parallelports] sections too.
492 </para>
493 <para>
495 This setting specifies the shell linker script to use for setting
496 up Windows icons in e.g. KDE or Gnome that are given by programs
497 making use of appropriate shell32.dll functionality to create
498 icons on the desktop/start menu during installation.
499 </para>
500 <para>
502 Sets up the symbol table file for the wine debugger. You
503 probably don't need to fiddle with this. May be useful if
504 your wine is stripped.
505 </para>
506 </sect3>
510 <para>
511 These settings provide wine's default handling of DLL loading.
512 </para>
513 <para>
515 </para>
516 <para>
517 This setting is a comma-delimited list of the order in
518 which to attempt loading DLLs. If the first option fails,
519 it will try the second, and so on. The order specified
520 above is probably the best in most conditions.
521 </para>
522 </sect3>
524 <sect3>
526 <para>
527 At one time, there was a section called [DllPairs] in the
528 default configuration file, but this has been obsoleted
529 because the pairing information has now been embedded into
530 Wine itself. (The purpose of this section was merely to be
531 able to issue warnings if the user attempted to pair
535 </para>
536 </sect3>
540 <para>
541 The format for this section is the same for each line:
542 <programlisting>
544 </programlisting>
545 </para>
546 <para>
547 For example, to load built-in KERNEL pair (case doesn't
548 matter here):
549 <programlisting>
551 </programlisting>
552 </para>
553 <para>
554 To load the native COMMDLG pair, but if that doesn't work
555 try built-in:
556 <programlisting>
558 </programlisting>
559 </para>
560 <para>
561 To load the native COMCTL32:
562 <programlisting>
564 </programlisting>
565 </para>
566 <para>
567 Here is a good generic setup (As it is defined in config
568 that was included with your wine package):
569 <programlisting>
570 [DllOverrides]
607 ; you can specify programs too
609 ; default for all other DLLs
611 </programlisting>
612 </para>
613 <note>
614 <para>
615 If loading of the libraries that are listed first fails,
616 wine will just go on by using the second or third option.
617 </para>
618 </note>
619 </sect3>
623 <para>
624 This section sets up wine's font handling.
625 </para>
626 <para>
628 </para>
629 <para>
630 Since the way X handles fonts is different from the way
631 Windows does, wine uses a special mechanism to deal with
632 them. It must scale them using the number defined in the
634 a nice in the middle one. If you have the real windows
638 important. Of course, it's always good to get your X fonts
639 working acceptably in wine.
640 </para>
641 <para>
643 The default font wine uses. Fool around with it if you'd like.
644 </para>
645 <para>
646 OPTIONAL:
647 </para>
648 <para>
650 used in wine. This is good for apps that need a special font you don't have,
651 but a good replacement exists. The syntax is like so:
652 <programlisting>
654 </programlisting>
655 </para>
656 <para>
658 then "Alias1" and so on. The fake windows name is the name
659 that the font will be under a windows app in wine. The
660 real X name is the font name as seen by X (Run
662 utilize the fake windows name you define. If it is not
663 used, then wine will just try to extract the fake windows
664 name itself and not use the value you enter.
665 </para>
666 <para>
667 Here is an example of an alias without masking. The font will show up in windows
668 apps as "Google".
670 <programlisting>
672 </programlisting>
673 </para>
674 <para>
675 Here is an example with masking enabled. The font will show up as "Foo" in
676 windows apps.
677 <programlisting>
679 </programlisting>
680 </para>
681 <para>
683 chapter.
684 </para>
685 </sect3>
689 <para>
690 Even though it sounds like a lot of sections, these are
691 all closely related. They are all for communications and
692 parallel ports.
693 </para>
694 <para>
695 The [serialports] section tells wine what serial ports it
696 is allowed to use.
698 </para>
699 <para>
704 can actually equal any device
706 not always necessary to define any COM ports (An optional
707 setting). Here is an example:
709 </para>
710 <para>
711 Use as many of these as you like in the section to define
712 all of the COM ports you need.
713 </para>
714 <para>
715 The [parallelports] section sets up any parallel ports
716 that will be allowed access under wine.
718 </para>
719 <para>
720 Sounds familiar? Syntax is just like the COM port setting.
724 minus 1, just like for COM ports). You don't always need
725 to define a parallel port (AKA, it's optional). As with
726 the other section, LptX can equal any device (Maybe
729 </para>
730 <para>
731 The [spooler] section will inform wine where to spool
732 print jobs. Use this if you want to try printing. Wine
733 docs claim that spooling is "rather primitive" at this
735 setting you use in this section works to map a port (LPT1,
736 for example) to a file or a command. Here is an example,
739 </para>
740 <para>
741 The following command maps printing jobs to LPT1 to the
744 </para>
745 <para>
746 The [ports] section is usually useful only for people who
747 need direct port access for programs requiring dongles or
748 scanners. <emphasis>If you don't need it, don't use
749 it!</emphasis>
750 </para>
751 <para>
753 Gives direct read access to those IO's.
754 </para>
755 <para>
757 Gives direct write access to those IO's. It's probably a
758 good idea to keep the values of the
760 settings the same. This stuff will only work when you're
761 root.
762 </para>
763 </sect3>
767 <para>
768 [Debug] is used to include or exclude debug messages, and to
769 output them to a file. The latter is rarely used. <emphasis>These
770 are all optional and you probably don't need to add or
771 remove anything in this section to your config.</emphasis> (In extreme
772 cases you may want to use these options to manage the amount
773 of information generated by the <parameter>--debugmsg +relay
774 </parameter> option.)
775 </para>
776 <para>
778 Sets the logfile for wine. Set to CON to log to standard out.
780 </para>
781 <para>
785 </para>
786 <para>
790 </para>
791 <para>
793 Include only the listed functions in a
796 </para>
797 <para>
798 <programlisting>"RelayExclude" = "RtlEnterCriticalSection;RtlLeaveCriticalSection"</programlisting>
799 Exclude the listed functions in a
802 entry. If neither entry is present then the trace includes
803 everything.
804 </para>
805 <para>
806 In both entries the functions may be specified either as a
807 function name or as a module and function. In this latter
808 case specify an asterisk for the function name to include/exclude
809 all functions in the module.
810 </para>
811 <para>
812 [Registry] can be used to tell wine where your old windows
813 registry files exist. This section is completely optional
814 and useless to people using wine without an existing
815 windows installation.
816 </para>
817 <para>
820 </para>
821 <para>
822 [tweak.layout] is devoted to wine's look. There is only
823 one setting for it.
824 </para>
825 <para>
830 </para>
831 <para>
832 [programs] can be used to say what programs run under
833 special conditions.
834 </para>
835 <para>
837 Sets the program to be run if wine is started without specifying a program.
838 </para>
839 <para>
841 Sets the program to automatically be run at startup every time.
842 </para>
843 </sect3>
847 <para>
848 [WinMM] is used to define which multimedia drivers have to be loaded. Since
849 those drivers may depend on the multimedia interfaces available on your system
850 (OSS, ALSA... to name a few), it's needed to be able to configure which driver
851 has to be loaded.
852 </para>
854 <para>
855 The content of the section looks like:
856 <programlisting>
857 [WinMM]
861 </programlisting>
862 All the keys must be defined:
863 <itemizedlist>
864 <listitem>
865 <para>
866 The "Drivers" key is a ';' separated list of modules name, each of
867 them containing a low level driver. All those drivers will be loaded
868 when MMSYSTEM/WINMM is started and will provide their inner features.
869 </para>
870 </listitem>
871 <listitem>
872 <para>
873 The "WaveMapper" represents the name of the module containing the Wave
874 Mapper driver. Only one wave mapper can be defined in the system.
875 </para>
876 </listitem>
877 <listitem>
878 <para>
879 The "MidiMapper" represents the name of the module containing the MIDI
880 Mapper driver. Only one MIDI mapper can be defined in the system.
881 </para>
882 </listitem>
883 </itemizedlist>
884 </para>
885 </sect3>
889 <para>
890 [Network] contains settings related to
891 networking. Currently there is only one value that can be set.
892 </para>
893 <variablelist>
894 <varlistentry>
896 <listitem>
897 <para>
899 that affects the way Wine sets the computer name. The computer
902 <varname>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ComputerName\ComputerName</varname>.
903 </para>
904 <para>
905 If this option is set to "Y" or missing, Wine will set the
906 NetBIOS name to the Unix host name of your computer, if
907 necessary truncated to 31 characters. The Unix hostname is the output
909 including the first dot ('.'). Among other things, this means that
910 Windows programs running under Wine cannot change the NetBIOS computer name.
911 </para>
912 <para>
913 If this option is set to "N", Wine will use the registry value above
914 to set the NetBIOS name. Only if the registry entry doesn't exist (usually
915 only during the first wine startup) it will use the Unix hostname as
916 usual. Windows programs can change the NetBIOS name. The change
917 will be effective after a "reboot", i.e. after restarting Wine.
918 </para>
919 </listitem>
920 </varlistentry>
921 </variablelist>
922 </sect3>
926 <para>
927 The section is used to overwrite certain settings of this file for a
928 special program with different settings.
929 [AppDefaults] is not the real name of the section. The real name
930 consists of the leading word AppDefaults followed by the name
931 of the executable the section is valid for.
932 The end of the section name is the name of the
933 corresponding "standard" section of the configuration file
934 that should have some of its settings overwritten with the
935 program specific settings you define.
936 The three parts of the section name are separated by two backslashes.
937 </para>
938 <para>
939 Currently wine supports overriding selected settings within
940 the sections [DllOverrides], [x11drv], [version] and [dsound] only.
941 </para>
942 <para>
943 Here is an example that overrides the normal settings for a
944 program:
945 <programlisting>
946 ;; default settings
947 [x11drv]
951 ;; run install in desktop mode
952 [AppDefaults\\install.exe\\x11drv]
955 </programlisting>
956 </para>
957 </sect3>
958 </sect2>
962 <para>
963 There is always a chance that things will go wrong. If the
964 unthinkable happens, report the problem to
966 try the newsgroup
969 irc.freenode.net, or connected servers.
970 Make sure that you have looked over this document thoroughly,
971 and have also read:
972 </para>
973 <itemizedlist>
974 <listitem>
976 </listitem>
977 <listitem>
978 <para>
980 </para>
981 </listitem>
982 </itemizedlist>
983 <para>
984 If indeed it looks like you've done your research, be
985 prepared for helpful suggestions. If you haven't, brace
986 yourself for heaving flaming.
987 </para>
988 </sect2>
989 </sect1>
993 <sect2>
995 <para>
996 If you're planning to include access to a CD-ROM drive in your Wine
1000 <programlisting>
1001 /dev/cdrom /cdrom iso9660 ro,noauto,users,unhide 0 0
1002 </programlisting>
1003 Several Windows program setup CD-ROMs or other CD-ROMs chose
1004 to do such braindamaged things as marking very important setup
1006 That's no problem on Windows, since the Windows CD-ROM driver by
1007 default displays even files that are supposed to be
1011 (the programs will simply abort with an <quote>installation file not found</quote> or similar error)
1012 Thus you should never forget to add this setting.
1013 </para>
1014 </sect2>
1016 <sect2>
1018 <para>
1019 Wine emulates drives by placing their virtual drive roots to
1020 user-configurable points in the Unix filesystem, so it's your
1025 indicates the home directory of a user), as the root of your
1027 into your Wine configuration file:
1028 </para>
1030 <programlisting>
1031 [Drive C]
1036 </programlisting>
1038 <para>
1039 With this configuration, what windows apps think of as
1040 "c:\windows\system" would map to
1042 filesystem. Note that you need to specify
1046 Windows compatible (case insensitive) filesystem, otherwise
1047 most apps won't work.
1048 </para>
1049 </sect2>
1053 <para>
1054 Here's the fundamental layout that Windows programs and
1055 installers expect and that we thus need to configure properly
1056 in Wine. Without it, they seldomly operate correctly. If you
1057 intend to use a no-windows environment (not using an existing
1058 Windows partition), then it is recommended to use either
1061 initial windows directory tree, since creating a directory
1062 structure manually is tiresome and error-prone.
1063 </para>
1065 <programlisting>
1066 C:\ Root directory of primary disk drive
1067 Windows\ Windows directory, containing .INI files,
1068 accessories, etc.
1072 Start Menu\ Program launcher directory structure
1073 Programs\ Program launcher links (.LNK files) to programs
1074 Program Files\ Application binaries (.EXE and .DLL files)
1075 </programlisting>
1076 </sect2>
1080 <para>
1081 These sections are supposed to make certain Unix
1082 directory locations accessible to Wine as a DOS/Windows drive
1083 (drive 'x:') and thus accessible to Windows programs
1084 under the drive name you specified.
1085 Every DOS/Windows program sort of expects at least a C:
1086 drive (and sometimes also an A: floppy drive), so your
1087 configuration file should at least contain the corresponding
1088 sections, [Drive C] and [Drive A].
1089 You need to decide on whether you want to use an existing Windows
1090 partition as the C drive or whether you want to create your own
1091 Wine drive C directory tree somewhere (take care about
1092 permissions!).
1093 Each drive section may specify up to 6 different settings
1094 as explained below.
1095 </para>
1096 <para>
1098 The above line begins the section for a drive whose letter is x
1099 (DOS notation: drive 'x:').
1100 You could e.g. create an equivalent to a drive 'C:'
1101 under DOS/Windows by using a [Drive C] section name.
1102 Note that the drive letter is case insensitive.
1103 </para>
1104 <para>
1106 This specifies the directory where the drive will begin.
1107 When Wine is browsing in drive x, it will be able
1108 to see the files that are in the directory
1110 (note that symlinks to directories won't get included!
1112 configuration setting)
1113 You can also make use of environment variables like $HOME here,
1115 directory in your home dir would be
1117 Don't forget to leave off the trailing slash!
1118 </para>
1119 <para>
1121 Sets up the type of drive Wine will see it as. Type must
1125 (The |'s mean "Type = '<one of the options>'".)
1127 For a home directory entry, it makes sense to choose
1128 "network" sometimes, since some home directories are being
1129 exported over the network via NFS and thus can have slow response
1130 times.
1131 </para>
1132 <para>
1134 Defines the drive label. Generally only needed
1135 for programs that look for a special CD-ROM.
1136 The label may be up to 11 characters.
1137 Note that the preferred way of managing labels and serial numbers
1138 of CD-ROMs and floppies is to give Wine raw device access for
1139 reading these on a per-CD case (see "Device" below) instead of
1140 hardcoding one specific "Label".
1141 </para>
1142 <para>
1144 Tells Wine the serial number of the drive. A few programs with
1145 intense protection for pirating might need this, but otherwise
1146 it's not needed. Up to 8 characters and hexadecimal.
1148 is a smarter choice.
1149 </para>
1150 <para>
1152 Sets up the way Wine looks at files on the drive.
1153 This setting controls the file name lookup and mapping of
1154 Wine to existing file systems on your PC, it does
1156 used itself.
1157 </para>
1159 <variablelist>
1160 <varlistentry>
1162 <listitem>
1163 <para>
1165 the long filename filesystem you are probably used
1166 to working with. The filesystem bæhaviour of choice for most
1167 programs to be run under wine. <emphasis>Probably the one
1168 you want!</emphasis>
1169 </para>
1170 </listitem>
1171 </varlistentry>
1172 <varlistentry>
1174 <listitem>
1175 <para>
1176 Case sensitive. This filesystem has almost no use
1177 (Windows apps expect case insensitive filenames),
1178 except maybe for Winelib applications.
1179 Try it if you dare, but win95 is a much better
1180 and always recommended choice.
1181 </para>
1182 </listitem>
1183 </varlistentry>
1184 <varlistentry>
1186 <listitem>
1187 <para>
1188 Case insensitive filesystem. Alike to DOS and
1190 length of files (eightdot.123) - longer ones will be
1191 truncated.
1192 <note>
1193 <para>
1195 you plan on running apps that use long filenames.
1196 win95 should work fine with apps that were designed
1197 to run under the msdos system. In other words, you
1198 might not want to use this.
1199 </para>
1200 </note>
1201 </para>
1202 </listitem>
1203 </varlistentry>
1204 </variablelist>
1207 <para>
1208 Needed for raw device access and <link linkend="config-drive-cdrom-labels">label and serial number reading</link>.
1210 Extended2 or other Unix file systems can have dire results
1211 (when a windows app tries to do a lowlevel write,
1212 they do it in a FAT way -- FAT format is completely different from
1213 any Unix file system).
1214 Also, make sure that you have proper permissions to this device
1215 file.
1216 </para>
1217 <note>
1218 <para>
1219 This setting is not really important; almost all apps
1220 will have no problem if it remains unspecified. For
1221 CD-ROMs it's quite useful in order to get automatic label
1222 detection, though. If you are unsure about specifying
1223 device names, just leave out this setting for your
1224 drives.
1225 </para>
1226 </note>
1227 <para>
1228 Here are a few sample entries:
1229 <programlisting>
1230 Here is a setup for Drive C, a generic hard drive:
1231 [Drive C]
1236 This is a setup for Drive E, a generic CD-ROM drive:
1237 [Drive E]
1243 And here is a setup for Drive A, a generic floppy drive:
1244 [Drive A]
1251 </programlisting>
1252 </para>
1253 </sect2>
1255 <sect2>
1257 <para>
1259 This tells Wine and Windows programs where the
1261 recommended to have this directory somewhere on your
1263 recommended to just call the directory "windows" (this is
1264 the default setup on Windows, and some stupid programs
1265 might rely on this). So in case you chose a "Windows"
1266 setting of "c:\\windows" and you chose to set up a drive C
1268 corresponding directory would be
1270 if you don't already have one. <emphasis>No trailing slash</emphasis> (<emphasis>not</emphasis>
1272 recommended, as Windows programs always assume write access
1273 to the Windows directory!
1274 </para>
1275 <para>
1277 This sets up where the windows system files are. The Windows
1278 system directory should reside below the directory used for the
1280 Thus when using the example above, the system directory would be
1282 Again, no trailing slash, and write access!
1283 </para>
1284 <para>
1286 be the directory you want your temp files stored in,
1287 /usr/local/wine_c/temp in our example.
1288 Again, no trailing slash, and <emphasis>write
1289 access</emphasis>!!
1290 </para>
1291 <para>
1292 <programlisting>
1294 </programlisting>
1295 </para>
1296 <para>
1298 boxes. When wine is run like <userinput>wine
1300 resides in a directory specified in the
1303 current directory, wine will run that one). Make sure it
1305 system directory (For this setup, it must have
1307 </para>
1309 <programlisting>
1311 </programlisting>
1312 Wine doesn't pass directory symlinks to Windows programs by
1313 default, as doing so may crash some programs that do
1314 recursive lookups of whole subdirectory trees
1315 whenever a directory symlink points back to itself or one of its
1316 parent directories.
1317 That's why we disallowed the use of directory symlinks
1318 and added this setting to reenable ("1") this functionality.
1320 account symlinked directories, then reenable it, but
1322 Windows programs when using the above method! (in other words:
1323 enabling it is certainly not recommended)
1324 </para>
1325 </sect2>
1327 <sect2>
1329 <para>
1330 Windows uses a different (and inferior) way than Unix to describe the
1331 location of files in a computer. Thus Windows programs also expect
1332 to find this different way supported by the system.
1333 Since we intend to run Windows programs on
1334 a Unix system, we're in trouble, as we need to translate
1335 between these different file access techniques.
1336 </para>
1337 <para>
1338 Windows uses drive letters to describe drives or
1339 any other form of storage media and to access files on them.
1340 For example, common drive names are
1343 first floppy drive.
1345 directory separator sign, whereas Unix uses
1347 Thus, an example document on the first data partition in
1348 Windows might be accessed by the name of
1350 </para>
1351 <para>
1352 So much for the Windows way of doing things.
1353 </para>
1354 <para>
1355 Well, the problem is, in Unix there is no such thing as
1357 much better way of having one single uniform directory tree
1358 (starting with the root directory
1360 such as e.g. harddisk partitions appended at various directory
1361 locations within the tree (an example would be
1363 partition mounted/attached to a directory called data1 in the
1365 directory of the data partition file system that's mounted
1367 In Unix, the Windows example document mentioned above could e.g.
1368 be accessed by the name of
1370 provided that the administrator decided to mount (attach) the first
1371 data partition at the directory /data1 inside the Unix
1372 directory tree. Note that in Unix, the administrator can
1376 suitable for the first data partition (here,
1378 change in partition order, Windows automatically
1380 suddenly find yourself with a first data partition at drive
1382 referencing confusion that entails. Thus, the Windows way of
1383 using ever-changing drive letters is <emphasis>clearly
1384 inferior</emphasis> to the Unix way of assigning
1386 data storage medium.
1387 As we'll see soon, fortunately this Windows limitation of
1388 changing drive letters doesn't affect us in Wine at all, since
1389 we can properly map <emphasis>never-changing</emphasis> drive letters to <emphasis>fixed</emphasis> locations inside the Unix directory tree (and even if the location of the respective Unix directory changes, we can still simply update the Wine drive mapping to reflect the updated location and at the same time keep the original drive letter).
1390 </para>
1391 <para>
1392 OK, now that we know some theory about Windows and Unix drive
1393 and filename mapping, it's probably time to ask how Wine
1394 achieves the magic of mapping a Unix directory location to a
1395 Windows drive...
1396 </para>
1397 <para>
1398 Wine chose to do the following:
1399 In Wine, you don't assign some real physical storage medium
1400 (such as a harddisk partition or similar) to each drive letter
1401 mapping entry.
1402 Instead, you choose certain sub directory trees inside the Unix
1404 you would like to assign a drive letter to.
1405 </para>
1406 <para>
1407 Note that for every Unix sub directory tree that you intend to
1408 start Windows programs in, it is <emphasis>absolutely
1409 required</emphasis> to have a Wine drive mapping entry:
1410 </para>
1411 <para>
1412 For example, if you had a publicly writable <quote>Windows
1414 able to access this sub directory tree from Wine, you should
1415 have a drive mapping entry that maps a certain drive letter
1417 either to <filename>/usr/mywine</filename> or <filename>/usr</filename> (to also access any directories belonging to the parent directory) or <filename>/</filename> (to also access any directory whatsoever on this system by this drive letter mapping). The DOS drive/directory location to access files in <filename>/usr/mywine</filename> <emphasis>in Wine</emphasis> in these configuration cases would then be <filename>P:\</filename> or <filename>P:\mywine</filename> or <filename>P:\usr\mywine</filename>, respectively.
1418 </para>
1419 </sect2>
1423 <para>
1425 </para>
1426 <para>
1428 </para>
1430 <para>
1431 A major goal of Wine is to allow users to run Windows programs
1432 without having to install Windows on their machine. Wine
1433 implements the functionality of the main DLLs usually
1434 provided with Windows. Therefore, once Wine is finished, you
1435 will not need to have Windows installed to use Wine.
1436 </para>
1437 <para>
1438 Wine has already made enough progress that it may be possible
1439 to run your target programs without Windows installed. If
1440 you want to try it, follow these steps:
1441 </para>
1443 <orderedlist>
1444 <listitem>
1445 <para>
1449 for more information.
1450 The directory to be used for emulating a C: drive will be
1451 the base directory for some Windows specific directories
1452 created below.
1453 Remember to use
1455 </para>
1456 </listitem>
1457 <listitem>
1458 <para>
1459 Within the directory to be used for C:, create empty
1464 directories. Do not point Wine to a
1466 installations and a messy registry. (Wine creates a
1469 Perhaps you have to remove these files).
1470 In one line:
1471 mkdir -p windows windows/system windows/Start\ Menu windows/Start\ Menu/Programs
1472 </para>
1473 </listitem>
1474 <listitem>
1475 <para>
1476 Run and/or install your programs.
1477 </para>
1478 </listitem>
1479 </orderedlist>
1481 <para>
1482 Because Wine is not yet complete, some programs will work
1483 better with native Windows DLLs than with Wine's
1484 replacements. Wine has been designed to make this possible.
1485 Here are some tips by Juergen Schmied (and others) on how to
1486 proceed. This assumes that your
1488 file does not point to a native Windows installation but is in
1492 </para>
1494 <itemizedlist>
1495 <listitem>
1496 <para>
1497 Run the program with <parameter>--debugmsg
1498 +loaddll</parameter> to find out which files are
1499 needed. Copy the required DLLs one by one to the
1501 copy KERNEL/KERNEL32, GDI/GDI32, USER/USER32 or NTDLL. These
1502 implement the core functionality of the Windows API, and
1503 the Wine internal versions must be used.
1504 </para>
1505 </listitem>
1506 <listitem>
1507 <para>
1511 the Windows DLLs you want to use. For more information
1512 about this, see the Wine manpage.
1513 </para>
1514 </listitem>
1515 <listitem>
1516 <para>
1517 Note that some network DLLs are not needed even though
1518 Wine is looking for them. The Windows
1520 must use the internal implementation.
1521 </para>
1522 </listitem>
1523 <listitem>
1524 <para>
1525 Copy SHELL.DLL/SHELL32.DLL, COMMDLG.DLL/COMDLG32.DLL
1526 and COMMCTRL.DLL/COMCTL32.DLL
1527 only as pairs to your Wine directory (these DLLs are
1531 </para>
1532 </listitem>
1533 <listitem>
1534 <para>
1535 Be consistent: Use only DLLs from the same Windows version
1536 together.
1537 </para>
1538 </listitem>
1539 <listitem>
1540 <para>
1545 registry, don't know about
1547 As of now, it might not be necessary any more to use
1548 regedit.exe, since Wine has its own regedit Winelib
1549 application now.
1550 </para>
1551 </listitem>
1552 <listitem>
1553 <para>
1556 to browse through your programs' help function
1557 (or in case Wine's winhelp implementation in programs/winhelp/
1558 is not good enough, for example).
1559 </para>
1560 </listitem>
1561 </itemizedlist>
1562 </sect2>
1566 <para>
1567 Some people intend to use the data of an existing Windows partition
1568 with Wine in order to gain some better compatibility or to run already
1569 installed programs in a setup as original as possible.
1570 Note that many Windows programs assume that they have full write
1571 access to all windows directories.
1573 This means that you either have to configure the Windows
1574 partition mount point for write permission by your Wine user
1576 on how to do that), or you'll have to copy over (some parts of) the Windows
1577 partition content to a directory of a Unix partition and make
1578 sure this directory structure is writable by your user.
1580 write access as a base for Wine!! (some programs, notably
1581 Explorer, corrupt large parts of the Windows partition in case
1582 of an incorrect setup; you've been warned).
1583 Not to mention that NTFS write support in Linux is still very
1585 Windows version using the NTFS file system).
1586 Thus we advise you to go the Unix directory way.
1587 </para>
1588 </sect2>
1592 <para>
1594 </para>
1595 <para>
1597 </para>
1598 <para>
1599 This document describes how FAT and
1600 VFAT file system permissions work in Linux
1601 with a focus on configuring them for Wine.
1602 </para>
1604 <sect3>
1606 <para>
1607 Linux is able to access DOS and Windows file systems using
1608 either the FAT (older 8.3 DOS filesystems) or VFAT (newer
1609 Windows 95 or later long filename filesystems) modules.
1610 Mounted FAT or VFAT filesystems provide the primary means
1611 for which existing programs and their data are accessed
1612 through Wine for dual boot (Linux + Windows) systems.
1613 </para>
1614 <para>
1615 Wine maps mounted FAT filesystems, such as
1620 </para>
1621 <programlisting>
1622 [Drive C]
1625 </programlisting>
1626 <para>
1627 Although VFAT filesystems are preferable to FAT filesystems
1629 will be used throughout the remainder of this document to
1630 refer to FAT filesystems and their derivatives. Also,
1632 examples throughout this document.
1633 </para>
1634 <para>
1635 Most modern Linux distributions either detect or allow
1636 existing FAT file systems to be configured so that they can be
1638 either persistently (on bootup) or on an as needed basis. In
1639 either case, by default, the permissions will probably be
1640 configured so that they look like:
1641 </para>
1642 <screen>
1648 </screen>
1649 <para>
1651 group and are only writable by "root"
1653 that it requires that Wine be run as root in order for
1654 programs to be able to write to any part of the
1655 filesystem.
1656 </para>
1657 <para>
1658 There are three major approaches to overcoming the restrictive
1659 permissions mentioned in the previous paragraph:
1660 </para>
1661 <orderedlist>
1662 <listitem>
1663 <para>
1665 </para>
1666 </listitem>
1667 <listitem>
1668 <para>
1669 Mount the FAT filesystem with less restrictive
1670 permissions
1671 </para>
1672 </listitem>
1673 <listitem>
1674 <para>
1675 Shadow the FAT filesystem by completely or partially
1676 copying it
1677 </para>
1678 </listitem>
1679 </orderedlist>
1680 <para>
1681 Each approach will be discussed in the following sections.
1682 </para>
1683 </sect3>
1685 <sect3>
1687 <para>
1688 Running Wine as root is the easiest and most thorough way of giving
1689 programs that Wine runs unrestricted access to FAT files systems.
1690 Running wine as root also allows programs to do things unrelated
1691 to FAT filesystems, such as listening to ports that are less than
1692 1024. Running Wine as root is dangerous since there is no limit to
1694 </para>
1695 </sect3>
1697 <sect3>
1699 <para>
1700 The FAT filesystem can be mounted with permissions less restrictive
1701 than the default. This can be done by either changing the user that
1702 mounts the FAT filesystem or by explicitly changing the permissions
1703 that the FAT filesystem is mounted with. The permissions are
1704 inherited from the process that mounts the FAT filesystem. Since the
1705 process that mounts the FAT filesystem is usually a startup script
1706 running as root the FAT filesystem inherits root's permissions. This
1707 results in the files on the FAT filesystem having permissions similar
1708 to files created by root. For example:
1709 </para>
1710 <screen>
1716 </screen>
1717 <para>
1718 which matches the owner, group and permissions of files seen
1719 on the FAT filesystem except for the missing 'x's. The
1720 permissions on the FAT filesystem can be changed by changing
1721 root's umask (unset permissions bits). For example:
1722 </para>
1723 <screen>
1734 </screen>
1735 <para>
1736 Mounting the FAT filesystem with a umask of
1738 it. Explicitly specifying the permissions of the FAT
1739 filesystem when it is mounted provides additional control.
1740 There are three mount options that are relevant to FAT
1743 when the filesystem is manually mounted. For example:
1744 </para>
1745 <screen>
1753 </screen>
1754 <para>
1755 which gives "sle" complete control over
1757 made permanent by adding them to the
1759 </para>
1760 <screen>
1762 <computeroutput>/dev/hda1 /c vfat uid=500,gid=500,umask=002,exec,dev,suid,rw 1 1</computeroutput>
1763 </screen>
1764 <para>
1766 the user private group file permission scheme. On FAT file
1767 systems this umask assures that all files are fully
1768 accessible by all users in the specified user group
1770 </para>
1771 </sect3>
1773 <sect3>
1775 <para>
1776 Shadowing provides a finer granularity of control. Parts of
1777 the original FAT filesystem can be copied so that the
1778 program can safely work with those copied parts while
1779 the program continues to directly read the remaining
1780 parts. This is done with symbolic links. For example,
1781 consider a system where a program named
1785 read access to the entire FAT filesystem. On this system
1786 the FAT filesystem has default permissions which should not
1787 be changed for security reasons or can not be changed due to
1788 lack of root access. On this system a shadow directory
1789 might be set up in the following manner:
1790 </para>
1791 <screen>
1799 <prompt>/c_shadow></prompt><userinput>perl -p -i -e 's|/c$|/c_shadow|g' ~/.wine/config</userinput>
1800 </screen>
1801 <para>
1802 The above gives everyone complete read and write access to
1805 write access to all other directories.
1806 </para>
1807 </sect3>
1808 </sect2>
1811 <sect2info>
1812 <authorgroup>
1813 <author>
1816 <affiliation>
1818 </affiliation>
1820 </author>
1821 <author>
1824 <affiliation>
1826 </affiliation>
1828 </author>
1829 </authorgroup>
1830 </sect2info>
1833 <para>
1835 Nov 14 1999
1836 </para>
1837 <para>
1839 Jan 25 2000
1840 </para>
1841 <para>
1843 </para>
1844 <para>
1845 Until now, your only possibility of specifying drive volume
1846 labels and serial numbers was to set them manually in the wine
1847 configuration file. By now, wine can read them directly from the
1848 device as well. This may be useful for many Win 9x games or
1849 for setup programs distributed on CD-ROMs that check for
1850 volume label.
1851 </para>
1853 <sect3>
1858 <thead>
1859 <row>
1863 </row>
1864 </thead>
1865 <tbody>
1866 <row>
1870 </row>
1871 <row>
1875 </row>
1876 </tbody>
1877 </tgroup>
1878 </informaltable>
1880 </sect3>
1882 <sect3>
1884 <para>
1885 Reading labels and serial numbers just works automagically
1888 Note that the device has to exist and must be accessible by the user
1889 running Wine if you do this, though.
1890 </para>
1891 <para>
1892 If you don't want to read labels and serial numbers directly from
1893 the device, then you should give fixed
1896 these entries instead if no device is given. If they don't
1897 exist, then Wine will return default values (label
1900 </para>
1901 <para>
1904 but not for reading the volume info from the device (i.e. you want
1907 to skip the volume reading.
1908 </para>
1909 </sect3>
1911 <sect3>
1913 <para>
1914 Here's a simple example of CD-ROM and floppy; labels will be
1915 read from the device on both CD-ROM and floppy; serial
1916 numbers on floppy only:
1917 </para>
1918 <screen>
1919 [Drive A]
1925 [Drive R]
1930 </screen>
1931 <para>
1932 Here's an example of overriding the CD-ROM label:
1933 </para>
1934 <screen>
1935 [Drive J]
1939 ; note that the device isn't really needed here as we have a fixed label
1942 </screen>
1943 </sect3>
1945 <sect3>
1947 <itemizedlist>
1948 <listitem> <para>
1949 The CD-ROM label can be read only if the data track of
1950 the disk resides in the first track and the cdrom is
1951 iso9660.
1952 </para> </listitem>
1953 <listitem> <para>
1954 Better checking for FAT superblock (it now checks only
1955 one byte). </para>
1956 </listitem>
1957 <listitem> <para>
1958 Support for labels/serial nums WRITING.
1959 </para> </listitem>
1960 <listitem> <para>
1962 chars).
1963 </para> </listitem>
1964 <listitem> <para>
1965 What about reading ext2 volume label? ....
1966 </para> </listitem>
1967 </itemizedlist>
1968 </sect3>
1969 </sect2>
1970 </sect1>
1972 ®istry;
1977 <sect2>
1979 <para>
1980 If your programs don't work as expected, then it's often because one
1981 DLL or another is failing. This can often be resolved by changing
1982 certain DLLs from Wine built-in to native Windows DLL file and vice
1983 versa.
1984 </para>
1985 <para>
1986 A very useful help to find out which DLLs are loaded as built-in and
1987 which are loaded as native Windows file can be the debug channel
1988 loaddll, activated via the Wine command line parameter
1990 </para>
1991 </sect2>
1993 <sect2>
1994 <!-- FIXME intro!!! -->
1996 <para>
1997 There are a few things you will need to know before
1998 configuring the DLL sections in your wine configuration
1999 file.
2000 </para>
2001 <sect3>
2003 <para>
2004 Most windows DLL's have a win16 (Windows 3.x) and win32
2005 (Windows 9x/NT) form. The combination of the win16 and
2006 win32 DLL versions are called the "DLL pair". This is a
2007 list of the most common pairs:
2008 </para>
2010 <informaltable>
2012 <thead>
2013 <row>
2016 <entry>
2017 Native
2018 <footnote>
2019 <para>
2020 Is it possible to use native DLL with wine?
2021 (See next section)
2022 </para>
2023 </footnote>
2024 </entry>
2025 </row>
2026 </thead>
2027 <tbody>
2028 <row>
2032 </row>
2033 <row>
2037 </row>
2038 <row>
2042 </row>
2043 <row>
2047 </row>
2048 <row>
2052 </row>
2053 <row>
2057 </row>
2058 </tbody>
2059 </tgroup>
2060 </informaltable>
2061 </sect3>
2063 <sect3>
2065 <para>
2066 There are a few different forms of DLL's wine can load:
2067 <variablelist>
2068 <varlistentry>
2070 <listitem><para>
2071 The DLL's that are included with windows. Many
2072 windows DLL's can be loaded in their native
2073 form. Many times these native versions work
2074 better than their non-Microsoft equivalent --
2075 other times they don't.
2076 </para></listitem>
2077 </varlistentry>
2078 <varlistentry>
2080 <listitem><para>
2081 The most common form of DLL loading. This is
2082 what you will use if the DLL is too system-specific
2083 or error-prone in native form (KERNEL for example),
2084 you don't have the native DLL, or you just want to be
2085 Microsoft-free.
2086 </para></listitem>
2087 </varlistentry>
2088 <varlistentry>
2090 <listitem><para>
2091 Native ELF libraries. Has been deprecated, ignored.
2092 </para></listitem>
2093 </varlistentry>
2094 <varlistentry>
2096 <listitem><para>
2097 ELF encapsulated windows DLL's.
2098 No longer used, ignored.
2099 </para></listitem>
2100 </varlistentry>
2101 </variablelist>
2102 </para>
2103 </sect3>
2104 </sect2>
2109 <para>
2111 </para>
2112 <para>
2114 </para>
2116 <para>
2117 The wine configuration file directives [DllDefaults]
2118 and [DllOverrides] are the subject of some confusion. The
2119 overall purpose of most of these directives are clear enough,
2120 though - given a choice, should Wine use its own built-in
2122 in an existing Windows installation? This document explains
2123 how this feature works.
2124 </para>
2126 <sect3>
2128 <variablelist>
2129 <varlistentry>
2131 <listitem> <para>
2133 written for the real Microsoft Windows.
2134 </para> </listitem>
2135 </varlistentry>
2136 <varlistentry>
2138 <listitem> <para>
2139 A "built-in" DLL is a Wine DLL. These can either be a
2142 that Wine is able to load on demand.
2143 </para> </listitem>
2144 </varlistentry>
2145 </variablelist>
2146 </sect3>
2148 <sect3>
2150 <variablelist>
2151 <varlistentry>
2153 <listitem> <para>
2154 This specifies in what order Wine should search for
2155 available DLL types, if the DLL in question was not
2156 found in the [DllOverrides] section.
2157 </para> </listitem>
2158 </varlistentry>
2159 </variablelist>
2160 </sect3>
2162 <sect3>
2164 <para>
2165 At one time, there was a section called [DllPairs] in the
2166 default configuration file, but this has been obsoleted
2167 because the pairing information has now been embedded into
2168 Wine itself. (The purpose of this section was merely to be
2169 able to issue warnings if the user attempted to pair
2173 </para>
2174 </sect3>
2176 <sect3>
2178 <para>
2179 This section specifies how you want specific DLLs to be
2180 handled, in particular whether you want to use "native" DLLs
2181 or not, if you have some from a real Windows configuration.
2182 Because built-ins do not mix seamlessly with native DLLs yet,
2183 certain DLL dependencies may be problematic, but workarounds
2184 exist in Wine for many popular DLL configurations. Also see
2185 WWN's [16]Status Page to figure out how well your favorite
2186 DLL is implemented in Wine.
2187 </para>
2188 <para>
2189 It is of course also possible to override these settings by
2191 command-line option (see the man page for details). Some
2192 hints for choosing your optimal configuration (listed by
2194 </para>
2195 <variablelist>
2196 <varlistentry>
2198 <listitem> <para>
2199 Native versions of these will never work, so don't try. Leave
2201 </para> </listitem>
2202 </varlistentry>
2203 <varlistentry>
2205 <listitem> <para>
2206 Graphics Device Interface. No effort has been made at trying to
2208 </para> </listitem>
2209 </varlistentry>
2210 <varlistentry>
2212 <listitem> <para>
2213 Window management and standard controls. It was
2215 versions at some point (if all other DLLs that depend
2216 on it, such as comctl32 and comdlg32, were also run
2218 possible after the Address Space Separation, so leave
2220 </para> </listitem>
2221 </varlistentry>
2222 <varlistentry>
2224 <listitem> <para>
2225 NT kernel API. Although badly documented, the
2228 </para> </listitem>
2229 </varlistentry>
2230 <varlistentry>
2232 <listitem> <para>
2234 version will probably never work. Leave at
2236 </para> </listitem>
2237 </varlistentry>
2238 <varlistentry>
2240 <listitem> <para>
2241 Win16 support library for NT. The
2244 </para> </listitem>
2245 </varlistentry>
2246 <varlistentry>
2248 <listitem> <para>
2249 Win16 kernel stuff. Will never work
2252 </para> </listitem>
2253 </varlistentry>
2254 <varlistentry>
2256 <listitem> <para>
2258 </para> </listitem>
2259 </varlistentry>
2260 <varlistentry>
2262 <listitem> <para>
2263 Tool helper routines. This is rarely a source of problems.
2265 </para> </listitem>
2266 </varlistentry>
2267 <varlistentry>
2269 <listitem> <para>
2270 Versioning. Seldom useful to mess with.
2271 </para> </listitem>
2272 </varlistentry>
2273 <varlistentry>
2275 <listitem> <para>
2276 Registry and security features. Trying the
2278 not work.
2279 </para> </listitem>
2280 </varlistentry>
2281 <varlistentry>
2283 <listitem> <para>
2284 Common Dialogs, such as color picker, font dialog,
2285 print dialog, open/save dialog, etc. It is safe to try
2287 </para> </listitem>
2288 </varlistentry>
2289 <varlistentry>
2291 <listitem> <para>
2292 Common Controls. This is toolbars, status bars, list controls,
2294 </para> </listitem>
2295 </varlistentry>
2296 <varlistentry>
2298 <listitem> <para>
2299 Shell interface (desktop, filesystem, etc). Being one of the
2300 most undocumented pieces of Windows, you may have luck with the
2302 </para> </listitem>
2303 </varlistentry>
2304 <varlistentry>
2306 <listitem> <para>
2308 will not work under Wine, so leave at
2310 </para> </listitem>
2311 </varlistentry>
2312 <varlistentry>
2314 <listitem> <para>
2315 ICMP routines for wsock32. As with wsock32, leave at
2317 </para> </listitem>
2318 </varlistentry>
2319 <varlistentry>
2321 <listitem> <para>
2323 to thunking issues. Leave at
2325 </para> </listitem>
2326 </varlistentry>
2327 <varlistentry>
2329 <listitem> <para>
2330 Lempel-Ziv decompression. Wine's
2332 </para> </listitem>
2333 </varlistentry>
2334 <varlistentry>
2336 <listitem> <para>
2337 Advanced SCSI Peripheral Interface. The
2340 </para> </listitem>
2341 </varlistentry>
2342 <varlistentry>
2344 <listitem> <para>
2346 version will easily work better than Wine's on this
2347 one.
2348 </para> </listitem>
2349 </varlistentry>
2350 <varlistentry>
2352 <listitem> <para>
2353 Printer spooler. You are not likely to have more luck
2355 </para> </listitem>
2356 </varlistentry>
2357 <varlistentry>
2359 <listitem> <para>
2360 DirectDraw/Direct3D. Since Wine does not implement the
2362 will not work at this time.
2363 </para> </listitem>
2364 </varlistentry>
2365 <varlistentry>
2367 <listitem> <para>
2369 may or may not work.
2370 </para> </listitem>
2371 </varlistentry>
2372 <varlistentry>
2374 <listitem> <para>
2375 DirectSound. It may be possible to run this
2377 </para> </listitem>
2378 </varlistentry>
2379 <varlistentry>
2381 <listitem> <para>
2383 ought to work best on this, if at all.
2384 </para> </listitem>
2385 </varlistentry>
2386 <varlistentry>
2388 <listitem> <para>
2390 version is not likely to work. Leave at
2392 </para> </listitem>
2393 </varlistentry>
2394 <varlistentry>
2396 <listitem> <para>
2397 Audio Compression Manager. The
2399 set msacm.drv to the same.
2400 </para> </listitem>
2401 </varlistentry>
2402 <varlistentry>
2404 <listitem> <para>
2405 Video for Windows. It is safe (and recommended) to try
2407 </para> </listitem>
2408 </varlistentry>
2409 <varlistentry>
2411 <listitem> <para>
2412 CD Audio MCI driver.
2413 </para> </listitem>
2414 </varlistentry>
2415 <varlistentry>
2417 <listitem> <para>
2419 playback).
2420 </para> </listitem>
2421 </varlistentry>
2422 <varlistentry>
2424 <listitem> <para>
2426 </para> </listitem>
2427 </varlistentry>
2428 <varlistentry>
2430 <listitem> <para>
2433 </para> </listitem>
2434 </varlistentry>
2435 <varlistentry>
2437 <listitem> <para>
2438 Animation MCI driver.
2439 </para> </listitem>
2440 </varlistentry>
2441 <varlistentry>
2443 <listitem> <para>
2444 Audio Compression Manager. Set to same as msacm32.
2445 </para> </listitem>
2446 </varlistentry>
2447 <varlistentry>
2449 <listitem> <para>
2450 MIDI Mapper.
2451 </para> </listitem>
2452 </varlistentry>
2453 <varlistentry>
2455 <listitem> <para>
2456 This is a pseudo-DLL used by Wine for thunking
2458 doesn't exist.
2459 </para> </listitem>
2460 </varlistentry>
2461 </variablelist>
2462 </sect3>
2463 </sect2>
2467 <para>
2468 The Wine team has determined that it is necessary to create
2469 fake DLL files to trick many programs that check for
2470 file existence to determine whether a particular feature
2471 (such as Winsock and its TCP/IP networking) is available. If
2472 this is a problem for you, you can create empty files in the
2474 to make the program think it's there, and Wine's built-in DLL
2475 will be loaded when the program actually asks for it.
2477 not create such empty files itself.)
2478 </para>
2479 <para>
2480 Applications sometimes also try to inspect the version
2481 resources from the physical files (for example, to determine
2482 the DirectX version). Empty files will not do in this case,
2483 it is rather necessary to install files with complete
2484 version resources. This problem is currently being worked
2485 on. In the meantime, you may still need to grab some real
2486 DLL files to fool these apps with.
2487 </para>
2488 <para>
2489 And there are of course DLLs that wine does not currently
2490 implement very well (or at all). If you do not have a real
2491 Windows you can steal necessary DLLs from, you can always
2492 get some from one of the Windows DLL archive sites
2493 that can be found via internet search engine.
2494 Please make sure to obey any licenses on the DLLs you fetch...
2495 (some are redistributable, some aren't).
2496 </para>
2497 </sect2>
2502 <para>
2504 </para>
2506 <para>
2507 In case Wine complains about a missing DLL, you should check whether
2508 this file is a publicly available DLL or a custom DLL belonging
2509 to your program (by searching for its name on the internet).
2510 If you managed to get hold of the DLL, then you should make sure
2511 that Wine is able to find and load it.
2512 DLLs usually get loaded according to the mechanism of the
2513 SearchPath() function.
2514 This function searches directories in the following order:
2516 <orderedlist>
2517 <listitem>
2518 <para>
2519 The directory the program was started from.
2520 </para>
2521 </listitem>
2522 <listitem>
2523 <para>
2524 The current directory.
2525 </para>
2526 </listitem>
2527 <listitem>
2528 <para>
2529 The Windows system directory.
2530 </para>
2531 </listitem>
2532 <listitem>
2533 <para>
2534 The Windows directory.
2535 </para>
2536 </listitem>
2537 <listitem>
2538 <para>
2539 The PATH variable directories.
2540 </para>
2541 </listitem>
2542 </orderedlist>
2544 In short: either put the required DLL into your program
2545 directory (might be ugly), or usually put it into the Windows system
2546 directory. Just find out its directory by having a look at the Wine
2547 configuration file variable "System" (which indicates the location of the
2548 Windows system directory) and the associated drive entry.
2549 Note that you probably shouldn't use NT-based native DLLs,
2550 since Wine's NT API support is somewhat weaker than its Win9x
2551 API support (thus leading to even worse compatibility with NT DLLs
2552 than with a no-windows setup!), so better use Win9x native DLLs
2553 instead or no native DLLs at all.
2554 </para>
2555 </sect2>
2560 <para>
2562 </para>
2564 <para>
2566 extract native Windows .dll files from .cab files that are to be
2567 found on many Windows installation CDs.
2568 </para>
2569 </sect2>
2570 </sect1>
2575 <para>
2576 Wine currently supports several different display subsystems
2577 (graphics / text) that are available on various operating
2578 systems today.
2579 For each of these, Wine implements its own interfacing driver.
2580 This section explains how to select one of these drivers
2581 and how to further configure the respective driver.
2582 Once you're finished with that, you can consider your Wine installation
2583 to be finished.
2584 </para>
2586 <para>
2587 The display drivers currently implemented in Wine are:
2588 x11drv, which is used for interfacing to X11 graphics
2589 (the one you'll most likely want to use) and ttydrv
2590 (used for text mode console apps mainly that don't really need
2591 any graphics output).
2592 Once you have decided which display driver to use, it is chosen
2595 </para>
2597 <sect2>
2600 <para>
2602 </para>
2603 <para>
2605 </para>
2607 <sect3>
2610 <para>
2611 The x11drv driver consists of two conceptually distinct
2612 pieces, the graphics driver (GDI part), and the windowing
2613 driver (USER part). Both of these are linked into the
2616 Wine, running on X11, the graphics driver must draw on
2617 drawables (window interiors) provided by the windowing
2618 driver. This differs a bit from the Windows model, where the
2619 windowing system creates and configures device contexts
2620 controlled by the graphics driver, and programs are
2621 allowed to hook into this relationship anywhere they like.
2622 Thus, to provide any reasonable tradeoff between
2623 compatibility and usability, the x11drv has three different
2624 modes of operation.
2625 </para>
2627 <variablelist>
2628 <varlistentry>
2630 <listitem>
2631 <para>
2633 wine configuration file option (see below).
2634 Ordinary top-level frame windows with thick borders,
2635 title bars, and system menus will be managed by your
2636 window manager. This lets these programs integrate
2637 better with the rest of your desktop, but may not
2638 always work perfectly (a rewrite of this mode of
2639 operation, to make it more robust and less patchy, is
2640 currently being done, though, and it's planned to be
2641 finished before the Wine 1.0 release).
2642 </para>
2643 </listitem>
2644 </varlistentry>
2645 <varlistentry>
2647 <listitem>
2648 <para>
2649 Window manager independent (any running
2650 window manager is ignored completely). Window
2651 decorations (title bars, borders, etc) are drawn by
2652 Wine to look and feel like the real Windows. This is
2653 compatible with programs that depend on being able
2654 to compute the exact sizes of any such decorations, or
2655 that want to draw their own.
2656 Unmanaged mode is only used if both Managed and Desktop
2657 are set to disabled.
2658 </para>
2659 </listitem>
2660 </varlistentry>
2661 <varlistentry>
2663 <listitem>
2664 <para>
2666 wine configuration file option (see below).
2668 for a such-sized desktop, or
2670 automatically position the desktop at the upper-left
2671 corner of the display). This is the mode most
2672 compatible with the Windows model. All program
2673 windows will just be Wine-drawn windows inside the
2674 Wine-provided desktop window (which will itself be
2675 managed by your window manager), and Windows
2676 programs can roam freely within this virtual
2677 workspace and think they own it all, without
2678 disturbing your other X apps.
2679 Note: currently there's one desktop window for every
2680 program; this will be fixed at some time.
2681 </para>
2682 </listitem>
2683 </varlistentry>
2684 </variablelist>
2685 </sect3>
2687 <sect3>
2690 <variablelist>
2691 <varlistentry>
2693 <listitem>
2694 <para>
2695 Wine can let frame windows be managed by your window
2696 manager. This option specifies whether you want that
2697 by default.
2698 </para>
2699 </listitem>
2700 </varlistentry>
2701 <varlistentry>
2703 <listitem>
2704 <para>
2705 Creates a main desktop window of a specified size
2706 to display all Windows programs in.
2707 The size argument could e.g. be "800x600".
2708 </para>
2709 </listitem>
2710 </varlistentry>
2711 <varlistentry>
2713 <listitem>
2714 <para>
2715 If you don't use DGA, you may want an alternative
2716 means to convince the mouse cursor to stay within the
2717 game window. This option does that. Of course, as with
2718 DGA, if Wine crashes, you're in trouble (although not
2719 as badly as in the DGA case, since you can still use
2720 the keyboard to get out of X).
2721 </para>
2722 </listitem>
2723 </varlistentry>
2724 <varlistentry>
2726 <listitem>
2727 <para>
2728 This specifies whether you want DirectDraw to use
2729 XFree86's <firstterm>Direct Graphics
2730 Architecture</firstterm> (DGA), which is able to
2731 take over the entire display and run the game
2732 full-screen at maximum speed. (With DGA1 (XFree86
2733 3.x), you still have to configure the X server to the
2734 game's requested bpp first, but with DGA2 (XFree86
2735 4.x), runtime depth-switching may be possible,
2736 depending on your driver's capabilities.) But be aware
2737 that if Wine crashes while in DGA mode, it may not be
2738 possible to regain control over your computer without
2739 rebooting. DGA normally requires either root
2740 privileges or read/write access to
2742 </para>
2743 </listitem>
2744 </varlistentry>
2745 <varlistentry>
2747 <listitem>
2748 <para>
2749 If you don't want DirectX to use DGA, you can at least
2750 use X Shared Memory extensions (XShm). It is much
2751 slower than DGA, since the app doesn't have direct
2752 access to the physical frame buffer, but using shared
2753 memory to draw the frame is at least faster than
2754 sending the data through the standard X11 socket, even
2755 though Wine's XShm support is still known to crash
2756 sometimes.
2757 </para>
2758 </listitem>
2759 </varlistentry>
2760 <varlistentry>
2762 <listitem>
2763 <para>
2764 Applies only if you use the
2766 to run in a desktop window. Specifies whether to
2767 create the desktop window with a double-buffered
2768 visual, something most OpenGL games need to run
2769 correctly.
2770 </para>
2771 </listitem>
2772 </varlistentry>
2773 <varlistentry>
2775 <listitem>
2776 <para>
2777 Applies only if you have a palette-based display, i.e.
2778 if your X server is set to a depth of 8bpp, and if you
2779 haven't requested a private color map. It specifies
2780 the maximum number of shared colormap cells (palette
2781 entries) Wine should occupy. The higher this value,
2782 the less colors will be available to other
2783 programs.
2784 </para>
2785 </listitem>
2786 </varlistentry>
2787 <varlistentry>
2789 <listitem>
2790 <para>
2791 Applies only if you have a palette-based display, i.e.
2792 if your X server is set to a depth of 8bpp. It
2793 specifies that you don't want to use the shared color
2794 map, but a private color map, where all 256 colors are
2795 available. The disadvantage is that Wine's private
2796 color map is only seen while the mouse pointer is
2797 inside a Wine window, so psychedelic flashing and
2798 funky colors will become routine if you use the mouse
2799 a lot.
2800 </para>
2801 </listitem>
2802 </varlistentry>
2803 <varlistentry>
2805 <listitem>
2806 <para>
2807 To be used for debugging X11 operations.
2808 If Wine crashes with an X11 error, then you should enable
2809 Synchronous mode to disable X11 request caching in order
2810 to make sure that the X11 error happens directly after
2811 the corresponding X11 call in the log file appears.
2812 Will slow down X11 output!
2813 </para>
2814 </listitem>
2815 </varlistentry>
2816 <varlistentry>
2818 <listitem>
2819 <para>
2820 Applies only to multi-depth displays. It specifies
2821 which of the available depths Wine should use (and
2822 tell Windows apps about).
2823 </para>
2824 </listitem>
2825 </varlistentry>
2826 <varlistentry>
2828 <listitem>
2829 <para>
2830 This specifies which X11 display to use, and if
2831 specified, will override the
2833 </para>
2834 </listitem>
2835 </varlistentry>
2836 <varlistentry>
2838 <listitem>
2839 <para>
2840 This option only determines whether fast X11 routines
2841 or exact Wine routines will be used for certain ROP
2842 codes in blit operations. Most users won't notice any
2843 difference.
2844 </para>
2845 </listitem>
2846 </varlistentry>
2847 <varlistentry>
2849 <listitem>
2850 <para>
2851 Codepage to be used for rendering the text in X11
2852 output. Some sample values would be 437 (USA, Canada),
2854 (Cyrillic). For additional suitable values, see e.g. the Linux
2855 kernel's codepage configuration page.
2856 </para>
2857 </listitem>
2858 </varlistentry>
2859 </variablelist>
2860 </sect3>
2861 </sect2>
2863 <sect2>
2865 <para>
2866 Currently, the ttydrv doesn't have any special configuration
2867 options to set in the configuration file.
2868 </para>
2869 </sect2>
2871 </sect1>
2877 <para>
2879 Oct 18 2002
2880 </para>
2882 <para>
2883 The windows and DOS version value a program gets e.g. by calling the
2884 Windows function GetVersion() plays a very important role:
2885 If your Wine installation for whatever reason fails to provide
2886 to your program the correct version value that it expects,
2887 then the program might assume some very bad things and fail (in
2888 the worst case even silently!).
2890 Fortunately Wine contains some more or less intelligent Windows
2891 version guessing algorithm that will try to guess the Windows
2892 version a program might expect and pass that one on to the
2893 program.
2895 Thus you should <emphasis>not</emphasis> lightly configure a version value, as this will be a "forced" value and thus turn out to be rather harmful to proper operation. In other words: only explicitly set a Windows version value in case Wine's own version detection was unable to provide the correct Windows version and the program fails.
2896 </para>
2898 <sect2>
2899 <title>How to configure the Windows and DOS version value Wine
2900 should return</title>
2902 <para>
2903 The version values can be configured in the wine configuration file in
2904 the [Version] section.
2905 </para>
2907 <variablelist>
2908 <varlistentry>
2910 <listitem>
2911 <para>
2912 default: none; chosen by semi-intelligent detection
2913 mechanism based on DLL environment.
2914 Used to specify which Windows version to return to
2915 programs (forced value, overrides standard detection
2918 Also valid as an
2920 setting (recommended/preferred use).
2921 </para>
2922 </listitem>
2923 </varlistentry>
2924 <varlistentry>
2926 <listitem>
2927 <para>
2928 Used to specify the DOS version that should be returned
2929 to programs. Only takes effect in case Wine acts as
2930 "win31" Windows version! Common DOS version settings
2932 Also valid as an
2934 setting (recommended/preferred use).
2935 </para>
2936 </listitem>
2937 </varlistentry>
2938 </variablelist>
2939 </sect2>
2940 </sect1>
2942 &fonts;
2943 &printing;
2947 <para>
2949 </para>
2950 <para>
2952 </para>
2953 <para>
2954 Win95/Win98 interface code is being introduced.
2955 </para>
2956 <para>
2957 Instead of compiling Wine for Win3.1 vs. Win95 using
2959 special [Tweak.Layout] section of
2963 </para>
2964 <para>
2965 A few new sections and a number of entries have been added to
2967 debugging the Win95 tweaks only and may be removed in a future
2968 release! These entries/sections are:
2969 </para>
2970 <programlisting>
2971 [Tweak.Fonts]
2977 "OEMFixed.xxx" # Same parameters for the OEM fixed typeface
2978 "AnsiFixed.xxx" # Same parameters for the Ansi fixed typeface
2979 "AnsiVar.xxx" # Same parameters for the Ansi variable typeface
2980 "SystemFixed.xxx" # Same parameters for the System fixed typeface
2982 [Tweak.Layout]
2984 </programlisting>
2985 </sect1>
2990 <para>
2992 </para>
2993 <para>
2995 </para>
2997 <para>
2998 Wine now needs to know about your keyboard layout. This
2999 requirement comes from a need from many apps to have the
3000 correct scancodes available, since they read these directly,
3001 instead of just taking the characters returned by the X
3002 server. This means that Wine now needs to have a mapping from
3003 X keys to the scancodes these programs expect.
3004 </para>
3005 <para>
3006 On startup, Wine will try to recognize the active X layout by
3007 seeing if it matches any of the defined tables. If it does,
3008 everything is alright. If not, you need to define it.
3009 </para>
3010 <para>
3011 To do this, open the file
3013 at the existing tables. Make a backup copy of it, especially
3014 if you don't use CVS.
3015 </para>
3016 <para>
3017 What you really would need to do, is find out which scancode
3018 each key needs to generate. Find it in the
3020 this:
3021 </para>
3022 <programlisting>
3023 static const int main_key_scan[MAIN_LEN] =
3024 {
3025 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
3031 };
3032 </programlisting>
3033 <para>
3034 Next, assign each scancode the characters imprinted on the
3035 keycaps. This was done (sort of) for the US 101-key keyboard,
3036 which you can find near the top in
3038 is no 102nd key, you can skip that.
3039 </para>
3040 <para>
3041 However, for most international 102-key keyboards, we have
3042 done it easy for you. The scancode layout for these already
3043 pretty much matches the physical layout in the
3045 to go through all the keys that generate characters on your
3046 main keyboard (except spacebar), and stuff those into an
3047 appropriate table. The only exception is that the 102nd key,
3048 which is usually to the left of the first key of the last line
3050 line after the last line.
3051 </para>
3052 <para>
3053 For example, my Norwegian keyboard looks like this
3054 </para>
3055 <screen>
3056 § ! " # ¤ % & / ( ) = ? ` Back-
3057 | 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
3059 Tab Q W E R T Y U I O P Å ^
3060 ¨~
3061 Enter
3062 Caps A S D F G H J K L Ø Æ *
3063 Lock '
3065 Sh- > Z X C V B N M ; : _ Shift
3066 ift < , . -
3068 Ctrl Alt Spacebar AltGr Ctrl
3069 </screen>
3070 <para>
3071 Note the 102nd key, which is the <keycap><></keycap> key, to
3072 the left of <keycap>Z</keycap>. The character to the right of
3073 the main character is the character generated by
3074 <keycap>AltGr</keycap>.
3075 </para>
3076 <para>
3077 This keyboard is defined as follows:
3078 </para>
3079 <programlisting>
3080 static const char main_key_NO[MAIN_LEN][4] =
3081 {
3086 "<>"
3087 };
3088 </programlisting>
3089 <para>
3090 Except that " and \ needs to be quoted with a backslash, and
3091 that the 102nd key is on a separate line, it's pretty
3092 straightforward.
3093 </para>
3094 <para>
3095 After you have written such a table, you need to add it to the
3096 <function>main_key_tab[]</function> layout index table. This
3097 will look like this:
3098 </para>
3099 <programlisting>
3100 static struct {
3101 WORD lang, ansi_codepage, oem_codepage;
3102 const char (*key)[MAIN_LEN][4];
3103 } main_key_tab[]={
3104 ...
3105 ...
3106 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
3107 ...
3108 </programlisting>
3109 <para>
3110 After you have added your table, recompile Wine and test that
3111 it works. If it fails to detect your table, try running
3112 </para>
3113 <screen>
3114 wine --debugmsg +key,+keyboard >& key.log
3115 </screen>
3116 <para>
3117 and look in the resulting <filename>key.log</filename> file to
3118 find the error messages it gives for your layout.
3119 </para>
3120 <para>
3121 Note that the <constant>LANG_*</constant> and
3122 <constant>SUBLANG_*</constant> definitions are in
3123 <filename>include/winnls.h</filename>, which you might need to
3124 know to find out which numbers your language is assigned, and
3125 find it in the debugmsg output. The numbers will be
3126 <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
3127 the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
3128 <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
3129 <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
3130 could look for <literal>0414</literal> in the debugmsg output
3131 to find out why my keyboard won't detect.
3132 </para>
3133 <para>
3134 Once it works, submit it to the Wine project. If you use CVS,
3135 you will just have to do
3136 </para>
3137 <screen>
3138 cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
3139 </screen>
3140 <para>
3141 from your main Wine directory, then submit
3142 <filename>layout.diff</filename> to
3143 <email>wine-patches@winehq.com</email> along with a brief note
3144 of what it is.
3145 </para>
3146 <para>
3147 If you don't use CVS, you need to do
3148 </para>
3149 <screen>
3150 diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
3151 </screen>
3152 <para>
3153 and submit it as explained above.
3154 </para>
3155 <para>
3156 If you did it right, it will be included in the next Wine
3157 release, and all the troublesome programs (especially
3158 remote-control programs) and games that use scancodes will
3159 be happily using your keyboard layout, and you won't get those
3160 annoying fixme messages either.
3161 </para>
3162 <para>
3163 Good luck.
3164 </para>
3165 </sect1>
3168 <title>SCSI Support</title>
3169 <para>
3170 Written by &name-bruce-milner; <email>&email-bruce-milner;</email>;
3171 Additions by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
3172 </para>
3173 <para>
3174 (Extracted from <filename>wine/documentation/aspi</filename>)
3175 </para>
3177 <para>
3178 This file describes setting up the Windows ASPI interface.
3179 </para>
3181 <para>
3182 <warning><title>Warning/Warning/Warning!!!!!!</title>
3183 <para>This may trash your system if used incorrectly. It may
3184 even trash your system when used <emphasis>correctly</>!
3185 </para>
3186 </warning>
3187 </para>
3189 <para>
3190 Now that I have said that. ASPI is a direct link to SCSI devices from
3191 windows programs. ASPI just forwards the SCSI commands that programs send
3192 to it to the SCSI bus.
3193 </para>
3194 <para>
3195 If you use the wrong SCSI device in your setup file, you can send
3196 completely bogus commands to the wrong device - An example would be
3197 formatting your hard drives (assuming the device gave you permission -
3198 if you're running as root, all bets are off).
3199 </para>
3200 <para>
3201 So please make sure that <emphasis>all</emphasis> SCSI devices not needed by the program
3202 have their permissions set as restricted as possible!
3203 </para>
3205 <para>
3206 Cookbook for setting up scanner: (At least how mine is to work)
3207 (well, for other devices such as CD burners, MO drives, ..., too)
3208 </para>
3210 <sect2>
3211 <title>Windows requirements</title>
3212 <orderedlist>
3213 <listitem>
3214 <para>
3216 compatible drivers (ASPI). At least with Mustek, they
3217 allow you the choice of using the built-in card or the
3219 any other way. Software that accesses the scanner via a
3220 DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM]
3221 </para>
3222 </listitem>
3223 <listitem>
3224 <para>
3225 You probably need a real windows install of the software
3226 to set the LUN's/SCSI id's up correctly. I'm not exactly
3227 sure.
3228 </para>
3229 </listitem>
3230 </orderedlist>
3231 </sect2>
3233 <sect2>
3234 <title>Linux requirements</title>
3235 <orderedlist>
3236 <listitem>
3237 <para>
3238 Your SCSI card must be supported under Linux. This will
3239 not work with an unknown SCSI card. Even for cheap'n
3241 drivers exist on the net.
3242 If you intend to use your IDE device, you need to use the
3243 ide-scsi emulation.
3244 Read
3246 http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html</ulink>
3247 for ide-scsi setup instructions.
3248 </para>
3249 </listitem>
3250 <listitem>
3251 <para>
3252 Compile generic SCSI drivers into your kernel.
3253 </para>
3254 </listitem>
3255 <listitem>
3256 <para>
3257 This seems to be not required any more for newer (2.2.x) kernels:
3258 Linux by default uses smaller SCSI buffers than Windows.
3259 There is a kernel build define <literal>SG_BIG_BUFF</literal> (in
3260 <filename>sg.h</filename>) that is by default set too
3261 low. The SANE project recommends
3262 <literal>130560</literal> and this seems to work just
3263 fine. This does require a kernel rebuild.
3264 </para>
3265 </listitem>
3266 <listitem>
3267 <para>
3268 Make the devices for the scanner (generic SCSI devices)
3269 - look at the SCSI programming HOWTO at
3271 http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html</ulink>
3272 for device numbering.
3273 </para>
3274 </listitem>
3275 <listitem>
3276 <para>
3277 I would recommend making the scanner device writable by
3278 a group. I made a group called
3279 <literal>scanner</literal> and added myself to it.
3280 Running as root increases your risk of sending bad SCSI
3281 commands to the wrong device. With a regular user, you
3282 are better protected.
3283 </para>
3284 </listitem>
3285 <listitem>
3286 <para>
3287 For Win32 software (WNASPI32), Wine has auto-detection in place.
3288 For Win16 software (WINASPI), you need to add a SCSI device entry
3289 for your particular scanner to ~/.wine/config. The format is
3290 <literal>[scsi cCtTdD]</literal> where
3293 </para>
3294 <para>
3295 For example, I set mine up as controller <literal>0</literal>,
3296 Target <literal>6</literal>, LUN <literal>0</literal>.
3297 <programlisting>
3298 [scsi c0t6d0]
3300 </programlisting>
3301 Yours will vary with your particular SCSI setup.
3302 </para>
3303 </listitem>
3304 </orderedlist>
3305 </sect2>
3307 <sect2>
3308 <title>General Information</title>
3309 <para>
3310 The mustek scanner I have was shipped with a package
3312 to access scanners.
3313 </para>
3314 <para>
3315 (TWAIN MANAGER)
3316 </para>
3317 <para>
3318 <programlisting>
3319 ipplus.exe <-> (TWAIN INTERFACE) <-> (TWAIN DATA SOURCE.ASPI) -> WINASPI
3320 </programlisting>
3321 </para>
3322 </sect2>
3324 <sect2>
3325 <title>NOTES/BUGS</title>
3326 <para>
3327 The biggest drwback is that it only works under Linux at the moment.
3328 </para>
3329 <para>
3330 The ASPI code has only been tested with:
3331 </para>
3332 <itemizedlist>
3333 <listitem>
3334 <para>
3335 a Mustek 800SP with a Buslogic controller under Linux [BM]
3336 </para>
3337 </listitem>
3338 <listitem>
3339 <para>
3340 a Siemens Nixdorf 9036 with Adaptec AVA-1505 under Linux
3341 accessed via DOSASPI. Note that I had color problems,
3342 though (barely readable result) [AM]
3343 </para>
3344 </listitem>
3345 <listitem>
3346 <para>
3347 a Fujitsu M2513A MO drive (640MB) using generic SCSI
3348 drivers. Formatting and ejecting worked perfectly.
3349 Thanks to Uwe Bonnes for access to the hardware! [AM]
3350 </para>
3351 </listitem>
3352 </itemizedlist>
3353 <para>
3354 I make no warranty to the ASPI code. It makes my scanner
3355 work. Your devices may explode. I have no way of determining
3356 this. I take zero responsibility!
3357 </para>
3358 </sect2>
3359 </sect1>
3362 <title>Using ODBC</title>
3363 <para>
3364 This section describes how ODBC works within Wine and how to configure
3365 it to do what you want (if it can do what you want).
3366 </para>
3367 <para>
3368 The ODBC system within Wine, as with the printing system, is designed
3369 to hook across to the Unix system at a high level. Rather than
3370 ensuring that all the windows code works under wine it uses a suitable
3371 Unix ODBC provider, such as UnixODBC. Thus if you configure Wine to
3372 use the built-in odbc32.dll, that Wine DLL will interface to your
3373 Unix ODBC package and let that do the work, whereas if you configure
3374 Wine to use the native odbc32.dll it will try to use the native
3375 ODBC32 drivers etc.
3376 </para>
3377 <sect2>
3378 <title>Using a Unix ODBC system with Wine</title>
3379 <para>
3380 The first step in using a Unix ODBC system with Wine is, of course,
3381 to get the Unix ODBC system working itself. This may involve
3382 downloading code or RPMs etc. There are several Unix ODBC systems
3383 available; the one the author is used to is unixODBC (with the
3384 IBM DB2 driver). Typically such systems will include a tool, such
3385 as <command>isql</command>, which will allow you to access the data from the command
3386 line so that you can check that the system is working.
3387 </para>
3388 <para>
3389 The next step is to hook the Unix ODBC library to the wine built-in
3390 odbc32 DLL. The built-in odbc32 (currently) looks to the
3391 environment variable <emphasis>LIB_ODBC_DRIVER_MANAGER</emphasis>
3392 for the name of the ODBC library. For example in the author's
3393 .bashrc file is the line:
3394 </para>
3395 <programlisting>
3396 export LIB_ODBC_DRIVER_MANAGER=/usr/lib/libodbc.so.1.0.0
3397 </programlisting>
3398 <para>
3399 If that environment variable is not set then it looks for a
3400 library called libodbc.so and so you can add a symbolic link to
3401 equate that to your own library. For example as root you could
3402 run the commands:
3403 </para>
3404 <screen>
3405 <prompt># </prompt><userinput>ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so</userinput>
3406 <prompt># </prompt><userinput>/sbin/ldconfig</userinput>
3407 </screen>
3408 <para>
3409 The last step in configuring this is to ensure that Wine is set up
3410 to run the built-in version of odbc32.dll, by modifying the DLL
3411 configuration. This built-in DLL merely acts as a stub between the
3412 calling code and the Unix ODBC library.
3413 </para>
3414 <para>
3415 If you have any problems then you can use the debugmsg channel
3416 odbc32 to trace what is happening. One word of warning. Some
3417 programs actually cheat a little and bypass the ODBC library. For
3418 example the Crystal Reports engine goes to the registry to check on
3419 the DSN. The fix for this is documented at unixODBC's site where
3420 there is a section on using unixODBC with Wine.
3421 </para>
3422 </sect2>
3423 <sect2>
3424 <title>Using Windows ODBC drivers</title>
3425 <para>
3426 Does anyone actually have any experience of this and anything to
3427 add?
3428 </para>
3429 </sect2>
3430 </sect1>
3432 </chapter>
3434 <!-- Keep this comment at the end of the file
3435 Local variables:
3436 mode: sgml
3438 End:
3439 -->