| blob | d7f86dc0b687b249e85a7be56f4740aec5ae8838 |
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 Note that since the Wine configuration file is a part of the
226 Wine registry file system, this file also
228 Version 2" header line to be recognized properly, just like
229 all other Wine registry text files (just in case you decided
230 to write your own registry file from scratch and wonder why
231 Wine keeps rejecting it).
232 </para>
233 <para>
234 The settings available in the configuration file include:
235 <itemizedlist>
236 <listitem>
237 <para>
238 Drives and information about them
239 </para>
240 </listitem>
241 <listitem>
242 <para>
243 Directory settings
244 </para>
245 </listitem>
246 <listitem>
247 <para>
248 Port settings
249 </para>
250 </listitem>
251 <listitem>
252 <para>
253 The Wine look and feel
254 </para>
255 </listitem>
256 <listitem>
257 <para>
258 Wine's DLL usage
259 </para>
260 </listitem>
261 <listitem>
262 <para>
263 Wine's multimedia drivers and DLL configuration
264 </para>
265 </listitem>
266 </itemizedlist>
267 </para>
268 </sect2>
270 <sect2>
272 <para>
273 If you just installed Wine for the first time and want to
274 finish Wine installation by configuring it now, then you could
276 (which can be found in the directory
278 code directory) as a base for adapting the Wine configuration
279 file to the settings you want.
280 First, I should mention that you should not forget to make
281 sure that any previous configuration file at
283 of the way instead of simply overwriting it when you will now
284 copy over the sample configuration file.
285 </para>
286 <para>
287 If you don't have a pre-existing configuration file and thus
288 need to copy over our sample configuration file to the
289 standard Wine configuration file location, do in a
291 <screen>
293 <prompt>$ </><userinput>cp <replaceable>dir_to_wine_source_code</replaceable>/documentation/samples/config ~/.wine/config</>
294 </screen>
295 Otherwise, simply use the already existing configuration file
297 </para>
298 <para>
299 Now you can start adapting the configuration file's settings with an
301 below.
303 configuration file settings if wineserver is not running (in
304 other words: if your user doesn't have a Wine session running),
305 otherwise Wine won't use them - and even worse, wineserver will
306 overwrite them with the old settings once wineserver quits!!
307 </para>
308 </sect2>
313 <para>
314 Let's start by giving an overview of which sections a
315 configuration file may contain, and whether the inclusion of
316 the respective section is <emphasis>needed</emphasis> or only <emphasis>recommended</emphasis> ("recmd").
317 </para>
321 <thead>
322 <row>
326 </row>
327 </thead>
328 <tbody>
329 <row>
333 </row>
334 <row>
338 </row>
339 <row>
343 </row>
344 <row>
348 </row>
349 <row>
353 </row>
354 <row>
358 </row>
359 <row>
363 </row>
364 <row>
368 </row>
369 <row>
373 </row>
374 <row>
378 </row>
379 <row>
383 </row>
384 <row>
388 </row>
389 <row>
393 </row>
394 <row>
398 </row>
399 <row>
403 </row>
404 <row>
408 </row>
409 <row>
413 </row>
414 <row>
418 </row>
419 <row>
423 </row>
424 <row>
428 </row>
429 <row>
433 </row>
434 </tbody>
435 </tgroup>
436 </informaltable>
438 <para>
439 Now let's explain the configuration file sections in a
440 detailed way.
441 </para>
443 <sect3>
445 <para>
446 For a detailed description of these configuration file
447 sections which are used to set up DOS drive mappings to Unix
448 directory space, please look at the <link
450 configuration section</link>.
451 </para>
452 </sect3>
456 <para>
457 The [wine] section of the configuration file contains all kinds
458 of general settings for Wine.
459 </para>
460 <para>
461 <programlisting>
467 </programlisting>
468 For a detailed description of drive layer configuration and
469 the meaning of these parameters, please look at the <link
471 configuration section</link>.
472 </para>
473 <para>
475 Sets the graphics driver to use for Wine output.
476 x11drv is for X11 output, ttydrv is for text console output.
477 WARNING: if you use ttydrv here, then you won't be able to run
478 a lot of Windows GUI programs (ttydrv is still pretty "broken"
479 at running graphical apps). Thus this option is mainly interesting
480 for e.g. embedded use of Wine in web server scripts.
481 Note that ttydrv is still very lacking, so if it doesn't work,
482 resort to using "xvfb", a virtual X11 server.
483 Another way to run Wine without display would be to run X11
484 via Xvnc, then connect to that VNC display using xvncviewer
485 (that way you're still able to connect to your app and
486 configure it if need be).
487 </para>
488 <para>
490 whether to allow printing via printer drivers to work.
491 This option isn't needed for our built-in psdrv printer driver
492 at all.
493 Using these things are pretty alpha, so you might want to
494 watch out. Some people might find it useful, however. If
495 you're not planning to work on printing via windows printer
496 drivers, don't even add this to your wine configuration file
497 (It probably isn't already in it).
498 Check out the [spooler] and [parallelports] sections too.
499 </para>
500 <para>
502 This setting specifies the shell linker script to use for setting
503 up Windows icons in e.g. KDE or Gnome that are given by programs
504 making use of appropriate shell32.dll functionality to create
505 icons on the desktop/start menu during installation.
506 </para>
507 <para>
509 Sets up the symbol table file for the wine debugger. You
510 probably don't need to fiddle with this. May be useful if
511 your wine is stripped.
512 </para>
513 </sect3>
517 <para>
518 These settings provide wine's default handling of DLL loading.
519 </para>
520 <para>
522 </para>
523 <para>
524 This setting is a comma-delimited list of the order in
525 which to attempt loading DLLs. If the first option fails,
526 it will try the second, and so on. The order specified
527 above is probably the best in most conditions.
528 </para>
529 </sect3>
531 <sect3>
533 <para>
534 At one time, there was a section called [DllPairs] in the
535 default configuration file, but this has been obsoleted
536 because the pairing information has now been embedded into
537 Wine itself. (The purpose of this section was merely to be
538 able to issue warnings if the user attempted to pair
542 </para>
543 </sect3>
547 <para>
548 The format for this section is the same for each line:
549 <programlisting>
551 </programlisting>
552 </para>
553 <para>
554 For example, to load built-in KERNEL pair (case doesn't
555 matter here):
556 <programlisting>
558 </programlisting>
559 </para>
560 <para>
561 To load the native COMMDLG pair, but if that doesn't work
562 try built-in:
563 <programlisting>
565 </programlisting>
566 </para>
567 <para>
568 To load the native COMCTL32:
569 <programlisting>
571 </programlisting>
572 </para>
573 <para>
574 Here is a good generic setup (As it is defined in config
575 that was included with your wine package):
576 <programlisting>
577 [DllOverrides]
614 ; you can specify programs too
616 ; default for all other DLLs
618 </programlisting>
619 </para>
620 <note>
621 <para>
622 If loading of the libraries that are listed first fails,
623 wine will just go on by using the second or third option.
624 </para>
625 </note>
626 </sect3>
630 <para>
631 This section sets up wine's font handling.
632 </para>
633 <para>
635 </para>
636 <para>
637 Since the way X handles fonts is different from the way
638 Windows does, wine uses a special mechanism to deal with
639 them. It must scale them using the number defined in the
641 a nice in the middle one. If you have the real windows
645 important. Of course, it's always good to get your X fonts
646 working acceptably in wine.
647 </para>
648 <para>
650 The default font wine uses. Fool around with it if you'd like.
651 </para>
652 <para>
653 OPTIONAL:
654 </para>
655 <para>
657 used in wine. This is good for apps that need a special font you don't have,
658 but a good replacement exists. The syntax is like so:
659 <programlisting>
661 </programlisting>
662 </para>
663 <para>
665 then "Alias1" and so on. The fake windows name is the name
666 that the font will be under a windows app in wine. The
667 real X name is the font name as seen by X (Run
669 utilize the fake windows name you define. If it is not
670 used, then wine will just try to extract the fake windows
671 name itself and not use the value you enter.
672 </para>
673 <para>
674 Here is an example of an alias without masking. The font will show up in windows
675 apps as "Google".
677 <programlisting>
679 </programlisting>
680 </para>
681 <para>
682 Here is an example with masking enabled. The font will show up as "Foo" in
683 windows apps.
684 <programlisting>
686 </programlisting>
687 </para>
688 <para>
690 chapter.
691 </para>
692 </sect3>
696 <para>
697 Even though it sounds like a lot of sections, these are
698 all closely related. They are all for communications and
699 parallel ports.
700 </para>
701 <para>
702 The [serialports] section tells wine what serial ports it
703 is allowed to use.
705 </para>
706 <para>
711 can actually equal any device
713 not always necessary to define any COM ports (An optional
714 setting). Here is an example:
716 </para>
717 <para>
718 Use as many of these as you like in the section to define
719 all of the COM ports you need.
720 </para>
721 <para>
722 The [parallelports] section sets up any parallel ports
723 that will be allowed access under wine.
725 </para>
726 <para>
727 Sounds familiar? Syntax is just like the COM port setting.
731 minus 1, just like for COM ports). You don't always need
732 to define a parallel port (AKA, it's optional). As with
733 the other section, LptX can equal any device (Maybe
736 </para>
737 <para>
738 The [spooler] section will inform wine where to spool
739 print jobs. Use this if you want to try printing. Wine
740 docs claim that spooling is "rather primitive" at this
742 setting you use in this section works to map a port (LPT1,
743 for example) to a file or a command. Here is an example,
746 </para>
747 <para>
748 The following command maps printing jobs to LPT1 to the
751 </para>
752 <para>
753 The [ports] section is usually useful only for people who
754 need direct port access for programs requiring dongles or
755 scanners. <emphasis>If you don't need it, don't use
756 it!</emphasis>
757 </para>
758 <para>
760 Gives direct read access to those IO's.
761 </para>
762 <para>
764 Gives direct write access to those IO's. It's probably a
765 good idea to keep the values of the
767 settings the same. This stuff will only work when you're
768 root.
769 </para>
770 </sect3>
774 <para>
775 [Debug] is used to include or exclude debug messages, and to
776 output them to a file. The latter is rarely used. <emphasis>These
777 are all optional and you probably don't need to add or
778 remove anything in this section to your config.</emphasis> (In extreme
779 cases you may want to use these options to manage the amount
780 of information generated by the <parameter>--debugmsg +relay
781 </parameter> option.)
782 </para>
783 <para>
785 Sets the logfile for wine. Set to CON to log to standard out.
787 </para>
788 <para>
792 </para>
793 <para>
797 </para>
798 <para>
800 Include only the listed functions in a
803 </para>
804 <para>
805 <programlisting>"RelayExclude" = "RtlEnterCriticalSection;RtlLeaveCriticalSection"</programlisting>
806 Exclude the listed functions in a
809 entry. If neither entry is present then the trace includes
810 everything.
811 </para>
812 <para>
813 In both entries the functions may be specified either as a
814 function name or as a module and function. In this latter
815 case specify an asterisk for the function name to include/exclude
816 all functions in the module.
817 </para>
818 <para>
819 [Registry] can be used to tell wine where your old windows
820 registry files exist. This section is completely optional
821 and useless to people using wine without an existing
822 windows installation.
823 </para>
824 <para>
827 </para>
828 <para>
829 [tweak.layout] is devoted to wine's look. There is only
830 one setting for it.
831 </para>
832 <para>
837 </para>
838 <para>
839 [programs] can be used to say what programs run under
840 special conditions.
841 </para>
842 <para>
844 Sets the program to be run if wine is started without specifying a program.
845 </para>
846 <para>
848 Sets the program to automatically be run at startup every time.
849 </para>
850 </sect3>
854 <para>
855 [WinMM] is used to define which multimedia drivers have to be loaded. Since
856 those drivers may depend on the multimedia interfaces available on your system
857 (OSS, ALSA... to name a few), it's needed to be able to configure which driver
858 has to be loaded.
859 </para>
861 <para>
862 The content of the section looks like:
863 <programlisting>
864 [WinMM]
868 </programlisting>
869 All the keys must be defined:
870 <itemizedlist>
871 <listitem>
872 <para>
873 The "Drivers" key is a ';' separated list of modules name, each of
874 them containing a low level driver. All those drivers will be loaded
875 when MMSYSTEM/WINMM is started and will provide their inner features.
876 </para>
877 </listitem>
878 <listitem>
879 <para>
880 The "WaveMapper" represents the name of the module containing the Wave
881 Mapper driver. Only one wave mapper can be defined in the system.
882 </para>
883 </listitem>
884 <listitem>
885 <para>
886 The "MidiMapper" represents the name of the module containing the MIDI
887 Mapper driver. Only one MIDI mapper can be defined in the system.
888 </para>
889 </listitem>
890 </itemizedlist>
891 </para>
892 </sect3>
896 <para>
897 [Network] contains settings related to
898 networking. Currently there is only one value that can be set.
899 </para>
900 <variablelist>
901 <varlistentry>
903 <listitem>
904 <para>
906 that affects the way Wine sets the computer name. The computer
909 <varname>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ComputerName\ComputerName</varname>.
910 </para>
911 <para>
912 If this option is set to "Y" or missing, Wine will set the
913 NetBIOS name to the Unix host name of your computer, if
914 necessary truncated to 31 characters. The Unix hostname is the output
916 including the first dot ('.'). Among other things, this means that
917 Windows programs running under Wine cannot change the NetBIOS computer name.
918 </para>
919 <para>
920 If this option is set to "N", Wine will use the registry value above
921 to set the NetBIOS name. Only if the registry entry doesn't exist (usually
922 only during the first wine startup) it will use the Unix hostname as
923 usual. Windows programs can change the NetBIOS name. The change
924 will be effective after a "reboot", i.e. after restarting Wine.
925 </para>
926 </listitem>
927 </varlistentry>
928 </variablelist>
929 </sect3>
933 <para>
934 The section is used to overwrite certain settings of this file for a
935 special program with different settings.
936 [AppDefaults] is not the real name of the section. The real name
937 consists of the leading word AppDefaults followed by the name
938 of the executable the section is valid for.
939 The end of the section name is the name of the
940 corresponding "standard" section of the configuration file
941 that should have some of its settings overwritten with the
942 program specific settings you define.
943 The three parts of the section name are separated by two backslashes.
944 </para>
945 <para>
946 Currently wine supports overriding selected settings within
947 the sections [DllOverrides], [x11drv], [version] and [dsound] only.
948 </para>
949 <para>
950 Here is an example that overrides the normal settings for a
951 program:
952 <programlisting>
953 ;; default settings
954 [x11drv]
958 ;; run install in desktop mode
959 [AppDefaults\\install.exe\\x11drv]
962 </programlisting>
963 </para>
964 </sect3>
965 </sect2>
969 <para>
970 There is always a chance that things will go wrong. If the
971 unthinkable happens, report the problem to
973 try the newsgroup
976 irc.freenode.net, or connected servers.
977 Make sure that you have looked over this document thoroughly,
978 and have also read:
979 </para>
980 <itemizedlist>
981 <listitem>
983 </listitem>
984 <listitem>
985 <para>
987 </para>
988 </listitem>
989 </itemizedlist>
990 <para>
991 If indeed it looks like you've done your research, be
992 prepared for helpful suggestions. If you haven't, brace
993 yourself for heaving flaming.
994 </para>
995 </sect2>
996 </sect1>
1000 <sect2>
1002 <para>
1003 If you're planning to include access to a CD-ROM drive in your Wine
1007 <programlisting>
1008 /dev/cdrom /cdrom iso9660 ro,noauto,users,unhide 0 0
1009 </programlisting>
1010 Several Windows program setup CD-ROMs or other CD-ROMs chose
1011 to do such braindamaged things as marking very important setup
1013 That's no problem on Windows, since the Windows CD-ROM driver by
1014 default displays even files that are supposed to be
1018 (the programs will simply abort with an <quote>installation file not found</quote> or similar error)
1019 Thus you should never forget to add this setting.
1020 </para>
1021 </sect2>
1023 <sect2>
1025 <para>
1026 Wine emulates drives by placing their virtual drive roots to
1027 user-configurable points in the Unix filesystem, so it's your
1032 indicates the home directory of a user), as the root of your
1034 into your Wine configuration file:
1035 </para>
1037 <programlisting>
1038 [Drive C]
1043 </programlisting>
1045 <para>
1046 With this configuration, what windows apps think of as
1047 "c:\windows\system" would map to
1049 filesystem. Note that you need to specify
1053 Windows compatible (case insensitive) filesystem, otherwise
1054 most apps won't work.
1055 </para>
1056 </sect2>
1060 <para>
1061 Here's the fundamental layout that Windows programs and
1062 installers expect and that we thus need to configure properly
1063 in Wine. Without it, they seldomly operate correctly. If you
1064 intend to use a no-windows environment (not using an existing
1065 Windows partition), then it is recommended to use either
1068 initial windows directory tree, since creating a directory
1069 structure manually is tiresome and error-prone.
1070 </para>
1072 <programlisting>
1073 C:\ Root directory of primary disk drive
1074 Windows\ Windows directory, containing .INI files,
1075 accessories, etc.
1079 Start Menu\ Program launcher directory structure
1080 Programs\ Program launcher links (.LNK files) to programs
1081 Program Files\ Application binaries (.EXE and .DLL files)
1082 </programlisting>
1083 </sect2>
1087 <para>
1088 These sections are supposed to make certain Unix
1089 directory locations accessible to Wine as a DOS/Windows drive
1090 (drive 'x:') and thus accessible to Windows programs
1091 under the drive name you specified.
1092 Every DOS/Windows program sort of expects at least a C:
1093 drive (and sometimes also an A: floppy drive), so your
1094 configuration file should at least contain the corresponding
1095 sections, [Drive C] and [Drive A].
1096 You need to decide on whether you want to use an existing Windows
1097 partition as the C drive or whether you want to create your own
1098 Wine drive C directory tree somewhere (take care about
1099 permissions!).
1100 Each drive section may specify up to 6 different settings
1101 as explained below.
1102 </para>
1103 <para>
1105 The above line begins the section for a drive whose letter is x
1106 (DOS notation: drive 'x:').
1107 You could e.g. create an equivalent to a drive 'C:'
1108 under DOS/Windows by using a [Drive C] section name.
1109 Note that the drive letter is case insensitive.
1110 </para>
1111 <para>
1113 This specifies the directory where the drive will begin.
1114 When Wine is browsing in drive x, it will be able
1115 to see the files that are in the directory
1117 (note that symlinks to directories won't get included!
1119 configuration setting)
1120 You can also make use of environment variables like $HOME here,
1122 directory in your home dir would be
1124 Don't forget to leave off the trailing slash!
1125 </para>
1126 <para>
1128 Sets up the type of drive Wine will see it as. Type must
1132 (The |'s mean "Type = '<one of the options>'".)
1134 For a home directory entry, it makes sense to choose
1135 "network" sometimes, since some home directories are being
1136 exported over the network via NFS and thus can have slow response
1137 times.
1138 </para>
1139 <para>
1141 Defines the drive label. Generally only needed
1142 for programs that look for a special CD-ROM.
1143 The label may be up to 11 characters.
1144 Note that the preferred way of managing labels and serial numbers
1145 of CD-ROMs and floppies is to give Wine raw device access for
1146 reading these on a per-CD case (see "Device" below) instead of
1147 hardcoding one specific "Label".
1148 </para>
1149 <para>
1151 Tells Wine the serial number of the drive. A few programs with
1152 intense protection for pirating might need this, but otherwise
1153 it's not needed. Up to 8 characters and hexadecimal.
1155 is a smarter choice.
1156 </para>
1157 <para>
1159 Sets up the way Wine looks at files on the drive.
1160 This setting controls the file name lookup and mapping of
1161 Wine to existing file systems on your PC, it does
1163 used itself.
1164 </para>
1166 <variablelist>
1167 <varlistentry>
1169 <listitem>
1170 <para>
1172 the long filename filesystem you are probably used
1173 to working with. The filesystem bæhaviour of choice for most
1174 programs to be run under wine. <emphasis>Probably the one
1175 you want!</emphasis>
1176 </para>
1177 </listitem>
1178 </varlistentry>
1179 <varlistentry>
1181 <listitem>
1182 <para>
1183 Case sensitive. This filesystem has almost no use
1184 (Windows apps expect case insensitive filenames),
1185 except maybe for Winelib applications.
1186 Try it if you dare, but win95 is a much better
1187 and always recommended choice.
1188 </para>
1189 </listitem>
1190 </varlistentry>
1191 <varlistentry>
1193 <listitem>
1194 <para>
1195 Case insensitive filesystem. Alike to DOS and
1197 length of files (eightdot.123) - longer ones will be
1198 truncated.
1199 <note>
1200 <para>
1202 you plan on running apps that use long filenames.
1203 win95 should work fine with apps that were designed
1204 to run under the msdos system. In other words, you
1205 might not want to use this.
1206 </para>
1207 </note>
1208 </para>
1209 </listitem>
1210 </varlistentry>
1211 </variablelist>
1214 <para>
1215 Needed for raw device access and <link linkend="config-drive-cdrom-labels">label and serial number reading</link>.
1217 Extended2 or other Unix file systems can have dire results
1218 (when a windows app tries to do a lowlevel write,
1219 they do it in a FAT way -- FAT format is completely different from
1220 any Unix file system).
1221 Also, make sure that you have proper permissions to this device
1222 file.
1223 </para>
1224 <note>
1225 <para>
1226 This setting is not really important; almost all apps
1227 will have no problem if it remains unspecified. For
1228 CD-ROMs it's quite useful in order to get automatic label
1229 detection, though. If you are unsure about specifying
1230 device names, just leave out this setting for your
1231 drives.
1232 </para>
1233 </note>
1234 <para>
1235 Here are a few sample entries:
1236 <programlisting>
1237 Here is a setup for Drive C, a generic hard drive:
1238 [Drive C]
1243 This is a setup for Drive E, a generic CD-ROM drive:
1244 [Drive E]
1250 And here is a setup for Drive A, a generic floppy drive:
1251 [Drive A]
1258 </programlisting>
1259 </para>
1260 </sect2>
1262 <sect2>
1264 <para>
1266 This tells Wine and Windows programs where the
1268 recommended to have this directory somewhere on your
1270 recommended to just call the directory "windows" (this is
1271 the default setup on Windows, and some stupid programs
1272 might rely on this). So in case you chose a "Windows"
1273 setting of "c:\\windows" and you chose to set up a drive C
1275 corresponding directory would be
1277 if you don't already have one. <emphasis>No trailing slash</emphasis> (<emphasis>not</emphasis>
1279 recommended, as Windows programs always assume write access
1280 to the Windows directory!
1281 </para>
1282 <para>
1284 This sets up where the windows system files are. The Windows
1285 system directory should reside below the directory used for the
1287 Thus when using the example above, the system directory would be
1289 Again, no trailing slash, and write access!
1290 </para>
1291 <para>
1293 be the directory you want your temp files stored in,
1294 /usr/local/wine_c/temp in our example.
1295 Again, no trailing slash, and <emphasis>write
1296 access</emphasis>!!
1297 </para>
1298 <para>
1299 <programlisting>
1301 </programlisting>
1302 </para>
1303 <para>
1305 boxes. When wine is run like <userinput>wine
1307 resides in a directory specified in the
1310 current directory, wine will run that one). Make sure it
1312 system directory (For this setup, it must have
1314 </para>
1316 <programlisting>
1318 </programlisting>
1319 Wine doesn't pass directory symlinks to Windows programs by
1320 default, as doing so may crash some programs that do
1321 recursive lookups of whole subdirectory trees
1322 whenever a directory symlink points back to itself or one of its
1323 parent directories.
1324 That's why we disallowed the use of directory symlinks
1325 and added this setting to reenable ("1") this functionality.
1327 account symlinked directories, then reenable it, but
1329 Windows programs when using the above method! (in other words:
1330 enabling it is certainly not recommended)
1331 </para>
1332 </sect2>
1334 <sect2>
1336 <para>
1337 Windows uses a different (and inferior) way than Unix to describe the
1338 location of files in a computer. Thus Windows programs also expect
1339 to find this different way supported by the system.
1340 Since we intend to run Windows programs on
1341 a Unix system, we're in trouble, as we need to translate
1342 between these different file access techniques.
1343 </para>
1344 <para>
1345 Windows uses drive letters to describe drives or
1346 any other form of storage media and to access files on them.
1347 For example, common drive names are
1350 first floppy drive.
1352 directory separator sign, whereas Unix uses
1354 Thus, an example document on the first data partition in
1355 Windows might be accessed by the name of
1357 </para>
1358 <para>
1359 So much for the Windows way of doing things.
1360 </para>
1361 <para>
1362 Well, the problem is, in Unix there is no such thing as
1364 much better way of having one single uniform directory tree
1365 (starting with the root directory
1367 such as e.g. harddisk partitions appended at various directory
1368 locations within the tree (an example would be
1370 partition mounted/attached to a directory called data1 in the
1372 directory of the data partition file system that's mounted
1374 In Unix, the Windows example document mentioned above could e.g.
1375 be accessed by the name of
1377 provided that the administrator decided to mount (attach) the first
1378 data partition at the directory /data1 inside the Unix
1379 directory tree. Note that in Unix, the administrator can
1383 suitable for the first data partition (here,
1385 change in partition order, Windows automatically
1387 suddenly find yourself with a first data partition at drive
1389 referencing confusion that entails. Thus, the Windows way of
1390 using ever-changing drive letters is <emphasis>clearly
1391 inferior</emphasis> to the Unix way of assigning
1393 data storage medium.
1394 As we'll see soon, fortunately this Windows limitation of
1395 changing drive letters doesn't affect us in Wine at all, since
1396 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).
1397 </para>
1398 <para>
1399 OK, now that we know some theory about Windows and Unix drive
1400 and filename mapping, it's probably time to ask how Wine
1401 achieves the magic of mapping a Unix directory location to a
1402 Windows drive...
1403 </para>
1404 <para>
1405 Wine chose to do the following:
1406 In Wine, you don't assign some real physical storage medium
1407 (such as a harddisk partition or similar) to each drive letter
1408 mapping entry.
1409 Instead, you choose certain sub directory trees inside the Unix
1411 you would like to assign a drive letter to.
1412 </para>
1413 <para>
1414 Note that for every Unix sub directory tree that you intend to
1415 start Windows programs in, it is <emphasis>absolutely
1416 required</emphasis> to have a Wine drive mapping entry:
1417 </para>
1418 <para>
1419 For example, if you had a publicly writable <quote>Windows
1421 able to access this sub directory tree from Wine, you should
1422 have a drive mapping entry that maps a certain drive letter
1424 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.
1425 </para>
1426 </sect2>
1430 <para>
1432 </para>
1433 <para>
1435 </para>
1437 <para>
1438 A major goal of Wine is to allow users to run Windows programs
1439 without having to install Windows on their machine. Wine
1440 implements the functionality of the main DLLs usually
1441 provided with Windows. Therefore, once Wine is finished, you
1442 will not need to have Windows installed to use Wine.
1443 </para>
1444 <para>
1445 Wine has already made enough progress that it may be possible
1446 to run your target programs without Windows installed. If
1447 you want to try it, follow these steps:
1448 </para>
1450 <orderedlist>
1451 <listitem>
1452 <para>
1456 for more information.
1457 The directory to be used for emulating a C: drive will be
1458 the base directory for some Windows specific directories
1459 created below.
1460 Remember to use
1462 </para>
1463 </listitem>
1464 <listitem>
1465 <para>
1466 Within the directory to be used for C:, create empty
1471 directories. Do not point Wine to a
1473 installations and a messy registry. (Wine creates a
1476 Perhaps you have to remove these files).
1477 In one line:
1478 mkdir -p windows windows/system windows/Start\ Menu windows/Start\ Menu/Programs
1479 </para>
1480 </listitem>
1481 <listitem>
1482 <para>
1483 Run and/or install your programs.
1484 </para>
1485 </listitem>
1486 </orderedlist>
1488 <para>
1489 Because Wine is not yet complete, some programs will work
1490 better with native Windows DLLs than with Wine's
1491 replacements. Wine has been designed to make this possible.
1492 Here are some tips by Juergen Schmied (and others) on how to
1493 proceed. This assumes that your
1495 file does not point to a native Windows installation but is in
1499 </para>
1501 <itemizedlist>
1502 <listitem>
1503 <para>
1504 Run the program with <parameter>--debugmsg
1505 +loaddll</parameter> to find out which files are
1506 needed. Copy the required DLLs one by one to the
1508 copy KERNEL/KERNEL32, GDI/GDI32, USER/USER32 or NTDLL. These
1509 implement the core functionality of the Windows API, and
1510 the Wine internal versions must be used.
1511 </para>
1512 </listitem>
1513 <listitem>
1514 <para>
1518 the Windows DLLs you want to use. For more information
1519 about this, see the Wine manpage.
1520 </para>
1521 </listitem>
1522 <listitem>
1523 <para>
1524 Note that some network DLLs are not needed even though
1525 Wine is looking for them. The Windows
1527 must use the internal implementation.
1528 </para>
1529 </listitem>
1530 <listitem>
1531 <para>
1532 Copy SHELL.DLL/SHELL32.DLL, COMMDLG.DLL/COMDLG32.DLL
1533 and COMMCTRL.DLL/COMCTL32.DLL
1534 only as pairs to your Wine directory (these DLLs are
1538 </para>
1539 </listitem>
1540 <listitem>
1541 <para>
1542 Be consistent: Use only DLLs from the same Windows version
1543 together.
1544 </para>
1545 </listitem>
1546 <listitem>
1547 <para>
1552 registry, don't know about
1554 As of now, it might not be necessary any more to use
1555 regedit.exe, since Wine has its own regedit Winelib
1556 application now.
1557 </para>
1558 </listitem>
1559 <listitem>
1560 <para>
1563 to browse through your programs' help function
1564 (or in case Wine's winhelp implementation in programs/winhelp/
1565 is not good enough, for example).
1566 </para>
1567 </listitem>
1568 </itemizedlist>
1569 </sect2>
1573 <para>
1574 Some people intend to use the data of an existing Windows partition
1575 with Wine in order to gain some better compatibility or to run already
1576 installed programs in a setup as original as possible.
1577 Note that many Windows programs assume that they have full write
1578 access to all windows directories.
1580 This means that you either have to configure the Windows
1581 partition mount point for write permission by your Wine user
1583 on how to do that), or you'll have to copy over (some parts of) the Windows
1584 partition content to a directory of a Unix partition and make
1585 sure this directory structure is writable by your user.
1587 write access as a base for Wine!! (some programs, notably
1588 Explorer, corrupt large parts of the Windows partition in case
1589 of an incorrect setup; you've been warned).
1590 Not to mention that NTFS write support in Linux is still very
1592 Windows version using the NTFS file system).
1593 Thus we advise you to go the Unix directory way.
1594 </para>
1595 </sect2>
1599 <para>
1601 </para>
1602 <para>
1604 </para>
1605 <para>
1606 This document describes how FAT and
1607 VFAT file system permissions work in Linux
1608 with a focus on configuring them for Wine.
1609 </para>
1611 <sect3>
1613 <para>
1614 Linux is able to access DOS and Windows file systems using
1615 either the FAT (older 8.3 DOS filesystems) or VFAT (newer
1616 Windows 95 or later long filename filesystems) modules.
1617 Mounted FAT or VFAT filesystems provide the primary means
1618 for which existing programs and their data are accessed
1619 through Wine for dual boot (Linux + Windows) systems.
1620 </para>
1621 <para>
1622 Wine maps mounted FAT filesystems, such as
1627 </para>
1628 <programlisting>
1629 [Drive C]
1632 </programlisting>
1633 <para>
1634 Although VFAT filesystems are preferable to FAT filesystems
1636 will be used throughout the remainder of this document to
1637 refer to FAT filesystems and their derivatives. Also,
1639 examples throughout this document.
1640 </para>
1641 <para>
1642 Most modern Linux distributions either detect or allow
1643 existing FAT file systems to be configured so that they can be
1645 either persistently (on bootup) or on an as needed basis. In
1646 either case, by default, the permissions will probably be
1647 configured so that they look like:
1648 </para>
1649 <screen>
1655 </screen>
1656 <para>
1658 group and are only writable by "root"
1660 that it requires that Wine be run as root in order for
1661 programs to be able to write to any part of the
1662 filesystem.
1663 </para>
1664 <para>
1665 There are three major approaches to overcoming the restrictive
1666 permissions mentioned in the previous paragraph:
1667 </para>
1668 <orderedlist>
1669 <listitem>
1670 <para>
1672 </para>
1673 </listitem>
1674 <listitem>
1675 <para>
1676 Mount the FAT filesystem with less restrictive
1677 permissions
1678 </para>
1679 </listitem>
1680 <listitem>
1681 <para>
1682 Shadow the FAT filesystem by completely or partially
1683 copying it
1684 </para>
1685 </listitem>
1686 </orderedlist>
1687 <para>
1688 Each approach will be discussed in the following sections.
1689 </para>
1690 </sect3>
1692 <sect3>
1694 <para>
1695 Running Wine as root is the easiest and most thorough way of giving
1696 programs that Wine runs unrestricted access to FAT files systems.
1697 Running wine as root also allows programs to do things unrelated
1698 to FAT filesystems, such as listening to ports that are less than
1699 1024. Running Wine as root is dangerous since there is no limit to
1701 </para>
1702 </sect3>
1704 <sect3>
1706 <para>
1707 The FAT filesystem can be mounted with permissions less restrictive
1708 than the default. This can be done by either changing the user that
1709 mounts the FAT filesystem or by explicitly changing the permissions
1710 that the FAT filesystem is mounted with. The permissions are
1711 inherited from the process that mounts the FAT filesystem. Since the
1712 process that mounts the FAT filesystem is usually a startup script
1713 running as root the FAT filesystem inherits root's permissions. This
1714 results in the files on the FAT filesystem having permissions similar
1715 to files created by root. For example:
1716 </para>
1717 <screen>
1723 </screen>
1724 <para>
1725 which matches the owner, group and permissions of files seen
1726 on the FAT filesystem except for the missing 'x's. The
1727 permissions on the FAT filesystem can be changed by changing
1728 root's umask (unset permissions bits). For example:
1729 </para>
1730 <screen>
1741 </screen>
1742 <para>
1743 Mounting the FAT filesystem with a umask of
1745 it. Explicitly specifying the permissions of the FAT
1746 filesystem when it is mounted provides additional control.
1747 There are three mount options that are relevant to FAT
1750 when the filesystem is manually mounted. For example:
1751 </para>
1752 <screen>
1760 </screen>
1761 <para>
1762 which gives "sle" complete control over
1764 made permanent by adding them to the
1766 </para>
1767 <screen>
1769 <computeroutput>/dev/hda1 /c vfat uid=500,gid=500,umask=002,exec,dev,suid,rw 1 1</computeroutput>
1770 </screen>
1771 <para>
1773 the user private group file permission scheme. On FAT file
1774 systems this umask assures that all files are fully
1775 accessible by all users in the specified user group
1777 </para>
1778 </sect3>
1780 <sect3>
1782 <para>
1783 Shadowing provides a finer granularity of control. Parts of
1784 the original FAT filesystem can be copied so that the
1785 program can safely work with those copied parts while
1786 the program continues to directly read the remaining
1787 parts. This is done with symbolic links. For example,
1788 consider a system where a program named
1792 read access to the entire FAT filesystem. On this system
1793 the FAT filesystem has default permissions which should not
1794 be changed for security reasons or can not be changed due to
1795 lack of root access. On this system a shadow directory
1796 might be set up in the following manner:
1797 </para>
1798 <screen>
1806 <prompt>/c_shadow></prompt><userinput>perl -p -i -e 's|/c$|/c_shadow|g' ~/.wine/config</userinput>
1807 </screen>
1808 <para>
1809 The above gives everyone complete read and write access to
1812 write access to all other directories.
1813 </para>
1814 </sect3>
1815 </sect2>
1818 <sect2info>
1819 <authorgroup>
1820 <author>
1823 <affiliation>
1825 </affiliation>
1827 </author>
1828 <author>
1831 <affiliation>
1833 </affiliation>
1835 </author>
1836 </authorgroup>
1837 </sect2info>
1840 <para>
1842 Nov 14 1999
1843 </para>
1844 <para>
1846 Jan 25 2000
1847 </para>
1848 <para>
1850 </para>
1851 <para>
1852 Until now, your only possibility of specifying drive volume
1853 labels and serial numbers was to set them manually in the wine
1854 configuration file. By now, wine can read them directly from the
1855 device as well. This may be useful for many Win 9x games or
1856 for setup programs distributed on CD-ROMs that check for
1857 volume label.
1858 </para>
1860 <sect3>
1865 <thead>
1866 <row>
1870 </row>
1871 </thead>
1872 <tbody>
1873 <row>
1877 </row>
1878 <row>
1882 </row>
1883 </tbody>
1884 </tgroup>
1885 </informaltable>
1887 </sect3>
1889 <sect3>
1891 <para>
1892 Reading labels and serial numbers just works automagically
1895 Note that the device has to exist and must be accessible by the user
1896 running Wine if you do this, though.
1897 </para>
1898 <para>
1899 If you don't want to read labels and serial numbers directly from
1900 the device, then you should give fixed
1903 these entries instead if no device is given. If they don't
1904 exist, then Wine will return default values (label
1907 </para>
1908 <para>
1911 but not for reading the volume info from the device (i.e. you want
1914 to skip the volume reading.
1915 </para>
1916 </sect3>
1918 <sect3>
1920 <para>
1921 Here's a simple example of CD-ROM and floppy; labels will be
1922 read from the device on both CD-ROM and floppy; serial
1923 numbers on floppy only:
1924 </para>
1925 <screen>
1926 [Drive A]
1932 [Drive R]
1937 </screen>
1938 <para>
1939 Here's an example of overriding the CD-ROM label:
1940 </para>
1941 <screen>
1942 [Drive J]
1946 ; note that the device isn't really needed here as we have a fixed label
1949 </screen>
1950 </sect3>
1952 <sect3>
1954 <itemizedlist>
1955 <listitem> <para>
1956 The CD-ROM label can be read only if the data track of
1957 the disk resides in the first track and the cdrom is
1958 iso9660.
1959 </para> </listitem>
1960 <listitem> <para>
1961 Better checking for FAT superblock (it now checks only
1962 one byte). </para>
1963 </listitem>
1964 <listitem> <para>
1965 Support for labels/serial nums WRITING.
1966 </para> </listitem>
1967 <listitem> <para>
1969 chars).
1970 </para> </listitem>
1971 <listitem> <para>
1972 What about reading ext2 volume label? ....
1973 </para> </listitem>
1974 </itemizedlist>
1975 </sect3>
1976 </sect2>
1977 </sect1>
1979 ®istry;
1984 <sect2>
1986 <para>
1987 If your programs don't work as expected, then it's often because one
1988 DLL or another is failing. This can often be resolved by changing
1989 certain DLLs from Wine built-in to native Windows DLL file and vice
1990 versa.
1991 </para>
1992 <para>
1993 A very useful help to find out which DLLs are loaded as built-in and
1994 which are loaded as native Windows file can be the debug channel
1995 loaddll, activated via the Wine command line parameter
1997 </para>
1998 </sect2>
2000 <sect2>
2001 <!-- FIXME intro!!! -->
2003 <para>
2004 There are a few things you will need to know before
2005 configuring the DLL sections in your wine configuration
2006 file.
2007 </para>
2008 <sect3>
2010 <para>
2011 Most windows DLL's have a win16 (Windows 3.x) and win32
2012 (Windows 9x/NT) form. The combination of the win16 and
2013 win32 DLL versions are called the "DLL pair". This is a
2014 list of the most common pairs:
2015 </para>
2017 <informaltable>
2019 <thead>
2020 <row>
2023 <entry>
2024 Native
2025 <footnote>
2026 <para>
2027 Is it possible to use native DLL with wine?
2028 (See next section)
2029 </para>
2030 </footnote>
2031 </entry>
2032 </row>
2033 </thead>
2034 <tbody>
2035 <row>
2039 </row>
2040 <row>
2044 </row>
2045 <row>
2049 </row>
2050 <row>
2054 </row>
2055 <row>
2059 </row>
2060 <row>
2064 </row>
2065 </tbody>
2066 </tgroup>
2067 </informaltable>
2068 </sect3>
2070 <sect3>
2072 <para>
2073 There are a few different forms of DLL's wine can load:
2074 <variablelist>
2075 <varlistentry>
2077 <listitem><para>
2078 The DLL's that are included with windows. Many
2079 windows DLL's can be loaded in their native
2080 form. Many times these native versions work
2081 better than their non-Microsoft equivalent --
2082 other times they don't.
2083 </para></listitem>
2084 </varlistentry>
2085 <varlistentry>
2087 <listitem><para>
2088 The most common form of DLL loading. This is
2089 what you will use if the DLL is too system-specific
2090 or error-prone in native form (KERNEL for example),
2091 you don't have the native DLL, or you just want to be
2092 Microsoft-free.
2093 </para></listitem>
2094 </varlistentry>
2095 <varlistentry>
2097 <listitem><para>
2098 Native ELF libraries. Has been deprecated, ignored.
2099 </para></listitem>
2100 </varlistentry>
2101 <varlistentry>
2103 <listitem><para>
2104 ELF encapsulated windows DLL's.
2105 No longer used, ignored.
2106 </para></listitem>
2107 </varlistentry>
2108 </variablelist>
2109 </para>
2110 </sect3>
2111 </sect2>
2116 <para>
2118 </para>
2119 <para>
2121 </para>
2123 <para>
2124 The wine configuration file directives [DllDefaults]
2125 and [DllOverrides] are the subject of some confusion. The
2126 overall purpose of most of these directives are clear enough,
2127 though - given a choice, should Wine use its own built-in
2129 in an existing Windows installation? This document explains
2130 how this feature works.
2131 </para>
2133 <sect3>
2135 <variablelist>
2136 <varlistentry>
2138 <listitem> <para>
2140 written for the real Microsoft Windows.
2141 </para> </listitem>
2142 </varlistentry>
2143 <varlistentry>
2145 <listitem> <para>
2146 A "built-in" DLL is a Wine DLL. These can either be a
2149 that Wine is able to load on demand.
2150 </para> </listitem>
2151 </varlistentry>
2152 </variablelist>
2153 </sect3>
2155 <sect3>
2157 <variablelist>
2158 <varlistentry>
2160 <listitem> <para>
2161 This specifies in what order Wine should search for
2162 available DLL types, if the DLL in question was not
2163 found in the [DllOverrides] section.
2164 </para> </listitem>
2165 </varlistentry>
2166 </variablelist>
2167 </sect3>
2169 <sect3>
2171 <para>
2172 At one time, there was a section called [DllPairs] in the
2173 default configuration file, but this has been obsoleted
2174 because the pairing information has now been embedded into
2175 Wine itself. (The purpose of this section was merely to be
2176 able to issue warnings if the user attempted to pair
2180 </para>
2181 </sect3>
2183 <sect3>
2185 <para>
2186 This section specifies how you want specific DLLs to be
2187 handled, in particular whether you want to use "native" DLLs
2188 or not, if you have some from a real Windows configuration.
2189 Because built-ins do not mix seamlessly with native DLLs yet,
2190 certain DLL dependencies may be problematic, but workarounds
2191 exist in Wine for many popular DLL configurations. Also see
2192 WWN's [16]Status Page to figure out how well your favorite
2193 DLL is implemented in Wine.
2194 </para>
2195 <para>
2196 It is of course also possible to override these settings by
2198 command-line option (see the man page for details). Some
2199 hints for choosing your optimal configuration (listed by
2201 </para>
2202 <variablelist>
2203 <varlistentry>
2205 <listitem> <para>
2206 Native versions of these will never work, so don't try. Leave
2208 </para> </listitem>
2209 </varlistentry>
2210 <varlistentry>
2212 <listitem> <para>
2213 Graphics Device Interface. No effort has been made at trying to
2215 </para> </listitem>
2216 </varlistentry>
2217 <varlistentry>
2219 <listitem> <para>
2220 Window management and standard controls. It was
2222 versions at some point (if all other DLLs that depend
2223 on it, such as comctl32 and comdlg32, were also run
2225 possible after the Address Space Separation, so leave
2227 </para> </listitem>
2228 </varlistentry>
2229 <varlistentry>
2231 <listitem> <para>
2232 NT kernel API. Although badly documented, the
2235 </para> </listitem>
2236 </varlistentry>
2237 <varlistentry>
2239 <listitem> <para>
2241 version will probably never work. Leave at
2243 </para> </listitem>
2244 </varlistentry>
2245 <varlistentry>
2247 <listitem> <para>
2248 Win16 support library for NT. The
2251 </para> </listitem>
2252 </varlistentry>
2253 <varlistentry>
2255 <listitem> <para>
2256 Win16 kernel stuff. Will never work
2259 </para> </listitem>
2260 </varlistentry>
2261 <varlistentry>
2263 <listitem> <para>
2265 </para> </listitem>
2266 </varlistentry>
2267 <varlistentry>
2269 <listitem> <para>
2270 Tool helper routines. This is rarely a source of problems.
2272 </para> </listitem>
2273 </varlistentry>
2274 <varlistentry>
2276 <listitem> <para>
2277 Versioning. Seldom useful to mess with.
2278 </para> </listitem>
2279 </varlistentry>
2280 <varlistentry>
2282 <listitem> <para>
2283 Registry and security features. Trying the
2285 not work.
2286 </para> </listitem>
2287 </varlistentry>
2288 <varlistentry>
2290 <listitem> <para>
2291 Common Dialogs, such as color picker, font dialog,
2292 print dialog, open/save dialog, etc. It is safe to try
2294 </para> </listitem>
2295 </varlistentry>
2296 <varlistentry>
2298 <listitem> <para>
2299 Common Controls. This is toolbars, status bars, list controls,
2301 </para> </listitem>
2302 </varlistentry>
2303 <varlistentry>
2305 <listitem> <para>
2306 Shell interface (desktop, filesystem, etc). Being one of the
2307 most undocumented pieces of Windows, you may have luck with the
2309 </para> </listitem>
2310 </varlistentry>
2311 <varlistentry>
2313 <listitem> <para>
2315 will not work under Wine, so leave at
2317 </para> </listitem>
2318 </varlistentry>
2319 <varlistentry>
2321 <listitem> <para>
2322 ICMP routines for wsock32. As with wsock32, leave at
2324 </para> </listitem>
2325 </varlistentry>
2326 <varlistentry>
2328 <listitem> <para>
2330 to thunking issues. Leave at
2332 </para> </listitem>
2333 </varlistentry>
2334 <varlistentry>
2336 <listitem> <para>
2337 Lempel-Ziv decompression. Wine's
2339 </para> </listitem>
2340 </varlistentry>
2341 <varlistentry>
2343 <listitem> <para>
2344 Advanced SCSI Peripheral Interface. The
2347 </para> </listitem>
2348 </varlistentry>
2349 <varlistentry>
2351 <listitem> <para>
2353 version will easily work better than Wine's on this
2354 one.
2355 </para> </listitem>
2356 </varlistentry>
2357 <varlistentry>
2359 <listitem> <para>
2360 Printer spooler. You are not likely to have more luck
2362 </para> </listitem>
2363 </varlistentry>
2364 <varlistentry>
2366 <listitem> <para>
2367 DirectDraw/Direct3D. Since Wine does not implement the
2369 will not work at this time.
2370 </para> </listitem>
2371 </varlistentry>
2372 <varlistentry>
2374 <listitem> <para>
2376 may or may not work.
2377 </para> </listitem>
2378 </varlistentry>
2379 <varlistentry>
2381 <listitem> <para>
2382 DirectSound. It may be possible to run this
2384 </para> </listitem>
2385 </varlistentry>
2386 <varlistentry>
2388 <listitem> <para>
2390 ought to work best on this, if at all.
2391 </para> </listitem>
2392 </varlistentry>
2393 <varlistentry>
2395 <listitem> <para>
2397 version is not likely to work. Leave at
2399 </para> </listitem>
2400 </varlistentry>
2401 <varlistentry>
2403 <listitem> <para>
2404 Audio Compression Manager. The
2406 set msacm.drv to the same.
2407 </para> </listitem>
2408 </varlistentry>
2409 <varlistentry>
2411 <listitem> <para>
2412 Video for Windows. It is safe (and recommended) to try
2414 </para> </listitem>
2415 </varlistentry>
2416 <varlistentry>
2418 <listitem> <para>
2419 CD Audio MCI driver.
2420 </para> </listitem>
2421 </varlistentry>
2422 <varlistentry>
2424 <listitem> <para>
2426 playback).
2427 </para> </listitem>
2428 </varlistentry>
2429 <varlistentry>
2431 <listitem> <para>
2433 </para> </listitem>
2434 </varlistentry>
2435 <varlistentry>
2437 <listitem> <para>
2440 </para> </listitem>
2441 </varlistentry>
2442 <varlistentry>
2444 <listitem> <para>
2445 Animation MCI driver.
2446 </para> </listitem>
2447 </varlistentry>
2448 <varlistentry>
2450 <listitem> <para>
2451 Audio Compression Manager. Set to same as msacm32.
2452 </para> </listitem>
2453 </varlistentry>
2454 <varlistentry>
2456 <listitem> <para>
2457 MIDI Mapper.
2458 </para> </listitem>
2459 </varlistentry>
2460 <varlistentry>
2462 <listitem> <para>
2463 This is a pseudo-DLL used by Wine for thunking
2465 doesn't exist.
2466 </para> </listitem>
2467 </varlistentry>
2468 </variablelist>
2469 </sect3>
2470 </sect2>
2474 <para>
2475 The Wine team has determined that it is necessary to create
2476 fake DLL files to trick many programs that check for
2477 file existence to determine whether a particular feature
2478 (such as Winsock and its TCP/IP networking) is available. If
2479 this is a problem for you, you can create empty files in the
2481 to make the program think it's there, and Wine's built-in DLL
2482 will be loaded when the program actually asks for it.
2484 not create such empty files itself.)
2485 </para>
2486 <para>
2487 Applications sometimes also try to inspect the version
2488 resources from the physical files (for example, to determine
2489 the DirectX version). Empty files will not do in this case,
2490 it is rather necessary to install files with complete
2491 version resources. This problem is currently being worked
2492 on. In the meantime, you may still need to grab some real
2493 DLL files to fool these apps with.
2494 </para>
2495 <para>
2496 And there are of course DLLs that wine does not currently
2497 implement very well (or at all). If you do not have a real
2498 Windows you can steal necessary DLLs from, you can always
2499 get some from one of the Windows DLL archive sites
2500 that can be found via internet search engine.
2501 Please make sure to obey any licenses on the DLLs you fetch...
2502 (some are redistributable, some aren't).
2503 </para>
2504 </sect2>
2509 <para>
2511 </para>
2513 <para>
2514 In case Wine complains about a missing DLL, you should check whether
2515 this file is a publicly available DLL or a custom DLL belonging
2516 to your program (by searching for its name on the internet).
2517 If you managed to get hold of the DLL, then you should make sure
2518 that Wine is able to find and load it.
2519 DLLs usually get loaded according to the mechanism of the
2520 SearchPath() function.
2521 This function searches directories in the following order:
2523 <orderedlist>
2524 <listitem>
2525 <para>
2526 The directory the program was started from.
2527 </para>
2528 </listitem>
2529 <listitem>
2530 <para>
2531 The current directory.
2532 </para>
2533 </listitem>
2534 <listitem>
2535 <para>
2536 The Windows system directory.
2537 </para>
2538 </listitem>
2539 <listitem>
2540 <para>
2541 The Windows directory.
2542 </para>
2543 </listitem>
2544 <listitem>
2545 <para>
2546 The PATH variable directories.
2547 </para>
2548 </listitem>
2549 </orderedlist>
2551 In short: either put the required DLL into your program
2552 directory (might be ugly), or usually put it into the Windows system
2553 directory. Just find out its directory by having a look at the Wine
2554 configuration file variable "System" (which indicates the location of the
2555 Windows system directory) and the associated drive entry.
2556 Note that you probably shouldn't use NT-based native DLLs,
2557 since Wine's NT API support is somewhat weaker than its Win9x
2558 API support (thus leading to even worse compatibility with NT DLLs
2559 than with a no-windows setup!), so better use Win9x native DLLs
2560 instead or no native DLLs at all.
2561 </para>
2562 </sect2>
2567 <para>
2569 </para>
2571 <para>
2573 extract native Windows .dll files from .cab files that are to be
2574 found on many Windows installation CDs.
2575 </para>
2576 </sect2>
2577 </sect1>
2582 <para>
2583 Wine currently supports several different display subsystems
2584 (graphics / text) that are available on various operating
2585 systems today.
2586 For each of these, Wine implements its own interfacing driver.
2587 This section explains how to select one of these drivers
2588 and how to further configure the respective driver.
2589 Once you're finished with that, you can consider your Wine installation
2590 to be finished.
2591 </para>
2593 <para>
2594 The display drivers currently implemented in Wine are:
2595 x11drv, which is used for interfacing to X11 graphics
2596 (the one you'll most likely want to use) and ttydrv
2597 (used for text mode console apps mainly that don't really need
2598 any graphics output).
2599 Once you have decided which display driver to use, it is chosen
2602 </para>
2604 <sect2>
2607 <para>
2609 </para>
2610 <para>
2612 </para>
2614 <sect3>
2617 <para>
2618 The x11drv driver consists of two conceptually distinct
2619 pieces, the graphics driver (GDI part), and the windowing
2620 driver (USER part). Both of these are linked into the
2623 Wine, running on X11, the graphics driver must draw on
2624 drawables (window interiors) provided by the windowing
2625 driver. This differs a bit from the Windows model, where the
2626 windowing system creates and configures device contexts
2627 controlled by the graphics driver, and programs are
2628 allowed to hook into this relationship anywhere they like.
2629 Thus, to provide any reasonable tradeoff between
2630 compatibility and usability, the x11drv has three different
2631 modes of operation.
2632 </para>
2634 <variablelist>
2635 <varlistentry>
2637 <listitem>
2638 <para>
2640 wine configuration file option (see below).
2641 Ordinary top-level frame windows with thick borders,
2642 title bars, and system menus will be managed by your
2643 window manager. This lets these programs integrate
2644 better with the rest of your desktop, but may not
2645 always work perfectly (a rewrite of this mode of
2646 operation, to make it more robust and less patchy, is
2647 currently being done, though, and it's planned to be
2648 finished before the Wine 1.0 release).
2649 </para>
2650 </listitem>
2651 </varlistentry>
2652 <varlistentry>
2654 <listitem>
2655 <para>
2656 Window manager independent (any running
2657 window manager is ignored completely). Window
2658 decorations (title bars, borders, etc) are drawn by
2659 Wine to look and feel like the real Windows. This is
2660 compatible with programs that depend on being able
2661 to compute the exact sizes of any such decorations, or
2662 that want to draw their own.
2663 Unmanaged mode is only used if both Managed and Desktop
2664 are set to disabled.
2665 </para>
2666 </listitem>
2667 </varlistentry>
2668 <varlistentry>
2670 <listitem>
2671 <para>
2673 wine configuration file option (see below).
2675 for a such-sized desktop, or
2677 automatically position the desktop at the upper-left
2678 corner of the display). This is the mode most
2679 compatible with the Windows model. All program
2680 windows will just be Wine-drawn windows inside the
2681 Wine-provided desktop window (which will itself be
2682 managed by your window manager), and Windows
2683 programs can roam freely within this virtual
2684 workspace and think they own it all, without
2685 disturbing your other X apps.
2686 Note: currently there's one desktop window for every
2687 program; this will be fixed at some time.
2688 </para>
2689 </listitem>
2690 </varlistentry>
2691 </variablelist>
2692 </sect3>
2694 <sect3>
2697 <variablelist>
2698 <varlistentry>
2700 <listitem>
2701 <para>
2702 Wine can let frame windows be managed by your window
2703 manager. This option specifies whether you want that
2704 by default.
2705 </para>
2706 </listitem>
2707 </varlistentry>
2708 <varlistentry>
2710 <listitem>
2711 <para>
2712 Creates a main desktop window of a specified size
2713 to display all Windows programs in.
2714 The size argument could e.g. be "800x600".
2715 </para>
2716 </listitem>
2717 </varlistentry>
2718 <varlistentry>
2720 <listitem>
2721 <para>
2722 If you don't use DGA, you may want an alternative
2723 means to convince the mouse cursor to stay within the
2724 game window. This option does that. Of course, as with
2725 DGA, if Wine crashes, you're in trouble (although not
2726 as badly as in the DGA case, since you can still use
2727 the keyboard to get out of X).
2728 </para>
2729 </listitem>
2730 </varlistentry>
2731 <varlistentry>
2733 <listitem>
2734 <para>
2735 This specifies whether you want DirectDraw to use
2736 XFree86's <firstterm>Direct Graphics
2737 Architecture</firstterm> (DGA), which is able to
2738 take over the entire display and run the game
2739 full-screen at maximum speed. (With DGA1 (XFree86
2740 3.x), you still have to configure the X server to the
2741 game's requested bpp first, but with DGA2 (XFree86
2742 4.x), runtime depth-switching may be possible,
2743 depending on your driver's capabilities.) But be aware
2744 that if Wine crashes while in DGA mode, it may not be
2745 possible to regain control over your computer without
2746 rebooting. DGA normally requires either root
2747 privileges or read/write access to
2749 </para>
2750 </listitem>
2751 </varlistentry>
2752 <varlistentry>
2754 <listitem>
2755 <para>
2756 If you don't want DirectX to use DGA, you can at least
2757 use X Shared Memory extensions (XShm). It is much
2758 slower than DGA, since the app doesn't have direct
2759 access to the physical frame buffer, but using shared
2760 memory to draw the frame is at least faster than
2761 sending the data through the standard X11 socket, even
2762 though Wine's XShm support is still known to crash
2763 sometimes.
2764 </para>
2765 </listitem>
2766 </varlistentry>
2767 <varlistentry>
2769 <listitem>
2770 <para>
2771 Applies only if you use the
2773 to run in a desktop window. Specifies whether to
2774 create the desktop window with a double-buffered
2775 visual, something most OpenGL games need to run
2776 correctly.
2777 </para>
2778 </listitem>
2779 </varlistentry>
2780 <varlistentry>
2782 <listitem>
2783 <para>
2784 Applies only if you have a palette-based display, i.e.
2785 if your X server is set to a depth of 8bpp, and if you
2786 haven't requested a private color map. It specifies
2787 the maximum number of shared colormap cells (palette
2788 entries) Wine should occupy. The higher this value,
2789 the less colors will be available to other
2790 programs.
2791 </para>
2792 </listitem>
2793 </varlistentry>
2794 <varlistentry>
2796 <listitem>
2797 <para>
2798 Applies only if you have a palette-based display, i.e.
2799 if your X server is set to a depth of 8bpp. It
2800 specifies that you don't want to use the shared color
2801 map, but a private color map, where all 256 colors are
2802 available. The disadvantage is that Wine's private
2803 color map is only seen while the mouse pointer is
2804 inside a Wine window, so psychedelic flashing and
2805 funky colors will become routine if you use the mouse
2806 a lot.
2807 </para>
2808 </listitem>
2809 </varlistentry>
2810 <varlistentry>
2812 <listitem>
2813 <para>
2814 To be used for debugging X11 operations.
2815 If Wine crashes with an X11 error, then you should enable
2816 Synchronous mode to disable X11 request caching in order
2817 to make sure that the X11 error happens directly after
2818 the corresponding X11 call in the log file appears.
2819 Will slow down X11 output!
2820 </para>
2821 </listitem>
2822 </varlistentry>
2823 <varlistentry>
2825 <listitem>
2826 <para>
2827 Applies only to multi-depth displays. It specifies
2828 which of the available depths Wine should use (and
2829 tell Windows apps about).
2830 </para>
2831 </listitem>
2832 </varlistentry>
2833 <varlistentry>
2835 <listitem>
2836 <para>
2837 This specifies which X11 display to use, and if
2838 specified, will override the
2840 </para>
2841 </listitem>
2842 </varlistentry>
2843 <varlistentry>
2845 <listitem>
2846 <para>
2847 This option only determines whether fast X11 routines
2848 or exact Wine routines will be used for certain ROP
2849 codes in blit operations. Most users won't notice any
2850 difference.
2851 </para>
2852 </listitem>
2853 </varlistentry>
2854 <varlistentry>
2856 <listitem>
2857 <para>
2858 Codepage to be used for rendering the text in X11
2859 output. Some sample values would be 437 (USA, Canada),
2861 (Cyrillic). For additional suitable values, see e.g. the Linux
2862 kernel's codepage configuration page.
2863 </para>
2864 </listitem>
2865 </varlistentry>
2866 </variablelist>
2867 </sect3>
2868 </sect2>
2870 <sect2>
2872 <para>
2873 Currently, the ttydrv doesn't have any special configuration
2874 options to set in the configuration file.
2875 </para>
2876 </sect2>
2878 </sect1>
2884 <para>
2886 Oct 18 2002
2887 </para>
2889 <para>
2890 The windows and DOS version value a program gets e.g. by calling the
2891 Windows function GetVersion() plays a very important role:
2892 If your Wine installation for whatever reason fails to provide
2893 to your program the correct version value that it expects,
2894 then the program might assume some very bad things and fail (in
2895 the worst case even silently!).
2897 Fortunately Wine contains some more or less intelligent Windows
2898 version guessing algorithm that will try to guess the Windows
2899 version a program might expect and pass that one on to the
2900 program.
2902 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.
2903 </para>
2905 <sect2>
2906 <title>How to configure the Windows and DOS version value Wine
2907 should return</title>
2909 <para>
2910 The version values can be configured in the wine configuration file in
2911 the [Version] section.
2912 </para>
2914 <variablelist>
2915 <varlistentry>
2917 <listitem>
2918 <para>
2919 default: none; chosen by semi-intelligent detection
2920 mechanism based on DLL environment.
2921 Used to specify which Windows version to return to
2922 programs (forced value, overrides standard detection
2925 Also valid as an
2927 setting (recommended/preferred use).
2928 </para>
2929 </listitem>
2930 </varlistentry>
2931 <varlistentry>
2933 <listitem>
2934 <para>
2935 Used to specify the DOS version that should be returned
2936 to programs. Only takes effect in case Wine acts as
2937 "win31" Windows version! Common DOS version settings
2939 Also valid as an
2941 setting (recommended/preferred use).
2942 </para>
2943 </listitem>
2944 </varlistentry>
2945 </variablelist>
2946 </sect2>
2947 </sect1>
2949 &fonts;
2950 &printing;
2954 <para>
2956 </para>
2957 <para>
2959 </para>
2960 <para>
2961 Win95/Win98 interface code is being introduced.
2962 </para>
2963 <para>
2964 Instead of compiling Wine for Win3.1 vs. Win95 using
2966 special [Tweak.Layout] section of
2970 </para>
2971 <para>
2972 A few new sections and a number of entries have been added to
2974 debugging the Win95 tweaks only and may be removed in a future
2975 release! These entries/sections are:
2976 </para>
2977 <programlisting>
2978 [Tweak.Fonts]
2984 "OEMFixed.xxx" # Same parameters for the OEM fixed typeface
2985 "AnsiFixed.xxx" # Same parameters for the Ansi fixed typeface
2986 "AnsiVar.xxx" # Same parameters for the Ansi variable typeface
2987 "SystemFixed.xxx" # Same parameters for the System fixed typeface
2989 [Tweak.Layout]
2991 </programlisting>
2992 </sect1>
2997 <para>
2999 </para>
3000 <para>
3002 </para>
3004 <para>
3005 Wine now needs to know about your keyboard layout. This
3006 requirement comes from a need from many apps to have the
3007 correct scancodes available, since they read these directly,
3008 instead of just taking the characters returned by the X
3009 server. This means that Wine now needs to have a mapping from
3010 X keys to the scancodes these programs expect.
3011 </para>
3012 <para>
3013 On startup, Wine will try to recognize the active X layout by
3014 seeing if it matches any of the defined tables. If it does,
3015 everything is alright. If not, you need to define it.
3016 </para>
3017 <para>
3018 To do this, open the file
3020 at the existing tables. Make a backup copy of it, especially
3021 if you don't use CVS.
3022 </para>
3023 <para>
3024 What you really would need to do, is find out which scancode
3025 each key needs to generate. Find it in the
3027 this:
3028 </para>
3029 <programlisting>
3030 static const int main_key_scan[MAIN_LEN] =
3031 {
3032 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
3038 };
3039 </programlisting>
3040 <para>
3041 Next, assign each scancode the characters imprinted on the
3042 keycaps. This was done (sort of) for the US 101-key keyboard,
3043 which you can find near the top in
3045 is no 102nd key, you can skip that.
3046 </para>
3047 <para>
3048 However, for most international 102-key keyboards, we have
3049 done it easy for you. The scancode layout for these already
3050 pretty much matches the physical layout in the
3052 to go through all the keys that generate characters on your
3053 main keyboard (except spacebar), and stuff those into an
3054 appropriate table. The only exception is that the 102nd key,
3055 which is usually to the left of the first key of the last line
3057 line after the last line.
3058 </para>
3059 <para>
3060 For example, my Norwegian keyboard looks like this
3061 </para>
3062 <screen>
3063 § ! " # ¤ % & / ( ) = ? ` Back-
3064 | 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
3066 Tab Q W E R T Y U I O P Å ^
3067 ¨~
3068 Enter
3069 Caps A S D F G H J K L Ø Æ *
3070 Lock '
3072 Sh- > Z X C V B N M ; : _ Shift
3073 ift < , . -
3075 Ctrl Alt Spacebar AltGr Ctrl
3076 </screen>
3077 <para>
3078 Note the 102nd key, which is the <keycap><></keycap> key, to
3079 the left of <keycap>Z</keycap>. The character to the right of
3080 the main character is the character generated by
3081 <keycap>AltGr</keycap>.
3082 </para>
3083 <para>
3084 This keyboard is defined as follows:
3085 </para>
3086 <programlisting>
3087 static const char main_key_NO[MAIN_LEN][4] =
3088 {
3093 "<>"
3094 };
3095 </programlisting>
3096 <para>
3097 Except that " and \ needs to be quoted with a backslash, and
3098 that the 102nd key is on a separate line, it's pretty
3099 straightforward.
3100 </para>
3101 <para>
3102 After you have written such a table, you need to add it to the
3103 <function>main_key_tab[]</function> layout index table. This
3104 will look like this:
3105 </para>
3106 <programlisting>
3107 static struct {
3108 WORD lang, ansi_codepage, oem_codepage;
3109 const char (*key)[MAIN_LEN][4];
3110 } main_key_tab[]={
3111 ...
3112 ...
3113 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
3114 ...
3115 </programlisting>
3116 <para>
3117 After you have added your table, recompile Wine and test that
3118 it works. If it fails to detect your table, try running
3119 </para>
3120 <screen>
3121 wine --debugmsg +key,+keyboard >& key.log
3122 </screen>
3123 <para>
3124 and look in the resulting <filename>key.log</filename> file to
3125 find the error messages it gives for your layout.
3126 </para>
3127 <para>
3128 Note that the <constant>LANG_*</constant> and
3129 <constant>SUBLANG_*</constant> definitions are in
3130 <filename>include/winnls.h</filename>, which you might need to
3131 know to find out which numbers your language is assigned, and
3132 find it in the debugmsg output. The numbers will be
3133 <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
3134 the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
3135 <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
3136 <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
3137 could look for <literal>0414</literal> in the debugmsg output
3138 to find out why my keyboard won't detect.
3139 </para>
3140 <para>
3141 Once it works, submit it to the Wine project. If you use CVS,
3142 you will just have to do
3143 </para>
3144 <screen>
3145 cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
3146 </screen>
3147 <para>
3148 from your main Wine directory, then submit
3149 <filename>layout.diff</filename> to
3150 <email>wine-patches@winehq.com</email> along with a brief note
3151 of what it is.
3152 </para>
3153 <para>
3154 If you don't use CVS, you need to do
3155 </para>
3156 <screen>
3157 diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
3158 </screen>
3159 <para>
3160 and submit it as explained above.
3161 </para>
3162 <para>
3163 If you did it right, it will be included in the next Wine
3164 release, and all the troublesome programs (especially
3165 remote-control programs) and games that use scancodes will
3166 be happily using your keyboard layout, and you won't get those
3167 annoying fixme messages either.
3168 </para>
3169 <para>
3170 Good luck.
3171 </para>
3172 </sect1>
3175 <title>SCSI Support</title>
3176 <para>
3177 Written by &name-bruce-milner; <email>&email-bruce-milner;</email>;
3178 Additions by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
3179 </para>
3180 <para>
3181 (Extracted from <filename>wine/documentation/aspi</filename>)
3182 </para>
3184 <para>
3185 This file describes setting up the Windows ASPI interface.
3186 </para>
3188 <para>
3189 <warning><title>Warning/Warning/Warning!!!!!!</title>
3190 <para>This may trash your system if used incorrectly. It may
3191 even trash your system when used <emphasis>correctly</>!
3192 </para>
3193 </warning>
3194 </para>
3196 <para>
3197 Now that I have said that. ASPI is a direct link to SCSI devices from
3198 windows programs. ASPI just forwards the SCSI commands that programs send
3199 to it to the SCSI bus.
3200 </para>
3201 <para>
3202 If you use the wrong SCSI device in your setup file, you can send
3203 completely bogus commands to the wrong device - An example would be
3204 formatting your hard drives (assuming the device gave you permission -
3205 if you're running as root, all bets are off).
3206 </para>
3207 <para>
3208 So please make sure that <emphasis>all</emphasis> SCSI devices not needed by the program
3209 have their permissions set as restricted as possible!
3210 </para>
3212 <para>
3213 Cookbook for setting up scanner: (At least how mine is to work)
3214 (well, for other devices such as CD burners, MO drives, ..., too)
3215 </para>
3217 <sect2>
3218 <title>Windows requirements</title>
3219 <orderedlist>
3220 <listitem>
3221 <para>
3223 compatible drivers (ASPI). At least with Mustek, they
3224 allow you the choice of using the built-in card or the
3226 any other way. Software that accesses the scanner via a
3227 DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM]
3228 </para>
3229 </listitem>
3230 <listitem>
3231 <para>
3232 You probably need a real windows install of the software
3233 to set the LUN's/SCSI id's up correctly. I'm not exactly
3234 sure.
3235 </para>
3236 </listitem>
3237 </orderedlist>
3238 </sect2>
3240 <sect2>
3241 <title>Linux requirements</title>
3242 <orderedlist>
3243 <listitem>
3244 <para>
3245 Your SCSI card must be supported under Linux. This will
3246 not work with an unknown SCSI card. Even for cheap'n
3248 drivers exist on the net.
3249 If you intend to use your IDE device, you need to use the
3250 ide-scsi emulation.
3251 Read
3253 http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html</ulink>
3254 for ide-scsi setup instructions.
3255 </para>
3256 </listitem>
3257 <listitem>
3258 <para>
3259 Compile generic SCSI drivers into your kernel.
3260 </para>
3261 </listitem>
3262 <listitem>
3263 <para>
3264 This seems to be not required any more for newer (2.2.x) kernels:
3265 Linux by default uses smaller SCSI buffers than Windows.
3266 There is a kernel build define <literal>SG_BIG_BUFF</literal> (in
3267 <filename>sg.h</filename>) that is by default set too
3268 low. The SANE project recommends
3269 <literal>130560</literal> and this seems to work just
3270 fine. This does require a kernel rebuild.
3271 </para>
3272 </listitem>
3273 <listitem>
3274 <para>
3275 Make the devices for the scanner (generic SCSI devices)
3276 - look at the SCSI programming HOWTO at
3278 http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html</ulink>
3279 for device numbering.
3280 </para>
3281 </listitem>
3282 <listitem>
3283 <para>
3284 I would recommend making the scanner device writable by
3285 a group. I made a group called
3286 <literal>scanner</literal> and added myself to it.
3287 Running as root increases your risk of sending bad SCSI
3288 commands to the wrong device. With a regular user, you
3289 are better protected.
3290 </para>
3291 </listitem>
3292 <listitem>
3293 <para>
3294 For Win32 software (WNASPI32), Wine has auto-detection in place.
3295 For Win16 software (WINASPI), you need to add a SCSI device entry
3296 for your particular scanner to ~/.wine/config. The format is
3297 <literal>[scsi cCtTdD]</literal> where
3300 </para>
3301 <para>
3302 For example, I set mine up as controller <literal>0</literal>,
3303 Target <literal>6</literal>, LUN <literal>0</literal>.
3304 <programlisting>
3305 [scsi c0t6d0]
3307 </programlisting>
3308 Yours will vary with your particular SCSI setup.
3309 </para>
3310 </listitem>
3311 </orderedlist>
3312 </sect2>
3314 <sect2>
3315 <title>General Information</title>
3316 <para>
3317 The mustek scanner I have was shipped with a package
3319 to access scanners.
3320 </para>
3321 <para>
3322 (TWAIN MANAGER)
3323 </para>
3324 <para>
3325 <programlisting>
3326 ipplus.exe <-> (TWAIN INTERFACE) <-> (TWAIN DATA SOURCE.ASPI) -> WINASPI
3327 </programlisting>
3328 </para>
3329 </sect2>
3331 <sect2>
3332 <title>NOTES/BUGS</title>
3333 <para>
3334 The biggest drwback is that it only works under Linux at the moment.
3335 </para>
3336 <para>
3337 The ASPI code has only been tested with:
3338 </para>
3339 <itemizedlist>
3340 <listitem>
3341 <para>
3342 a Mustek 800SP with a Buslogic controller under Linux [BM]
3343 </para>
3344 </listitem>
3345 <listitem>
3346 <para>
3347 a Siemens Nixdorf 9036 with Adaptec AVA-1505 under Linux
3348 accessed via DOSASPI. Note that I had color problems,
3349 though (barely readable result) [AM]
3350 </para>
3351 </listitem>
3352 <listitem>
3353 <para>
3354 a Fujitsu M2513A MO drive (640MB) using generic SCSI
3355 drivers. Formatting and ejecting worked perfectly.
3356 Thanks to Uwe Bonnes for access to the hardware! [AM]
3357 </para>
3358 </listitem>
3359 </itemizedlist>
3360 <para>
3361 I make no warranty to the ASPI code. It makes my scanner
3362 work. Your devices may explode. I have no way of determining
3363 this. I take zero responsibility!
3364 </para>
3365 </sect2>
3366 </sect1>
3369 <title>Using ODBC</title>
3370 <para>
3371 This section describes how ODBC works within Wine and how to configure
3372 it to do what you want (if it can do what you want).
3373 </para>
3374 <para>
3375 The ODBC system within Wine, as with the printing system, is designed
3376 to hook across to the Unix system at a high level. Rather than
3377 ensuring that all the windows code works under wine it uses a suitable
3378 Unix ODBC provider, such as UnixODBC. Thus if you configure Wine to
3379 use the built-in odbc32.dll, that Wine DLL will interface to your
3380 Unix ODBC package and let that do the work, whereas if you configure
3381 Wine to use the native odbc32.dll it will try to use the native
3382 ODBC32 drivers etc.
3383 </para>
3384 <sect2>
3385 <title>Using a Unix ODBC system with Wine</title>
3386 <para>
3387 The first step in using a Unix ODBC system with Wine is, of course,
3388 to get the Unix ODBC system working itself. This may involve
3389 downloading code or RPMs etc. There are several Unix ODBC systems
3390 available; the one the author is used to is unixODBC (with the
3391 IBM DB2 driver). Typically such systems will include a tool, such
3392 as <command>isql</command>, which will allow you to access the data from the command
3393 line so that you can check that the system is working.
3394 </para>
3395 <para>
3396 The next step is to hook the Unix ODBC library to the wine built-in
3397 odbc32 DLL. The built-in odbc32 (currently) looks to the
3398 environment variable <emphasis>LIB_ODBC_DRIVER_MANAGER</emphasis>
3399 for the name of the ODBC library. For example in the author's
3400 .bashrc file is the line:
3401 </para>
3402 <programlisting>
3403 export LIB_ODBC_DRIVER_MANAGER=/usr/lib/libodbc.so.1.0.0
3404 </programlisting>
3405 <para>
3406 If that environment variable is not set then it looks for a
3407 library called libodbc.so and so you can add a symbolic link to
3408 equate that to your own library. For example as root you could
3409 run the commands:
3410 </para>
3411 <screen>
3412 <prompt># </prompt><userinput>ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so</userinput>
3413 <prompt># </prompt><userinput>/sbin/ldconfig</userinput>
3414 </screen>
3415 <para>
3416 The last step in configuring this is to ensure that Wine is set up
3417 to run the built-in version of odbc32.dll, by modifying the DLL
3418 configuration. This built-in DLL merely acts as a stub between the
3419 calling code and the Unix ODBC library.
3420 </para>
3421 <para>
3422 If you have any problems then you can use the debugmsg channel
3423 odbc32 to trace what is happening. One word of warning. Some
3424 programs actually cheat a little and bypass the ODBC library. For
3425 example the Crystal Reports engine goes to the registry to check on
3426 the DSN. The fix for this is documented at unixODBC's site where
3427 there is a section on using unixODBC with Wine.
3428 </para>
3429 </sect2>
3430 <sect2>
3431 <title>Using Windows ODBC drivers</title>
3432 <para>
3433 Does anyone actually have any experience of this and anything to
3434 add?
3435 </para>
3436 </sect2>
3437 </sect1>
3439 </chapter>
3441 <!-- Keep this comment at the end of the file
3442 Local variables:
3443 mode: sgml
3445 End:
3446 -->