| blob | 5a5ea419f84454304ebc393750b8cc45bdf913fa |
3 <para>
4 Now that you hopefully managed to successfully install
5 the Wine program files,
6 this chapter will tell you how to configure the Wine environment
7 properly to run your Windows programs.
8 </para>
9 <para>
10 First, we'll give you an overview about which kinds of
11 configuration and program execution aspects a fully configured
12 Windows environment has to fulfill in order to ensure that many
13 Windows programs run successfully without encountering any
14 misconfigured or missing items.
15 Next, we'll show you which easy helper programs exist
16 to enable even novice users to complete the Wine environment
17 configuration in a fast and easy way.
18 The next section will explain the purpose of the Wine configuration file,
19 and we'll list all of its settings.
20 After that, the next section will detail the most important and
21 unfortunately most difficult configuration part:
22 how to configure the file system and DOS drive environment that
23 Windows programs need.
24 In the last step we'll tell you how to establish a working Windows
25 registry base.
26 Finally, the remaining parts of this chapter contain descriptions
27 of specific Wine configuration items that might also be
28 of interest to you.
29 </para>
34 <para>
35 Formerly a part of: "WWN #52 Feature: Replacing Windows".
37 </para>
39 <para>
40 A Windows installation is a very complex structure. It consists of
41 many different parts with very different functionality.
42 We'll try to outline the most important aspects of it.
43 </para>
45 <itemizedlist>
46 <listitem>
47 <para>
48 Registry. Many keys are supposed to exist and contain
49 meaningful data, even in a newly-installed Windows.
50 </para>
51 </listitem>
52 <listitem>
53 <para>
54 Directory structure. Applications expect to find and/or
55 install things in specific predetermined locations. Most
56 of these directories are expected to exist. But unlike
57 Unix directory structures, most of these locations are
58 not hardcoded, and can be queried via the Windows API
59 and the registry. This places additional requirements on
60 a Wine installation.
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 System DLLs. In Windows, these usually reside in the
68 programs check for their existence in these
69 directories before attempting to load them. While Wine
70 is able to load its own internal DLLs
72 asks for a DLL, Wine does not simulate the presence of
73 non-existent files.
74 </para>
75 </listitem>
76 </itemizedlist>
78 <para>
79 While the users are of course free to set up everything
80 themselves, the Wine team will make the automated Wine source
82 do everything we find necessary to do; running the
83 conventional <userinput>configure && make depend && make && make
84 install</userinput> cycle is thus not recommended, unless
85 you know what you're doing. At the moment,
87 configuration file, install the registry, and create the
88 directory structure itself.
89 </para>
91 </sect1>
96 <para>
97 Managing the Wine configuration file settings can be a
98 difficult task, sometimes too difficult for some people.
99 That's why there are some helper applications for easily setting up an
100 initial wine configuration file with useful default settings.
101 </para>
105 <para>
106 WineSetupTk is a graphical Wine configuration tool with
107 incredibly easy handling of Wine configuration issues, to be
108 used for configuring the Wine environment after having
109 installed the Wine files.
110 It has been written by CodeWeavers in 2000 as part of a host
111 of other efforts to make Wine more desktop oriented.
112 </para>
113 <para>
114 If you're using Debian, simply install the winesetuptk
115 package (as root):
116 </para>
117 <screen>
119 </screen>
120 <para>
121 If you're using another distribution, search for the package on
122 the net.
123 </para>
124 </sect2>
128 <para>
131 source code tree. It has been written to allow for an easy
132 and complete compilation/installation of Wine source code for
133 people who don't bother with reading heaps of very valuable
134 and informative documentation ;-)
135 </para>
136 <para>
137 Once you have successfully extracted the Wine source code
138 tree, change to the main directory of it and then run (as
139 user):
140 </para>
141 <screen>
143 </screen>
144 <para>
145 Doing so will compile Wine, install Wine and configure the
146 Wine environment (either by providing access to a Windows
147 partition or by creating a properly configured no-windows
148 directory environment).
149 </para>
150 </sect2>
154 <para>
157 source code tree. It is a Winelib app making use of standard
158 Win32 GUI controls to easily customize entries in a Wine
159 configuration file.
160 </para>
161 </sect2>
162 </sect1>
167 <para>
168 After you finished configuring Wine, you may run a Perl
170 in Wine's tools/ directory. It tries to check your
171 configuration's correctness by checking for some popular
172 problems.
174 The latest version can always be found at
175 <ulink url="http://home.arcor.de/andi.mohr/download/winecheck">http://home.arcor.de/andi.mohr/download/winecheck</ulink>.
178 </para>
179 <screen>
182 </screen>
183 <para>
184 The winecheck output will be a percentage score indicating Wine
185 configuration correctness.
186 Note that winecheck is only alpha, so it's not very complete or
187 100% accurate.
188 </para>
190 <para>
191 If this yields a "good" percentage score, then you can consider
192 your Wine installation to be finished successfully:
193 Congratulations!
194 Otherwise (or if there are still some configuration problems
196 configuration documentation below to find out more about some
198 chapter</link>.
199 </para>
200 </sect1>
204 <para>
205 This section is meant to contain both an easy step-by-step introduction
206 to the Wine configuration file (for new Wine users)
207 and a complete reference to all Wine configuration file settings (for
208 advanced users).
209 </para>
210 <para>
213 </para>
215 <sect2>
217 <para>
218 The Wine configuration file is the central file to store
219 configuration settings for Wine.
222 of your user's home directory
225 Note that since the Wine configuration file is a part of the
226 Wine registry file system, this file also
228 Version 2" header line to be recognized properly, just like
229 all other Wine registry text files (just in case you decided
230 to write your own registry file from scratch and wonder why
231 Wine keeps rejecting it).
232 </para>
233 <para>
234 The settings available in the configuration file include:
235 <itemizedlist>
236 <listitem>
237 <para>
238 Drives and information about them
239 </para>
240 </listitem>
241 <listitem>
242 <para>
243 Directory settings
244 </para>
245 </listitem>
246 <listitem>
247 <para>
248 Port settings
249 </para>
250 </listitem>
251 <listitem>
252 <para>
253 The Wine look and feel
254 </para>
255 </listitem>
256 <listitem>
257 <para>
258 Wine's DLL usage
259 </para>
260 </listitem>
261 <listitem>
262 <para>
263 Wine's multimedia drivers and DLL configuration
264 </para>
265 </listitem>
266 </itemizedlist>
267 </para>
268 </sect2>
270 <sect2>
272 <para>
273 If you just installed Wine for the first time and want to
274 finish Wine installation by configuring it now, then you could
276 (which can be found in the directory
278 code directory) as a base for adapting the Wine configuration
279 file to the settings you want.
280 First, I should mention that you should not forget to make
281 sure that any previous configuration file at
283 of the way instead of simply overwriting it when you will now
284 copy over the sample configuration file.
285 </para>
286 <para>
287 If you don't have a pre-existing configuration file and thus
288 need to copy over our sample configuration file to the
289 standard Wine configuration file location, do in a
291 <screen>
293 <prompt>$ </><userinput>cp <replaceable>dir_to_wine_source_code</replaceable>/documentation/samples/config ~/.wine/config</>
294 </screen>
295 Otherwise, simply use the already existing configuration file
297 </para>
298 <para>
299 Now you can start adapting the configuration file's settings with an
301 below.
303 configuration file settings if wineserver is not running (in
304 other words: if your user doesn't have a Wine session running),
305 otherwise Wine won't use them - and even worse, wineserver will
306 overwrite them with the old settings once wineserver quits!!
307 </para>
308 </sect2>
313 <para>
314 Let's start by giving an overview of which sections a
315 configuration file may contain, and whether the inclusion of
316 the respective section is <emphasis>needed</emphasis> or only <emphasis>recommended</emphasis> ("recmd").
317 </para>
321 <thead>
322 <row>
326 </row>
327 </thead>
328 <tbody>
329 <row>
333 </row>
334 <row>
338 </row>
339 <row>
343 </row>
344 <row>
348 </row>
349 <row>
353 </row>
354 <row>
358 </row>
359 <row>
363 </row>
364 <row>
368 </row>
369 <row>
373 </row>
374 <row>
378 </row>
379 <row>
383 </row>
384 <row>
388 </row>
389 <row>
393 </row>
394 <row>
398 </row>
399 <row>
403 </row>
404 <row>
408 </row>
409 <row>
413 </row>
414 <row>
418 </row>
419 <row>
423 </row>
424 <row>
428 </row>
429 <row>
433 </row>
434 </tbody>
435 </tgroup>
436 </informaltable>
438 <para>
439 Now let's explain the configuration file sections in a
440 detailed way.
441 </para>
443 <sect3>
445 <para>
446 For a detailed description of these configuration file
447 sections which are used to set up DOS drive mappings to Unix
448 directory space, please look at the <link
450 configuration section</link>.
451 </para>
452 </sect3>
456 <para>
457 The [wine] section of the configuration file contains all kinds
458 of general settings for Wine.
459 </para>
460 <para>
461 <programlisting>
467 </programlisting>
468 For a detailed description of drive layer configuration and
469 the meaning of these parameters, please look at the <link
471 configuration section</link>.
472 </para>
473 <para>
475 Sets the graphics driver to use for Wine output.
476 x11drv is for X11 output, ttydrv is for text console output.
477 WARNING: if you use ttydrv here, then you won't be able to run
478 a lot of Windows GUI programs (ttydrv is still pretty "broken"
479 at running graphical apps). Thus this option is mainly interesting
480 for e.g. embedded use of Wine in web server scripts.
481 Note that ttydrv is still very lacking, so if it doesn't work,
482 resort to using "xvfb", a virtual X11 server.
483 Another way to run Wine without display would be to run X11
484 via Xvnc, then connect to that VNC display using xvncviewer
485 (that way you're still able to connect to your app and
486 configure it if need be).
487 </para>
488 <para>
490 whether to allow printing via printer drivers to work.
491 This option isn't needed for our built-in psdrv printer driver
492 at all.
493 Using these things are pretty alpha, so you might want to
494 watch out. Some people might find it useful, however. If
495 you're not planning to work on printing via windows printer
496 drivers, don't even add this to your wine configuration file
497 (It probably isn't already in it).
498 Check out the [spooler] and [parallelports] sections too.
499 </para>
500 <para>
502 This setting specifies the shell linker script to use for setting
503 up Windows icons in e.g. KDE or Gnome that are given by programs
504 making use of appropriate shell32.dll functionality to create
505 icons on the desktop/start menu during installation.
506 </para>
507 <para>
509 Sets up the symbol table file for the wine debugger. You
510 probably don't need to fiddle with this. May be useful if
511 your wine is stripped.
512 </para>
513 </sect3>
517 <para>
518 These settings provide wine's default handling of DLL loading.
519 </para>
520 <para>
522 This setting is a comma-delimited list of the order in
523 which to attempt loading DLLs. If the first option fails,
524 it will try the second, and so on. The order specified
525 above is probably the best in most conditions.
526 </para>
527 </sect3>
529 <sect3>
531 <para>
532 At one time, there was a section called [DllPairs] in the
533 default configuration file, but this has been obsoleted
534 because the pairing information has now been embedded into
535 Wine itself. (The purpose of this section was merely to be
536 able to issue warnings if the user attempted to pair
540 </para>
541 </sect3>
545 <para>
546 The format for this section is the same for each line:
547 <programlisting><DLL>{,<DLL>,<DLL>...} = <FORM>{,<FORM>,<FORM>...}</programlisting>
548 For example, to load built-in KERNEL pair (case doesn't
549 matter here):
551 To load the native COMMDLG pair, but if that doesn't work
552 try built-in:
554 To load the native COMCTL32:
556 Here is a good generic setup (As it is defined in config
557 that was included with your wine package):
558 <programlisting>
559 [DllOverrides]
596 ; you can specify programs too
598 ; default for all other DLLs
600 </programlisting>
601 </para>
602 <note>
603 <para>
604 If loading of the libraries that are listed first fails,
605 wine will just go on by using the second or third option.
606 </para>
607 </note>
608 </sect3>
612 <para>
613 This section sets up wine's font handling.
614 </para>
615 <para>
617 Since the way X handles fonts is different from the way
618 Windows does, wine uses a special mechanism to deal with
619 them. It must scale them using the number defined in the
621 a nice in the middle one. If you have the real windows
625 important. Of course, it's always good to get your X fonts
626 working acceptably in wine.
627 </para>
628 <para>
630 The default font wine uses. Fool around with it if you'd like.
631 </para>
632 <para>
633 OPTIONAL:
634 </para>
635 <para>
637 used in wine. This is good for apps that need a special font you don't have,
638 but a good replacement exists. The syntax is like so:
639 <programlisting>"AliasX" = "[Fake windows name],[Real X name]"<,optional "masking" section></programlisting>
641 then "Alias1" and so on. The fake windows name is the name
642 that the font will be under a windows app in wine. The
643 real X name is the font name as seen by X (Run
645 utilize the fake windows name you define. If it is not
646 used, then wine will just try to extract the fake windows
647 name itself and not use the value you enter.
648 </para>
649 <para>
650 Here is an example of an alias without masking. The font will show up in windows
651 apps as "Google".
653 Here is an example with masking enabled. The font will show up as "Foo" in
654 windows apps.
657 chapter.
658 </para>
659 </sect3>
663 <para>
664 Even though it sounds like a lot of sections, these are
665 all closely related. They are all for communications and
666 parallel ports.
667 </para>
668 <para>
669 The [serialports] section tells wine what serial ports it
670 is allowed to use.
676 can actually equal any device
678 not always necessary to define any COM ports (An optional
679 setting). Here is an example:
681 Use as many of these as you like in the section to define
682 all of the COM ports you need.
683 </para>
684 <para>
685 The [parallelports] section sets up any parallel ports
686 that will be allowed access under wine.
688 Sounds familiar? Syntax is just like the COM port setting.
692 minus 1, just like for COM ports). You don't always need
693 to define a parallel port (AKA, it's optional). As with
694 the other section, LptX can equal any device (Maybe
697 The [spooler] section will inform wine where to spool
698 print jobs. Use this if you want to try printing. Wine
699 docs claim that spooling is "rather primitive" at this
701 setting you use in this section works to map a port (LPT1,
702 for example) to a file or a command. Here is an example,
705 The following command maps printing jobs to LPT1 to the
708 The [ports] section is usually useful only for people who
709 need direct port access for programs requiring dongles or
710 scanners. <emphasis>If you don't need it, don't use
711 it!</emphasis>
712 </para>
713 <para>
715 Gives direct read access to those IO's.
716 </para>
717 <para>
719 Gives direct write access to those IO's. It's probably a
720 good idea to keep the values of the
722 settings the same. This stuff will only work when you're
723 root.
724 </para>
725 </sect3>
729 <para>
730 [Debug] is used to include or exclude debug messages, and to
731 output them to a file. The latter is rarely used. <emphasis>These
732 are all optional and you probably don't need to add or
733 remove anything in this section to your config.</emphasis> (In extreme
734 cases you may want to use these options to manage the amount
735 of information generated by the <parameter>--debugmsg +relay
736 </parameter> option.)
737 </para>
738 <para>
740 Sets the logfile for wine. Set to CON to log to standard out.
742 </para>
743 <para>
747 </para>
748 <para>
752 </para>
753 <para>
755 Include only the listed functions in a
758 </para>
759 <para>
760 <programlisting>"RelayExclude" = "RtlEnterCriticalSection;RtlLeaveCriticalSection"</programlisting>
761 Exclude the listed functions in a
764 entry. If neither entry is present then the trace includes
765 everything.
766 </para>
767 <para>
768 In both entries the functions may be specified either as a
769 function name or as a module and function. In this latter
770 case specify an asterisk for the function name to include/exclude
771 all functions in the module.
772 </para>
773 <para>
774 [Registry] can be used to tell wine where your old windows
775 registry files exist. This section is completely optional
776 and useless to people using wine without an existing
777 windows installation.
778 </para>
779 <para>
782 </para>
783 <para>
784 [tweak.layout] is devoted to wine's look. There is only
785 one setting for it.
786 </para>
787 <para>
792 </para>
793 <para>
794 [programs] can be used to say what programs run under
795 special conditions.
796 </para>
797 <para>
799 Sets the program to be run if wine is started without specifying a program.
800 </para>
801 <para>
803 Sets the program to automatically be run at startup every time.
804 </para>
805 </sect3>
809 <para>
810 [WinMM] is used to define which multimedia drivers have to be loaded. Since
811 those drivers may depend on the multimedia interfaces available on your system
812 (OSS, ALSA... to name a few), it's needed to be able to configure which driver
813 has to be loaded.
814 </para>
816 <para>
817 The content of the section looks like:
818 <programlisting>
819 [WinMM]
823 </programlisting>
824 All the keys must be defined:
825 <itemizedlist>
826 <listitem>
827 <para>
828 The "Drivers" key is a ';' separated list of modules name, each of
829 them containing a low level driver. All those drivers will be loaded
830 when MMSYSTEM/WINMM is started and will provide their inner features.
831 </para>
832 </listitem>
833 <listitem>
834 <para>
835 The "WaveMapper" represents the name of the module containing the Wave
836 Mapper driver. Only one wave mapper can be defined in the system.
837 </para>
838 </listitem>
839 <listitem>
840 <para>
841 The "MidiMapper" represents the name of the module containing the MIDI
842 Mapper driver. Only one MIDI mapper can be defined in the system.
843 </para>
844 </listitem>
845 </itemizedlist>
846 </para>
847 </sect3>
851 <para>
852 [Network] contains settings related to
853 networking. Currently there is only one value that can be set.
854 </para>
855 <variablelist>
856 <varlistentry>
858 <listitem>
859 <para>
861 that affects the way Wine sets the computer name. The computer
864 <varname>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ComputerName\ComputerName</varname>.
865 </para>
866 <para>
867 If this option is set to "Y" or missing, Wine will set the
868 NetBIOS name to the Unix host name of your computer, if
869 necessary truncated to 31 characters. The Unix hostname is the output
871 including the first dot ('.'). Among other things, this means that
872 Windows programs running under Wine cannot change the NetBIOS computer name.
873 </para>
874 <para>
875 If this option is set to "N", Wine will use the registry value above
876 to set the NetBIOS name. Only if the registry entry doesn't exist (usually
877 only during the first wine startup) it will use the Unix hostname as
878 usual. Windows programs can change the NetBIOS name. The change
879 will be effective after a "reboot", i.e. after restarting Wine.
880 </para>
881 </listitem>
882 </varlistentry>
883 </variablelist>
884 </sect3>
888 <para>
889 The section is used to overwrite certain settings of this file for a
890 special program with different settings.
891 [AppDefaults] is not the real name of the section. The real name
892 consists of the leading word AppDefaults followed by the name
893 of the executable the section is valid for.
894 The end of the section name is the name of the
895 corresponding "standard" section of the configuration file
896 that should have some of its settings overwritten with the
897 program specific settings you define.
898 The three parts of the section name are separated by two backslashes.
899 </para>
900 <para>
901 Currently wine supports overriding selected settings within
902 the sections [DllOverrides], [x11drv], [version] and [dsound] only.
903 </para>
904 <para>
905 Here is an example that overrides the normal settings for a
906 program:
907 <programlisting>
908 ;; default settings
909 [x11drv]
913 ;; run install in desktop mode
914 [AppDefaults\\install.exe\\x11drv]
917 </programlisting>
918 </para>
919 </sect3>
920 </sect2>
924 <para>
925 There is always a chance that things will go wrong. If the
926 unthinkable happens, report the problem to
928 try the newsgroup
931 irc.freenode.net, or connected servers.
932 Make sure that you have looked over this document thoroughly,
933 and have also read:
934 </para>
935 <itemizedlist>
936 <listitem>
937 <para>
939 </para>
940 </listitem>
941 <listitem>
942 <para>
944 </para>
945 </listitem>
946 </itemizedlist>
947 <para>
948 If indeed it looks like you've done your research, be
949 prepared for helpful suggestions. If you haven't, brace
950 yourself for heaving flaming.
951 </para>
952 </sect2>
953 </sect1>
957 <sect2>
959 <para>
960 If you're planning to include access to a CD-ROM drive in your Wine
965 Several Windows program setup CD-ROMs or other CD-ROMs chose
966 to do such braindamaged things as marking very important setup
968 That's no problem on Windows, since the Windows CD-ROM driver by
969 default displays even files that are supposed to be
973 (the programs will simply abort with an <quote>installation file not found</quote> or similar error)
974 Thus you should never forget to add this setting.
975 </para>
976 </sect2>
978 <sect2>
980 <para>
981 Wine emulates drives by placing their virtual drive roots to
982 user-configurable points in the Unix filesystem, so it's your
987 indicates the home directory of a user), as the root of your
989 into your Wine configuration file:
990 </para>
992 <programlisting>
993 [Drive C]
998 </programlisting>
1000 <para>
1001 With this configuration, what windows apps think of as
1002 "c:\windows\system" would map to
1004 filesystem. Note that you need to specify
1008 Windows compatible (case insensitive) filesystem, otherwise
1009 most apps won't work.
1010 </para>
1011 </sect2>
1015 <para>
1016 Here's the fundamental layout that Windows programs and
1017 installers expect and that we thus need to configure properly
1018 in Wine. Without it, they seldomly operate correctly. If you
1019 intend to use a no-windows environment (not using an existing
1020 Windows partition), then it is recommended to use either
1023 initial windows directory tree, since creating a directory
1024 structure manually is tiresome and error-prone.
1025 </para>
1027 <programlisting>
1028 C:\ Root directory of primary disk drive
1029 Windows\ Windows directory, containing .INI files,
1030 accessories, etc.
1034 Start Menu\ Program launcher directory structure
1035 Programs\ Program launcher links (.LNK files) to programs
1036 Program Files\ Application binaries (.EXE and .DLL files)
1037 </programlisting>
1038 </sect2>
1042 <para>
1043 These sections are supposed to make certain Unix
1044 directory locations accessible to Wine as a DOS/Windows drive
1045 (drive 'x:') and thus accessible to Windows programs
1046 under the drive name you specified.
1047 Every DOS/Windows program sort of expects at least a C:
1048 drive (and sometimes also an A: floppy drive), so your
1049 configuration file should at least contain the corresponding
1050 sections, [Drive C] and [Drive A].
1051 You need to decide on whether you want to use an existing Windows
1052 partition as the C drive or whether you want to create your own
1053 Wine drive C directory tree somewhere (take care about
1054 permissions!).
1055 Each drive section may specify up to 6 different settings
1056 as explained below.
1057 </para>
1058 <para>
1060 The above line begins the section for a drive whose letter is x
1061 (DOS notation: drive 'x:').
1062 You could e.g. create an equivalent to a drive 'C:'
1063 under DOS/Windows by using a [Drive C] section name.
1064 Note that the drive letter is case insensitive.
1065 </para>
1066 <para>
1068 This specifies the directory where the drive will begin.
1069 When Wine is browsing in drive x, it will be able
1070 to see the files that are in the directory
1072 (note that symlinks to directories won't get included!
1074 configuration setting)
1075 You can also make use of environment variables like $HOME here,
1077 directory in your home dir would be
1079 Don't forget to leave off the trailing slash!
1080 </para>
1081 <para>
1083 Sets up the type of drive Wine will see it as. Type must
1087 (The |'s mean "Type = '<one of the options>'".)
1089 For a home directory entry, it makes sense to choose
1090 "network" sometimes, since some home directories are being
1091 exported over the network via NFS and thus can have slow response
1092 times.
1093 </para>
1094 <para>
1096 Defines the drive label. Generally only needed
1097 for programs that look for a special CD-ROM.
1098 The label may be up to 11 characters.
1099 Note that the preferred way of managing labels and serial numbers
1100 of CD-ROMs and floppies is to give Wine raw device access for
1101 reading these on a per-CD case (see "Device" below) instead of
1102 hardcoding one specific "Label".
1103 </para>
1104 <para>
1106 Tells Wine the serial number of the drive. A few programs with
1107 intense protection for pirating might need this, but otherwise
1108 it's not needed. Up to 8 characters and hexadecimal.
1110 is a smarter choice.
1111 </para>
1112 <para>
1114 Sets up the way Wine looks at files on the drive.
1115 This setting controls the file name lookup and mapping of
1116 Wine to existing file systems on your PC, it does
1118 used itself.
1119 </para>
1121 <variablelist>
1122 <varlistentry>
1124 <listitem>
1125 <para>
1127 the long filename filesystem you are probably used
1128 to working with. The filesystem behavior of choice for most
1129 programs to be run under wine. <emphasis>Probably the one
1130 you want!</emphasis>
1131 </para>
1132 </listitem>
1133 </varlistentry>
1134 <varlistentry>
1136 <listitem>
1137 <para>
1138 Case sensitive. This filesystem has almost no use
1139 (Windows apps expect case insensitive filenames),
1140 except maybe for Winelib applications.
1141 Try it if you dare, but win95 is a much better
1142 and always recommended choice.
1143 </para>
1144 </listitem>
1145 </varlistentry>
1146 <varlistentry>
1148 <listitem>
1149 <para>
1150 Case insensitive filesystem. Alike to DOS and
1152 length of files (eightdot.123) - longer ones will be
1153 truncated.
1154 <note>
1155 <para>
1157 you plan on running apps that use long filenames.
1158 win95 should work fine with apps that were designed
1159 to run under the msdos system. In other words, you
1160 might not want to use this.
1161 </para>
1162 </note>
1163 </para>
1164 </listitem>
1165 </varlistentry>
1166 </variablelist>
1169 <para>
1170 Needed for raw device access and <link linkend="config-drive-cdrom-labels">label and serial number reading</link>.
1172 Extended2 or other Unix file systems can have dire results
1173 (when a windows app tries to do a lowlevel write,
1174 they do it in a FAT way -- FAT format is completely different from
1175 any Unix file system).
1176 Also, make sure that you have proper permissions to this device
1177 file.
1178 </para>
1179 <note>
1180 <para>
1181 This setting is not really important; almost all apps
1182 will have no problem if it remains unspecified. For
1183 CD-ROMs it's quite useful in order to get automatic label
1184 detection, though. If you are unsure about specifying
1185 device names, just leave out this setting for your
1186 drives.
1187 </para>
1188 </note>
1189 <para>
1190 Here are a few sample entries:
1191 <programlisting>
1192 Here is a setup for Drive C, a generic hard drive:
1193 [Drive C]
1198 This is a setup for Drive E, a generic CD-ROM drive:
1199 [Drive E]
1205 And here is a setup for Drive A, a generic floppy drive:
1206 [Drive A]
1213 </programlisting>
1214 </para>
1215 </sect2>
1217 <sect2>
1219 <para>
1221 This tells Wine and Windows programs where the
1223 recommended to have this directory somewhere on your
1225 recommended to just call the directory "windows" (this is
1226 the default setup on Windows, and some stupid programs
1227 might rely on this). So in case you chose a "Windows"
1228 setting of "c:\\windows" and you chose to set up a drive C
1230 corresponding directory would be
1232 if you don't already have one. <emphasis>No trailing slash</emphasis> (<emphasis>not</emphasis>
1234 recommended, as Windows programs always assume write access
1235 to the Windows directory!
1236 </para>
1237 <para>
1239 This sets up where the windows system files are. The Windows
1240 system directory should reside below the directory used for the
1242 Thus when using the example above, the system directory would be
1244 Again, no trailing slash, and write access!
1245 </para>
1246 <para>
1248 be the directory you want your temp files stored in,
1249 /usr/local/wine_c/temp in our example.
1250 Again, no trailing slash, and <emphasis>write
1251 access</emphasis>!!
1252 </para>
1253 <para>
1256 boxes. When wine is run like <userinput>wine
1258 resides in a directory specified in the
1261 current directory, wine will run that one). Make sure it
1263 system directory (For this setup, it must have
1265 </para>
1268 Wine doesn't pass directory symlinks to Windows programs by
1269 default, as doing so may crash some programs that do
1270 recursive lookups of whole subdirectory trees
1271 whenever a directory symlink points back to itself or one of its
1272 parent directories.
1273 That's why we disallowed the use of directory symlinks
1274 and added this setting to reenable ("1") this functionality.
1276 account symlinked directories, then reenable it, but
1278 Windows programs when using the above method! (in other words:
1279 enabling it is certainly not recommended)
1280 </para>
1281 </sect2>
1283 <sect2>
1285 <para>
1286 Windows uses a different (and inferior) way than Unix to describe the
1287 location of files in a computer. Thus Windows programs also expect
1288 to find this different way supported by the system.
1289 Since we intend to run Windows programs on
1290 a Unix system, we're in trouble, as we need to translate
1291 between these different file access techniques.
1292 </para>
1293 <para>
1294 Windows uses drive letters to describe drives or
1295 any other form of storage media and to access files on them.
1296 For example, common drive names are
1299 first floppy drive.
1301 directory separator sign, whereas Unix uses
1303 Thus, an example document on the first data partition in
1304 Windows might be accessed by the name of
1306 </para>
1307 <para>
1308 So much for the Windows way of doing things.
1309 </para>
1310 <para>
1311 Well, the problem is, in Unix there is no such thing as
1313 much better way of having one single uniform directory tree
1314 (starting with the root directory
1316 such as e.g. harddisk partitions appended at various directory
1317 locations within the tree (an example would be
1319 partition mounted/attached to a directory called data1 in the
1321 directory of the data partition file system that's mounted
1323 In Unix, the Windows example document mentioned above could e.g.
1324 be accessed by the name of
1326 provided that the administrator decided to mount (attach) the first
1327 data partition at the directory /data1 inside the Unix
1328 directory tree. Note that in Unix, the administrator can
1332 suitable for the first data partition (here,
1334 change in partition order, Windows automatically
1336 suddenly find yourself with a first data partition at drive
1338 referencing confusion that entails. Thus, the Windows way of
1339 using ever-changing drive letters is <emphasis>clearly
1340 inferior</emphasis> to the Unix way of assigning
1342 data storage medium.
1343 As we'll see soon, fortunately this Windows limitation of
1344 changing drive letters doesn't affect us in Wine at all, since
1345 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).
1346 </para>
1347 <para>
1348 OK, now that we know some theory about Windows and Unix drive
1349 and filename mapping, it's probably time to ask how Wine
1350 achieves the magic of mapping a Unix directory location to a
1351 Windows drive...
1352 </para>
1353 <para>
1354 Wine chose to do the following:
1355 In Wine, you don't assign some real physical storage medium
1356 (such as a harddisk partition or similar) to each drive letter
1357 mapping entry.
1358 Instead, you choose certain sub directory trees inside the Unix
1360 you would like to assign a drive letter to.
1361 </para>
1362 <para>
1363 Note that for every Unix sub directory tree that you intend to
1364 start Windows programs in, it is <emphasis>absolutely
1365 required</emphasis> to have a Wine drive mapping entry:
1366 </para>
1367 <para>
1368 For example, if you had a publicly writable <quote>Windows
1370 able to access this sub directory tree from Wine, you should
1371 have a drive mapping entry that maps a certain drive letter
1373 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.
1374 </para>
1375 </sect2>
1379 <para>
1381 </para>
1382 <para>
1384 </para>
1386 <para>
1387 A major goal of Wine is to allow users to run Windows programs
1388 without having to install Windows on their machine. Wine
1389 implements the functionality of the main DLLs usually
1390 provided with Windows. Therefore, once Wine is finished, you
1391 will not need to have Windows installed to use Wine.
1392 </para>
1393 <para>
1394 Wine has already made enough progress that it may be possible
1395 to run your target programs without Windows installed. If
1396 you want to try it, follow these steps:
1397 </para>
1399 <orderedlist>
1400 <listitem>
1401 <para>
1405 for more information.
1406 The directory to be used for emulating a C: drive will be
1407 the base directory for some Windows specific directories
1408 created below.
1409 Remember to use
1411 </para>
1412 </listitem>
1413 <listitem>
1414 <para>
1415 Within the directory to be used for C:, create empty
1420 directories. Do not point Wine to a
1422 installations and a messy registry. (Wine creates a
1425 Perhaps you have to remove these files).
1426 In one line:
1427 mkdir -p windows windows/system windows/Start\ Menu windows/Start\ Menu/Programs
1428 </para>
1429 </listitem>
1430 <listitem>
1431 <para>
1432 Run and/or install your programs.
1433 </para>
1434 </listitem>
1435 </orderedlist>
1437 <para>
1438 Because Wine is not yet complete, some programs will work
1439 better with native Windows DLLs than with Wine's
1440 replacements. Wine has been designed to make this possible.
1441 Here are some tips by Juergen Schmied (and others) on how to
1442 proceed. This assumes that your
1444 file does not point to a native Windows installation but is in
1448 </para>
1450 <itemizedlist>
1451 <listitem>
1452 <para>
1453 Run the program with <parameter>--debugmsg
1454 +loaddll</parameter> to find out which files are
1455 needed. Copy the required DLLs one by one to the
1457 copy KERNEL/KERNEL32, GDI/GDI32, USER/USER32 or NTDLL. These
1458 implement the core functionality of the Windows API, and
1459 the Wine internal versions must be used.
1460 </para>
1461 </listitem>
1462 <listitem>
1463 <para>
1467 the Windows DLLs you want to use. For more information
1468 about this, see the Wine manpage.
1469 </para>
1470 </listitem>
1471 <listitem>
1472 <para>
1473 Note that some network DLLs are not needed even though
1474 Wine is looking for them. The Windows
1476 must use the internal implementation.
1477 </para>
1478 </listitem>
1479 <listitem>
1480 <para>
1481 Copy SHELL.DLL/SHELL32.DLL, COMMDLG.DLL/COMDLG32.DLL
1482 and COMMCTRL.DLL/COMCTL32.DLL
1483 only as pairs to your Wine directory (these DLLs are
1487 </para>
1488 </listitem>
1489 <listitem>
1490 <para>
1491 Be consistent: Use only DLLs from the same Windows version
1492 together.
1493 </para>
1494 </listitem>
1495 <listitem>
1496 <para>
1501 registry, don't know about
1503 As of now, it might not be necessary any more to use
1504 regedit.exe, since Wine has its own regedit Winelib
1505 application now.
1506 </para>
1507 </listitem>
1508 <listitem>
1509 <para>
1512 to browse through your programs' help function
1513 (or in case Wine's winhelp implementation in programs/winhelp/
1514 is not good enough, for example).
1515 </para>
1516 </listitem>
1517 </itemizedlist>
1518 </sect2>
1522 <para>
1523 Some people intend to use the data of an existing Windows partition
1524 with Wine in order to gain some better compatibility or to run already
1525 installed programs in a setup as original as possible.
1526 Note that many Windows programs assume that they have full write
1527 access to all windows directories.
1529 This means that you either have to configure the Windows
1530 partition mount point for write permission by your Wine user
1532 on how to do that), or you'll have to copy over (some parts of) the Windows
1533 partition content to a directory of a Unix partition and make
1534 sure this directory structure is writable by your user.
1536 write access as a base for Wine!! (some programs, notably
1537 Explorer, corrupt large parts of the Windows partition in case
1538 of an incorrect setup; you've been warned).
1539 Not to mention that NTFS write support in Linux is still very
1541 Windows version using the NTFS file system).
1542 Thus we advise you to go the Unix directory way.
1543 </para>
1544 </sect2>
1548 <para>
1550 </para>
1551 <para>
1553 </para>
1554 <para>
1555 This document describes how FAT and
1556 VFAT file system permissions work in Linux
1557 with a focus on configuring them for Wine.
1558 </para>
1560 <sect3>
1562 <para>
1563 Linux is able to access DOS and Windows file systems using
1564 either the FAT (older 8.3 DOS filesystems) or VFAT (newer
1565 Windows 95 or later long filename filesystems) modules.
1566 Mounted FAT or VFAT filesystems provide the primary means
1567 for which existing programs and their data are accessed
1568 through Wine for dual boot (Linux + Windows) systems.
1569 </para>
1570 <para>
1571 Wine maps mounted FAT filesystems, such as
1576 </para>
1577 <programlisting>
1578 [Drive C]
1581 </programlisting>
1582 <para>
1583 Although VFAT filesystems are preferable to FAT filesystems
1585 will be used throughout the remainder of this document to
1586 refer to FAT filesystems and their derivatives. Also,
1588 examples throughout this document.
1589 </para>
1590 <para>
1591 Most modern Linux distributions either detect or allow
1592 existing FAT file systems to be configured so that they can be
1594 either persistently (on bootup) or on an as needed basis. In
1595 either case, by default, the permissions will probably be
1596 configured so that they look like:
1597 </para>
1598 <screen>
1604 </screen>
1605 <para>
1607 group and are only writable by "root"
1609 that it requires that Wine be run as root in order for
1610 programs to be able to write to any part of the
1611 filesystem.
1612 </para>
1613 <para>
1614 There are three major approaches to overcoming the restrictive
1615 permissions mentioned in the previous paragraph:
1616 </para>
1617 <orderedlist>
1618 <listitem>
1619 <para>
1621 </para>
1622 </listitem>
1623 <listitem>
1624 <para>
1625 Mount the FAT filesystem with less restrictive
1626 permissions
1627 </para>
1628 </listitem>
1629 <listitem>
1630 <para>
1631 Shadow the FAT filesystem by completely or partially
1632 copying it
1633 </para>
1634 </listitem>
1635 </orderedlist>
1636 <para>
1637 Each approach will be discussed in the following sections.
1638 </para>
1639 </sect3>
1641 <sect3>
1643 <para>
1644 Running Wine as root is the easiest and most thorough way of giving
1645 programs that Wine runs unrestricted access to FAT files systems.
1646 Running wine as root also allows programs to do things unrelated
1647 to FAT filesystems, such as listening to ports that are less than
1648 1024. Running Wine as root is dangerous since there is no limit to
1650 </para>
1651 </sect3>
1653 <sect3>
1655 <para>
1656 The FAT filesystem can be mounted with permissions less restrictive
1657 than the default. This can be done by either changing the user that
1658 mounts the FAT filesystem or by explicitly changing the permissions
1659 that the FAT filesystem is mounted with. The permissions are
1660 inherited from the process that mounts the FAT filesystem. Since the
1661 process that mounts the FAT filesystem is usually a startup script
1662 running as root the FAT filesystem inherits root's permissions. This
1663 results in the files on the FAT filesystem having permissions similar
1664 to files created by root. For example:
1665 </para>
1666 <screen>
1672 </screen>
1673 <para>
1674 which matches the owner, group and permissions of files seen
1675 on the FAT filesystem except for the missing 'x's. The
1676 permissions on the FAT filesystem can be changed by changing
1677 root's umask (unset permissions bits). For example:
1678 </para>
1679 <screen>
1690 </screen>
1691 <para>
1692 Mounting the FAT filesystem with a umask of
1694 it. Explicitly specifying the permissions of the FAT
1695 filesystem when it is mounted provides additional control.
1696 There are three mount options that are relevant to FAT
1699 when the filesystem is manually mounted. For example:
1700 </para>
1701 <screen>
1709 </screen>
1710 <para>
1711 which gives "sle" complete control over
1713 made permanent by adding them to the
1715 </para>
1716 <screen>
1718 <computeroutput>/dev/hda1 /c vfat uid=500,gid=500,umask=002,exec,dev,suid,rw 1 1</computeroutput>
1719 </screen>
1720 <para>
1722 the user private group file permission scheme. On FAT file
1723 systems this umask assures that all files are fully
1724 accessible by all users in the specified user group
1726 </para>
1727 </sect3>
1729 <sect3>
1731 <para>
1732 Shadowing provides a finer granularity of control. Parts of
1733 the original FAT filesystem can be copied so that the
1734 program can safely work with those copied parts while
1735 the program continues to directly read the remaining
1736 parts. This is done with symbolic links. For example,
1737 consider a system where a program named
1741 read access to the entire FAT filesystem. On this system
1742 the FAT filesystem has default permissions which should not
1743 be changed for security reasons or can not be changed due to
1744 lack of root access. On this system a shadow directory
1745 might be set up in the following manner:
1746 </para>
1747 <screen>
1755 <prompt>/c_shadow></prompt><userinput>perl -p -i -e 's|/c$|/c_shadow|g' ~/.wine/config</userinput>
1756 </screen>
1757 <para>
1758 The above gives everyone complete read and write access to
1761 write access to all other directories.
1762 </para>
1763 </sect3>
1764 </sect2>
1767 <sect2info>
1768 <authorgroup>
1769 <author>
1772 <affiliation>
1774 </affiliation>
1776 </author>
1777 <author>
1780 <affiliation>
1782 </affiliation>
1784 </author>
1785 </authorgroup>
1786 </sect2info>
1789 <para>
1791 Nov 14 1999
1792 </para>
1793 <para>
1795 Jan 25 2000
1796 </para>
1797 <para>
1799 </para>
1800 <para>
1801 Until now, your only possibility of specifying drive volume
1802 labels and serial numbers was to set them manually in the wine
1803 configuration file. By now, wine can read them directly from the
1804 device as well. This may be useful for many Win 9x games or
1805 for setup programs distributed on CD-ROMs that check for
1806 volume label.
1807 </para>
1809 <sect3>
1814 <thead>
1815 <row>
1819 </row>
1820 </thead>
1821 <tbody>
1822 <row>
1826 </row>
1827 <row>
1831 </row>
1832 </tbody>
1833 </tgroup>
1834 </informaltable>
1836 </sect3>
1838 <sect3>
1840 <para>
1841 Reading labels and serial numbers just works automatically
1844 Note that the device has to exist and must be accessible by the user
1845 running Wine if you do this, though.
1846 </para>
1847 <para>
1848 If you don't want to read labels and serial numbers directly from
1849 the device, then you should give fixed
1852 these entries instead if no device is given. If they don't
1853 exist, then Wine will return default values (label
1856 </para>
1857 <para>
1860 but not for reading the volume info from the device (i.e. you want
1863 to skip the volume reading.
1864 </para>
1865 </sect3>
1867 <sect3>
1869 <para>
1870 Here's a simple example of CD-ROM and floppy; labels will be
1871 read from the device on both CD-ROM and floppy; serial
1872 numbers on floppy only:
1873 </para>
1874 <programlisting>
1875 [Drive A]
1881 [Drive R]
1886 </programlisting>
1887 <para>
1888 Here's an example of overriding the CD-ROM label:
1889 </para>
1890 <programlisting>
1891 [Drive J]
1895 ; note that the device isn't really needed here as we have a fixed label
1898 </programlisting>
1899 </sect3>
1901 <sect3>
1903 <itemizedlist>
1904 <listitem> <para>
1905 The CD-ROM label can be read only if the data track of
1906 the disk resides in the first track and the cdrom is
1907 iso9660.
1908 </para> </listitem>
1909 <listitem> <para>
1910 Better checking for FAT superblock (it now checks only
1911 one byte). </para>
1912 </listitem>
1913 <listitem> <para>
1914 Support for labels/serial nums WRITING.
1915 </para> </listitem>
1916 <listitem> <para>
1918 chars).
1919 </para> </listitem>
1920 <listitem> <para>
1921 What about reading ext2 volume label? ....
1922 </para> </listitem>
1923 </itemizedlist>
1924 </sect3>
1925 </sect2>
1926 </sect1>
1928 ®istry;
1933 <sect2>
1935 <para>
1936 If your programs don't work as expected, then it's often because one
1937 DLL or another is failing. This can often be resolved by changing
1938 certain DLLs from Wine built-in to native Windows DLL file and vice
1939 versa.
1940 </para>
1941 <para>
1942 A very useful help to find out which DLLs are loaded as built-in and
1943 which are loaded as native Windows file can be the debug channel
1944 loaddll, activated via the Wine command line parameter
1946 </para>
1947 </sect2>
1949 <sect2>
1950 <!-- FIXME intro!!! -->
1952 <para>
1953 There are a few things you will need to know before
1954 configuring the DLL sections in your wine configuration
1955 file.
1956 </para>
1957 <sect3>
1959 <para>
1960 Most windows DLL's have a win16 (Windows 3.x) and win32
1961 (Windows 9x/NT) form. The combination of the win16 and
1962 win32 DLL versions are called the "DLL pair". This is a
1963 list of the most common pairs:
1964 </para>
1966 <informaltable>
1968 <thead>
1969 <row>
1972 <entry>
1973 Native
1974 <footnote>
1975 <para>
1976 Is it possible to use native DLL with wine?
1977 (See next section)
1978 </para>
1979 </footnote>
1980 </entry>
1981 </row>
1982 </thead>
1983 <tbody>
1984 <row>
1988 </row>
1989 <row>
1993 </row>
1994 <row>
1998 </row>
1999 <row>
2003 </row>
2004 <row>
2008 </row>
2009 <row>
2013 </row>
2014 </tbody>
2015 </tgroup>
2016 </informaltable>
2017 </sect3>
2019 <sect3>
2021 <para>
2022 There are a few different forms of DLL's wine can load:
2023 <variablelist>
2024 <varlistentry>
2026 <listitem><para>
2027 The DLL's that are included with windows. Many
2028 windows DLL's can be loaded in their native
2029 form. Many times these native versions work
2030 better than their non-Microsoft equivalent --
2031 other times they don't.
2032 </para></listitem>
2033 </varlistentry>
2034 <varlistentry>
2036 <listitem><para>
2037 The most common form of DLL loading. This is
2038 what you will use if the DLL is too system-specific
2039 or error-prone in native form (KERNEL for example),
2040 you don't have the native DLL, or you just want to be
2041 Microsoft-free.
2042 </para></listitem>
2043 </varlistentry>
2044 <varlistentry>
2046 <listitem><para>
2047 Native ELF libraries. Has been deprecated, ignored.
2048 </para></listitem>
2049 </varlistentry>
2050 <varlistentry>
2052 <listitem><para>
2053 ELF encapsulated windows DLL's.
2054 No longer used, ignored.
2055 </para></listitem>
2056 </varlistentry>
2057 </variablelist>
2058 </para>
2059 </sect3>
2060 </sect2>
2065 <para>
2067 </para>
2068 <para>
2070 </para>
2072 <para>
2073 The wine configuration file directives [DllDefaults]
2074 and [DllOverrides] are the subject of some confusion. The
2075 overall purpose of most of these directives are clear enough,
2076 though - given a choice, should Wine use its own built-in
2078 in an existing Windows installation? This document explains
2079 how this feature works.
2080 </para>
2082 <sect3>
2084 <variablelist>
2085 <varlistentry>
2087 <listitem> <para>
2089 written for the real Microsoft Windows.
2090 </para> </listitem>
2091 </varlistentry>
2092 <varlistentry>
2094 <listitem> <para>
2095 A "built-in" DLL is a Wine DLL. These can either be a
2098 that Wine is able to load on demand.
2099 </para> </listitem>
2100 </varlistentry>
2101 </variablelist>
2102 </sect3>
2104 <sect3>
2106 <variablelist>
2107 <varlistentry>
2109 <listitem> <para>
2110 This specifies in what order Wine should search for
2111 available DLL types, if the DLL in question was not
2112 found in the [DllOverrides] section.
2113 </para> </listitem>
2114 </varlistentry>
2115 </variablelist>
2116 </sect3>
2118 <sect3>
2120 <para>
2121 At one time, there was a section called [DllPairs] in the
2122 default configuration file, but this has been obsoleted
2123 because the pairing information has now been embedded into
2124 Wine itself. (The purpose of this section was merely to be
2125 able to issue warnings if the user attempted to pair
2129 </para>
2130 </sect3>
2132 <sect3>
2134 <para>
2135 This section specifies how you want specific DLLs to be
2136 handled, in particular whether you want to use "native" DLLs
2137 or not, if you have some from a real Windows configuration.
2138 Because built-ins do not mix seamlessly with native DLLs yet,
2139 certain DLL dependencies may be problematic, but workarounds
2140 exist in Wine for many popular DLL configurations. Also see
2141 WWN's [16]Status Page to figure out how well your favorite
2142 DLL is implemented in Wine.
2143 </para>
2144 <para>
2145 It is of course also possible to override these settings by
2147 command-line option (see the man page for details). Some
2148 hints for choosing your optimal configuration (listed by
2150 </para>
2151 <variablelist>
2152 <varlistentry>
2154 <listitem> <para>
2155 Native versions of these will never work, so don't try. Leave
2157 </para> </listitem>
2158 </varlistentry>
2159 <varlistentry>
2161 <listitem> <para>
2162 Graphics Device Interface. No effort has been made at trying to
2164 </para> </listitem>
2165 </varlistentry>
2166 <varlistentry>
2168 <listitem> <para>
2169 Window management and standard controls. It was
2171 versions at some point (if all other DLLs that depend
2172 on it, such as comctl32 and comdlg32, were also run
2174 possible after the Address Space Separation, so leave
2176 </para> </listitem>
2177 </varlistentry>
2178 <varlistentry>
2180 <listitem> <para>
2181 NT kernel API. Although badly documented, the
2184 </para> </listitem>
2185 </varlistentry>
2186 <varlistentry>
2188 <listitem> <para>
2190 version will probably never work. Leave at
2192 </para> </listitem>
2193 </varlistentry>
2194 <varlistentry>
2196 <listitem> <para>
2197 Win16 support library for NT. The
2200 </para> </listitem>
2201 </varlistentry>
2202 <varlistentry>
2204 <listitem> <para>
2205 Win16 kernel stuff. Will never work
2208 </para> </listitem>
2209 </varlistentry>
2210 <varlistentry>
2212 <listitem> <para>
2214 </para> </listitem>
2215 </varlistentry>
2216 <varlistentry>
2218 <listitem> <para>
2219 Tool helper routines. This is rarely a source of problems.
2221 </para> </listitem>
2222 </varlistentry>
2223 <varlistentry>
2225 <listitem> <para>
2226 Versioning. Seldom useful to mess with.
2227 </para> </listitem>
2228 </varlistentry>
2229 <varlistentry>
2231 <listitem> <para>
2232 Registry and security features. Trying the
2234 not work.
2235 </para> </listitem>
2236 </varlistentry>
2237 <varlistentry>
2239 <listitem> <para>
2240 Common Dialogs, such as color picker, font dialog,
2241 print dialog, open/save dialog, etc. It is safe to try
2243 </para> </listitem>
2244 </varlistentry>
2245 <varlistentry>
2247 <listitem> <para>
2248 Common Controls. This is toolbars, status bars, list controls,
2250 </para> </listitem>
2251 </varlistentry>
2252 <varlistentry>
2254 <listitem> <para>
2255 Shell interface (desktop, filesystem, etc). Being one of the
2256 most undocumented pieces of Windows, you may have luck with the
2258 </para> </listitem>
2259 </varlistentry>
2260 <varlistentry>
2262 <listitem> <para>
2264 will not work under Wine, so leave at
2266 </para> </listitem>
2267 </varlistentry>
2268 <varlistentry>
2270 <listitem> <para>
2271 ICMP routines for wsock32. As with wsock32, leave at
2273 </para> </listitem>
2274 </varlistentry>
2275 <varlistentry>
2277 <listitem> <para>
2279 to thunking issues. Leave at
2281 </para> </listitem>
2282 </varlistentry>
2283 <varlistentry>
2285 <listitem> <para>
2286 Lempel-Ziv decompression. Wine's
2288 </para> </listitem>
2289 </varlistentry>
2290 <varlistentry>
2292 <listitem> <para>
2293 Advanced SCSI Peripheral Interface. The
2296 </para> </listitem>
2297 </varlistentry>
2298 <varlistentry>
2300 <listitem> <para>
2302 version will easily work better than Wine's on this
2303 one.
2304 </para> </listitem>
2305 </varlistentry>
2306 <varlistentry>
2308 <listitem> <para>
2309 Printer spooler. You are not likely to have more luck
2311 </para> </listitem>
2312 </varlistentry>
2313 <varlistentry>
2315 <listitem> <para>
2316 DirectDraw/Direct3D. Since Wine does not implement the
2318 will not work at this time.
2319 </para> </listitem>
2320 </varlistentry>
2321 <varlistentry>
2323 <listitem> <para>
2325 may or may not work.
2326 </para> </listitem>
2327 </varlistentry>
2328 <varlistentry>
2330 <listitem> <para>
2331 DirectSound. It may be possible to run this
2333 </para> </listitem>
2334 </varlistentry>
2335 <varlistentry>
2337 <listitem> <para>
2339 ought to work best on this, if at all.
2340 </para> </listitem>
2341 </varlistentry>
2342 <varlistentry>
2344 <listitem> <para>
2346 version is not likely to work. Leave at
2348 </para> </listitem>
2349 </varlistentry>
2350 <varlistentry>
2352 <listitem> <para>
2353 Audio Compression Manager. The
2355 set msacm.drv to the same.
2356 </para> </listitem>
2357 </varlistentry>
2358 <varlistentry>
2360 <listitem> <para>
2361 Video for Windows. It is safe (and recommended) to try
2363 </para> </listitem>
2364 </varlistentry>
2365 <varlistentry>
2367 <listitem> <para>
2368 CD Audio MCI driver.
2369 </para> </listitem>
2370 </varlistentry>
2371 <varlistentry>
2373 <listitem> <para>
2375 playback).
2376 </para> </listitem>
2377 </varlistentry>
2378 <varlistentry>
2380 <listitem> <para>
2382 </para> </listitem>
2383 </varlistentry>
2384 <varlistentry>
2386 <listitem> <para>
2389 </para> </listitem>
2390 </varlistentry>
2391 <varlistentry>
2393 <listitem> <para>
2394 Animation MCI driver.
2395 </para> </listitem>
2396 </varlistentry>
2397 <varlistentry>
2399 <listitem> <para>
2400 Audio Compression Manager. Set to same as msacm32.
2401 </para> </listitem>
2402 </varlistentry>
2403 <varlistentry>
2405 <listitem> <para>
2406 MIDI Mapper.
2407 </para> </listitem>
2408 </varlistentry>
2409 <varlistentry>
2411 <listitem> <para>
2412 This is a pseudo-DLL used by Wine for thunking
2414 doesn't exist.
2415 </para> </listitem>
2416 </varlistentry>
2417 </variablelist>
2418 </sect3>
2419 </sect2>
2423 <para>
2424 The Wine team has determined that it is necessary to create
2425 fake DLL files to trick many programs that check for
2426 file existence to determine whether a particular feature
2427 (such as Winsock and its TCP/IP networking) is available. If
2428 this is a problem for you, you can create empty files in the
2430 to make the program think it's there, and Wine's built-in DLL
2431 will be loaded when the program actually asks for it.
2433 not create such empty files itself.)
2434 </para>
2435 <para>
2436 Applications sometimes also try to inspect the version
2437 resources from the physical files (for example, to determine
2438 the DirectX version). Empty files will not do in this case,
2439 it is rather necessary to install files with complete
2440 version resources. This problem is currently being worked
2441 on. In the meantime, you may still need to grab some real
2442 DLL files to fool these apps with.
2443 </para>
2444 <para>
2445 And there are of course DLLs that wine does not currently
2446 implement very well (or at all). If you do not have a real
2447 Windows you can steal necessary DLLs from, you can always
2448 get some from one of the Windows DLL archive sites
2449 that can be found via internet search engine.
2450 Please make sure to obey any licenses on the DLLs you fetch...
2451 (some are redistributable, some aren't).
2452 </para>
2453 </sect2>
2458 <para>
2460 </para>
2462 <para>
2463 In case Wine complains about a missing DLL, you should check whether
2464 this file is a publicly available DLL or a custom DLL belonging
2465 to your program (by searching for its name on the internet).
2466 If you managed to get hold of the DLL, then you should make sure
2467 that Wine is able to find and load it.
2468 DLLs usually get loaded according to the mechanism of the
2469 SearchPath() function.
2470 This function searches directories in the following order:
2472 <orderedlist>
2473 <listitem>
2474 <para>
2475 The directory the program was started from.
2476 </para>
2477 </listitem>
2478 <listitem>
2479 <para>
2480 The current directory.
2481 </para>
2482 </listitem>
2483 <listitem>
2484 <para>
2485 The Windows system directory.
2486 </para>
2487 </listitem>
2488 <listitem>
2489 <para>
2490 The Windows directory.
2491 </para>
2492 </listitem>
2493 <listitem>
2494 <para>
2495 The PATH variable directories.
2496 </para>
2497 </listitem>
2498 </orderedlist>
2500 In short: either put the required DLL into your program
2501 directory (might be ugly), or usually put it into the Windows system
2502 directory. Just find out its directory by having a look at the Wine
2503 configuration file variable "System" (which indicates the location of the
2504 Windows system directory) and the associated drive entry.
2505 Note that you probably shouldn't use NT-based native DLLs,
2506 since Wine's NT API support is somewhat weaker than its Win9x
2507 API support (thus leading to even worse compatibility with NT DLLs
2508 than with a no-windows setup!), so better use Win9x native DLLs
2509 instead or no native DLLs at all.
2510 </para>
2511 </sect2>
2516 <para>
2518 </para>
2520 <para>
2522 extract native Windows .dll files from .cab files that are to be
2523 found on many Windows installation CDs.
2524 </para>
2525 </sect2>
2526 </sect1>
2531 <para>
2532 Wine currently supports several different display subsystems
2533 (graphics / text) that are available on various operating
2534 systems today.
2535 For each of these, Wine implements its own interfacing driver.
2536 This section explains how to select one of these drivers
2537 and how to further configure the respective driver.
2538 Once you're finished with that, you can consider your Wine installation
2539 to be finished.
2540 </para>
2542 <para>
2543 The display drivers currently implemented in Wine are:
2544 x11drv, which is used for interfacing to X11 graphics
2545 (the one you'll most likely want to use) and ttydrv
2546 (used for text mode console apps mainly that don't really need
2547 any graphics output).
2548 Once you have decided which display driver to use, it is chosen
2551 </para>
2553 <sect2>
2556 <para>
2558 </para>
2559 <para>
2561 </para>
2563 <sect3>
2566 <para>
2567 The x11drv driver consists of two conceptually distinct
2568 pieces, the graphics driver (GDI part), and the windowing
2569 driver (USER part). Both of these are linked into the
2572 Wine, running on X11, the graphics driver must draw on
2573 drawables (window interiors) provided by the windowing
2574 driver. This differs a bit from the Windows model, where the
2575 windowing system creates and configures device contexts
2576 controlled by the graphics driver, and programs are
2577 allowed to hook into this relationship anywhere they like.
2578 Thus, to provide any reasonable tradeoff between
2579 compatibility and usability, the x11drv has three different
2580 modes of operation.
2581 </para>
2583 <variablelist>
2584 <varlistentry>
2586 <listitem>
2587 <para>
2589 wine configuration file option (see below).
2590 Ordinary top-level frame windows with thick borders,
2591 title bars, and system menus will be managed by your
2592 window manager. This lets these programs integrate
2593 better with the rest of your desktop, but may not
2594 always work perfectly (a rewrite of this mode of
2595 operation, to make it more robust and less patchy, is
2596 currently being done, though, and it's planned to be
2597 finished before the Wine 1.0 release).
2598 </para>
2599 </listitem>
2600 </varlistentry>
2601 <varlistentry>
2603 <listitem>
2604 <para>
2605 Window manager independent (any running
2606 window manager is ignored completely). Window
2607 decorations (title bars, borders, etc) are drawn by
2608 Wine to look and feel like the real Windows. This is
2609 compatible with programs that depend on being able
2610 to compute the exact sizes of any such decorations, or
2611 that want to draw their own.
2612 Unmanaged mode is only used if both Managed and Desktop
2613 are set to disabled.
2614 </para>
2615 </listitem>
2616 </varlistentry>
2617 <varlistentry>
2619 <listitem>
2620 <para>
2622 wine configuration file option (see below).
2624 for a such-sized desktop, or
2626 automatically position the desktop at the upper-left
2627 corner of the display). This is the mode most
2628 compatible with the Windows model. All program
2629 windows will just be Wine-drawn windows inside the
2630 Wine-provided desktop window (which will itself be
2631 managed by your window manager), and Windows
2632 programs can roam freely within this virtual
2633 workspace and think they own it all, without
2634 disturbing your other X apps.
2635 Note: currently there's one desktop window for every
2636 program; this will be fixed at some time.
2637 </para>
2638 </listitem>
2639 </varlistentry>
2640 </variablelist>
2641 </sect3>
2643 <sect3>
2646 <variablelist>
2647 <varlistentry>
2649 <listitem>
2650 <para>
2651 Wine can let frame windows be managed by your window
2652 manager. This option specifies whether you want that
2653 by default.
2654 </para>
2655 </listitem>
2656 </varlistentry>
2657 <varlistentry>
2659 <listitem>
2660 <para>
2661 Creates a main desktop window of a specified size
2662 to display all Windows programs in.
2663 The size argument could e.g. be "800x600".
2664 </para>
2665 </listitem>
2666 </varlistentry>
2667 <varlistentry>
2669 <listitem>
2670 <para>
2671 If you don't use DGA, you may want an alternative
2672 means to convince the mouse cursor to stay within the
2673 game window. This option does that. Of course, as with
2674 DGA, if Wine crashes, you're in trouble (although not
2675 as badly as in the DGA case, since you can still use
2676 the keyboard to get out of X).
2677 </para>
2678 </listitem>
2679 </varlistentry>
2680 <varlistentry>
2682 <listitem>
2683 <para>
2684 This specifies whether you want DirectDraw to use
2685 XFree86's <firstterm>Direct Graphics
2686 Architecture</firstterm> (DGA), which is able to
2687 take over the entire display and run the game
2688 full-screen at maximum speed. (With DGA1 (XFree86
2689 3.x), you still have to configure the X server to the
2690 game's requested bpp first, but with DGA2 (XFree86
2691 4.x), runtime depth-switching may be possible,
2692 depending on your driver's capabilities.) But be aware
2693 that if Wine crashes while in DGA mode, it may not be
2694 possible to regain control over your computer without
2695 rebooting. DGA normally requires either root
2696 privileges or read/write access to
2698 </para>
2699 </listitem>
2700 </varlistentry>
2701 <varlistentry>
2703 <listitem>
2704 <para>
2705 If you don't want DirectX to use DGA, you can at least
2706 use X Shared Memory extensions (XShm). It is much
2707 slower than DGA, since the app doesn't have direct
2708 access to the physical frame buffer, but using shared
2709 memory to draw the frame is at least faster than
2710 sending the data through the standard X11 socket, even
2711 though Wine's XShm support is still known to crash
2712 sometimes.
2713 </para>
2714 </listitem>
2715 </varlistentry>
2716 <varlistentry>
2718 <listitem>
2719 <para>
2720 Applies only if you use the
2722 to run in a desktop window. Specifies whether to
2723 create the desktop window with a double-buffered
2724 visual, something most OpenGL games need to run
2725 correctly.
2726 </para>
2727 </listitem>
2728 </varlistentry>
2729 <varlistentry>
2731 <listitem>
2732 <para>
2733 Applies only if you have a palette-based display, i.e.
2734 if your X server is set to a depth of 8bpp, and if you
2735 haven't requested a private color map. It specifies
2736 the maximum number of shared colormap cells (palette
2737 entries) Wine should occupy. The higher this value,
2738 the less colors will be available to other
2739 programs.
2740 </para>
2741 </listitem>
2742 </varlistentry>
2743 <varlistentry>
2745 <listitem>
2746 <para>
2747 Applies only if you have a palette-based display, i.e.
2748 if your X server is set to a depth of 8bpp. It
2749 specifies that you don't want to use the shared color
2750 map, but a private color map, where all 256 colors are
2751 available. The disadvantage is that Wine's private
2752 color map is only seen while the mouse pointer is
2753 inside a Wine window, so psychedelic flashing and
2754 funky colors will become routine if you use the mouse
2755 a lot.
2756 </para>
2757 </listitem>
2758 </varlistentry>
2759 <varlistentry>
2761 <listitem>
2762 <para>
2763 To be used for debugging X11 operations.
2764 If Wine crashes with an X11 error, then you should enable
2765 Synchronous mode to disable X11 request caching in order
2766 to make sure that the X11 error happens directly after
2767 the corresponding X11 call in the log file appears.
2768 Will slow down X11 output!
2769 </para>
2770 </listitem>
2771 </varlistentry>
2772 <varlistentry>
2774 <listitem>
2775 <para>
2776 Applies only to multi-depth displays. It specifies
2777 which of the available depths Wine should use (and
2778 tell Windows apps about).
2779 </para>
2780 </listitem>
2781 </varlistentry>
2782 <varlistentry>
2784 <listitem>
2785 <para>
2786 This specifies which X11 display to use, and if
2787 specified, will override the
2789 </para>
2790 </listitem>
2791 </varlistentry>
2792 <varlistentry>
2794 <listitem>
2795 <para>
2796 This option only determines whether fast X11 routines
2797 or exact Wine routines will be used for certain ROP
2798 codes in blit operations. Most users won't notice any
2799 difference.
2800 </para>
2801 </listitem>
2802 </varlistentry>
2803 </variablelist>
2804 </sect3>
2805 </sect2>
2807 <sect2>
2809 <para>
2810 Currently, the ttydrv doesn't have any special configuration
2811 options to set in the configuration file.
2812 </para>
2813 </sect2>
2815 </sect1>
2821 <para>
2823 Oct 18 2002
2824 </para>
2826 <para>
2827 The windows and DOS version value a program gets e.g. by calling the
2828 Windows function GetVersion() plays a very important role:
2829 If your Wine installation for whatever reason fails to provide
2830 to your program the correct version value that it expects,
2831 then the program might assume some very bad things and fail (in
2832 the worst case even silently!).
2834 Fortunately Wine contains some more or less intelligent Windows
2835 version guessing algorithm that will try to guess the Windows
2836 version a program might expect and pass that one on to the
2837 program.
2839 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.
2840 </para>
2842 <sect2>
2843 <title>How to configure the Windows and DOS version value Wine
2844 should return</title>
2846 <para>
2847 The version values can be configured in the wine configuration file in
2848 the [Version] section.
2849 </para>
2851 <variablelist>
2852 <varlistentry>
2854 <listitem>
2855 <para>
2856 default: none; chosen by semi-intelligent detection
2857 mechanism based on DLL environment.
2858 Used to specify which Windows version to return to
2859 programs (forced value, overrides standard detection
2862 Also valid as an
2864 setting (recommended/preferred use).
2865 </para>
2866 </listitem>
2867 </varlistentry>
2868 <varlistentry>
2870 <listitem>
2871 <para>
2872 Used to specify the DOS version that should be returned
2873 to programs. Only takes effect in case Wine acts as
2874 "win31" Windows version! Common DOS version settings
2876 Also valid as an
2878 setting (recommended/preferred use).
2879 </para>
2880 </listitem>
2881 </varlistentry>
2882 </variablelist>
2883 </sect2>
2884 </sect1>
2886 &fonts;
2887 &printing;
2891 <para>
2893 </para>
2894 <para>
2896 </para>
2897 <para>
2898 Win95/Win98 interface code is being introduced.
2899 </para>
2900 <para>
2901 Instead of compiling Wine for Win3.1 vs. Win95 using
2903 special [Tweak.Layout] section of
2907 </para>
2908 <para>
2909 A few new sections and a number of entries have been added to
2911 debugging the Win95 tweaks only and may be removed in a future
2912 release! These entries/sections are:
2913 </para>
2914 <programlisting>
2915 [Tweak.Fonts]
2921 "OEMFixed.xxx" # Same parameters for the OEM fixed typeface
2922 "AnsiFixed.xxx" # Same parameters for the Ansi fixed typeface
2923 "AnsiVar.xxx" # Same parameters for the Ansi variable typeface
2924 "SystemFixed.xxx" # Same parameters for the System fixed typeface
2926 [Tweak.Layout]
2928 </programlisting>
2929 </sect1>
2934 <para>
2936 </para>
2937 <para>
2939 </para>
2941 <para>
2942 Wine now needs to know about your keyboard layout. This
2943 requirement comes from a need from many apps to have the
2944 correct scancodes available, since they read these directly,
2945 instead of just taking the characters returned by the X
2946 server. This means that Wine now needs to have a mapping from
2947 X keys to the scancodes these programs expect.
2948 </para>
2949 <para>
2950 On startup, Wine will try to recognize the active X layout by
2951 seeing if it matches any of the defined tables. If it does,
2952 everything is alright. If not, you need to define it.
2953 </para>
2954 <para>
2955 To do this, open the file
2957 at the existing tables. Make a backup copy of it, especially
2958 if you don't use CVS.
2959 </para>
2960 <para>
2961 What you really would need to do, is find out which scancode
2962 each key needs to generate. Find it in the
2964 this:
2965 </para>
2966 <programlisting>
2967 static const int main_key_scan[MAIN_LEN] =
2968 {
2969 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
2975 };
2976 </programlisting>
2977 <para>
2978 Next, assign each scancode the characters imprinted on the
2979 keycaps. This was done (sort of) for the US 101-key keyboard,
2980 which you can find near the top in
2982 is no 102nd key, you can skip that.
2983 </para>
2984 <para>
2985 However, for most international 102-key keyboards, we have
2986 done it easy for you. The scancode layout for these already
2987 pretty much matches the physical layout in the
2989 to go through all the keys that generate characters on your
2990 main keyboard (except spacebar), and stuff those into an
2991 appropriate table. The only exception is that the 102nd key,
2992 which is usually to the left of the first key of the last line
2994 line after the last line.
2995 </para>
2996 <para>
2997 For example, my Norwegian keyboard looks like this
2998 </para>
2999 <screen>
3000 § ! " # ¤ % & / ( ) = ? ` Back-
3001 | 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
3003 Tab Q W E R T Y U I O P Å ^
3004 ¨~
3005 Enter
3006 Caps A S D F G H J K L Ø Æ *
3007 Lock '
3009 Sh- > Z X C V B N M ; : _ Shift
3010 ift < , . -
3012 Ctrl Alt Spacebar AltGr Ctrl
3013 </screen>
3014 <para>
3015 Note the 102nd key, which is the <keycap><></keycap> key, to
3016 the left of <keycap>Z</keycap>. The character to the right of
3017 the main character is the character generated by
3018 <keycap>AltGr</keycap>.
3019 </para>
3020 <para>
3021 This keyboard is defined as follows:
3022 </para>
3023 <programlisting>
3024 static const char main_key_NO[MAIN_LEN][4] =
3025 {
3030 "<>"
3031 };
3032 </programlisting>
3033 <para>
3034 Except that " and \ needs to be quoted with a backslash, and
3035 that the 102nd key is on a separate line, it's pretty
3036 straightforward.
3037 </para>
3038 <para>
3039 After you have written such a table, you need to add it to the
3040 <function>main_key_tab[]</function> layout index table. This
3041 will look like this:
3042 </para>
3043 <programlisting>
3044 static struct {
3045 WORD lang, ansi_codepage, oem_codepage;
3046 const char (*key)[MAIN_LEN][4];
3047 } main_key_tab[]={
3048 ...
3049 ...
3050 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
3051 ...
3052 </programlisting>
3053 <para>
3054 After you have added your table, recompile Wine and test that
3055 it works. If it fails to detect your table, try running
3056 </para>
3057 <screen>
3058 wine --debugmsg +key,+keyboard >& key.log
3059 </screen>
3060 <para>
3061 and look in the resulting <filename>key.log</filename> file to
3062 find the error messages it gives for your layout.
3063 </para>
3064 <para>
3065 Note that the <constant>LANG_*</constant> and
3066 <constant>SUBLANG_*</constant> definitions are in
3067 <filename>include/winnls.h</filename>, which you might need to
3068 know to find out which numbers your language is assigned, and
3069 find it in the debugmsg output. The numbers will be
3070 <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
3071 the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
3072 <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
3073 <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
3074 could look for <literal>0414</literal> in the debugmsg output
3075 to find out why my keyboard won't detect.
3076 </para>
3077 <para>
3078 Once it works, submit it to the Wine project. If you use CVS,
3079 you will just have to do
3080 </para>
3081 <screen>
3082 cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
3083 </screen>
3084 <para>
3085 from your main Wine directory, then submit
3086 <filename>layout.diff</filename> to
3087 <email>wine-patches@winehq.com</email> along with a brief note
3088 of what it is.
3089 </para>
3090 <para>
3091 If you don't use CVS, you need to do
3092 </para>
3093 <screen>
3094 diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
3095 </screen>
3096 <para>
3097 and submit it as explained above.
3098 </para>
3099 <para>
3100 If you did it right, it will be included in the next Wine
3101 release, and all the troublesome programs (especially
3102 remote-control programs) and games that use scancodes will
3103 be happily using your keyboard layout, and you won't get those
3104 annoying fixme messages either.
3105 </para>
3106 <para>
3107 Good luck.
3108 </para>
3109 </sect1>
3112 <title>SCSI Support</title>
3113 <para>
3114 Written by &name-bruce-milner; <email>&email-bruce-milner;</email>;
3115 Additions by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
3116 </para>
3117 <para>
3118 (Extracted from <filename>wine/documentation/aspi</filename>)
3119 </para>
3121 <para>
3122 This file describes setting up the Windows ASPI interface.
3123 </para>
3125 <para>
3126 <warning><title>Warning/Warning/Warning!!!!!!</title>
3127 <para>This may trash your system if used incorrectly. It may
3128 even trash your system when used <emphasis>correctly</>!
3129 </para>
3130 </warning>
3131 </para>
3133 <para>
3134 Now that I have said that. ASPI is a direct link to SCSI devices from
3135 windows programs. ASPI just forwards the SCSI commands that programs send
3136 to it to the SCSI bus.
3137 </para>
3138 <para>
3139 If you use the wrong SCSI device in your setup file, you can send
3140 completely bogus commands to the wrong device - An example would be
3141 formatting your hard drives (assuming the device gave you permission -
3142 if you're running as root, all bets are off).
3143 </para>
3144 <para>
3145 So please make sure that <emphasis>all</emphasis> SCSI devices not needed by the program
3146 have their permissions set as restricted as possible!
3147 </para>
3149 <para>
3150 Cookbook for setting up scanner: (At least how mine is to work)
3151 (well, for other devices such as CD burners, MO drives, ..., too)
3152 </para>
3154 <sect2>
3155 <title>Windows requirements</title>
3156 <orderedlist>
3157 <listitem>
3158 <para>
3160 compatible drivers (ASPI). At least with Mustek, they
3161 allow you the choice of using the built-in card or the
3163 any other way. Software that accesses the scanner via a
3164 DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM]
3165 </para>
3166 </listitem>
3167 <listitem>
3168 <para>
3169 You probably need a real windows install of the software
3170 to set the LUN's/SCSI id's up correctly. I'm not exactly
3171 sure.
3172 </para>
3173 </listitem>
3174 </orderedlist>
3175 </sect2>
3177 <sect2>
3178 <title>Linux requirements</title>
3179 <orderedlist>
3180 <listitem>
3181 <para>
3182 Your SCSI card must be supported under Linux. This will
3183 not work with an unknown SCSI card. Even for cheap'n
3185 drivers exist on the net.
3186 If you intend to use your IDE device, you need to use the
3187 ide-scsi emulation.
3188 Read
3190 http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html</ulink>
3191 for ide-scsi setup instructions.
3192 </para>
3193 </listitem>
3194 <listitem>
3195 <para>
3196 Compile generic SCSI drivers into your kernel.
3197 </para>
3198 </listitem>
3199 <listitem>
3200 <para>
3201 This seems to be not required any more for newer (2.2.x) kernels:
3202 Linux by default uses smaller SCSI buffers than Windows.
3203 There is a kernel build define <literal>SG_BIG_BUFF</literal> (in
3204 <filename>sg.h</filename>) that is by default set too
3205 low. The SANE project recommends
3206 <literal>130560</literal> and this seems to work just
3207 fine. This does require a kernel rebuild.
3208 </para>
3209 </listitem>
3210 <listitem>
3211 <para>
3212 Make the devices for the scanner (generic SCSI devices)
3213 - look at the SCSI programming HOWTO at
3215 http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html</ulink>
3216 for device numbering.
3217 </para>
3218 </listitem>
3219 <listitem>
3220 <para>
3221 I would recommend making the scanner device writable by
3222 a group. I made a group called
3223 <literal>scanner</literal> and added myself to it.
3224 Running as root increases your risk of sending bad SCSI
3225 commands to the wrong device. With a regular user, you
3226 are better protected.
3227 </para>
3228 </listitem>
3229 <listitem>
3230 <para>
3231 For Win32 software (WNASPI32), Wine has auto-detection in place.
3232 For Win16 software (WINASPI), you need to add a SCSI device entry
3233 for your particular scanner to ~/.wine/config. The format is
3234 <literal>[scsi cCtTdD]</literal> where
3237 </para>
3238 <para>
3239 For example, I set mine up as controller <literal>0</literal>,
3240 Target <literal>6</literal>, LUN <literal>0</literal>.
3241 <programlisting>
3242 [scsi c0t6d0]
3244 </programlisting>
3245 Yours will vary with your particular SCSI setup.
3246 </para>
3247 </listitem>
3248 </orderedlist>
3249 </sect2>
3251 <sect2>
3252 <title>General Information</title>
3253 <para>
3254 The mustek scanner I have was shipped with a package
3256 to access scanners.
3257 </para>
3258 <para>
3259 (TWAIN MANAGER)
3260 </para>
3261 <para>
3262 <programlisting>
3263 ipplus.exe <-> (TWAIN INTERFACE) <-> (TWAIN DATA SOURCE.ASPI) -> WINASPI
3264 </programlisting>
3265 </para>
3266 </sect2>
3268 <sect2>
3269 <title>NOTES/BUGS</title>
3270 <para>
3271 The biggest drawback is that it only works under Linux at the moment.
3272 </para>
3273 <para>
3274 The ASPI code has only been tested with:
3275 </para>
3276 <itemizedlist>
3277 <listitem>
3278 <para>
3279 a Mustek 800SP with a Buslogic controller under Linux [BM]
3280 </para>
3281 </listitem>
3282 <listitem>
3283 <para>
3284 a Siemens Nixdorf 9036 with Adaptec AVA-1505 under Linux
3285 accessed via DOSASPI. Note that I had color problems,
3286 though (barely readable result) [AM]
3287 </para>
3288 </listitem>
3289 <listitem>
3290 <para>
3291 a Fujitsu M2513A MO drive (640MB) using generic SCSI
3292 drivers. Formatting and ejecting worked perfectly.
3293 Thanks to Uwe Bonnes for access to the hardware! [AM]
3294 </para>
3295 </listitem>
3296 </itemizedlist>
3297 <para>
3298 I make no warranty to the ASPI code. It makes my scanner
3299 work. Your devices may explode. I have no way of determining
3300 this. I take zero responsibility!
3301 </para>
3302 </sect2>
3303 </sect1>
3306 <title>Using ODBC</title>
3307 <para>
3308 This section describes how ODBC works within Wine and how to configure
3309 it to do what you want (if it can do what you want).
3310 </para>
3311 <para>
3312 The ODBC system within Wine, as with the printing system, is designed
3313 to hook across to the Unix system at a high level. Rather than
3314 ensuring that all the windows code works under wine it uses a suitable
3315 Unix ODBC provider, such as UnixODBC. Thus if you configure Wine to
3316 use the built-in odbc32.dll, that Wine DLL will interface to your
3317 Unix ODBC package and let that do the work, whereas if you configure
3318 Wine to use the native odbc32.dll it will try to use the native
3319 ODBC32 drivers etc.
3320 </para>
3321 <sect2>
3322 <title>Using a Unix ODBC system with Wine</title>
3323 <para>
3324 The first step in using a Unix ODBC system with Wine is, of course,
3325 to get the Unix ODBC system working itself. This may involve
3326 downloading code or RPMs etc. There are several Unix ODBC systems
3327 available; the one the author is used to is unixODBC (with the
3328 IBM DB2 driver). Typically such systems will include a tool, such
3329 as <command>isql</command>, which will allow you to access the data from the command
3330 line so that you can check that the system is working.
3331 </para>
3332 <para>
3333 The next step is to hook the Unix ODBC library to the wine built-in
3334 odbc32 DLL. The built-in odbc32 (currently) looks to the
3335 environment variable <emphasis>LIB_ODBC_DRIVER_MANAGER</emphasis>
3336 for the name of the ODBC library. For example in the author's
3337 .bashrc file is the line:
3338 </para>
3339 <programlisting>
3340 export LIB_ODBC_DRIVER_MANAGER=/usr/lib/libodbc.so.1.0.0
3341 </programlisting>
3342 <para>
3343 If that environment variable is not set then it looks for a
3344 library called libodbc.so and so you can add a symbolic link to
3345 equate that to your own library. For example as root you could
3346 run the commands:
3347 </para>
3348 <screen>
3349 <prompt># </prompt><userinput>ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so</userinput>
3350 <prompt># </prompt><userinput>/sbin/ldconfig</userinput>
3351 </screen>
3352 <para>
3353 The last step in configuring this is to ensure that Wine is set up
3354 to run the built-in version of odbc32.dll, by modifying the DLL
3355 configuration. This built-in DLL merely acts as a stub between the
3356 calling code and the Unix ODBC library.
3357 </para>
3358 <para>
3359 If you have any problems then you can use the debugmsg channel
3360 odbc32 to trace what is happening. One word of warning. Some
3361 programs actually cheat a little and bypass the ODBC library. For
3362 example the Crystal Reports engine goes to the registry to check on
3363 the DSN. The fix for this is documented at unixODBC's site where
3364 there is a section on using unixODBC with Wine.
3365 </para>
3366 </sect2>
3367 <sect2>
3368 <title>Using Windows ODBC drivers</title>
3369 <para>
3370 Does anyone actually have any experience of this and anything to
3371 add?
3372 </para>
3373 </sect2>
3374 </sect1>
3376 </chapter>
3378 <!-- Keep this comment at the end of the file
3379 Local variables:
3380 mode: sgml
3382 End:
3383 -->