| blob | fb85f4356994b772631d57d5be45e76041809c3d |
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.
107 </para>
108 <para>
109 If you're using Debian, simply install the winesetuptk
110 package (as root):
111 </para>
112 <screen>
114 </screen>
115 <para>
116 If you're using another distribution, search for the package on
117 the net.
118 </para>
119 </sect2>
123 <para>
126 source code tree. It has been written to allow for an easy
127 and complete compilation/installation of Wine source code for
128 people who don't bother with reading heaps of very valuable
129 and informative documentation ;-)
130 </para>
131 <para>
132 Once you have successfully extracted the Wine source code
133 tree, change to the main directory of it and then run (as
134 user):
135 </para>
136 <screen>
138 </screen>
139 <para>
140 Doing so will compile Wine, install Wine and configure the
141 Wine environment (either by providing access to a Windows
142 partition or by creating a properly configured no-windows
143 directory environment).
144 </para>
145 </sect2>
149 <para>
152 source code tree. It is a Winelib app making use of standard
153 Win32 GUI controls to easily customize entries in a Wine
154 configuration file.
155 </para>
156 </sect2>
157 </sect1>
162 <para>
163 After you finished configuring Wine, you may run a Perl
165 in Wine's tools/ directory. It tries to check your
166 configuration's correctness by checking for some popular
167 problems.
169 The latest version can always be found at
170 <ulink url="http://home.arcor.de/andi.mohr/download/winecheck">http://home.arcor.de/andi.mohr/download/winecheck</ulink>.
173 </para>
174 <screen>
177 </screen>
178 <para>
179 The winecheck output will be a percentage score indicating Wine
180 configuration correctness.
181 Note that winecheck is only alpha, so it's not very complete or
182 100% accurate.
183 </para>
185 <para>
186 If this yields a "good" percentage score, then you can consider
187 your Wine installation to be finished successfully:
188 Congratulations!
189 Otherwise (or if there are still some configuration problems
191 configuration documentation below to find out more about some
193 chapter</link>.
194 </para>
195 </sect1>
199 <para>
200 This section is meant to contain both an easy step-by-step introduction
201 to the Wine configuration file (for new Wine users)
202 and a complete reference to all Wine configuration file settings (for
203 advanced users).
204 </para>
206 <sect2>
208 <para>
209 The Wine configuration file is the central file to store
210 configuration settings for Wine.
213 of your user's home directory
216 Note that since the Wine configuration file is a part of the
217 Wine registry file system, this file also
219 Version 2" header line to be recognized properly, just like
220 all other Wine registry text files (just in case you decided
221 to write your own registry file from scratch and wonder why
222 Wine keeps rejecting it).
223 </para>
224 <para>
225 The settings available in the configuration file include:
226 <itemizedlist>
227 <listitem>
228 <para>
229 Drives and information about them
230 </para>
231 </listitem>
232 <listitem>
233 <para>
234 Directory settings
235 </para>
236 </listitem>
237 <listitem>
238 <para>
239 Port settings
240 </para>
241 </listitem>
242 <listitem>
243 <para>
244 The Wine look and feel
245 </para>
246 </listitem>
247 <listitem>
248 <para>
249 Wine's DLL usage
250 </para>
251 </listitem>
252 <listitem>
253 <para>
254 Wine's multimedia drivers and DLL configuration
255 </para>
256 </listitem>
257 </itemizedlist>
258 </para>
259 </sect2>
261 <sect2>
263 <para>
264 If you just installed Wine for the first time and want to
265 finish Wine installation by configuring it now, then you could
267 (which can be found in the directory
269 code directory) as a base for adapting the Wine configuration
270 file to the settings you want.
271 First, I should mention that you should not forget to make
272 sure that any previous configuration file at
274 of the way instead of simply overwriting it when you will now
275 copy over the sample configuration file.
276 </para>
277 <para>
278 If you don't have a pre-existing configuration file and thus
279 need to copy over our sample configuration file to the
280 standard Wine configuration file location, do in a
282 <screen>
284 <prompt>$ </><userinput>cp <replaceable>dir_to_wine_source_code</replaceable>/documentation/samples/config ~/.wine/config</>
285 </screen>
286 Otherwise, simply use the already existing configuration file
288 </para>
289 <para>
290 Now you can start adapting the configuration file's settings with an
292 below.
294 configuration file settings if wineserver is not running (in
295 other words: if your user doesn't have a Wine session running),
296 otherwise Wine won't use them - and even worse, wineserver will
297 overwrite them with the old settings once wineserver quits!!
298 </para>
299 </sect2>
304 <para>
305 Let's start by giving an overview of which sections a
306 configuration file may contain, and whether the inclusion of
307 the respective section is <emphasis>needed</emphasis> or only <emphasis>recommended</emphasis> ("recmd").
308 </para>
312 <thead>
313 <row>
317 </row>
318 </thead>
319 <tbody>
320 <row>
324 </row>
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 </tbody>
426 </tgroup>
427 </informaltable>
429 <para>
430 Now let's explain the configuration file sections in a
431 detailed way.
432 </para>
434 <sect3>
436 <para>
437 For a detailed description of these configuration file
438 sections which are used to set up DOS drive mappings to Unix
439 directory space, please look at the <link
441 configuration section</link>.
442 </para>
443 </sect3>
447 <para>
448 The [wine] section of the configuration file contains all kinds
449 of general settings for Wine.
450 </para>
451 <para>
452 <programlisting>
458 </programlisting>
459 For a detailed description of drive layer configuration and
460 the meaning of these parameters, please look at the <link
462 configuration section</link>.
463 </para>
464 <para>
466 Sets the graphics driver to use for Wine output.
467 x11drv is for X11 output, ttydrv is for text console output.
468 WARNING: if you use ttydrv here, then you won't be able to run
469 a lot of Windows GUI programs (ttydrv is still pretty "broken"
470 at running graphical apps). Thus this option is mainly interesting
471 for e.g. embedded use of Wine in web server scripts.
472 Note that ttydrv is still very lacking, so if it doesn't work,
473 resort to using "xvfb", a virtual X11 server.
474 Another way to run Wine without display would be to run X11
475 via Xvnc, then connect to that VNC display using xvncviewer
476 (that way you're still able to connect to your app and
477 configure it if need be).
478 </para>
479 <para>
481 whether to allow printing via printer drivers to work.
482 This option isn't needed for our built-in psdrv printer driver
483 at all.
484 Using these things are pretty alpha, so you might want to
485 watch out. Some people might find it useful, however. If
486 you're not planning to work on printing via windows printer
487 drivers, don't even add this to your wine configuration file
488 (It probably isn't already in it).
489 Check out the [spooler] and [parallelports] sections too.
490 </para>
491 <para>
493 This setting specifies the shell linker script to use for setting
494 up Windows icons in e.g. KDE or Gnome that are given by programs
495 making use of appropriate shell32.dll functionality to create
496 icons on the desktop/start menu during installation.
497 </para>
498 <para>
500 Sets up the symbol table file for the wine debugger. You
501 probably don't need to fiddle with this. May be useful if
502 your wine is stripped.
503 </para>
504 </sect3>
508 <para>
509 These settings provide wine's default handling of DLL loading.
510 </para>
511 <para>
513 This setting is a comma-delimited list of the order in
514 which to attempt loading DLLs. If the first option fails,
515 it will try the second, and so on. The order specified
516 above is probably the best in most conditions.
517 </para>
518 </sect3>
520 <sect3>
522 <para>
523 At one time, there was a section called [DllPairs] in the
524 default configuration file, but this has been obsoleted
525 because the pairing information has now been embedded into
526 Wine itself. (The purpose of this section was merely to be
527 able to issue warnings if the user attempted to pair
531 </para>
532 </sect3>
536 <para>
537 The format for this section is the same for each line:
538 <programlisting><DLL>{,<DLL>,<DLL>...} = <FORM>{,<FORM>,<FORM>...}</programlisting>
539 For example, to load built-in KERNEL pair (case doesn't
540 matter here):
542 To load the native COMMDLG pair, but if that doesn't work
543 try built-in:
545 To load the native COMCTL32:
547 Here is a good generic setup (As it is defined in config
548 that was included with your wine package):
549 <programlisting>
550 [DllOverrides]
587 ; you can specify programs too
589 ; default for all other DLLs
591 </programlisting>
592 </para>
593 <note>
594 <para>
595 If loading of the libraries that are listed first fails,
596 wine will just go on by using the second or third option.
597 </para>
598 </note>
599 </sect3>
603 <para>
604 This section sets up wine's font handling.
605 </para>
606 <para>
608 Since the way X handles fonts is different from the way
609 Windows does, wine uses a special mechanism to deal with
610 them. It must scale them using the number defined in the
612 a nice in the middle one. If you have the real windows
613 fonts available , this parameter will not be as
614 important. Of course, it's always good to get your X fonts
615 working acceptably in wine.
616 </para>
617 <para>
619 The default font wine uses. Fool around with it if you'd like.
620 </para>
621 <para>
622 OPTIONAL:
623 </para>
624 <para>
626 used in wine. This is good for apps that need a special font you don't have,
627 but a good replacement exists. The syntax is like so:
628 <programlisting>"AliasX" = "[Fake windows name],[Real X name]"<,optional "masking" section></programlisting>
630 then "Alias1" and so on. The fake windows name is the name
631 that the font will be under a windows app in wine. The
632 real X name is the font name as seen by X (Run
634 utilize the fake windows name you define. If it is not
635 used, then wine will just try to extract the fake windows
636 name itself and not use the value you enter.
637 </para>
638 <para>
639 Here is an example of an alias without masking. The font will show up in windows
640 apps as "Google".
642 Here is an example with masking enabled. The font will show up as "Foo" in
643 windows apps.
646 chapter.
647 </para>
648 </sect3>
652 <para>
653 Even though it sounds like a lot of sections, these are
654 all closely related. They are all for communications and
655 parallel ports.
656 </para>
657 <para>
658 The [serialports] section tells wine what serial ports it
659 is allowed to use.
665 can actually equal any device
667 not always necessary to define any COM ports (An optional
668 setting). Here is an example:
670 Use as many of these as you like in the section to define
671 all of the COM ports you need.
672 </para>
673 <para>
674 The [parallelports] section sets up any parallel ports
675 that will be allowed access under wine.
677 Sounds familiar? Syntax is just like the COM port setting.
681 minus 1, just like for COM ports). You don't always need
682 to define a parallel port (AKA, it's optional). As with
683 the other section, LptX can equal any device (Maybe
686 The [spooler] section will inform wine where to spool
687 print jobs. Use this if you want to try printing. Wine
688 docs claim that spooling is "rather primitive" at this
690 setting you use in this section works to map a port (LPT1,
691 for example) to a file or a command. Here is an example,
694 The following command maps printing jobs to LPT1 to the
697 The [ports] section is usually useful only for people who
698 need direct port access for programs requiring dongles or
699 scanners. <emphasis>If you don't need it, don't use
700 it!</emphasis>
701 </para>
702 <para>
704 Gives direct read access to those IO's.
705 </para>
706 <para>
708 Gives direct write access to those IO's. It's probably a
709 good idea to keep the values of the
711 settings the same. This stuff will only work when you're
712 root.
713 </para>
714 </sect3>
718 <para>
719 [Debug] is used to include or exclude debug messages, and to
720 output them to a file. The latter is rarely used. <emphasis>These
721 are all optional and you probably don't need to add or
722 remove anything in this section to your config.</emphasis> (In extreme
723 cases you may want to use these options to manage the amount
724 of information generated by the <parameter>--debugmsg +relay
725 </parameter> option.)
726 </para>
727 <para>
729 Sets the logfile for wine. Set to CON to log to standard out.
731 </para>
732 <para>
736 </para>
737 <para>
741 </para>
742 <para>
744 Include only the listed functions in a
747 </para>
748 <para>
749 <programlisting>"RelayExclude" = "RtlEnterCriticalSection;RtlLeaveCriticalSection"</programlisting>
750 Exclude the listed functions in a
753 entry. If neither entry is present then the trace includes
754 everything.
755 </para>
756 <para>
757 In both entries the functions may be specified either as a
758 function name or as a module and function. In this latter
759 case specify an asterisk for the function name to include/exclude
760 all functions in the module.
761 </para>
762 <para>
763 [Registry] can be used to tell wine where your old windows
764 registry files exist. This section is completely optional
765 and useless to people using wine without an existing
766 windows installation.
767 </para>
768 <para>
771 </para>
772 <para>
773 [tweak.layout] is devoted to wine's look. There is only
774 one setting for it.
775 </para>
776 <para>
781 </para>
782 <para>
783 [programs] can be used to say what programs run under
784 special conditions.
785 </para>
786 <para>
788 Sets the program to be run if wine is started without specifying a program.
789 </para>
790 <para>
792 Sets the program to automatically be run at startup every time.
793 </para>
794 </sect3>
798 <para>
799 [WinMM] is used to define which multimedia drivers have to be loaded. Since
800 those drivers may depend on the multimedia interfaces available on your system
801 (OSS, ALSA... to name a few), it's needed to be able to configure which driver
802 has to be loaded.
803 </para>
805 <para>
806 The content of the section looks like:
807 <programlisting>
808 [WinMM]
812 </programlisting>
813 All the keys must be defined:
814 <itemizedlist>
815 <listitem>
816 <para>
817 The "Drivers" key is a ';' separated list of modules name, each of
818 them containing a low level driver. All those drivers will be loaded
819 when MMSYSTEM/WINMM is started and will provide their inner features.
820 </para>
821 </listitem>
822 <listitem>
823 <para>
824 The "WaveMapper" represents the name of the module containing the Wave
825 Mapper driver. Only one wave mapper can be defined in the system.
826 </para>
827 </listitem>
828 <listitem>
829 <para>
830 The "MidiMapper" represents the name of the module containing the MIDI
831 Mapper driver. Only one MIDI mapper can be defined in the system.
832 </para>
833 </listitem>
834 </itemizedlist>
835 </para>
836 </sect3>
840 <para>
841 [Network] contains settings related to
842 networking. Currently there is only one value that can be set.
843 </para>
844 <variablelist>
845 <varlistentry>
847 <listitem>
848 <para>
850 that affects the way Wine sets the computer name. The computer
853 <varname>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ComputerName\ComputerName</varname>.
854 </para>
855 <para>
856 If this option is set to "Y" or missing, Wine will set the
857 NetBIOS name to the Unix host name of your computer, if
858 necessary truncated to 31 characters. The Unix hostname is the output
860 including the first dot ('.'). Among other things, this means that
861 Windows programs running under Wine cannot change the NetBIOS computer name.
862 </para>
863 <para>
864 If this option is set to "N", Wine will use the registry value above
865 to set the NetBIOS name. Only if the registry entry doesn't exist (usually
866 only during the first wine startup) it will use the Unix hostname as
867 usual. Windows programs can change the NetBIOS name. The change
868 will be effective after a "reboot", i.e. after restarting Wine.
869 </para>
870 </listitem>
871 </varlistentry>
872 </variablelist>
873 </sect3>
877 <para>
878 The section is used to overwrite certain settings of this file for a
879 special program with different settings.
880 [AppDefaults] is not the real name of the section. The real name
881 consists of the leading word AppDefaults followed by the name
882 of the executable the section is valid for.
883 The end of the section name is the name of the
884 corresponding "standard" section of the configuration file
885 that should have some of its settings overwritten with the
886 program specific settings you define.
887 The three parts of the section name are separated by two backslashes.
888 </para>
889 <para>
890 Currently wine supports overriding selected settings within
891 the sections [DllOverrides], [x11drv], [version] and [dsound] only.
892 </para>
893 <para>
894 Here is an example that overrides the normal settings for a
895 program:
896 <programlisting>
897 ;; default settings
898 [x11drv]
902 ;; run install in desktop mode
903 [AppDefaults\\install.exe\\x11drv]
906 </programlisting>
907 </para>
908 </sect3>
909 </sect2>
913 <para>
914 There is always a chance that things will go wrong. If the
915 unthinkable happens, report the problem to
917 try the newsgroup
920 irc.freenode.net, or connected servers.
921 Make sure that you have looked over this document thoroughly,
922 and have also read:
923 </para>
924 <itemizedlist>
925 <listitem>
926 <para>
928 </para>
929 </listitem>
930 <listitem>
931 <para>
933 </para>
934 </listitem>
935 </itemizedlist>
936 <para>
937 If indeed it looks like you've done your research, be
938 prepared for helpful suggestions. If you haven't, brace
939 yourself for heaving flaming.
940 </para>
941 </sect2>
942 </sect1>
946 <sect2>
948 <para>
949 If you're planning to include access to a CD-ROM drive in your Wine
954 Several Windows program setup CD-ROMs or other CD-ROMs chose
955 to do such braindamaged things as marking very important setup
957 That's no problem on Windows, since the Windows CD-ROM driver by
958 default displays even files that are supposed to be
962 (the programs will simply abort with an <quote>installation file not found</quote> or similar error)
963 Thus you should never forget to add this setting.
964 </para>
965 </sect2>
967 <sect2>
969 <para>
970 Wine emulates drives by placing their virtual drive roots to
971 user-configurable points in the Unix filesystem, so it's your
976 indicates the home directory of a user), as the root of your
978 into your Wine configuration file:
979 </para>
981 <programlisting>
982 [Drive C]
987 </programlisting>
989 <para>
990 With this configuration, what windows apps think of as
991 "c:\windows\system" would map to
993 filesystem. Note that you need to specify
997 Windows compatible (case insensitive) filesystem, otherwise
998 most apps won't work.
999 </para>
1000 </sect2>
1004 <para>
1005 Here's the fundamental layout that Windows programs and
1006 installers expect and that we thus need to configure properly
1007 in Wine. Without it, they seldomly operate correctly. If you
1008 intend to use a no-windows environment (not using an existing
1009 Windows partition), then it is recommended to use either
1012 initial windows directory tree, since creating a directory
1013 structure manually is tiresome and error-prone.
1014 </para>
1016 <programlisting>
1017 C:\ Root directory of primary disk drive
1018 Windows\ Windows directory, containing .INI files,
1019 accessories, etc.
1023 Start Menu\ Program launcher directory structure
1024 Programs\ Program launcher links (.LNK files) to programs
1025 Program Files\ Application binaries (.EXE and .DLL files)
1026 </programlisting>
1027 </sect2>
1031 <para>
1032 These sections are supposed to make certain Unix
1033 directory locations accessible to Wine as a DOS/Windows drive
1034 (drive 'x:') and thus accessible to Windows programs
1035 under the drive name you specified.
1036 Every DOS/Windows program sort of expects at least a C:
1037 drive (and sometimes also an A: floppy drive), so your
1038 configuration file should at least contain the corresponding
1039 sections, [Drive C] and [Drive A].
1040 You need to decide on whether you want to use an existing Windows
1041 partition as the C drive or whether you want to create your own
1042 Wine drive C directory tree somewhere (take care about
1043 permissions!).
1044 Each drive section may specify up to 6 different settings
1045 as explained below.
1046 </para>
1047 <para>
1049 The above line begins the section for a drive whose letter is x
1050 (DOS notation: drive 'x:').
1051 You could e.g. create an equivalent to a drive 'C:'
1052 under DOS/Windows by using a [Drive C] section name.
1053 Note that the drive letter is case insensitive.
1054 </para>
1055 <para>
1057 This specifies the directory where the drive will begin.
1058 When Wine is browsing in drive x, it will be able
1059 to see the files that are in the directory
1061 (note that symlinks to directories won't get included!
1063 configuration setting)
1064 You can also make use of environment variables like $HOME here,
1066 directory in your home dir would be
1068 but don't forget to put it as a DOS environment variable,
1069 ie surrounded by '%' signs rather than preceded by a '$'.
1070 Don't forget to leave off the trailing slash!
1071 </para>
1072 <para>
1074 Sets up the type of drive Wine will see it as. Type must
1078 (The |'s mean "Type = '<one of the options>'".)
1080 For a home directory entry, it makes sense to choose
1081 "network" sometimes, since some home directories are being
1082 exported over the network via NFS and thus can have slow response
1083 times.
1084 </para>
1085 <para>
1087 Defines the drive label. Generally only needed
1088 for programs that look for a special CD-ROM.
1089 The label may be up to 11 characters.
1090 Note that the preferred way of managing labels and serial numbers
1091 of CD-ROMs and floppies is to give Wine raw device access for
1092 reading these on a per-CD case (see "Device" below) instead of
1093 hardcoding one specific "Label".
1094 </para>
1095 <para>
1097 Tells Wine the serial number of the drive. A few programs with
1098 intense protection for pirating might need this, but otherwise
1099 it's not needed. Up to 8 characters and hexadecimal.
1101 is a smarter choice.
1102 </para>
1103 <para>
1105 Sets up the way Wine looks at files on the drive.
1106 This setting controls the file name lookup and mapping of
1107 Wine to existing file systems on your PC, it does
1109 used itself.
1110 </para>
1112 <variablelist>
1113 <varlistentry>
1115 <listitem>
1116 <para>
1118 the long filename filesystem you are probably used
1119 to working with. The filesystem behavior of choice for most
1120 programs to be run under wine. <emphasis>Probably the one
1121 you want!</emphasis>
1122 </para>
1123 </listitem>
1124 </varlistentry>
1125 <varlistentry>
1127 <listitem>
1128 <para>
1129 Case sensitive. This filesystem has almost no use
1130 (Windows apps expect case insensitive filenames),
1131 except maybe for Winelib applications.
1132 Try it if you dare, but win95 is a much better
1133 and always recommended choice.
1134 </para>
1135 </listitem>
1136 </varlistentry>
1137 <varlistentry>
1139 <listitem>
1140 <para>
1141 Case insensitive filesystem. Alike to DOS and
1143 length of files (eightdot.123) - longer ones will be
1144 truncated.
1145 <note>
1146 <para>
1148 you plan on running apps that use long filenames.
1149 win95 should work fine with apps that were designed
1150 to run under the msdos system. In other words, you
1151 might not want to use this.
1152 </para>
1153 </note>
1154 </para>
1155 </listitem>
1156 </varlistentry>
1157 </variablelist>
1160 <para>
1161 Needed for raw device access and <link linkend="config-drive-cdrom-labels">label and serial number reading</link>.
1163 Extended2 or other Unix file systems can have dire results
1164 (when a windows app tries to do a lowlevel write,
1165 they do it in a FAT way -- FAT format is completely different from
1166 any Unix file system).
1167 Also, make sure that you have proper permissions to this device
1168 file.
1169 </para>
1170 <note>
1171 <para>
1172 This setting is not really important; almost all apps
1173 will have no problem if it remains unspecified. For
1174 CD-ROMs it's quite useful in order to get automatic label
1175 detection, though. If you are unsure about specifying
1176 device names, just leave out this setting for your
1177 drives.
1178 </para>
1179 </note>
1180 <para>
1181 Here are a few sample entries:
1182 <programlisting>
1183 Here is a setup for Drive C, a generic hard drive:
1184 [Drive C]
1189 This is a setup for Drive E, a generic CD-ROM drive:
1190 [Drive E]
1196 And here is a setup for Drive A, a generic floppy drive:
1197 [Drive A]
1204 </programlisting>
1205 </para>
1206 </sect2>
1208 <sect2>
1210 <para>
1212 This tells Wine and Windows programs where the
1214 recommended to have this directory somewhere on your
1216 recommended to just call the directory "windows" (this is
1217 the default setup on Windows, and some stupid programs
1218 might rely on this). So in case you chose a "Windows"
1219 setting of "c:\\windows" and you chose to set up a drive C
1221 corresponding directory would be
1223 if you don't already have one. <emphasis>No trailing slash</emphasis> (<emphasis>not</emphasis>
1225 recommended, as Windows programs always assume write access
1226 to the Windows directory!
1227 </para>
1228 <para>
1230 This sets up where the windows system files are. The Windows
1231 system directory should reside below the directory used for the
1233 Thus when using the example above, the system directory would be
1235 Again, no trailing slash, and write access!
1236 </para>
1237 <para>
1239 be the directory you want your temp files stored in,
1240 /usr/local/wine_c/temp in our example.
1241 Again, no trailing slash, and <emphasis>write
1242 access</emphasis>!!
1243 </para>
1244 <para>
1247 boxes. When wine is run like <userinput>wine
1249 resides in a directory specified in the
1252 current directory, wine will run that one). Make sure it
1254 system directory (For this setup, it must have
1256 </para>
1259 Wine doesn't pass directory symlinks to Windows programs by
1260 default, as doing so may crash some programs that do
1261 recursive lookups of whole subdirectory trees
1262 whenever a directory symlink points back to itself or one of its
1263 parent directories.
1264 That's why we disallowed the use of directory symlinks
1265 and added this setting to reenable ("1") this functionality.
1267 account symlinked directories, then reenable it, but
1269 Windows programs when using the above method! (in other words:
1270 enabling it is certainly not recommended)
1271 </para>
1272 </sect2>
1274 <sect2>
1276 <para>
1277 Windows uses a different (and inferior) way than Unix to describe the
1278 location of files in a computer. Thus Windows programs also expect
1279 to find this different way supported by the system.
1280 Since we intend to run Windows programs on
1281 a Unix system, we're in trouble, as we need to translate
1282 between these different file access techniques.
1283 </para>
1284 <para>
1285 Windows uses drive letters to describe drives or
1286 any other form of storage media and to access files on them.
1287 For example, common drive names are
1290 first floppy drive.
1292 directory separator sign, whereas Unix uses
1294 Thus, an example document on the first data partition in
1295 Windows might be accessed by the name of
1297 </para>
1298 <para>
1299 So much for the Windows way of doing things.
1300 </para>
1301 <para>
1302 Well, the problem is, in Unix there is no such thing as
1304 much better way of having one single uniform directory tree
1305 (starting with the root directory
1307 such as e.g. harddisk partitions appended at various directory
1308 locations within the tree (an example would be
1310 partition mounted/attached to a directory called data1 in the
1312 directory of the data partition file system that's mounted
1314 In Unix, the Windows example document mentioned above could e.g.
1315 be accessed by the name of
1317 provided that the administrator decided to mount (attach) the first
1318 data partition at the directory /data1 inside the Unix
1319 directory tree. Note that in Unix, the administrator can
1323 suitable for the first data partition (here,
1325 change in partition order, Windows automatically
1327 suddenly find yourself with a first data partition at drive
1329 referencing confusion that entails. Thus, the Windows way of
1330 using ever-changing drive letters is <emphasis>clearly
1331 inferior</emphasis> to the Unix way of assigning
1333 data storage medium.
1334 As we'll see soon, fortunately this Windows limitation of
1335 changing drive letters doesn't affect us in Wine at all, since
1336 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).
1337 </para>
1338 <para>
1339 OK, now that we know some theory about Windows and Unix drive
1340 and filename mapping, it's probably time to ask how Wine
1341 achieves the magic of mapping a Unix directory location to a
1342 Windows drive...
1343 </para>
1344 <para>
1345 Wine chose to do the following:
1346 In Wine, you don't assign some real physical storage medium
1347 (such as a harddisk partition or similar) to each drive letter
1348 mapping entry.
1349 Instead, you choose certain sub directory trees inside the Unix
1351 you would like to assign a drive letter to.
1352 </para>
1353 <para>
1354 Note that for every Unix sub directory tree that you intend to
1355 start Windows programs in, it is <emphasis>absolutely
1356 required</emphasis> to have a Wine drive mapping entry:
1357 </para>
1358 <para>
1359 For example, if you had a publicly writable <quote>Windows
1361 able to access this sub directory tree from Wine, you should
1362 have a drive mapping entry that maps a certain drive letter
1364 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.
1365 </para>
1366 </sect2>
1371 <para>
1372 A major goal of Wine is to allow users to run Windows programs
1373 without having to install Windows on their machine. Wine
1374 implements the functionality of the main DLLs usually
1375 provided with Windows. Therefore, once Wine is finished, you
1376 will not need to have Windows installed to use Wine.
1377 </para>
1378 <para>
1379 Wine has already made enough progress that it may be possible
1380 to run your target programs without Windows installed. If
1381 you want to try it, follow these steps:
1382 </para>
1384 <orderedlist>
1385 <listitem>
1386 <para>
1390 for more information.
1391 The directory to be used for emulating a C: drive will be
1392 the base directory for some Windows specific directories
1393 created below.
1394 Remember to use
1396 </para>
1397 </listitem>
1398 <listitem>
1399 <para>
1400 Within the directory to be used for C:, create empty
1405 directories. Do not point Wine to a
1407 installations and a messy registry. (Wine creates a
1410 Perhaps you have to remove these files).
1411 In one line:
1412 mkdir -p windows windows/system windows/Start\ Menu windows/Start\ Menu/Programs
1413 </para>
1414 </listitem>
1415 <listitem>
1416 <para>
1417 Run and/or install your programs.
1418 </para>
1419 </listitem>
1420 </orderedlist>
1422 <para>
1423 Because Wine is not yet complete, some programs will work
1424 better with native Windows DLLs than with Wine's
1425 replacements. Wine has been designed to make this possible.
1426 Here are some tips by Juergen Schmied (and others) on how to
1427 proceed. This assumes that your
1429 file does not point to a native Windows installation but is in
1433 </para>
1435 <itemizedlist>
1436 <listitem>
1437 <para>
1438 Run the program with <parameter>--debugmsg
1439 +loaddll</parameter> to find out which files are
1440 needed. Copy the required DLLs one by one to the
1442 copy KERNEL/KERNEL32, GDI/GDI32, USER/USER32 or NTDLL. These
1443 implement the core functionality of the Windows API, and
1444 the Wine internal versions must be used.
1445 </para>
1446 </listitem>
1447 <listitem>
1448 <para>
1452 the Windows DLLs you want to use. For more information
1453 about this, see the Wine manpage.
1454 </para>
1455 </listitem>
1456 <listitem>
1457 <para>
1458 Note that some network DLLs are not needed even though
1459 Wine is looking for them. The Windows
1461 must use the internal implementation.
1462 </para>
1463 </listitem>
1464 <listitem>
1465 <para>
1466 Copy SHELL.DLL/SHELL32.DLL, COMMDLG.DLL/COMDLG32.DLL
1467 and COMMCTRL.DLL/COMCTL32.DLL
1468 only as pairs to your Wine directory (these DLLs are
1472 </para>
1473 </listitem>
1474 <listitem>
1475 <para>
1476 Be consistent: Use only DLLs from the same Windows version
1477 together.
1478 </para>
1479 </listitem>
1480 <listitem>
1481 <para>
1486 registry, don't know about
1488 As of now, it might not be necessary any more to use
1489 regedit.exe, since Wine has its own regedit Winelib
1490 application now.
1491 </para>
1492 </listitem>
1493 <listitem>
1494 <para>
1497 to browse through your programs' help function
1498 (or in case Wine's winhelp implementation in programs/winhelp/
1499 is not good enough, for example).
1500 </para>
1501 </listitem>
1502 </itemizedlist>
1503 </sect2>
1507 <para>
1508 Some people intend to use the data of an existing Windows partition
1509 with Wine in order to gain some better compatibility or to run already
1510 installed programs in a setup as original as possible.
1511 Note that many Windows programs assume that they have full write
1512 access to all windows directories.
1514 This means that you either have to configure the Windows
1515 partition mount point for write permission by your Wine user
1517 on how to do that), or you'll have to copy over (some parts of) the Windows
1518 partition content to a directory of a Unix partition and make
1519 sure this directory structure is writable by your user.
1521 write access as a base for Wine!! (some programs, notably
1522 Explorer, corrupt large parts of the Windows partition in case
1523 of an incorrect setup; you've been warned).
1524 Not to mention that NTFS write support in Linux is still very
1526 Windows version using the NTFS file system).
1527 Thus we advise you to go the Unix directory way.
1528 </para>
1529 </sect2>
1533 <para>
1534 This document describes how FAT and
1535 VFAT file system permissions work in Linux
1536 with a focus on configuring them for Wine.
1537 </para>
1539 <sect3>
1541 <para>
1542 Linux is able to access DOS and Windows file systems using
1543 either the FAT (older 8.3 DOS filesystems) or VFAT (newer
1544 Windows 95 or later long filename filesystems) modules.
1545 Mounted FAT or VFAT filesystems provide the primary means
1546 for which existing programs and their data are accessed
1547 through Wine for dual boot (Linux + Windows) systems.
1548 </para>
1549 <para>
1550 Wine maps mounted FAT filesystems, such as
1555 </para>
1556 <programlisting>
1557 [Drive C]
1560 </programlisting>
1561 <para>
1562 Although VFAT filesystems are preferable to FAT filesystems
1564 will be used throughout the remainder of this document to
1565 refer to FAT filesystems and their derivatives. Also,
1567 examples throughout this document.
1568 </para>
1569 <para>
1570 Most modern Linux distributions either detect or allow
1571 existing FAT file systems to be configured so that they can be
1573 either persistently (on bootup) or on an as needed basis. In
1574 either case, by default, the permissions will probably be
1575 configured so that they look like:
1576 </para>
1577 <screen>
1583 </screen>
1584 <para>
1586 group and are only writable by "root"
1588 that it requires that Wine be run as root in order for
1589 programs to be able to write to any part of the
1590 filesystem.
1591 </para>
1592 <para>
1593 There are three major approaches to overcoming the restrictive
1594 permissions mentioned in the previous paragraph:
1595 </para>
1596 <orderedlist>
1597 <listitem>
1598 <para>
1600 </para>
1601 </listitem>
1602 <listitem>
1603 <para>
1604 Mount the FAT filesystem with less restrictive
1605 permissions
1606 </para>
1607 </listitem>
1608 <listitem>
1609 <para>
1610 Shadow the FAT filesystem by completely or partially
1611 copying it
1612 </para>
1613 </listitem>
1614 </orderedlist>
1615 <para>
1616 Each approach will be discussed in the following sections.
1617 </para>
1618 </sect3>
1620 <sect3>
1622 <para>
1623 Running Wine as root is the easiest and most thorough way of giving
1624 programs that Wine runs unrestricted access to FAT files systems.
1625 Running wine as root also allows programs to do things unrelated
1626 to FAT filesystems, such as listening to ports that are less than
1627 1024. Running Wine as root is dangerous since there is no limit to
1629 </para>
1630 </sect3>
1632 <sect3>
1634 <para>
1635 The FAT filesystem can be mounted with permissions less restrictive
1636 than the default. This can be done by either changing the user that
1637 mounts the FAT filesystem or by explicitly changing the permissions
1638 that the FAT filesystem is mounted with. The permissions are
1639 inherited from the process that mounts the FAT filesystem. Since the
1640 process that mounts the FAT filesystem is usually a startup script
1641 running as root the FAT filesystem inherits root's permissions. This
1642 results in the files on the FAT filesystem having permissions similar
1643 to files created by root. For example:
1644 </para>
1645 <screen>
1651 </screen>
1652 <para>
1653 which matches the owner, group and permissions of files seen
1654 on the FAT filesystem except for the missing 'x's. The
1655 permissions on the FAT filesystem can be changed by changing
1656 root's umask (unset permissions bits). For example:
1657 </para>
1658 <screen>
1669 </screen>
1670 <para>
1671 Mounting the FAT filesystem with a umask of
1673 it. Explicitly specifying the permissions of the FAT
1674 filesystem when it is mounted provides additional control.
1675 There are three mount options that are relevant to FAT
1678 when the filesystem is manually mounted. For example:
1679 </para>
1680 <screen>
1688 </screen>
1689 <para>
1690 which gives "sle" complete control over
1692 made permanent by adding them to the
1694 </para>
1695 <screen>
1697 <computeroutput>/dev/hda1 /c vfat uid=500,gid=500,umask=002,exec,dev,suid,rw 1 1</computeroutput>
1698 </screen>
1699 <para>
1701 the user private group file permission scheme. On FAT file
1702 systems this umask assures that all files are fully
1703 accessible by all users in the specified user group
1705 </para>
1706 </sect3>
1708 <sect3>
1710 <para>
1711 Shadowing provides a finer granularity of control. Parts of
1712 the original FAT filesystem can be copied so that the
1713 program can safely work with those copied parts while
1714 the program continues to directly read the remaining
1715 parts. This is done with symbolic links. For example,
1716 consider a system where a program named
1720 read access to the entire FAT filesystem. On this system
1721 the FAT filesystem has default permissions which should not
1722 be changed for security reasons or can not be changed due to
1723 lack of root access. On this system a shadow directory
1724 might be set up in the following manner:
1725 </para>
1726 <screen>
1734 <prompt>/c_shadow></prompt><userinput>perl -p -i -e 's|/c$|/c_shadow|g' ~/.wine/config</userinput>
1735 </screen>
1736 <para>
1737 The above gives everyone complete read and write access to
1740 write access to all other directories.
1741 </para>
1742 </sect3>
1743 </sect2>
1748 <para>
1749 Until now, your only possibility of specifying drive volume
1750 labels and serial numbers was to set them manually in the wine
1751 configuration file. By now, wine can read them directly from the
1752 device as well. This may be useful for many Win 9x games or
1753 for setup programs distributed on CD-ROMs that check for
1754 volume label.
1755 </para>
1757 <sect3>
1762 <thead>
1763 <row>
1767 </row>
1768 </thead>
1769 <tbody>
1770 <row>
1774 </row>
1775 <row>
1779 </row>
1780 </tbody>
1781 </tgroup>
1782 </informaltable>
1784 </sect3>
1786 <sect3>
1788 <para>
1789 Reading labels and serial numbers just works automatically
1792 Note that the device has to exist and must be accessible by the user
1793 running Wine if you do this, though.
1794 </para>
1795 <para>
1796 If you don't want to read labels and serial numbers directly from
1797 the device, then you should give fixed
1800 these entries instead if no device is given. If they don't
1801 exist, then Wine will return default values (label
1804 </para>
1805 <para>
1808 but not for reading the volume info from the device (i.e. you want
1811 to skip the volume reading.
1812 </para>
1813 </sect3>
1815 <sect3>
1817 <para>
1818 Here's a simple example of CD-ROM and floppy; labels will be
1819 read from the device on both CD-ROM and floppy; serial
1820 numbers on floppy only:
1821 </para>
1822 <programlisting>
1823 [Drive A]
1829 [Drive R]
1834 </programlisting>
1835 <para>
1836 Here's an example of overriding the CD-ROM label:
1837 </para>
1838 <programlisting>
1839 [Drive J]
1843 ; note that the device isn't really needed here as we have a fixed label
1846 </programlisting>
1847 </sect3>
1849 <sect3>
1851 <itemizedlist>
1852 <listitem> <para>
1853 The CD-ROM label can be read only if the data track of
1854 the disk resides in the first track and the cdrom is
1855 iso9660.
1856 </para> </listitem>
1857 <listitem> <para>
1858 Better checking for FAT superblock (it now checks only
1859 one byte). </para>
1860 </listitem>
1861 <listitem> <para>
1862 Support for labels/serial nums WRITING.
1863 </para> </listitem>
1864 <listitem> <para>
1866 chars).
1867 </para> </listitem>
1868 <listitem> <para>
1869 What about reading ext2 volume label? ....
1870 </para> </listitem>
1871 </itemizedlist>
1872 </sect3>
1873 </sect2>
1874 </sect1>
1876 ®istry;
1881 <sect2>
1883 <para>
1884 If your programs don't work as expected, then it's often because one
1885 DLL or another is failing. This can often be resolved by changing
1886 certain DLLs from Wine built-in to native Windows DLL file and vice
1887 versa.
1888 </para>
1889 <para>
1890 A very useful help to find out which DLLs are loaded as built-in and
1891 which are loaded as native Windows file can be the debug channel
1892 loaddll, activated via the Wine command line parameter
1894 </para>
1895 </sect2>
1897 <sect2>
1898 <!-- FIXME intro!!! -->
1900 <para>
1901 There are a few things you will need to know before
1902 configuring the DLL sections in your wine configuration
1903 file.
1904 </para>
1905 <sect3>
1907 <para>
1908 Most windows DLL's have a win16 (Windows 3.x) and win32
1909 (Windows 9x/NT) form. The combination of the win16 and
1910 win32 DLL versions are called the "DLL pair". This is a
1911 list of the most common pairs:
1912 </para>
1914 <informaltable>
1916 <thead>
1917 <row>
1920 <entry>
1921 Native
1922 <footnote>
1923 <para>
1924 Is it possible to use native DLL with wine?
1925 (See next section)
1926 </para>
1927 </footnote>
1928 </entry>
1929 </row>
1930 </thead>
1931 <tbody>
1932 <row>
1936 </row>
1937 <row>
1941 </row>
1942 <row>
1946 </row>
1947 <row>
1951 </row>
1952 <row>
1956 </row>
1957 <row>
1961 </row>
1962 </tbody>
1963 </tgroup>
1964 </informaltable>
1965 </sect3>
1967 <sect3>
1969 <para>
1970 There are a few different forms of DLL's wine can load:
1971 <variablelist>
1972 <varlistentry>
1974 <listitem><para>
1975 The DLL's that are included with windows. Many
1976 windows DLL's can be loaded in their native
1977 form. Many times these native versions work
1978 better than their non-Microsoft equivalent --
1979 other times they don't.
1980 </para></listitem>
1981 </varlistentry>
1982 <varlistentry>
1984 <listitem><para>
1985 The most common form of DLL loading. This is
1986 what you will use if the DLL is too system-specific
1987 or error-prone in native form (KERNEL for example),
1988 you don't have the native DLL, or you just want to be
1989 Microsoft-free.
1990 </para></listitem>
1991 </varlistentry>
1992 <varlistentry>
1994 <listitem><para>
1995 Native ELF libraries. Has been deprecated, ignored.
1996 </para></listitem>
1997 </varlistentry>
1998 <varlistentry>
2000 <listitem><para>
2001 ELF encapsulated windows DLL's.
2002 No longer used, ignored.
2003 </para></listitem>
2004 </varlistentry>
2005 </variablelist>
2006 </para>
2007 </sect3>
2008 </sect2>
2013 <para>
2014 The wine configuration file directives [DllDefaults]
2015 and [DllOverrides] are the subject of some confusion. The
2016 overall purpose of most of these directives are clear enough,
2017 though - given a choice, should Wine use its own built-in
2019 in an existing Windows installation? This document explains
2020 how this feature works.
2021 </para>
2023 <sect3>
2025 <variablelist>
2026 <varlistentry>
2028 <listitem> <para>
2030 written for the real Microsoft Windows.
2031 </para> </listitem>
2032 </varlistentry>
2033 <varlistentry>
2035 <listitem> <para>
2036 A "built-in" DLL is a Wine DLL. These can either be a
2039 that Wine is able to load on demand.
2040 </para> </listitem>
2041 </varlistentry>
2042 </variablelist>
2043 </sect3>
2045 <sect3>
2047 <variablelist>
2048 <varlistentry>
2050 <listitem> <para>
2051 This specifies in what order Wine should search for
2052 available DLL types, if the DLL in question was not
2053 found in the [DllOverrides] section.
2054 </para> </listitem>
2055 </varlistentry>
2056 </variablelist>
2057 </sect3>
2059 <sect3>
2061 <para>
2062 At one time, there was a section called [DllPairs] in the
2063 default configuration file, but this has been obsoleted
2064 because the pairing information has now been embedded into
2065 Wine itself. (The purpose of this section was merely to be
2066 able to issue warnings if the user attempted to pair
2070 </para>
2071 </sect3>
2073 <sect3>
2075 <para>
2076 This section specifies how you want specific DLLs to be
2077 handled, in particular whether you want to use "native" DLLs
2078 or not, if you have some from a real Windows configuration.
2079 Because built-ins do not mix seamlessly with native DLLs yet,
2080 certain DLL dependencies may be problematic, but workarounds
2081 exist in Wine for many popular DLL configurations. Also see
2082 WWN's [16]Status Page to figure out how well your favorite
2083 DLL is implemented in Wine.
2084 </para>
2085 <para>
2086 It is of course also possible to override these settings by
2088 command-line option (see the man page for details). Some
2089 hints for choosing your optimal configuration (listed by
2091 </para>
2092 <variablelist>
2093 <varlistentry>
2095 <listitem> <para>
2096 Native versions of these will never work, so don't try. Leave
2098 </para> </listitem>
2099 </varlistentry>
2100 <varlistentry>
2102 <listitem> <para>
2103 Graphics Device Interface. No effort has been made at trying to
2105 </para> </listitem>
2106 </varlistentry>
2107 <varlistentry>
2109 <listitem> <para>
2110 Window management and standard controls. It was
2112 versions at some point (if all other DLLs that depend
2113 on it, such as comctl32 and comdlg32, were also run
2115 possible after the Address Space Separation, so leave
2117 </para> </listitem>
2118 </varlistentry>
2119 <varlistentry>
2121 <listitem> <para>
2122 NT kernel API. Although badly documented, the
2125 </para> </listitem>
2126 </varlistentry>
2127 <varlistentry>
2129 <listitem> <para>
2131 version will probably never work. Leave at
2133 </para> </listitem>
2134 </varlistentry>
2135 <varlistentry>
2137 <listitem> <para>
2138 Win16 support library for NT. The
2141 </para> </listitem>
2142 </varlistentry>
2143 <varlistentry>
2145 <listitem> <para>
2146 Win16 kernel stuff. Will never work
2149 </para> </listitem>
2150 </varlistentry>
2151 <varlistentry>
2153 <listitem> <para>
2155 </para> </listitem>
2156 </varlistentry>
2157 <varlistentry>
2159 <listitem> <para>
2160 Tool helper routines. This is rarely a source of problems.
2162 </para> </listitem>
2163 </varlistentry>
2164 <varlistentry>
2166 <listitem> <para>
2167 Versioning. Seldom useful to mess with.
2168 </para> </listitem>
2169 </varlistentry>
2170 <varlistentry>
2172 <listitem> <para>
2173 Registry and security features. Trying the
2175 not work.
2176 </para> </listitem>
2177 </varlistentry>
2178 <varlistentry>
2180 <listitem> <para>
2181 Common Dialogs, such as color picker, font dialog,
2182 print dialog, open/save dialog, etc. It is safe to try
2184 </para> </listitem>
2185 </varlistentry>
2186 <varlistentry>
2188 <listitem> <para>
2189 Common Controls. This is toolbars, status bars, list controls,
2191 </para> </listitem>
2192 </varlistentry>
2193 <varlistentry>
2195 <listitem> <para>
2196 Shell interface (desktop, filesystem, etc). Being one of the
2197 most undocumented pieces of Windows, you may have luck with the
2199 </para> </listitem>
2200 </varlistentry>
2201 <varlistentry>
2203 <listitem> <para>
2205 will not work under Wine, so leave at
2207 </para> </listitem>
2208 </varlistentry>
2209 <varlistentry>
2211 <listitem> <para>
2212 ICMP routines for wsock32. As with wsock32, leave at
2214 </para> </listitem>
2215 </varlistentry>
2216 <varlistentry>
2218 <listitem> <para>
2220 to thunking issues. Leave at
2222 </para> </listitem>
2223 </varlistentry>
2224 <varlistentry>
2226 <listitem> <para>
2227 Lempel-Ziv decompression. Wine's
2229 </para> </listitem>
2230 </varlistentry>
2231 <varlistentry>
2233 <listitem> <para>
2234 Advanced SCSI Peripheral Interface. The
2237 </para> </listitem>
2238 </varlistentry>
2239 <varlistentry>
2241 <listitem> <para>
2243 version will easily work better than Wine's on this
2244 one.
2245 </para> </listitem>
2246 </varlistentry>
2247 <varlistentry>
2249 <listitem> <para>
2250 Printer spooler. You are not likely to have more luck
2252 </para> </listitem>
2253 </varlistentry>
2254 <varlistentry>
2256 <listitem> <para>
2257 DirectDraw/Direct3D. Since Wine does not implement the
2259 will not work at this time.
2260 </para> </listitem>
2261 </varlistentry>
2262 <varlistentry>
2264 <listitem> <para>
2266 may or may not work.
2267 </para> </listitem>
2268 </varlistentry>
2269 <varlistentry>
2271 <listitem> <para>
2272 DirectSound. It may be possible to run this
2274 </para> </listitem>
2275 </varlistentry>
2276 <varlistentry>
2278 <listitem> <para>
2280 ought to work best on this, if at all.
2281 </para> </listitem>
2282 </varlistentry>
2283 <varlistentry>
2285 <listitem> <para>
2287 version is not likely to work. Leave at
2289 </para> </listitem>
2290 </varlistentry>
2291 <varlistentry>
2293 <listitem> <para>
2294 Audio Compression Manager. The
2296 set msacm.drv to the same.
2297 </para> </listitem>
2298 </varlistentry>
2299 <varlistentry>
2301 <listitem> <para>
2302 Video for Windows. It is safe (and recommended) to try
2304 </para> </listitem>
2305 </varlistentry>
2306 <varlistentry>
2308 <listitem> <para>
2309 CD Audio MCI driver.
2310 </para> </listitem>
2311 </varlistentry>
2312 <varlistentry>
2314 <listitem> <para>
2316 playback).
2317 </para> </listitem>
2318 </varlistentry>
2319 <varlistentry>
2321 <listitem> <para>
2323 </para> </listitem>
2324 </varlistentry>
2325 <varlistentry>
2327 <listitem> <para>
2330 </para> </listitem>
2331 </varlistentry>
2332 <varlistentry>
2334 <listitem> <para>
2335 Animation MCI driver.
2336 </para> </listitem>
2337 </varlistentry>
2338 <varlistentry>
2340 <listitem> <para>
2341 Audio Compression Manager. Set to same as msacm32.
2342 </para> </listitem>
2343 </varlistentry>
2344 <varlistentry>
2346 <listitem> <para>
2347 MIDI Mapper.
2348 </para> </listitem>
2349 </varlistentry>
2350 <varlistentry>
2352 <listitem> <para>
2353 This is a pseudo-DLL used by Wine for thunking
2355 doesn't exist.
2356 </para> </listitem>
2357 </varlistentry>
2358 </variablelist>
2359 </sect3>
2360 </sect2>
2364 <para>
2365 The Wine team has determined that it is necessary to create
2366 fake DLL files to trick many programs that check for
2367 file existence to determine whether a particular feature
2368 (such as Winsock and its TCP/IP networking) is available. If
2369 this is a problem for you, you can create empty files in the
2371 to make the program think it's there, and Wine's built-in DLL
2372 will be loaded when the program actually asks for it.
2374 not create such empty files itself.)
2375 </para>
2376 <para>
2377 Applications sometimes also try to inspect the version
2378 resources from the physical files (for example, to determine
2379 the DirectX version). Empty files will not do in this case,
2380 it is rather necessary to install files with complete
2381 version resources. This problem is currently being worked
2382 on. In the meantime, you may still need to grab some real
2383 DLL files to fool these apps with.
2384 </para>
2385 <para>
2386 And there are of course DLLs that wine does not currently
2387 implement very well (or at all). If you do not have a real
2388 Windows you can steal necessary DLLs from, you can always
2389 get some from one of the Windows DLL archive sites
2390 that can be found via internet search engine.
2391 Please make sure to obey any licenses on the DLLs you fetch...
2392 (some are redistributable, some aren't).
2393 </para>
2394 </sect2>
2399 <para>
2400 In case Wine complains about a missing DLL, you should check whether
2401 this file is a publicly available DLL or a custom DLL belonging
2402 to your program (by searching for its name on the internet).
2403 If you managed to get hold of the DLL, then you should make sure
2404 that Wine is able to find and load it.
2405 DLLs usually get loaded according to the mechanism of the
2406 SearchPath() function.
2407 This function searches directories in the following order:
2409 <orderedlist>
2410 <listitem>
2411 <para>
2412 The directory the program was started from.
2413 </para>
2414 </listitem>
2415 <listitem>
2416 <para>
2417 The current directory.
2418 </para>
2419 </listitem>
2420 <listitem>
2421 <para>
2422 The Windows system directory.
2423 </para>
2424 </listitem>
2425 <listitem>
2426 <para>
2427 The Windows directory.
2428 </para>
2429 </listitem>
2430 <listitem>
2431 <para>
2432 The PATH variable directories.
2433 </para>
2434 </listitem>
2435 </orderedlist>
2437 In short: either put the required DLL into your program
2438 directory (might be ugly), or usually put it into the Windows system
2439 directory. Just find out its directory by having a look at the Wine
2440 configuration file variable "System" (which indicates the location of the
2441 Windows system directory) and the associated drive entry.
2442 Note that you probably shouldn't use NT-based native DLLs,
2443 since Wine's NT API support is somewhat weaker than its Win9x
2444 API support (thus leading to even worse compatibility with NT DLLs
2445 than with a no-windows setup!), so better use Win9x native DLLs
2446 instead or no native DLLs at all.
2447 </para>
2448 </sect2>
2453 <para>
2455 extract native Windows .dll files from .cab files that are to be
2456 found on many Windows installation CDs.
2457 </para>
2458 </sect2>
2459 </sect1>
2464 <para>
2465 Wine currently supports several different display subsystems
2466 (graphics / text) that are available on various operating
2467 systems today.
2468 For each of these, Wine implements its own interfacing driver.
2469 This section explains how to select one of these drivers
2470 and how to further configure the respective driver.
2471 Once you're finished with that, you can consider your Wine installation
2472 to be finished.
2473 </para>
2475 <para>
2476 The display drivers currently implemented in Wine are:
2477 x11drv, which is used for interfacing to X11 graphics
2478 (the one you'll most likely want to use) and ttydrv
2479 (used for text mode console apps mainly that don't really need
2480 any graphics output).
2481 Once you have decided which display driver to use, it is chosen
2484 </para>
2486 <sect2>
2489 <sect3>
2492 <para>
2493 The x11drv driver consists of two conceptually distinct
2494 pieces, the graphics driver (GDI part), and the windowing
2495 driver (USER part). Both of these are linked into the
2498 Wine, running on X11, the graphics driver must draw on
2499 drawables (window interiors) provided by the windowing
2500 driver. This differs a bit from the Windows model, where the
2501 windowing system creates and configures device contexts
2502 controlled by the graphics driver, and programs are
2503 allowed to hook into this relationship anywhere they like.
2504 Thus, to provide any reasonable tradeoff between
2505 compatibility and usability, the x11drv has three different
2506 modes of operation.
2507 </para>
2509 <variablelist>
2510 <varlistentry>
2512 <listitem>
2513 <para>
2515 wine configuration file option (see below).
2516 Ordinary top-level frame windows with thick borders,
2517 title bars, and system menus will be managed by your
2518 window manager. This lets these programs integrate
2519 better with the rest of your desktop, but may not
2520 always work perfectly (a rewrite of this mode of
2521 operation, to make it more robust and less patchy, is
2522 currently being done, though, and it's planned to be
2523 finished before the Wine 1.0 release).
2524 </para>
2525 </listitem>
2526 </varlistentry>
2527 <varlistentry>
2529 <listitem>
2530 <para>
2531 Window manager independent (any running
2532 window manager is ignored completely). Window
2533 decorations (title bars, borders, etc) are drawn by
2534 Wine to look and feel like the real Windows. This is
2535 compatible with programs that depend on being able
2536 to compute the exact sizes of any such decorations, or
2537 that want to draw their own.
2538 Unmanaged mode is only used if both Managed and Desktop
2539 are set to disabled.
2540 </para>
2541 </listitem>
2542 </varlistentry>
2543 <varlistentry>
2545 <listitem>
2546 <para>
2548 wine configuration file option (see below).
2550 for a such-sized desktop, or
2552 automatically position the desktop at the upper-left
2553 corner of the display). This is the mode most
2554 compatible with the Windows model. All program
2555 windows will just be Wine-drawn windows inside the
2556 Wine-provided desktop window (which will itself be
2557 managed by your window manager), and Windows
2558 programs can roam freely within this virtual
2559 workspace and think they own it all, without
2560 disturbing your other X apps.
2561 Note: currently there's one desktop window for every
2562 program; this will be fixed at some time.
2563 </para>
2564 </listitem>
2565 </varlistentry>
2566 </variablelist>
2567 </sect3>
2569 <sect3>
2572 <variablelist>
2573 <varlistentry>
2575 <listitem>
2576 <para>
2577 Wine can let frame windows be managed by your window
2578 manager. This option specifies whether you want that
2579 by default.
2580 </para>
2581 </listitem>
2582 </varlistentry>
2583 <varlistentry>
2585 <listitem>
2586 <para>
2587 Creates a main desktop window of a specified size
2588 to display all Windows programs in.
2589 The size argument could e.g. be "800x600".
2590 </para>
2591 </listitem>
2592 </varlistentry>
2593 <varlistentry>
2595 <listitem>
2596 <para>
2597 If you don't use DGA, you may want an alternative
2598 means to convince the mouse cursor to stay within the
2599 game window. This option does that. Of course, as with
2600 DGA, if Wine crashes, you're in trouble (although not
2601 as badly as in the DGA case, since you can still use
2602 the keyboard to get out of X).
2603 </para>
2604 </listitem>
2605 </varlistentry>
2606 <varlistentry>
2608 <listitem>
2609 <para>
2610 This specifies whether you want DirectDraw to use
2611 XFree86's <firstterm>Direct Graphics
2612 Architecture</firstterm> (DGA), which is able to
2613 take over the entire display and run the game
2614 full-screen at maximum speed. (With DGA1 (XFree86
2615 3.x), you still have to configure the X server to the
2616 game's requested bpp first, but with DGA2 (XFree86
2617 4.x), runtime depth-switching may be possible,
2618 depending on your driver's capabilities.) But be aware
2619 that if Wine crashes while in DGA mode, it may not be
2620 possible to regain control over your computer without
2621 rebooting. DGA normally requires either root
2622 privileges or read/write access to
2624 </para>
2625 </listitem>
2626 </varlistentry>
2627 <varlistentry>
2629 <listitem>
2630 <para>
2631 Applies only if you use the
2633 to run in a desktop window. Specifies whether to
2634 create the desktop window with a double-buffered
2635 visual, something most OpenGL games need to run
2636 correctly.
2637 </para>
2638 </listitem>
2639 </varlistentry>
2640 <varlistentry>
2642 <listitem>
2643 <para>
2644 Applies only if you have a palette-based display, i.e.
2645 if your X server is set to a depth of 8bpp, and if you
2646 haven't requested a private color map. It specifies
2647 the maximum number of shared colormap cells (palette
2648 entries) Wine should occupy. The higher this value,
2649 the less colors will be available to other
2650 programs.
2651 </para>
2652 </listitem>
2653 </varlistentry>
2654 <varlistentry>
2656 <listitem>
2657 <para>
2658 Applies only if you have a palette-based display, i.e.
2659 if your X server is set to a depth of 8bpp. It
2660 specifies that you don't want to use the shared color
2661 map, but a private color map, where all 256 colors are
2662 available. The disadvantage is that Wine's private
2663 color map is only seen while the mouse pointer is
2664 inside a Wine window, so psychedelic flashing and
2665 funky colors will become routine if you use the mouse
2666 a lot.
2667 </para>
2668 </listitem>
2669 </varlistentry>
2670 <varlistentry>
2672 <listitem>
2673 <para>
2674 To be used for debugging X11 operations.
2675 If Wine crashes with an X11 error, then you should enable
2676 Synchronous mode to disable X11 request caching in order
2677 to make sure that the X11 error happens directly after
2678 the corresponding X11 call in the log file appears.
2679 Will slow down X11 output!
2680 </para>
2681 </listitem>
2682 </varlistentry>
2683 <varlistentry>
2685 <listitem>
2686 <para>
2687 Applies only to multi-depth displays. It specifies
2688 which of the available depths Wine should use (and
2689 tell Windows apps about).
2690 </para>
2691 </listitem>
2692 </varlistentry>
2693 <varlistentry>
2695 <listitem>
2696 <para>
2697 This specifies which X11 display to use, and if
2698 specified, will override the
2700 </para>
2701 </listitem>
2702 </varlistentry>
2703 <varlistentry>
2705 <listitem>
2706 <para>
2707 This option only determines whether fast X11 routines
2708 or exact Wine routines will be used for certain ROP
2709 codes in blit operations. Most users won't notice any
2710 difference.
2711 </para>
2712 </listitem>
2713 </varlistentry>
2714 </variablelist>
2715 </sect3>
2716 </sect2>
2718 <sect2>
2720 <para>
2721 Currently, the ttydrv doesn't have any special configuration
2722 options to set in the configuration file.
2723 </para>
2724 </sect2>
2726 </sect1>
2732 <para>
2733 The windows and DOS version value a program gets e.g. by calling the
2734 Windows function GetVersion() plays a very important role:
2735 If your Wine installation for whatever reason fails to provide
2736 to your program the correct version value that it expects,
2737 then the program might assume some very bad things and fail (in
2738 the worst case even silently!).
2740 Fortunately Wine contains some more or less intelligent Windows
2741 version guessing algorithm that will try to guess the Windows
2742 version a program might expect and pass that one on to the
2743 program.
2745 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.
2746 </para>
2748 <sect2>
2749 <title>How to configure the Windows and DOS version value Wine
2750 should return</title>
2752 <para>
2753 The version values can be configured in the wine configuration file in
2754 the [Version] section.
2755 </para>
2757 <variablelist>
2758 <varlistentry>
2760 <listitem>
2761 <para>
2762 default: none; chosen by semi-intelligent detection
2763 mechanism based on DLL environment.
2764 Used to specify which Windows version to return to
2765 programs (forced value, overrides standard detection
2768 Also valid as an
2770 setting (recommended/preferred use).
2771 </para>
2772 </listitem>
2773 </varlistentry>
2774 <varlistentry>
2776 <listitem>
2777 <para>
2778 Used to specify the DOS version that should be returned
2779 to programs. Only takes effect in case Wine acts as
2780 "win31" Windows version! Common DOS version settings
2782 Also valid as an
2784 setting (recommended/preferred use).
2785 </para>
2786 </listitem>
2787 </varlistentry>
2788 </variablelist>
2789 </sect2>
2790 </sect1>
2792 &fonts;
2793 &printing;
2797 <para>
2798 Instead of compiling Wine for Win3.1 vs. Win95 using
2800 special [Tweak.Layout] section of
2804 </para>
2805 <para>
2806 A few new sections and a number of entries have been added to
2808 debugging the Win95 tweaks only and may be removed in a future
2809 release! These entries/sections are:
2810 </para>
2811 <programlisting>
2812 [Tweak.Fonts]
2818 "OEMFixed.xxx" # Same parameters for the OEM fixed typeface
2819 "AnsiFixed.xxx" # Same parameters for the Ansi fixed typeface
2820 "AnsiVar.xxx" # Same parameters for the Ansi variable typeface
2821 "SystemFixed.xxx" # Same parameters for the System fixed typeface
2823 [Tweak.Layout]
2825 </programlisting>
2826 </sect1>
2831 <para>
2832 Wine now needs to know about your keyboard layout. This
2833 requirement comes from a need from many apps to have the
2834 correct scancodes available, since they read these directly,
2835 instead of just taking the characters returned by the X
2836 server. This means that Wine now needs to have a mapping from
2837 X keys to the scancodes these programs expect.
2838 </para>
2839 <para>
2840 On startup, Wine will try to recognize the active X layout by
2841 seeing if it matches any of the defined tables. If it does,
2842 everything is alright. If not, you need to define it.
2843 </para>
2844 <para>
2845 To do this, open the file
2847 at the existing tables. Make a backup copy of it, especially
2848 if you don't use CVS.
2849 </para>
2850 <para>
2851 What you really would need to do, is find out which scancode
2852 each key needs to generate. Find it in the
2854 this:
2855 </para>
2856 <programlisting>
2857 static const int main_key_scan[MAIN_LEN] =
2858 {
2859 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
2865 };
2866 </programlisting>
2867 <para>
2868 Next, assign each scancode the characters imprinted on the
2869 keycaps. This was done (sort of) for the US 101-key keyboard,
2870 which you can find near the top in
2872 is no 102nd key, you can skip that.
2873 </para>
2874 <para>
2875 However, for most international 102-key keyboards, we have
2876 done it easy for you. The scancode layout for these already
2877 pretty much matches the physical layout in the
2879 to go through all the keys that generate characters on your
2880 main keyboard (except spacebar), and stuff those into an
2881 appropriate table. The only exception is that the 102nd key,
2882 which is usually to the left of the first key of the last line
2884 line after the last line.
2885 </para>
2886 <para>
2887 For example, my Norwegian keyboard looks like this
2888 </para>
2889 <screen>
2890 § ! " # ¤ % & / ( ) = ? ` Back-
2891 | 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
2893 Tab Q W E R T Y U I O P Å ^
2894 ¨~
2895 Enter
2896 Caps A S D F G H J K L Ø Æ *
2897 Lock '
2899 Sh- > Z X C V B N M ; : _ Shift
2900 ift < , . -
2902 Ctrl Alt Spacebar AltGr Ctrl
2903 </screen>
2904 <para>
2905 Note the 102nd key, which is the <keycap><></keycap> key, to
2906 the left of <keycap>Z</keycap>. The character to the right of
2907 the main character is the character generated by
2908 <keycap>AltGr</keycap>.
2909 </para>
2910 <para>
2911 This keyboard is defined as follows:
2912 </para>
2913 <programlisting>
2914 static const char main_key_NO[MAIN_LEN][4] =
2915 {
2920 "<>"
2921 };
2922 </programlisting>
2923 <para>
2924 Except that " and \ needs to be quoted with a backslash, and
2925 that the 102nd key is on a separate line, it's pretty
2926 straightforward.
2927 </para>
2928 <para>
2929 After you have written such a table, you need to add it to the
2930 <function>main_key_tab[]</function> layout index table. This
2931 will look like this:
2932 </para>
2933 <programlisting>
2934 static struct {
2935 WORD lang, ansi_codepage, oem_codepage;
2936 const char (*key)[MAIN_LEN][4];
2937 } main_key_tab[]={
2938 ...
2939 ...
2940 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
2941 ...
2942 </programlisting>
2943 <para>
2944 After you have added your table, recompile Wine and test that
2945 it works. If it fails to detect your table, try running
2946 </para>
2947 <screen>
2948 wine --debugmsg +key,+keyboard >& key.log
2949 </screen>
2950 <para>
2951 and look in the resulting <filename>key.log</filename> file to
2952 find the error messages it gives for your layout.
2953 </para>
2954 <para>
2955 Note that the <constant>LANG_*</constant> and
2956 <constant>SUBLANG_*</constant> definitions are in
2957 <filename>include/winnls.h</filename>, which you might need to
2958 know to find out which numbers your language is assigned, and
2959 find it in the debugmsg output. The numbers will be
2960 <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
2961 the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
2962 <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
2963 <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
2964 could look for <literal>0414</literal> in the debugmsg output
2965 to find out why my keyboard won't detect.
2966 </para>
2967 <para>
2968 Once it works, submit it to the Wine project. If you use CVS,
2969 you will just have to do
2970 </para>
2971 <screen>
2972 cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
2973 </screen>
2974 <para>
2975 from your main Wine directory, then submit
2976 <filename>layout.diff</filename> to
2977 <email>wine-patches@winehq.com</email> along with a brief note
2978 of what it is.
2979 </para>
2980 <para>
2981 If you don't use CVS, you need to do
2982 </para>
2983 <screen>
2984 diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
2985 </screen>
2986 <para>
2987 and submit it as explained above.
2988 </para>
2989 <para>
2990 If you did it right, it will be included in the next Wine
2991 release, and all the troublesome programs (especially
2992 remote-control programs) and games that use scancodes will
2993 be happily using your keyboard layout, and you won't get those
2994 annoying fixme messages either.
2995 </para>
2996 <para>
2997 Good luck.
2998 </para>
2999 </sect1>
3002 <title>SCSI Support</title>
3003 <para>
3004 This file describes setting up the Windows ASPI interface.
3005 </para>
3007 <para>
3008 <warning><title>Warning/Warning/Warning!!!!!!</title>
3009 <para>This may trash your system if used incorrectly. It may
3010 even trash your system when used <emphasis>correctly</>!
3011 </para>
3012 </warning>
3013 </para>
3015 <para>
3016 Now that I have said that. ASPI is a direct link to SCSI devices from
3017 windows programs. ASPI just forwards the SCSI commands that programs send
3018 to it to the SCSI bus.
3019 </para>
3020 <para>
3021 If you use the wrong SCSI device in your setup file, you can send
3022 completely bogus commands to the wrong device - An example would be
3023 formatting your hard drives (assuming the device gave you permission -
3024 if you're running as root, all bets are off).
3025 </para>
3026 <para>
3027 So please make sure that <emphasis>all</emphasis> SCSI devices not needed by the program
3028 have their permissions set as restricted as possible!
3029 </para>
3031 <para>
3032 Cookbook for setting up scanner: (At least how mine is to work)
3033 (well, for other devices such as CD burners, MO drives, ..., too)
3034 </para>
3036 <sect2>
3037 <title>Windows requirements</title>
3038 <orderedlist>
3039 <listitem>
3040 <para>
3042 compatible drivers (ASPI). At least with Mustek, they
3043 allow you the choice of using the built-in card or the
3045 any other way. Software that accesses the scanner via a
3046 DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM]
3047 </para>
3048 </listitem>
3049 <listitem>
3050 <para>
3051 You probably need a real windows install of the software
3052 to set the LUN's/SCSI id's up correctly. I'm not exactly
3053 sure.
3054 </para>
3055 </listitem>
3056 </orderedlist>
3057 </sect2>
3059 <sect2>
3060 <title>Linux requirements</title>
3061 <orderedlist>
3062 <listitem>
3063 <para>
3064 Your SCSI card must be supported under Linux. This will
3065 not work with an unknown SCSI card. Even for cheap'n
3067 drivers exist on the net.
3068 If you intend to use your IDE device, you need to use the
3069 ide-scsi emulation.
3070 Read
3072 http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html</ulink>
3073 for ide-scsi setup instructions.
3074 </para>
3075 </listitem>
3076 <listitem>
3077 <para>
3078 Compile generic SCSI drivers into your kernel.
3079 </para>
3080 </listitem>
3081 <listitem>
3082 <para>
3083 This seems to be not required any more for newer (2.2.x) kernels:
3084 Linux by default uses smaller SCSI buffers than Windows.
3085 There is a kernel build define <literal>SG_BIG_BUFF</literal> (in
3086 <filename>sg.h</filename>) that is by default set too
3087 low. The SANE project recommends
3088 <literal>130560</literal> and this seems to work just
3089 fine. This does require a kernel rebuild.
3090 </para>
3091 </listitem>
3092 <listitem>
3093 <para>
3094 Make the devices for the scanner (generic SCSI devices)
3095 - look at the SCSI programming HOWTO at
3097 http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html</ulink>
3098 for device numbering.
3099 </para>
3100 </listitem>
3101 <listitem>
3102 <para>
3103 I would recommend making the scanner device writable by
3104 a group. I made a group called
3105 <literal>scanner</literal> and added myself to it.
3106 Running as root increases your risk of sending bad SCSI
3107 commands to the wrong device. With a regular user, you
3108 are better protected.
3109 </para>
3110 </listitem>
3111 <listitem>
3112 <para>
3113 For Win32 software (WNASPI32), Wine has auto-detection in place.
3114 For Win16 software (WINASPI), you need to add a SCSI device entry
3115 for your particular scanner to ~/.wine/config. The format is
3116 <literal>[scsi cCtTdD]</literal> where
3119 </para>
3120 <para>
3121 For example, I set mine up as controller <literal>0</literal>,
3122 Target <literal>6</literal>, LUN <literal>0</literal>.
3123 <programlisting>
3124 [scsi c0t6d0]
3126 </programlisting>
3127 Yours will vary with your particular SCSI setup.
3128 </para>
3129 </listitem>
3130 </orderedlist>
3131 </sect2>
3133 <sect2>
3134 <title>General Information</title>
3135 <para>
3136 The mustek scanner I have was shipped with a package
3138 to access scanners.
3139 </para>
3140 <para>
3141 (TWAIN MANAGER)
3142 </para>
3143 <para>
3144 <programlisting>
3145 ipplus.exe <-> (TWAIN INTERFACE) <-> (TWAIN DATA SOURCE.ASPI) -> WINASPI
3146 </programlisting>
3147 </para>
3148 </sect2>
3150 <sect2>
3151 <title>NOTES/BUGS</title>
3152 <para>
3153 The biggest drawback is that it only works under Linux at the moment.
3154 </para>
3155 <para>
3156 The ASPI code has only been tested with:
3157 </para>
3158 <itemizedlist>
3159 <listitem>
3160 <para>
3161 a Mustek 800SP with a Buslogic controller under Linux [BM]
3162 </para>
3163 </listitem>
3164 <listitem>
3165 <para>
3166 a Siemens Nixdorf 9036 with Adaptec AVA-1505 under Linux
3167 accessed via DOSASPI. Note that I had color problems,
3168 though (barely readable result) [AM]
3169 </para>
3170 </listitem>
3171 <listitem>
3172 <para>
3173 a Fujitsu M2513A MO drive (640MB) using generic SCSI
3174 drivers. Formatting and ejecting worked perfectly.
3175 Thanks to Uwe Bonnes for access to the hardware! [AM]
3176 </para>
3177 </listitem>
3178 </itemizedlist>
3179 <para>
3180 I make no warranty to the ASPI code. It makes my scanner
3181 work. Your devices may explode. I have no way of determining
3182 this. I take zero responsibility!
3183 </para>
3184 </sect2>
3185 </sect1>
3188 <title>Using ODBC</title>
3189 <para>
3190 This section describes how ODBC works within Wine and how to configure
3191 it to do what you want (if it can do what you want).
3192 </para>
3193 <para>
3194 The ODBC system within Wine, as with the printing system, is designed
3195 to hook across to the Unix system at a high level. Rather than
3196 ensuring that all the windows code works under wine it uses a suitable
3197 Unix ODBC provider, such as UnixODBC. Thus if you configure Wine to
3198 use the built-in odbc32.dll, that Wine DLL will interface to your
3199 Unix ODBC package and let that do the work, whereas if you configure
3200 Wine to use the native odbc32.dll it will try to use the native
3201 ODBC32 drivers etc.
3202 </para>
3203 <sect2>
3204 <title>Using a Unix ODBC system with Wine</title>
3205 <para>
3206 The first step in using a Unix ODBC system with Wine is, of course,
3207 to get the Unix ODBC system working itself. This may involve
3208 downloading code or RPMs etc. There are several Unix ODBC systems
3209 available; the one the author is used to is unixODBC (with the
3210 IBM DB2 driver). Typically such systems will include a tool, such
3211 as <command>isql</command>, which will allow you to access the data from the command
3212 line so that you can check that the system is working.
3213 </para>
3214 <para>
3215 The next step is to hook the Unix ODBC library to the wine built-in
3216 odbc32 DLL. The built-in odbc32 (currently) looks to the
3217 environment variable <emphasis>LIB_ODBC_DRIVER_MANAGER</emphasis>
3218 for the name of the ODBC library. For example in the author's
3219 .bashrc file is the line:
3220 </para>
3221 <programlisting>
3222 export LIB_ODBC_DRIVER_MANAGER=/usr/lib/libodbc.so.1.0.0
3223 </programlisting>
3224 <para>
3225 If that environment variable is not set then it looks for a
3226 library called libodbc.so and so you can add a symbolic link to
3227 equate that to your own library. For example as root you could
3228 run the commands:
3229 </para>
3230 <screen>
3231 <prompt># </prompt><userinput>ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so</userinput>
3232 <prompt># </prompt><userinput>/sbin/ldconfig</userinput>
3233 </screen>
3234 <para>
3235 The last step in configuring this is to ensure that Wine is set up
3236 to run the built-in version of odbc32.dll, by modifying the DLL
3237 configuration. This built-in DLL merely acts as a stub between the
3238 calling code and the Unix ODBC library.
3239 </para>
3240 <para>
3241 If you have any problems then you can use the debugmsg channel
3242 odbc32 to trace what is happening. One word of warning. Some
3243 programs actually cheat a little and bypass the ODBC library. For
3244 example the Crystal Reports engine goes to the registry to check on
3245 the DSN. The fix for this is documented at unixODBC's site where
3246 there is a section on using unixODBC with Wine.
3247 </para>
3248 </sect2>
3249 <sect2>
3250 <title>Using Windows ODBC drivers</title>
3251 <para>
3252 Does anyone actually have any experience of this and anything to
3253 add?
3254 </para>
3255 </sect2>
3256 </sect1>
3258 </chapter>
3260 <!-- Keep this comment at the end of the file
3261 Local variables:
3262 mode: sgml
3264 End:
3265 -->