| blob | dfc3ed73919b7a5c3740084ccaa059cf3c7b3032 |
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 A Windows installation is a very complex structure. It consists of
36 many different parts with very different functionality.
37 We'll try to outline the most important aspects of it.
38 </para>
40 <itemizedlist>
41 <listitem>
42 <para>
43 Registry. Many keys are supposed to exist and contain
44 meaningful data, even in a newly-installed Windows.
45 </para>
46 </listitem>
47 <listitem>
48 <para>
49 Directory structure. Applications expect to find and/or
50 install things in specific predetermined locations. Most
51 of these directories are expected to exist. But unlike
52 Unix directory structures, most of these locations are
53 not hardcoded, and can be queried via the Windows API
54 and the registry. This places additional requirements on
55 a Wine installation.
56 </para>
57 </listitem>
58 <listitem>
59 <para>
60 System DLLs. In Windows, these usually reside in the
63 programs check for their existence in these
64 directories before attempting to load them. While Wine
65 is able to load its own internal DLLs
67 asks for a DLL, Wine does not simulate the presence of
68 non-existent files.
69 </para>
70 </listitem>
71 </itemizedlist>
73 <para>
74 While the users are of course free to set up everything
75 themselves, the Wine team will make the automated Wine source
77 do everything we find necessary to do; running the
78 conventional <userinput>configure && make depend && make && make
79 install</userinput> cycle is thus not recommended, unless
80 you know what you're doing. At the moment,
82 configuration file, install the registry, and create the
83 directory structure itself.
84 </para>
86 </sect1>
91 <para>
92 Managing the Wine configuration file settings can be a
93 difficult task, sometimes too difficult for some people.
94 That's why there are some helper applications for easily setting up an
95 initial wine configuration file with useful default settings.
96 </para>
100 <para>
101 WineSetupTk is a graphical Wine configuration tool with
102 incredibly easy handling of Wine configuration issues, to be
103 used for configuring the Wine environment after having
104 installed the Wine files.
105 It has been written by CodeWeavers in 2000 as part of a host
106 of other efforts to make Wine more desktop oriented, and updated
107 in 2003 by Vincent Béron, Alex Pasadyn and Ivan Leo Murray-Smith.
108 </para>
109 <para>
110 If you're using Debian, simply install the WineSetupTk
111 package (as root):
112 </para>
113 <screen>
115 </screen>
116 <para>
117 If you're using another distribution, you can get WineSetupTk from the
119 sourceforge.net Wine download page</ulink>
120 </para>
121 </sect2>
125 <para>
128 source code tree. It has been written to allow for an easy
129 and complete compilation/installation of Wine source code for
130 people who don't bother with reading heaps of very valuable
131 and informative documentation ;-)
132 </para>
133 <para>
134 Once you have successfully extracted the Wine source code
135 tree, change to the main directory of it and then run (as
136 user):
137 </para>
138 <screen>
140 </screen>
141 <para>
142 Doing so will compile Wine, install Wine and configure the
143 Wine environment (either by providing access to a Windows
144 partition or by creating a properly configured no-windows
145 directory environment).
146 </para>
148 </sect2>
149 <!--
150 Commenting out until winecfg doesn't actually do something.
151 <sect2 id="config-helper-winecfg">
152 <title>winecfg</title>
153 <para>
154 <command>winecfg</command> is a small graphical configuration tool
155 residing as <filename>programs/winecfg</filename> in a Wine
156 source code tree. It is a Winelib app making use of standard
157 Win32 GUI controls to easily customize entries in a Wine
158 configuration file.
159 </para>
160 </sect2>
161 -->
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>
211 <sect2>
213 <para>
214 The Wine configuration file is the central file to store
215 configuration settings for Wine.
218 of your user's home directory
221 Note that since the Wine configuration file is a part of the
222 Wine registry file system, this file also
224 Version 2" header line to be recognized properly, just like
225 all other Wine registry text files (just in case you decided
226 to write your own registry file from scratch and wonder why
227 Wine keeps rejecting it).
228 </para>
229 <para>
230 The settings available in the configuration file include:
231 <itemizedlist>
232 <listitem>
233 <para>
234 Drives and information about them
235 </para>
236 </listitem>
237 <listitem>
238 <para>
239 Directory settings
240 </para>
241 </listitem>
242 <listitem>
243 <para>
244 Port settings
245 </para>
246 </listitem>
247 <listitem>
248 <para>
249 The Wine look and feel
250 </para>
251 </listitem>
252 <listitem>
253 <para>
254 Wine's DLL usage
255 </para>
256 </listitem>
257 <listitem>
258 <para>
259 Wine's multimedia drivers and DLL configuration
260 </para>
261 </listitem>
262 </itemizedlist>
263 </para>
264 </sect2>
266 <sect2>
268 <para>
269 If you just installed Wine for the first time and want to
270 finish Wine installation by configuring it now, then you could
272 (which can be found in the directory
274 code directory) as a base for adapting the Wine configuration
275 file to the settings you want.
276 First, I should mention that you should not forget to make
277 sure that any previous configuration file at
279 of the way instead of simply overwriting it when you will now
280 copy over the sample configuration file.
281 </para>
282 <para>
283 If you don't have a pre-existing configuration file and thus
284 need to copy over our sample configuration file to the
285 standard Wine configuration file location, do in a
287 <screen>
289 <prompt>$ </><userinput>cp <replaceable>dir_to_wine_source_code</replaceable>/documentation/samples/config ~/.wine/config</>
290 </screen>
291 Otherwise, simply use the already existing configuration file
293 </para>
294 <para>
295 Now you can start adapting the configuration file's settings with an
297 below.
299 configuration file settings if wineserver is not running (in
300 other words: if your user doesn't have a Wine session running),
301 otherwise Wine won't use them - and even worse, wineserver will
302 overwrite them with the old settings once wineserver quits!!
303 </para>
304 </sect2>
309 <para>
310 Let's start by giving an overview of which sections a
311 configuration file may contain, and whether the inclusion of
312 the respective section is <emphasis>needed</emphasis> or only <emphasis>recommended</emphasis> ("recmd").
313 </para>
317 <thead>
318 <row>
322 </row>
323 </thead>
324 <tbody>
325 <row>
329 </row>
330 <row>
334 </row>
335 <row>
339 </row>
340 <row>
344 </row>
345 <row>
349 </row>
350 <row>
354 </row>
355 <row>
359 </row>
360 <row>
364 </row>
365 <row>
369 </row>
370 <row>
374 </row>
375 <row>
379 </row>
380 <row>
384 </row>
385 <row>
389 </row>
390 <row>
394 </row>
395 <row>
399 </row>
400 <row>
404 </row>
405 <row>
409 </row>
410 <row>
414 </row>
415 <row>
419 </row>
420 <row>
424 </row>
425 <row>
429 </row>
430 </tbody>
431 </tgroup>
432 </informaltable>
434 <para>
435 Now let's explain the configuration file sections in a
436 detailed way.
437 </para>
439 <sect3>
441 <para>
442 For a detailed description of these configuration file
443 sections which are used to set up DOS drive mappings to Unix
444 directory space, please look at the <link
446 configuration section</link>.
447 </para>
448 </sect3>
452 <para>
453 The [wine] section of the configuration file contains all kinds
454 of general settings for Wine.
455 </para>
456 <para>
457 <programlisting>
463 </programlisting>
464 For a detailed description of drive layer configuration and
465 the meaning of these parameters, please look at the <link
467 configuration section</link>.
468 </para>
469 <para>
471 Sets the graphics driver to use for Wine output.
472 x11drv is for X11 output, ttydrv is for text console output.
473 WARNING: if you use ttydrv here, then you won't be able to run
474 a lot of Windows GUI programs (ttydrv is still pretty "broken"
475 at running graphical apps). Thus this option is mainly interesting
476 for e.g. embedded use of Wine in web server scripts.
477 Note that ttydrv is still very lacking, so if it doesn't work,
478 resort to using "xvfb", a virtual X11 server.
479 Another way to run Wine without display would be to run X11
480 via Xvnc, then connect to that VNC display using xvncviewer
481 (that way you're still able to connect to your app and
482 configure it if need be).
483 </para>
484 <para>
486 whether to allow printing via printer drivers to work.
487 This option isn't needed for our built-in psdrv printer driver
488 at all.
489 Using these things are pretty alpha, so you might want to
490 watch out. Some people might find it useful, however. If
491 you're not planning to work on printing via windows printer
492 drivers, don't even add this to your wine configuration file
493 (It probably isn't already in it).
494 Check out the [spooler] and [parallelports] sections too.
495 </para>
496 <para>
498 This setting specifies the shell linker script to use for setting
499 up Windows icons in e.g. KDE or Gnome that are given by programs
500 making use of appropriate shell32.dll functionality to create
501 icons on the desktop/start menu during installation.
502 </para>
503 <para>
505 Sets up the symbol table file for the wine debugger. You
506 probably don't need to fiddle with this. May be useful if
507 your wine is stripped.
508 </para>
509 </sect3>
513 <para>
514 These settings provide wine's default handling of DLL loading.
515 </para>
516 <para>
518 This setting is a comma-delimited list of the order in
519 which to attempt loading DLLs. If the first option fails,
520 it will try the second, and so on. The order specified
521 above is probably the best in most conditions.
522 </para>
523 </sect3>
525 <sect3>
527 <para>
528 At one time, there was a section called [DllPairs] in the
529 default configuration file, but this has been obsoleted
530 because the pairing information has now been embedded into
531 Wine itself. (The purpose of this section was merely to be
532 able to issue warnings if the user attempted to pair
536 </para>
537 </sect3>
541 <para>
542 The format for this section is the same for each line:
543 <programlisting><DLL>{,<DLL>,<DLL>...} = <FORM>{,<FORM>,<FORM>...}</programlisting>
544 For example, to load built-in KERNEL pair (case doesn't
545 matter here):
547 To load the native COMMDLG pair, but if that doesn't work
548 try built-in:
550 To load the native COMCTL32:
552 Here is a good generic setup (As it is defined in config
553 that was included with your wine package):
554 <programlisting>
555 [DllOverrides]
592 ; you can specify programs too
594 ; default for all other DLLs
596 </programlisting>
597 </para>
598 <note>
599 <para>
600 If loading of the libraries that are listed first fails,
601 wine will just go on by using the second or third option.
602 </para>
603 </note>
604 </sect3>
608 <para>
609 This section sets up wine's font handling.
610 </para>
611 <para>
613 Since the way X handles fonts is different from the way
614 Windows does, wine uses a special mechanism to deal with
615 them. It must scale them using the number defined in the
617 a nice in the middle one. If you have the real windows
618 fonts available , this parameter will not be as
619 important. Of course, it's always good to get your X fonts
620 working acceptably in wine.
621 </para>
622 <para>
624 The default font wine uses. Fool around with it if you'd like.
625 </para>
626 <para>
627 OPTIONAL:
628 </para>
629 <para>
631 used in wine. This is good for apps that need a special font you don't have,
632 but a good replacement exists. The syntax is like so:
633 <programlisting>"AliasX" = "[Fake windows name],[Real X name]"<,optional "masking" section></programlisting>
635 then "Alias1" and so on. The fake windows name is the name
636 that the font will be under a windows app in wine. The
637 real X name is the font name as seen by X (Run
639 utilize the fake windows name you define. If it is not
640 used, then wine will just try to extract the fake windows
641 name itself and not use the value you enter.
642 </para>
643 <para>
644 Here is an example of an alias without masking. The font will show up in windows
645 apps as "Google".
647 Here is an example with masking enabled. The font will show up as "Foo" in
648 windows apps.
651 chapter.
652 </para>
653 </sect3>
657 <para>
658 Even though it sounds like a lot of sections, these are
659 all closely related. They are all for communications and
660 parallel ports.
661 </para>
662 <para>
663 The [serialports] section tells wine what serial ports it
664 is allowed to use.
670 can actually equal any device
672 not always necessary to define any COM ports (An optional
673 setting). Here is an example:
675 Use as many of these as you like in the section to define
676 all of the COM ports you need.
677 </para>
678 <para>
679 The [parallelports] section sets up any parallel ports
680 that will be allowed access under wine.
682 Sounds familiar? Syntax is just like the COM port setting.
686 minus 1, just like for COM ports). You don't always need
687 to define a parallel port (AKA, it's optional). As with
688 the other section, LptX can equal any device (Maybe
691 The [spooler] section will inform wine where to spool
692 print jobs. Use this if you want to try printing. Wine
693 docs claim that spooling is "rather primitive" at this
695 setting you use in this section works to map a port (LPT1,
696 for example) to a file or a command. Here is an example,
699 The following command maps printing jobs to LPT1 to the
702 The [ports] section is usually useful only for people who
703 need direct port access for programs requiring dongles or
704 scanners. <emphasis>If you don't need it, don't use
705 it!</emphasis>
706 </para>
707 <para>
709 Gives direct read access to those IO's.
710 </para>
711 <para>
713 Gives direct write access to those IO's. It's probably a
714 good idea to keep the values of the
716 settings the same. This stuff will only work when you're
717 root.
718 </para>
719 </sect3>
723 <para>
724 [Debug] is used to include or exclude debug messages, and to
725 output them to a file. The latter is rarely used. <emphasis>These
726 are all optional and you probably don't need to add or
727 remove anything in this section to your config.</emphasis> (In extreme
728 cases you may want to use these options to manage the amount
729 of information generated by the <parameter>--debugmsg +relay
730 </parameter> option.)
731 </para>
732 <para>
734 Sets the logfile for wine. Set to CON to log to standard out.
736 </para>
737 <para>
741 </para>
742 <para>
746 </para>
747 <para>
749 Include only the listed functions in a
752 </para>
753 <para>
754 <programlisting>"RelayExclude" = "RtlEnterCriticalSection;RtlLeaveCriticalSection"</programlisting>
755 Exclude the listed functions in a
758 entry. If neither entry is present then the trace includes
759 everything.
760 </para>
761 <para>
762 In both entries the functions may be specified either as a
763 function name or as a module and function. In this latter
764 case specify an asterisk for the function name to include/exclude
765 all functions in the module.
766 </para>
767 <para>
768 [Registry] can be used to tell wine where your old windows
769 registry files exist. This section is completely optional
770 and useless to people using wine without an existing
771 windows installation.
772 </para>
773 <para>
776 </para>
777 <para>
778 [tweak.layout] is devoted to wine's look. There is only
779 one setting for it.
780 </para>
781 <para>
786 </para>
787 <para>
788 [programs] can be used to say what programs run under
789 special conditions.
790 </para>
791 <para>
793 Sets the program to be run if wine is started without specifying a program.
794 </para>
795 <para>
797 Sets the program to automatically be run at startup every time.
798 </para>
799 </sect3>
803 <para>
804 [WinMM] is used to define which multimedia drivers have to be loaded. Since
805 those drivers may depend on the multimedia interfaces available on your system
806 (OSS, ALSA... to name a few), it's needed to be able to configure which driver
807 has to be loaded.
808 </para>
810 <para>
811 The content of the section looks like:
812 <programlisting>
813 [WinMM]
817 </programlisting>
818 All the keys must be defined:
819 <itemizedlist>
820 <listitem>
821 <para>
822 The "Drivers" key is a ';' separated list of modules name, each of
823 them containing a low level driver. All those drivers will be loaded
824 when MMSYSTEM/WINMM is started and will provide their inner features.
825 </para>
826 </listitem>
827 <listitem>
828 <para>
829 The "WaveMapper" represents the name of the module containing the Wave
830 Mapper driver. Only one wave mapper can be defined in the system.
831 </para>
832 </listitem>
833 <listitem>
834 <para>
835 The "MidiMapper" represents the name of the module containing the MIDI
836 Mapper driver. Only one MIDI mapper can be defined in the system.
837 </para>
838 </listitem>
839 </itemizedlist>
840 </para>
841 </sect3>
845 <para>
846 [Network] contains settings related to
847 networking. Currently there is only one value that can be set.
848 </para>
849 <variablelist>
850 <varlistentry>
852 <listitem>
853 <para>
855 that affects the way Wine sets the computer name. The computer
858 <varname>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ComputerName\ComputerName</varname>.
859 </para>
860 <para>
861 If this option is set to "Y" or missing, Wine will set the
862 NetBIOS name to the Unix host name of your computer, if
863 necessary truncated to 31 characters. The Unix hostname is the output
865 including the first dot ('.'). Among other things, this means that
866 Windows programs running under Wine cannot change the NetBIOS computer name.
867 </para>
868 <para>
869 If this option is set to "N", Wine will use the registry value above
870 to set the NetBIOS name. Only if the registry entry doesn't exist (usually
871 only during the first wine startup) it will use the Unix hostname as
872 usual. Windows programs can change the NetBIOS name. The change
873 will be effective after a "reboot", i.e. after restarting Wine.
874 </para>
875 </listitem>
876 </varlistentry>
877 </variablelist>
878 </sect3>
882 <para>
883 The section is used to overwrite certain settings of this file for a
884 special program with different settings.
885 [AppDefaults] is not the real name of the section. The real name
886 consists of the leading word AppDefaults followed by the name
887 of the executable the section is valid for.
888 The end of the section name is the name of the
889 corresponding "standard" section of the configuration file
890 that should have some of its settings overwritten with the
891 program specific settings you define.
892 The three parts of the section name are separated by two backslashes.
893 </para>
894 <para>
895 Currently wine supports overriding selected settings within
896 the sections [DllOverrides], [x11drv], [version] and [dsound] only.
897 </para>
898 <para>
899 Here is an example that overrides the normal settings for a
900 program:
901 <programlisting>
902 ;; default settings
903 [x11drv]
907 ;; run install in desktop mode
908 [AppDefaults\\install.exe\\x11drv]
911 </programlisting>
912 </para>
913 </sect3>
914 </sect2>
918 <para>
919 There is always a chance that things will go wrong. If the
920 unthinkable happens, report the problem to
922 try the newsgroup
925 irc.freenode.net, or connected servers.
926 Make sure that you have looked over this document thoroughly,
927 and have also read:
928 </para>
929 <itemizedlist>
930 <listitem>
931 <para>
933 </para>
934 </listitem>
935 <listitem>
936 <para>
938 </para>
939 </listitem>
940 </itemizedlist>
941 <para>
942 If indeed it looks like you've done your research, be
943 prepared for helpful suggestions. If you haven't, brace
944 yourself for heaving flaming.
945 </para>
946 </sect2>
947 </sect1>
951 <sect2>
953 <para>
954 If you're planning to include access to a CD-ROM drive in your Wine
959 Several Windows program setup CD-ROMs or other CD-ROMs chose
960 to do such braindamaged things as marking very important setup
962 That's no problem on Windows, since the Windows CD-ROM driver by
963 default displays even files that are supposed to be
967 (the programs will simply abort with an <quote>installation file not found</quote> or similar error)
968 Thus you should never forget to add this setting.
969 </para>
970 </sect2>
972 <sect2>
974 <para>
975 Wine emulates drives by placing their virtual drive roots to
976 user-configurable points in the Unix filesystem, so it's your
981 indicates the home directory of a user), as the root of your
983 into your Wine configuration file:
984 </para>
986 <programlisting>
987 [Drive C]
992 </programlisting>
994 <para>
995 With this configuration, what windows apps think of as
996 "c:\windows\system" would map to
998 filesystem. Note that you need to specify
1002 Windows compatible (case insensitive) filesystem, otherwise
1003 most apps won't work.
1004 </para>
1005 </sect2>
1009 <para>
1010 Here's the fundamental layout that Windows programs and
1011 installers expect and that we thus need to configure properly
1012 in Wine. Without it, they seldomly operate correctly. If you
1013 intend to use a no-windows environment (not using an existing
1014 Windows partition), then it is recommended to use either
1017 initial windows directory tree, since creating a directory
1018 structure manually is tiresome and error-prone.
1019 </para>
1021 <programlisting>
1022 C:\ Root directory of primary disk drive
1023 Windows\ Windows directory, containing .INI files,
1024 accessories, etc.
1028 Start Menu\ Program launcher directory structure
1029 Programs\ Program launcher links (.LNK files) to programs
1030 Program Files\ Application binaries (.EXE and .DLL files)
1031 </programlisting>
1032 </sect2>
1036 <para>
1037 These sections are supposed to make certain Unix
1038 directory locations accessible to Wine as a DOS/Windows drive
1039 (drive 'x:') and thus accessible to Windows programs
1040 under the drive name you specified.
1041 Every DOS/Windows program sort of expects at least a C:
1042 drive (and sometimes also an A: floppy drive), so your
1043 configuration file should at least contain the corresponding
1044 sections, [Drive C] and [Drive A].
1045 You need to decide on whether you want to use an existing Windows
1046 partition as the C drive or whether you want to create your own
1047 Wine drive C directory tree somewhere (take care about
1048 permissions!).
1049 Each drive section may specify up to 6 different settings
1050 as explained below.
1051 </para>
1052 <para>
1054 The above line begins the section for a drive whose letter is x
1055 (DOS notation: drive 'x:').
1056 You could e.g. create an equivalent to a drive 'C:'
1057 under DOS/Windows by using a [Drive C] section name.
1058 Note that the drive letter is case insensitive.
1059 </para>
1060 <para>
1062 This specifies the directory where the drive will begin.
1063 When Wine is browsing in drive x, it will be able
1064 to see the files that are in the directory
1066 (note that symlinks to directories won't get included!
1068 configuration setting)
1069 You can also make use of environment variables like $HOME here,
1071 directory in your home dir would be
1073 but don't forget to put it as a DOS environment variable,
1074 ie surrounded by '%' signs rather than preceded by a '$'.
1075 Don't forget to leave off the trailing slash!
1076 </para>
1077 <para>
1079 Sets up the type of drive Wine will see it as. Type must
1083 (The |'s mean "Type = '<one of the options>'".)
1085 For a home directory entry, it makes sense to choose
1086 "network" sometimes, since some home directories are being
1087 exported over the network via NFS and thus can have slow response
1088 times.
1089 </para>
1090 <para>
1092 Defines the drive label. Generally only needed
1093 for programs that look for a special CD-ROM.
1094 The label may be up to 11 characters.
1095 Note that the preferred way of managing labels and serial numbers
1096 of CD-ROMs and floppies is to give Wine raw device access for
1097 reading these on a per-CD case (see "Device" below) instead of
1098 hardcoding one specific "Label".
1099 </para>
1100 <para>
1102 Tells Wine the serial number of the drive. A few programs with
1103 intense protection for pirating might need this, but otherwise
1104 it's not needed. Up to 8 characters and hexadecimal.
1106 is a smarter choice.
1107 </para>
1108 <para>
1110 Sets up the way Wine looks at files on the drive.
1111 This setting controls the file name lookup and mapping of
1112 Wine to existing file systems on your PC, it does
1114 used itself.
1115 </para>
1117 <variablelist>
1118 <varlistentry>
1120 <listitem>
1121 <para>
1123 the long filename filesystem you are probably used
1124 to working with. The filesystem behavior of choice for most
1125 programs to be run under wine. <emphasis>Probably the one
1126 you want!</emphasis>
1127 </para>
1128 </listitem>
1129 </varlistentry>
1130 <varlistentry>
1132 <listitem>
1133 <para>
1134 Case sensitive. This filesystem has almost no use
1135 (Windows apps expect case insensitive filenames),
1136 except maybe for Winelib applications.
1137 Try it if you dare, but win95 is a much better
1138 and always recommended choice.
1139 </para>
1140 </listitem>
1141 </varlistentry>
1142 <varlistentry>
1144 <listitem>
1145 <para>
1146 Case insensitive filesystem. Alike to DOS and
1148 length of files (eightdot.123) - longer ones will be
1149 truncated.
1150 <note>
1151 <para>
1153 you plan on running apps that use long filenames.
1154 win95 should work fine with apps that were designed
1155 to run under the msdos system. In other words, you
1156 might not want to use this.
1157 </para>
1158 </note>
1159 </para>
1160 </listitem>
1161 </varlistentry>
1162 </variablelist>
1165 <para>
1166 Needed for raw device access and <link linkend="config-drive-cdrom-labels">label and serial number reading</link>.
1168 Extended2 or other Unix file systems can have dire results
1169 (when a windows app tries to do a lowlevel write,
1170 they do it in a FAT way -- FAT format is completely different from
1171 any Unix file system).
1172 Also, make sure that you have proper permissions to this device
1173 file.
1174 </para>
1175 <note>
1176 <para>
1177 This setting is not really important; almost all apps
1178 will have no problem if it remains unspecified. For
1179 CD-ROMs it's quite useful in order to get automatic label
1180 detection, though. If you are unsure about specifying
1181 device names, just leave out this setting for your
1182 drives.
1183 </para>
1184 </note>
1185 <para>
1186 Here are a few sample entries:
1187 <programlisting>
1188 Here is a setup for Drive C, a generic hard drive:
1189 [Drive C]
1194 This is a setup for Drive E, a generic CD-ROM drive:
1195 [Drive E]
1201 And here is a setup for Drive A, a generic floppy drive:
1202 [Drive A]
1209 </programlisting>
1210 </para>
1211 </sect2>
1213 <sect2>
1215 <para>
1217 This tells Wine and Windows programs where the
1219 recommended to have this directory somewhere on your
1221 recommended to just call the directory "windows" (this is
1222 the default setup on Windows, and some stupid programs
1223 might rely on this). So in case you chose a "Windows"
1224 setting of "c:\\windows" and you chose to set up a drive C
1226 corresponding directory would be
1228 if you don't already have one. <emphasis>No trailing slash</emphasis> (<emphasis>not</emphasis>
1230 recommended, as Windows programs always assume write access
1231 to the Windows directory!
1232 </para>
1233 <para>
1235 This sets up where the windows system files are. The Windows
1236 system directory should reside below the directory used for the
1238 Thus when using the example above, the system directory would be
1240 Again, no trailing slash, and write access!
1241 </para>
1242 <para>
1244 be the directory you want your temp files stored in,
1245 /usr/local/wine_c/temp in our example.
1246 Again, no trailing slash, and <emphasis>write
1247 access</emphasis>!!
1248 </para>
1249 <para>
1252 boxes. When wine is run like <userinput>wine
1254 resides in a directory specified in the
1257 current directory, wine will run that one). Make sure it
1259 system directory (For this setup, it must have
1261 </para>
1264 Wine doesn't pass directory symlinks to Windows programs by
1265 default, as doing so may crash some programs that do
1266 recursive lookups of whole subdirectory trees
1267 whenever a directory symlink points back to itself or one of its
1268 parent directories.
1269 That's why we disallowed the use of directory symlinks
1270 and added this setting to reenable ("1") this functionality.
1272 account symlinked directories, then reenable it, but
1274 Windows programs when using the above method! (in other words:
1275 enabling it is certainly not recommended)
1276 </para>
1277 </sect2>
1279 <sect2>
1281 <para>
1282 Windows uses a different (and inferior) way than Unix to describe the
1283 location of files in a computer. Thus Windows programs also expect
1284 to find this different way supported by the system.
1285 Since we intend to run Windows programs on
1286 a Unix system, we're in trouble, as we need to translate
1287 between these different file access techniques.
1288 </para>
1289 <para>
1290 Windows uses drive letters to describe drives or
1291 any other form of storage media and to access files on them.
1292 For example, common drive names are
1295 first floppy drive.
1297 directory separator sign, whereas Unix uses
1299 Thus, an example document on the first data partition in
1300 Windows might be accessed by the name of
1302 </para>
1303 <para>
1304 So much for the Windows way of doing things.
1305 </para>
1306 <para>
1307 Well, the problem is, in Unix there is no such thing as
1309 much better way of having one single uniform directory tree
1310 (starting with the root directory
1312 such as e.g. harddisk partitions appended at various directory
1313 locations within the tree (an example would be
1315 partition mounted/attached to a directory called data1 in the
1317 directory of the data partition file system that's mounted
1319 In Unix, the Windows example document mentioned above could e.g.
1320 be accessed by the name of
1322 provided that the administrator decided to mount (attach) the first
1323 data partition at the directory /data1 inside the Unix
1324 directory tree. Note that in Unix, the administrator can
1328 suitable for the first data partition (here,
1330 change in partition order, Windows automatically
1332 suddenly find yourself with a first data partition at drive
1334 referencing confusion that entails. Thus, the Windows way of
1335 using ever-changing drive letters is <emphasis>clearly
1336 inferior</emphasis> to the Unix way of assigning
1338 data storage medium.
1339 As we'll see soon, fortunately this Windows limitation of
1340 changing drive letters doesn't affect us in Wine at all, since
1341 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).
1342 </para>
1343 <para>
1344 OK, now that we know some theory about Windows and Unix drive
1345 and filename mapping, it's probably time to ask how Wine
1346 achieves the magic of mapping a Unix directory location to a
1347 Windows drive...
1348 </para>
1349 <para>
1350 Wine chose to do the following:
1351 In Wine, you don't assign some real physical storage medium
1352 (such as a harddisk partition or similar) to each drive letter
1353 mapping entry.
1354 Instead, you choose certain sub directory trees inside the Unix
1356 you would like to assign a drive letter to.
1357 </para>
1358 <para>
1359 Note that for every Unix sub directory tree that you intend to
1360 start Windows programs in, it is <emphasis>absolutely
1361 required</emphasis> to have a Wine drive mapping entry:
1362 </para>
1363 <para>
1364 For example, if you had a publicly writable <quote>Windows
1366 able to access this sub directory tree from Wine, you should
1367 have a drive mapping entry that maps a certain drive letter
1369 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.
1370 </para>
1371 </sect2>
1376 <para>
1377 A major goal of Wine is to allow users to run Windows programs
1378 without having to install Windows on their machine. Wine
1379 implements the functionality of the main DLLs usually
1380 provided with Windows. Therefore, once Wine is finished, you
1381 will not need to have Windows installed to use Wine.
1382 </para>
1383 <para>
1384 Wine has already made enough progress that it may be possible
1385 to run your target programs without Windows installed. If
1386 you want to try it, follow these steps:
1387 </para>
1389 <orderedlist>
1390 <listitem>
1391 <para>
1395 for more information.
1396 The directory to be used for emulating a C: drive will be
1397 the base directory for some Windows specific directories
1398 created below.
1399 Remember to use
1401 </para>
1402 </listitem>
1403 <listitem>
1404 <para>
1405 Within the directory to be used for C:, create empty
1410 directories. Do not point Wine to a
1412 installations and a messy registry. (Wine creates a
1415 Perhaps you have to remove these files).
1416 In one line:
1417 mkdir -p windows windows/system windows/Start\ Menu windows/Start\ Menu/Programs
1418 </para>
1419 </listitem>
1420 <listitem>
1421 <para>
1422 Run and/or install your programs.
1423 </para>
1424 </listitem>
1425 </orderedlist>
1427 <para>
1428 Because Wine is not yet complete, some programs will work
1429 better with native Windows DLLs than with Wine's
1430 replacements. Wine has been designed to make this possible.
1431 Here are some tips by Juergen Schmied (and others) on how to
1432 proceed. This assumes that your
1434 file does not point to a native Windows installation but is in
1438 </para>
1440 <itemizedlist>
1441 <listitem>
1442 <para>
1443 Run the program with <parameter>--debugmsg
1444 +loaddll</parameter> to find out which files are
1445 needed. Copy the required DLLs one by one to the
1447 copy KERNEL/KERNEL32, GDI/GDI32, USER/USER32 or NTDLL. These
1448 implement the core functionality of the Windows API, and
1449 the Wine internal versions must be used.
1450 </para>
1451 </listitem>
1452 <listitem>
1453 <para>
1457 the Windows DLLs you want to use. For more information
1458 about this, see the Wine manpage.
1459 </para>
1460 </listitem>
1461 <listitem>
1462 <para>
1463 Note that some network DLLs are not needed even though
1464 Wine is looking for them. The Windows
1466 must use the internal implementation.
1467 </para>
1468 </listitem>
1469 <listitem>
1470 <para>
1471 Copy SHELL.DLL/SHELL32.DLL, COMMDLG.DLL/COMDLG32.DLL
1472 and COMMCTRL.DLL/COMCTL32.DLL
1473 only as pairs to your Wine directory (these DLLs are
1477 </para>
1478 </listitem>
1479 <listitem>
1480 <para>
1481 Be consistent: Use only DLLs from the same Windows version
1482 together.
1483 </para>
1484 </listitem>
1485 <listitem>
1486 <para>
1491 registry, don't know about
1493 As of now, it might not be necessary any more to use
1494 regedit.exe, since Wine has its own regedit Winelib
1495 application now.
1496 </para>
1497 </listitem>
1498 <listitem>
1499 <para>
1502 to browse through your programs' help function
1503 (or in case Wine's winhelp implementation in programs/winhelp/
1504 is not good enough, for example).
1505 </para>
1506 </listitem>
1507 </itemizedlist>
1508 </sect2>
1512 <para>
1513 Some people intend to use the data of an existing Windows partition
1514 with Wine in order to gain some better compatibility or to run already
1515 installed programs in a setup as original as possible.
1516 Note that many Windows programs assume that they have full write
1517 access to all windows directories.
1519 This means that you either have to configure the Windows
1520 partition mount point for write permission by your Wine user
1522 on how to do that), or you'll have to copy over (some parts of) the Windows
1523 partition content to a directory of a Unix partition and make
1524 sure this directory structure is writable by your user.
1526 write access as a base for Wine!! (some programs, notably
1527 Explorer, corrupt large parts of the Windows partition in case
1528 of an incorrect setup; you've been warned).
1529 Not to mention that NTFS write support in Linux is still very
1531 Windows version using the NTFS file system).
1532 Thus we advise you to go the Unix directory way.
1533 </para>
1534 </sect2>
1538 <para>
1539 This document describes how FAT and
1540 VFAT file system permissions work in Linux
1541 with a focus on configuring them for Wine.
1542 </para>
1544 <sect3>
1546 <para>
1547 Linux is able to access DOS and Windows file systems using
1548 either the FAT (older 8.3 DOS filesystems) or VFAT (newer
1549 Windows 95 or later long filename filesystems) modules.
1550 Mounted FAT or VFAT filesystems provide the primary means
1551 for which existing programs and their data are accessed
1552 through Wine for dual boot (Linux + Windows) systems.
1553 </para>
1554 <para>
1555 Wine maps mounted FAT filesystems, such as
1560 </para>
1561 <programlisting>
1562 [Drive C]
1565 </programlisting>
1566 <para>
1567 Although VFAT filesystems are preferable to FAT filesystems
1569 will be used throughout the remainder of this document to
1570 refer to FAT filesystems and their derivatives. Also,
1572 examples throughout this document.
1573 </para>
1574 <para>
1575 Most modern Linux distributions either detect or allow
1576 existing FAT file systems to be configured so that they can be
1578 either persistently (on bootup) or on an as needed basis. In
1579 either case, by default, the permissions will probably be
1580 configured so that they look like:
1581 </para>
1582 <screen>
1588 </screen>
1589 <para>
1591 group and are only writable by "root"
1593 that it requires that Wine be run as root in order for
1594 programs to be able to write to any part of the
1595 filesystem.
1596 </para>
1597 <para>
1598 There are three major approaches to overcoming the restrictive
1599 permissions mentioned in the previous paragraph:
1600 </para>
1601 <orderedlist>
1602 <listitem>
1603 <para>
1605 </para>
1606 </listitem>
1607 <listitem>
1608 <para>
1609 Mount the FAT filesystem with less restrictive
1610 permissions
1611 </para>
1612 </listitem>
1613 <listitem>
1614 <para>
1615 Shadow the FAT filesystem by completely or partially
1616 copying it
1617 </para>
1618 </listitem>
1619 </orderedlist>
1620 <para>
1621 Each approach will be discussed in the following sections.
1622 </para>
1623 </sect3>
1625 <sect3>
1627 <para>
1628 Running Wine as root is the easiest and most thorough way of giving
1629 programs that Wine runs unrestricted access to FAT files systems.
1630 Running wine as root also allows programs to do things unrelated
1631 to FAT filesystems, such as listening to ports that are less than
1632 1024. Running Wine as root is dangerous since there is no limit to
1634 </para>
1635 </sect3>
1637 <sect3>
1639 <para>
1640 The FAT filesystem can be mounted with permissions less restrictive
1641 than the default. This can be done by either changing the user that
1642 mounts the FAT filesystem or by explicitly changing the permissions
1643 that the FAT filesystem is mounted with. The permissions are
1644 inherited from the process that mounts the FAT filesystem. Since the
1645 process that mounts the FAT filesystem is usually a startup script
1646 running as root the FAT filesystem inherits root's permissions. This
1647 results in the files on the FAT filesystem having permissions similar
1648 to files created by root. For example:
1649 </para>
1650 <screen>
1656 </screen>
1657 <para>
1658 which matches the owner, group and permissions of files seen
1659 on the FAT filesystem except for the missing 'x's. The
1660 permissions on the FAT filesystem can be changed by changing
1661 root's umask (unset permissions bits). For example:
1662 </para>
1663 <screen>
1674 </screen>
1675 <para>
1676 Mounting the FAT filesystem with a umask of
1678 it. Explicitly specifying the permissions of the FAT
1679 filesystem when it is mounted provides additional control.
1680 There are three mount options that are relevant to FAT
1683 when the filesystem is manually mounted. For example:
1684 </para>
1685 <screen>
1693 </screen>
1694 <para>
1695 which gives "sle" complete control over
1697 made permanent by adding them to the
1699 </para>
1700 <screen>
1702 <computeroutput>/dev/hda1 /c vfat uid=500,gid=500,umask=002,exec,dev,suid,rw 1 1</computeroutput>
1703 </screen>
1704 <para>
1706 the user private group file permission scheme. On FAT file
1707 systems this umask assures that all files are fully
1708 accessible by all users in the specified user group
1710 </para>
1711 </sect3>
1713 <sect3>
1715 <para>
1716 Shadowing provides a finer granularity of control. Parts of
1717 the original FAT filesystem can be copied so that the
1718 program can safely work with those copied parts while
1719 the program continues to directly read the remaining
1720 parts. This is done with symbolic links. For example,
1721 consider a system where a program named
1725 read access to the entire FAT filesystem. On this system
1726 the FAT filesystem has default permissions which should not
1727 be changed for security reasons or can not be changed due to
1728 lack of root access. On this system a shadow directory
1729 might be set up in the following manner:
1730 </para>
1731 <screen>
1739 <prompt>/c_shadow></prompt><userinput>perl -p -i -e 's|/c$|/c_shadow|g' ~/.wine/config</userinput>
1740 </screen>
1741 <para>
1742 The above gives everyone complete read and write access to
1745 write access to all other directories.
1746 </para>
1747 </sect3>
1748 </sect2>
1753 <para>
1754 Until now, your only possibility of specifying drive volume
1755 labels and serial numbers was to set them manually in the wine
1756 configuration file. By now, wine can read them directly from the
1757 device as well. This may be useful for many Win 9x games or
1758 for setup programs distributed on CD-ROMs that check for
1759 volume label.
1760 </para>
1762 <sect3>
1767 <thead>
1768 <row>
1772 </row>
1773 </thead>
1774 <tbody>
1775 <row>
1779 </row>
1780 <row>
1784 </row>
1785 </tbody>
1786 </tgroup>
1787 </informaltable>
1789 </sect3>
1791 <sect3>
1793 <para>
1794 Reading labels and serial numbers just works automatically
1797 Note that the device has to exist and must be accessible by the user
1798 running Wine if you do this, though.
1799 </para>
1800 <para>
1801 If you don't want to read labels and serial numbers directly from
1802 the device, then you should give fixed
1805 these entries instead if no device is given. If they don't
1806 exist, then Wine will return default values (label
1809 </para>
1810 <para>
1813 but not for reading the volume info from the device (i.e. you want
1816 to skip the volume reading.
1817 </para>
1818 </sect3>
1820 <sect3>
1822 <para>
1823 Here's a simple example of CD-ROM and floppy; labels will be
1824 read from the device on both CD-ROM and floppy; serial
1825 numbers on floppy only:
1826 </para>
1827 <programlisting>
1828 [Drive A]
1834 [Drive R]
1839 </programlisting>
1840 <para>
1841 Here's an example of overriding the CD-ROM label:
1842 </para>
1843 <programlisting>
1844 [Drive J]
1848 ; note that the device isn't really needed here as we have a fixed label
1851 </programlisting>
1852 </sect3>
1854 <sect3>
1856 <itemizedlist>
1857 <listitem> <para>
1858 The CD-ROM label can be read only if the data track of
1859 the disk resides in the first track and the cdrom is
1860 iso9660.
1861 </para> </listitem>
1862 <listitem> <para>
1863 Better checking for FAT superblock (it now checks only
1864 one byte). </para>
1865 </listitem>
1866 <listitem> <para>
1867 Support for labels/serial nums WRITING.
1868 </para> </listitem>
1869 <listitem> <para>
1871 chars).
1872 </para> </listitem>
1873 <listitem> <para>
1874 What about reading ext2 volume label? ....
1875 </para> </listitem>
1876 </itemizedlist>
1877 </sect3>
1878 </sect2>
1879 </sect1>
1881 ®istry;
1886 <sect2>
1888 <para>
1889 If your programs don't work as expected, then it's often because one
1890 DLL or another is failing. This can often be resolved by changing
1891 certain DLLs from Wine built-in to native Windows DLL file and vice
1892 versa.
1893 </para>
1894 <para>
1895 A very useful help to find out which DLLs are loaded as built-in and
1896 which are loaded as native Windows file can be the debug channel
1897 loaddll, activated via the Wine command line parameter
1899 </para>
1900 </sect2>
1902 <sect2>
1903 <!-- FIXME intro!!! -->
1905 <para>
1906 There are a few things you will need to know before
1907 configuring the DLL sections in your wine configuration
1908 file.
1909 </para>
1910 <sect3>
1912 <para>
1913 Most windows DLL's have a win16 (Windows 3.x) and win32
1914 (Windows 9x/NT) form. The combination of the win16 and
1915 win32 DLL versions are called the "DLL pair". This is a
1916 list of the most common pairs:
1917 </para>
1919 <informaltable>
1921 <thead>
1922 <row>
1925 <entry>
1926 Native
1927 <footnote>
1928 <para>
1929 Is it possible to use native DLL with wine?
1930 (See next section)
1931 </para>
1932 </footnote>
1933 </entry>
1934 </row>
1935 </thead>
1936 <tbody>
1937 <row>
1941 </row>
1942 <row>
1946 </row>
1947 <row>
1951 </row>
1952 <row>
1956 </row>
1957 <row>
1961 </row>
1962 <row>
1966 </row>
1967 </tbody>
1968 </tgroup>
1969 </informaltable>
1970 </sect3>
1972 <sect3>
1974 <para>
1975 There are a few different forms of DLL's wine can load:
1976 <variablelist>
1977 <varlistentry>
1979 <listitem><para>
1980 The DLL's that are included with windows. Many
1981 windows DLL's can be loaded in their native
1982 form. Many times these native versions work
1983 better than their non-Microsoft equivalent --
1984 other times they don't.
1985 </para></listitem>
1986 </varlistentry>
1987 <varlistentry>
1989 <listitem><para>
1990 The most common form of DLL loading. This is
1991 what you will use if the DLL is too system-specific
1992 or error-prone in native form (KERNEL for example),
1993 you don't have the native DLL, or you just want to be
1994 Microsoft-free.
1995 </para></listitem>
1996 </varlistentry>
1997 <varlistentry>
1999 <listitem><para>
2000 Native ELF libraries. Has been deprecated, ignored.
2001 </para></listitem>
2002 </varlistentry>
2003 <varlistentry>
2005 <listitem><para>
2006 ELF encapsulated windows DLL's.
2007 No longer used, ignored.
2008 </para></listitem>
2009 </varlistentry>
2010 </variablelist>
2011 </para>
2012 </sect3>
2013 </sect2>
2018 <para>
2019 The wine configuration file directives [DllDefaults]
2020 and [DllOverrides] are the subject of some confusion. The
2021 overall purpose of most of these directives are clear enough,
2022 though - given a choice, should Wine use its own built-in
2024 in an existing Windows installation? This document explains
2025 how this feature works.
2026 </para>
2028 <sect3>
2030 <variablelist>
2031 <varlistentry>
2033 <listitem> <para>
2035 written for the real Microsoft Windows.
2036 </para> </listitem>
2037 </varlistentry>
2038 <varlistentry>
2040 <listitem> <para>
2041 A "built-in" DLL is a Wine DLL. These can either be a
2044 that Wine is able to load on demand.
2045 </para> </listitem>
2046 </varlistentry>
2047 </variablelist>
2048 </sect3>
2050 <sect3>
2052 <variablelist>
2053 <varlistentry>
2055 <listitem> <para>
2056 This specifies in what order Wine should search for
2057 available DLL types, if the DLL in question was not
2058 found in the [DllOverrides] section.
2059 </para> </listitem>
2060 </varlistentry>
2061 </variablelist>
2062 </sect3>
2064 <sect3>
2066 <para>
2067 At one time, there was a section called [DllPairs] in the
2068 default configuration file, but this has been obsoleted
2069 because the pairing information has now been embedded into
2070 Wine itself. (The purpose of this section was merely to be
2071 able to issue warnings if the user attempted to pair
2075 </para>
2076 </sect3>
2078 <sect3>
2080 <para>
2081 This section specifies how you want specific DLLs to be
2082 handled, in particular whether you want to use "native" DLLs
2083 or not, if you have some from a real Windows configuration.
2084 Because built-ins do not mix seamlessly with native DLLs yet,
2085 certain DLL dependencies may be problematic, but workarounds
2086 exist in Wine for many popular DLL configurations. Also see
2087 WWN's [16]Status Page to figure out how well your favorite
2088 DLL is implemented in Wine.
2089 </para>
2090 <para>
2091 It is of course also possible to override these settings by
2093 command-line option (see the man page for details). Some
2094 hints for choosing your optimal configuration (listed by
2096 </para>
2097 <variablelist>
2098 <varlistentry>
2100 <listitem> <para>
2101 Native versions of these will never work, so don't try. Leave
2103 </para> </listitem>
2104 </varlistentry>
2105 <varlistentry>
2107 <listitem> <para>
2108 Graphics Device Interface. No effort has been made at trying to
2110 </para> </listitem>
2111 </varlistentry>
2112 <varlistentry>
2114 <listitem> <para>
2115 Window management and standard controls. It was
2117 versions at some point (if all other DLLs that depend
2118 on it, such as comctl32 and comdlg32, were also run
2120 possible after the Address Space Separation, so leave
2122 </para> </listitem>
2123 </varlistentry>
2124 <varlistentry>
2126 <listitem> <para>
2127 NT kernel API. Although badly documented, the
2130 </para> </listitem>
2131 </varlistentry>
2132 <varlistentry>
2134 <listitem> <para>
2136 version will probably never work. Leave at
2138 </para> </listitem>
2139 </varlistentry>
2140 <varlistentry>
2142 <listitem> <para>
2143 Win16 support library for NT. The
2146 </para> </listitem>
2147 </varlistentry>
2148 <varlistentry>
2150 <listitem> <para>
2151 Win16 kernel stuff. Will never work
2154 </para> </listitem>
2155 </varlistentry>
2156 <varlistentry>
2158 <listitem> <para>
2160 </para> </listitem>
2161 </varlistentry>
2162 <varlistentry>
2164 <listitem> <para>
2165 Tool helper routines. This is rarely a source of problems.
2167 </para> </listitem>
2168 </varlistentry>
2169 <varlistentry>
2171 <listitem> <para>
2172 Versioning. Seldom useful to mess with.
2173 </para> </listitem>
2174 </varlistentry>
2175 <varlistentry>
2177 <listitem> <para>
2178 Registry and security features. Trying the
2180 not work.
2181 </para> </listitem>
2182 </varlistentry>
2183 <varlistentry>
2185 <listitem> <para>
2186 Common Dialogs, such as color picker, font dialog,
2187 print dialog, open/save dialog, etc. It is safe to try
2189 </para> </listitem>
2190 </varlistentry>
2191 <varlistentry>
2193 <listitem> <para>
2194 Common Controls. This is toolbars, status bars, list controls,
2196 </para> </listitem>
2197 </varlistentry>
2198 <varlistentry>
2200 <listitem> <para>
2201 Shell interface (desktop, filesystem, etc). Being one of the
2202 most undocumented pieces of Windows, you may have luck with the
2204 </para> </listitem>
2205 </varlistentry>
2206 <varlistentry>
2208 <listitem> <para>
2210 will not work under Wine, so leave at
2212 </para> </listitem>
2213 </varlistentry>
2214 <varlistentry>
2216 <listitem> <para>
2217 ICMP routines for wsock32. As with wsock32, leave at
2219 </para> </listitem>
2220 </varlistentry>
2221 <varlistentry>
2223 <listitem> <para>
2225 to thunking issues. Leave at
2227 </para> </listitem>
2228 </varlistentry>
2229 <varlistentry>
2231 <listitem> <para>
2232 Lempel-Ziv decompression. Wine's
2234 </para> </listitem>
2235 </varlistentry>
2236 <varlistentry>
2238 <listitem> <para>
2239 Advanced SCSI Peripheral Interface. The
2242 </para> </listitem>
2243 </varlistentry>
2244 <varlistentry>
2246 <listitem> <para>
2248 version will easily work better than Wine's on this
2249 one.
2250 </para> </listitem>
2251 </varlistentry>
2252 <varlistentry>
2254 <listitem> <para>
2255 Printer spooler. You are not likely to have more luck
2257 </para> </listitem>
2258 </varlistentry>
2259 <varlistentry>
2261 <listitem> <para>
2262 DirectDraw/Direct3D. Since Wine does not implement the
2264 will not work at this time.
2265 </para> </listitem>
2266 </varlistentry>
2267 <varlistentry>
2269 <listitem> <para>
2271 may or may not work.
2272 </para> </listitem>
2273 </varlistentry>
2274 <varlistentry>
2276 <listitem> <para>
2277 DirectSound. It may be possible to run this
2279 </para> </listitem>
2280 </varlistentry>
2281 <varlistentry>
2283 <listitem> <para>
2285 ought to work best on this, if at all.
2286 </para> </listitem>
2287 </varlistentry>
2288 <varlistentry>
2290 <listitem> <para>
2292 version is not likely to work. Leave at
2294 </para> </listitem>
2295 </varlistentry>
2296 <varlistentry>
2298 <listitem> <para>
2299 Audio Compression Manager. The
2301 set msacm.drv to the same.
2302 </para> </listitem>
2303 </varlistentry>
2304 <varlistentry>
2306 <listitem> <para>
2307 Video for Windows. It is safe (and recommended) to try
2309 </para> </listitem>
2310 </varlistentry>
2311 <varlistentry>
2313 <listitem> <para>
2314 CD Audio MCI driver.
2315 </para> </listitem>
2316 </varlistentry>
2317 <varlistentry>
2319 <listitem> <para>
2321 playback).
2322 </para> </listitem>
2323 </varlistentry>
2324 <varlistentry>
2326 <listitem> <para>
2328 </para> </listitem>
2329 </varlistentry>
2330 <varlistentry>
2332 <listitem> <para>
2335 </para> </listitem>
2336 </varlistentry>
2337 <varlistentry>
2339 <listitem> <para>
2340 Animation MCI driver.
2341 </para> </listitem>
2342 </varlistentry>
2343 <varlistentry>
2345 <listitem> <para>
2346 Audio Compression Manager. Set to same as msacm32.
2347 </para> </listitem>
2348 </varlistentry>
2349 <varlistentry>
2351 <listitem> <para>
2352 MIDI Mapper.
2353 </para> </listitem>
2354 </varlistentry>
2355 <varlistentry>
2357 <listitem> <para>
2358 This is a pseudo-DLL used by Wine for thunking
2360 doesn't exist.
2361 </para> </listitem>
2362 </varlistentry>
2363 </variablelist>
2364 </sect3>
2365 </sect2>
2369 <para>
2370 The Wine team has determined that it is necessary to create
2371 fake DLL files to trick many programs that check for
2372 file existence to determine whether a particular feature
2373 (such as Winsock and its TCP/IP networking) is available. If
2374 this is a problem for you, you can create empty files in the
2376 to make the program think it's there, and Wine's built-in DLL
2377 will be loaded when the program actually asks for it.
2379 not create such empty files itself.)
2380 </para>
2381 <para>
2382 Applications sometimes also try to inspect the version
2383 resources from the physical files (for example, to determine
2384 the DirectX version). Empty files will not do in this case,
2385 it is rather necessary to install files with complete
2386 version resources. This problem is currently being worked
2387 on. In the meantime, you may still need to grab some real
2388 DLL files to fool these apps with.
2389 </para>
2390 <para>
2391 And there are of course DLLs that wine does not currently
2392 implement very well (or at all). If you do not have a real
2393 Windows you can steal necessary DLLs from, you can always
2394 get some from one of the Windows DLL archive sites
2395 that can be found via internet search engine.
2396 Please make sure to obey any licenses on the DLLs you fetch...
2397 (some are redistributable, some aren't).
2398 </para>
2399 </sect2>
2404 <para>
2405 In case Wine complains about a missing DLL, you should check whether
2406 this file is a publicly available DLL or a custom DLL belonging
2407 to your program (by searching for its name on the internet).
2408 If you managed to get hold of the DLL, then you should make sure
2409 that Wine is able to find and load it.
2410 DLLs usually get loaded according to the mechanism of the
2411 SearchPath() function.
2412 This function searches directories in the following order:
2414 <orderedlist>
2415 <listitem>
2416 <para>
2417 The directory the program was started from.
2418 </para>
2419 </listitem>
2420 <listitem>
2421 <para>
2422 The current directory.
2423 </para>
2424 </listitem>
2425 <listitem>
2426 <para>
2427 The Windows system directory.
2428 </para>
2429 </listitem>
2430 <listitem>
2431 <para>
2432 The Windows directory.
2433 </para>
2434 </listitem>
2435 <listitem>
2436 <para>
2437 The PATH variable directories.
2438 </para>
2439 </listitem>
2440 </orderedlist>
2442 In short: either put the required DLL into your program
2443 directory (might be ugly), or usually put it into the Windows system
2444 directory. Just find out its directory by having a look at the Wine
2445 configuration file variable "System" (which indicates the location of the
2446 Windows system directory) and the associated drive entry.
2447 Note that you probably shouldn't use NT-based native DLLs,
2448 since Wine's NT API support is somewhat weaker than its Win9x
2449 API support (thus leading to even worse compatibility with NT DLLs
2450 than with a no-windows setup!), so better use Win9x native DLLs
2451 instead or no native DLLs at all.
2452 </para>
2453 </sect2>
2458 <para>
2460 extract native Windows .dll files from .cab files that are to be
2461 found on many Windows installation CDs.
2462 </para>
2463 </sect2>
2464 </sect1>
2469 <para>
2470 Wine currently supports several different display subsystems
2471 (graphics / text) that are available on various operating
2472 systems today.
2473 For each of these, Wine implements its own interfacing driver.
2474 This section explains how to select one of these drivers
2475 and how to further configure the respective driver.
2476 Once you're finished with that, you can consider your Wine installation
2477 to be finished.
2478 </para>
2480 <para>
2481 The display drivers currently implemented in Wine are:
2482 x11drv, which is used for interfacing to X11 graphics
2483 (the one you'll most likely want to use) and ttydrv
2484 (used for text mode console apps mainly that don't really need
2485 any graphics output).
2486 Once you have decided which display driver to use, it is chosen
2489 </para>
2491 <sect2>
2494 <sect3>
2497 <para>
2498 The x11drv driver consists of two conceptually distinct
2499 pieces, the graphics driver (GDI part), and the windowing
2500 driver (USER part). Both of these are linked into the
2503 Wine, running on X11, the graphics driver must draw on
2504 drawables (window interiors) provided by the windowing
2505 driver. This differs a bit from the Windows model, where the
2506 windowing system creates and configures device contexts
2507 controlled by the graphics driver, and programs are
2508 allowed to hook into this relationship anywhere they like.
2509 Thus, to provide any reasonable tradeoff between
2510 compatibility and usability, the x11drv has three different
2511 modes of operation.
2512 </para>
2514 <variablelist>
2515 <varlistentry>
2517 <listitem>
2518 <para>
2520 wine configuration file option (see below).
2521 Ordinary top-level frame windows with thick borders,
2522 title bars, and system menus will be managed by your
2523 window manager. This lets these programs integrate
2524 better with the rest of your desktop, but may not
2525 always work perfectly (a rewrite of this mode of
2526 operation, to make it more robust and less patchy, is
2527 currently being done, though, and it's planned to be
2528 finished before the Wine 1.0 release).
2529 </para>
2530 </listitem>
2531 </varlistentry>
2532 <varlistentry>
2534 <listitem>
2535 <para>
2536 Window manager independent (any running
2537 window manager is ignored completely). Window
2538 decorations (title bars, borders, etc) are drawn by
2539 Wine to look and feel like the real Windows. This is
2540 compatible with programs that depend on being able
2541 to compute the exact sizes of any such decorations, or
2542 that want to draw their own.
2543 Unmanaged mode is only used if both Managed and Desktop
2544 are set to disabled.
2545 </para>
2546 </listitem>
2547 </varlistentry>
2548 <varlistentry>
2550 <listitem>
2551 <para>
2553 wine configuration file option (see below).
2555 for a such-sized desktop, or
2557 automatically position the desktop at the upper-left
2558 corner of the display). This is the mode most
2559 compatible with the Windows model. All program
2560 windows will just be Wine-drawn windows inside the
2561 Wine-provided desktop window (which will itself be
2562 managed by your window manager), and Windows
2563 programs can roam freely within this virtual
2564 workspace and think they own it all, without
2565 disturbing your other X apps.
2566 Note: currently there's one desktop window for every
2567 program; this will be fixed at some time.
2568 </para>
2569 </listitem>
2570 </varlistentry>
2571 </variablelist>
2572 </sect3>
2574 <sect3>
2577 <variablelist>
2578 <varlistentry>
2580 <listitem>
2581 <para>
2582 Wine can let frame windows be managed by your window
2583 manager. This option specifies whether you want that
2584 by default.
2585 </para>
2586 </listitem>
2587 </varlistentry>
2588 <varlistentry>
2590 <listitem>
2591 <para>
2592 Creates a main desktop window of a specified size
2593 to display all Windows programs in.
2594 The size argument could e.g. be "800x600".
2595 </para>
2596 </listitem>
2597 </varlistentry>
2598 <varlistentry>
2600 <listitem>
2601 <para>
2602 If you don't use DGA, you may want an alternative
2603 means to convince the mouse cursor to stay within the
2604 game window. This option does that. Of course, as with
2605 DGA, if Wine crashes, you're in trouble (although not
2606 as badly as in the DGA case, since you can still use
2607 the keyboard to get out of X).
2608 </para>
2609 </listitem>
2610 </varlistentry>
2611 <varlistentry>
2613 <listitem>
2614 <para>
2615 This specifies whether you want DirectDraw to use
2616 XFree86's <firstterm>Direct Graphics
2617 Architecture</firstterm> (DGA), which is able to
2618 take over the entire display and run the game
2619 full-screen at maximum speed. (With DGA1 (XFree86
2620 3.x), you still have to configure the X server to the
2621 game's requested bpp first, but with DGA2 (XFree86
2622 4.x), runtime depth-switching may be possible,
2623 depending on your driver's capabilities.) But be aware
2624 that if Wine crashes while in DGA mode, it may not be
2625 possible to regain control over your computer without
2626 rebooting. DGA normally requires either root
2627 privileges or read/write access to
2629 </para>
2630 </listitem>
2631 </varlistentry>
2632 <varlistentry>
2634 <listitem>
2635 <para>
2636 Applies only if you use the
2638 to run in a desktop window. Specifies whether to
2639 create the desktop window with a double-buffered
2640 visual, something most OpenGL games need to run
2641 correctly.
2642 </para>
2643 </listitem>
2644 </varlistentry>
2645 <varlistentry>
2647 <listitem>
2648 <para>
2649 Applies only if you have a palette-based display, i.e.
2650 if your X server is set to a depth of 8bpp, and if you
2651 haven't requested a private color map. It specifies
2652 the maximum number of shared colormap cells (palette
2653 entries) Wine should occupy. The higher this value,
2654 the less colors will be available to other
2655 programs.
2656 </para>
2657 </listitem>
2658 </varlistentry>
2659 <varlistentry>
2661 <listitem>
2662 <para>
2663 Applies only if you have a palette-based display, i.e.
2664 if your X server is set to a depth of 8bpp. It
2665 specifies that you don't want to use the shared color
2666 map, but a private color map, where all 256 colors are
2667 available. The disadvantage is that Wine's private
2668 color map is only seen while the mouse pointer is
2669 inside a Wine window, so psychedelic flashing and
2670 funky colors will become routine if you use the mouse
2671 a lot.
2672 </para>
2673 </listitem>
2674 </varlistentry>
2675 <varlistentry>
2677 <listitem>
2678 <para>
2679 To be used for debugging X11 operations.
2680 If Wine crashes with an X11 error, then you should enable
2681 Synchronous mode to disable X11 request caching in order
2682 to make sure that the X11 error happens directly after
2683 the corresponding X11 call in the log file appears.
2684 Will slow down X11 output!
2685 </para>
2686 </listitem>
2687 </varlistentry>
2688 <varlistentry>
2690 <listitem>
2691 <para>
2692 Applies only to multi-depth displays. It specifies
2693 which of the available depths Wine should use (and
2694 tell Windows apps about).
2695 </para>
2696 </listitem>
2697 </varlistentry>
2698 <varlistentry>
2700 <listitem>
2701 <para>
2702 This specifies which X11 display to use, and if
2703 specified, will override the
2705 </para>
2706 </listitem>
2707 </varlistentry>
2708 <varlistentry>
2710 <listitem>
2711 <para>
2712 This option only determines whether fast X11 routines
2713 or exact Wine routines will be used for certain ROP
2714 codes in blit operations. Most users won't notice any
2715 difference.
2716 </para>
2717 </listitem>
2718 </varlistentry>
2719 </variablelist>
2720 </sect3>
2721 </sect2>
2723 <sect2>
2725 <para>
2726 Currently, the ttydrv doesn't have any special configuration
2727 options to set in the configuration file.
2728 </para>
2729 </sect2>
2731 </sect1>
2737 <para>
2738 The windows and DOS version value a program gets e.g. by calling the
2739 Windows function GetVersion() plays a very important role:
2740 If your Wine installation for whatever reason fails to provide
2741 to your program the correct version value that it expects,
2742 then the program might assume some very bad things and fail (in
2743 the worst case even silently!).
2745 Fortunately Wine contains some more or less intelligent Windows
2746 version guessing algorithm that will try to guess the Windows
2747 version a program might expect and pass that one on to the
2748 program.
2750 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.
2751 </para>
2753 <sect2>
2754 <title>How to configure the Windows and DOS version value Wine
2755 should return</title>
2757 <para>
2758 The version values can be configured in the wine configuration file in
2759 the [Version] section.
2760 </para>
2762 <variablelist>
2763 <varlistentry>
2765 <listitem>
2766 <para>
2767 default: none; chosen by semi-intelligent detection
2768 mechanism based on DLL environment.
2769 Used to specify which Windows version to return to
2770 programs (forced value, overrides standard detection
2773 Also valid as an
2775 setting (recommended/preferred use).
2776 </para>
2777 </listitem>
2778 </varlistentry>
2779 <varlistentry>
2781 <listitem>
2782 <para>
2783 Used to specify the DOS version that should be returned
2784 to programs. Only takes effect in case Wine acts as
2785 "win31" Windows version! Common DOS version settings
2787 Also valid as an
2789 setting (recommended/preferred use).
2790 </para>
2791 </listitem>
2792 </varlistentry>
2793 </variablelist>
2794 </sect2>
2795 </sect1>
2797 &fonts;
2798 &printing;
2802 <para>
2803 Instead of compiling Wine for Win3.1 vs. Win95 using
2805 special [Tweak.Layout] section of
2809 </para>
2810 <para>
2811 A few new sections and a number of entries have been added to
2813 debugging the Win95 tweaks only and may be removed in a future
2814 release! These entries/sections are:
2815 </para>
2816 <programlisting>
2817 [Tweak.Fonts]
2823 "OEMFixed.xxx" # Same parameters for the OEM fixed typeface
2824 "AnsiFixed.xxx" # Same parameters for the Ansi fixed typeface
2825 "AnsiVar.xxx" # Same parameters for the Ansi variable typeface
2826 "SystemFixed.xxx" # Same parameters for the System fixed typeface
2828 [Tweak.Layout]
2830 </programlisting>
2831 </sect1>
2836 <para>
2837 Wine now needs to know about your keyboard layout. This
2838 requirement comes from a need from many apps to have the
2839 correct scancodes available, since they read these directly,
2840 instead of just taking the characters returned by the X
2841 server. This means that Wine now needs to have a mapping from
2842 X keys to the scancodes these programs expect.
2843 </para>
2844 <para>
2845 On startup, Wine will try to recognize the active X layout by
2846 seeing if it matches any of the defined tables. If it does,
2847 everything is alright. If not, you need to define it.
2848 </para>
2849 <para>
2850 To do this, open the file
2852 at the existing tables. Make a backup copy of it, especially
2853 if you don't use CVS.
2854 </para>
2855 <para>
2856 What you really would need to do, is find out which scancode
2857 each key needs to generate. Find it in the
2859 this:
2860 </para>
2861 <programlisting>
2862 static const int main_key_scan[MAIN_LEN] =
2863 {
2864 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
2870 };
2871 </programlisting>
2872 <para>
2873 Next, assign each scancode the characters imprinted on the
2874 keycaps. This was done (sort of) for the US 101-key keyboard,
2875 which you can find near the top in
2877 is no 102nd key, you can skip that.
2878 </para>
2879 <para>
2880 However, for most international 102-key keyboards, we have
2881 done it easy for you. The scancode layout for these already
2882 pretty much matches the physical layout in the
2884 to go through all the keys that generate characters on your
2885 main keyboard (except spacebar), and stuff those into an
2886 appropriate table. The only exception is that the 102nd key,
2887 which is usually to the left of the first key of the last line
2889 line after the last line.
2890 </para>
2891 <para>
2892 For example, my Norwegian keyboard looks like this
2893 </para>
2894 <screen>
2895 § ! " # ¤ % & / ( ) = ? ` Back-
2896 | 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
2898 Tab Q W E R T Y U I O P Å ^
2899 ¨~
2900 Enter
2901 Caps A S D F G H J K L Ø Æ *
2902 Lock '
2904 Sh- > Z X C V B N M ; : _ Shift
2905 ift < , . -
2907 Ctrl Alt Spacebar AltGr Ctrl
2908 </screen>
2909 <para>
2910 Note the 102nd key, which is the <keycap><></keycap> key, to
2911 the left of <keycap>Z</keycap>. The character to the right of
2912 the main character is the character generated by
2913 <keycap>AltGr</keycap>.
2914 </para>
2915 <para>
2916 This keyboard is defined as follows:
2917 </para>
2918 <programlisting>
2919 static const char main_key_NO[MAIN_LEN][4] =
2920 {
2925 "<>"
2926 };
2927 </programlisting>
2928 <para>
2929 Except that " and \ needs to be quoted with a backslash, and
2930 that the 102nd key is on a separate line, it's pretty
2931 straightforward.
2932 </para>
2933 <para>
2934 After you have written such a table, you need to add it to the
2935 <function>main_key_tab[]</function> layout index table. This
2936 will look like this:
2937 </para>
2938 <programlisting>
2939 static struct {
2940 WORD lang, ansi_codepage, oem_codepage;
2941 const char (*key)[MAIN_LEN][4];
2942 } main_key_tab[]={
2943 ...
2944 ...
2945 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
2946 ...
2947 </programlisting>
2948 <para>
2949 After you have added your table, recompile Wine and test that
2950 it works. If it fails to detect your table, try running
2951 </para>
2952 <screen>
2953 wine --debugmsg +key,+keyboard >& key.log
2954 </screen>
2955 <para>
2956 and look in the resulting <filename>key.log</filename> file to
2957 find the error messages it gives for your layout.
2958 </para>
2959 <para>
2960 Note that the <constant>LANG_*</constant> and
2961 <constant>SUBLANG_*</constant> definitions are in
2962 <filename>include/winnls.h</filename>, which you might need to
2963 know to find out which numbers your language is assigned, and
2964 find it in the debugmsg output. The numbers will be
2965 <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
2966 the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
2967 <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
2968 <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
2969 could look for <literal>0414</literal> in the debugmsg output
2970 to find out why my keyboard won't detect.
2971 </para>
2972 <para>
2973 Once it works, submit it to the Wine project. If you use CVS,
2974 you will just have to do
2975 </para>
2976 <screen>
2977 cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
2978 </screen>
2979 <para>
2980 from your main Wine directory, then submit
2981 <filename>layout.diff</filename> to
2982 <email>wine-patches@winehq.org</email> along with a brief note
2983 of what it is.
2984 </para>
2985 <para>
2986 If you don't use CVS, you need to do
2987 </para>
2988 <screen>
2989 diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
2990 </screen>
2991 <para>
2992 and submit it as explained above.
2993 </para>
2994 <para>
2995 If you did it right, it will be included in the next Wine
2996 release, and all the troublesome programs (especially
2997 remote-control programs) and games that use scancodes will
2998 be happily using your keyboard layout, and you won't get those
2999 annoying fixme messages either.
3000 </para>
3001 <para>
3002 Good luck.
3003 </para>
3004 </sect1>
3007 <title>SCSI Support</title>
3008 <para>
3009 This file describes setting up the Windows ASPI interface.
3010 </para>
3012 <para>
3013 <warning><title>Warning/Warning/Warning!!!!!!</title>
3014 <para>This may trash your system if used incorrectly. It may
3015 even trash your system when used <emphasis>correctly</>!
3016 </para>
3017 </warning>
3018 </para>
3020 <para>
3021 Now that I have said that. ASPI is a direct link to SCSI devices from
3022 windows programs. ASPI just forwards the SCSI commands that programs send
3023 to it to the SCSI bus.
3024 </para>
3025 <para>
3026 If you use the wrong SCSI device in your setup file, you can send
3027 completely bogus commands to the wrong device - An example would be
3028 formatting your hard drives (assuming the device gave you permission -
3029 if you're running as root, all bets are off).
3030 </para>
3031 <para>
3032 So please make sure that <emphasis>all</emphasis> SCSI devices not needed by the program
3033 have their permissions set as restricted as possible!
3034 </para>
3036 <para>
3037 Cookbook for setting up scanner: (At least how mine is to work)
3038 (well, for other devices such as CD burners, MO drives, ..., too)
3039 </para>
3041 <sect2>
3042 <title>Windows requirements</title>
3043 <orderedlist>
3044 <listitem>
3045 <para>
3047 compatible drivers (ASPI). At least with Mustek, they
3048 allow you the choice of using the built-in card or the
3050 any other way. Software that accesses the scanner via a
3051 DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM]
3052 </para>
3053 </listitem>
3054 <listitem>
3055 <para>
3056 You probably need a real windows install of the software
3057 to set the LUN's/SCSI id's up correctly. I'm not exactly
3058 sure.
3059 </para>
3060 </listitem>
3061 </orderedlist>
3062 </sect2>
3064 <sect2>
3065 <title>Linux requirements</title>
3066 <orderedlist>
3067 <listitem>
3068 <para>
3069 Your SCSI card must be supported under Linux. This will
3070 not work with an unknown SCSI card. Even for cheap'n
3072 drivers exist on the net.
3073 If you intend to use your IDE device, you need to use the
3074 ide-scsi emulation.
3075 Read
3077 http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html</ulink>
3078 for ide-scsi setup instructions.
3079 </para>
3080 </listitem>
3081 <listitem>
3082 <para>
3083 Compile generic SCSI drivers into your kernel.
3084 </para>
3085 </listitem>
3086 <listitem>
3087 <para>
3088 This seems to be not required any more for newer (2.2.x) kernels:
3089 Linux by default uses smaller SCSI buffers than Windows.
3090 There is a kernel build define <literal>SG_BIG_BUFF</literal> (in
3091 <filename>sg.h</filename>) that is by default set too
3092 low. The SANE project recommends
3093 <literal>130560</literal> and this seems to work just
3094 fine. This does require a kernel rebuild.
3095 </para>
3096 </listitem>
3097 <listitem>
3098 <para>
3099 Make the devices for the scanner (generic SCSI devices)
3100 - look at the SCSI programming HOWTO at
3102 http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html</ulink>
3103 for device numbering.
3104 </para>
3105 </listitem>
3106 <listitem>
3107 <para>
3108 I would recommend making the scanner device writable by
3109 a group. I made a group called
3110 <literal>scanner</literal> and added myself to it.
3111 Running as root increases your risk of sending bad SCSI
3112 commands to the wrong device. With a regular user, you
3113 are better protected.
3114 </para>
3115 </listitem>
3116 <listitem>
3117 <para>
3118 For Win32 software (WNASPI32), Wine has auto-detection in place.
3119 For Win16 software (WINASPI), you need to add a SCSI device entry
3120 for your particular scanner to ~/.wine/config. The format is
3121 <literal>[scsi cCtTdD]</literal> where
3124 </para>
3125 <para>
3126 For example, I set mine up as controller <literal>0</literal>,
3127 Target <literal>6</literal>, LUN <literal>0</literal>.
3128 <programlisting>
3129 [scsi c0t6d0]
3131 </programlisting>
3132 Yours will vary with your particular SCSI setup.
3133 </para>
3134 </listitem>
3135 </orderedlist>
3136 </sect2>
3138 <sect2>
3139 <title>General Information</title>
3140 <para>
3141 The mustek scanner I have was shipped with a package
3143 to access scanners.
3144 </para>
3145 <para>
3146 (TWAIN MANAGER)
3147 </para>
3148 <para>
3149 <programlisting>
3150 ipplus.exe <-> (TWAIN INTERFACE) <-> (TWAIN DATA SOURCE.ASPI) -> WINASPI
3151 </programlisting>
3152 </para>
3153 </sect2>
3155 <sect2>
3156 <title>NOTES/BUGS</title>
3157 <para>
3158 The biggest drawback is that it only works under Linux at the moment.
3159 </para>
3160 <para>
3161 The ASPI code has only been tested with:
3162 </para>
3163 <itemizedlist>
3164 <listitem>
3165 <para>
3166 a Mustek 800SP with a Buslogic controller under Linux [BM]
3167 </para>
3168 </listitem>
3169 <listitem>
3170 <para>
3171 a Siemens Nixdorf 9036 with Adaptec AVA-1505 under Linux
3172 accessed via DOSASPI. Note that I had color problems,
3173 though (barely readable result) [AM]
3174 </para>
3175 </listitem>
3176 <listitem>
3177 <para>
3178 a Fujitsu M2513A MO drive (640MB) using generic SCSI
3179 drivers. Formatting and ejecting worked perfectly.
3180 Thanks to Uwe Bonnes for access to the hardware! [AM]
3181 </para>
3182 </listitem>
3183 </itemizedlist>
3184 <para>
3185 I make no warranty to the ASPI code. It makes my scanner
3186 work. Your devices may explode. I have no way of determining
3187 this. I take zero responsibility!
3188 </para>
3189 </sect2>
3190 </sect1>
3193 <title>Using ODBC</title>
3194 <para>
3195 This section describes how ODBC works within Wine and how to configure
3196 it to do what you want (if it can do what you want).
3197 </para>
3198 <para>
3199 The ODBC system within Wine, as with the printing system, is designed
3200 to hook across to the Unix system at a high level. Rather than
3201 ensuring that all the windows code works under wine it uses a suitable
3202 Unix ODBC provider, such as UnixODBC. Thus if you configure Wine to
3203 use the built-in odbc32.dll, that Wine DLL will interface to your
3204 Unix ODBC package and let that do the work, whereas if you configure
3205 Wine to use the native odbc32.dll it will try to use the native
3206 ODBC32 drivers etc.
3207 </para>
3208 <sect2>
3209 <title>Using a Unix ODBC system with Wine</title>
3210 <para>
3211 The first step in using a Unix ODBC system with Wine is, of course,
3212 to get the Unix ODBC system working itself. This may involve
3213 downloading code or RPMs etc. There are several Unix ODBC systems
3214 available; the one the author is used to is unixODBC (with the
3215 IBM DB2 driver). Typically such systems will include a tool, such
3216 as <command>isql</command>, which will allow you to access the data from the command
3217 line so that you can check that the system is working.
3218 </para>
3219 <para>
3220 The next step is to hook the Unix ODBC library to the wine built-in
3221 odbc32 DLL. The built-in odbc32 (currently) looks to the
3222 environment variable <emphasis>LIB_ODBC_DRIVER_MANAGER</emphasis>
3223 for the name of the ODBC library. For example in the author's
3224 .bashrc file is the line:
3225 </para>
3226 <programlisting>
3227 export LIB_ODBC_DRIVER_MANAGER=/usr/lib/libodbc.so.1.0.0
3228 </programlisting>
3229 <para>
3230 If that environment variable is not set then it looks for a
3231 library called libodbc.so and so you can add a symbolic link to
3232 equate that to your own library. For example as root you could
3233 run the commands:
3234 </para>
3235 <screen>
3236 <prompt># </prompt><userinput>ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so</userinput>
3237 <prompt># </prompt><userinput>/sbin/ldconfig</userinput>
3238 </screen>
3239 <para>
3240 The last step in configuring this is to ensure that Wine is set up
3241 to run the built-in version of odbc32.dll, by modifying the DLL
3242 configuration. This built-in DLL merely acts as a stub between the
3243 calling code and the Unix ODBC library.
3244 </para>
3245 <para>
3246 If you have any problems then you can use the debugmsg channel
3247 odbc32 to trace what is happening. One word of warning. Some
3248 programs actually cheat a little and bypass the ODBC library. For
3249 example the Crystal Reports engine goes to the registry to check on
3250 the DSN. The fix for this is documented at unixODBC's site where
3251 there is a section on using unixODBC with Wine.
3252 </para>
3253 </sect2>
3254 <sect2>
3255 <title>Using Windows ODBC drivers</title>
3256 <para>
3257 Does anyone actually have any experience of this and anything to
3258 add?
3259 </para>
3260 </sect2>
3261 </sect1>
3263 </chapter>
3265 <!-- Keep this comment at the end of the file
3266 Local variables:
3267 mode: sgml
3269 End:
3270 -->