| blob | 7528a0b6766bb88598ff2b8f77aa8c42fc7259ee |
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 but don't forget to put it as a DOS environment variable,
1080 ie surrounded by '%' signs rather than preceded by a '$'.
1081 Don't forget to leave off the trailing slash!
1082 </para>
1083 <para>
1085 Sets up the type of drive Wine will see it as. Type must
1089 (The |'s mean "Type = '<one of the options>'".)
1091 For a home directory entry, it makes sense to choose
1092 "network" sometimes, since some home directories are being
1093 exported over the network via NFS and thus can have slow response
1094 times.
1095 </para>
1096 <para>
1098 Defines the drive label. Generally only needed
1099 for programs that look for a special CD-ROM.
1100 The label may be up to 11 characters.
1101 Note that the preferred way of managing labels and serial numbers
1102 of CD-ROMs and floppies is to give Wine raw device access for
1103 reading these on a per-CD case (see "Device" below) instead of
1104 hardcoding one specific "Label".
1105 </para>
1106 <para>
1108 Tells Wine the serial number of the drive. A few programs with
1109 intense protection for pirating might need this, but otherwise
1110 it's not needed. Up to 8 characters and hexadecimal.
1112 is a smarter choice.
1113 </para>
1114 <para>
1116 Sets up the way Wine looks at files on the drive.
1117 This setting controls the file name lookup and mapping of
1118 Wine to existing file systems on your PC, it does
1120 used itself.
1121 </para>
1123 <variablelist>
1124 <varlistentry>
1126 <listitem>
1127 <para>
1129 the long filename filesystem you are probably used
1130 to working with. The filesystem behavior of choice for most
1131 programs to be run under wine. <emphasis>Probably the one
1132 you want!</emphasis>
1133 </para>
1134 </listitem>
1135 </varlistentry>
1136 <varlistentry>
1138 <listitem>
1139 <para>
1140 Case sensitive. This filesystem has almost no use
1141 (Windows apps expect case insensitive filenames),
1142 except maybe for Winelib applications.
1143 Try it if you dare, but win95 is a much better
1144 and always recommended choice.
1145 </para>
1146 </listitem>
1147 </varlistentry>
1148 <varlistentry>
1150 <listitem>
1151 <para>
1152 Case insensitive filesystem. Alike to DOS and
1154 length of files (eightdot.123) - longer ones will be
1155 truncated.
1156 <note>
1157 <para>
1159 you plan on running apps that use long filenames.
1160 win95 should work fine with apps that were designed
1161 to run under the msdos system. In other words, you
1162 might not want to use this.
1163 </para>
1164 </note>
1165 </para>
1166 </listitem>
1167 </varlistentry>
1168 </variablelist>
1171 <para>
1172 Needed for raw device access and <link linkend="config-drive-cdrom-labels">label and serial number reading</link>.
1174 Extended2 or other Unix file systems can have dire results
1175 (when a windows app tries to do a lowlevel write,
1176 they do it in a FAT way -- FAT format is completely different from
1177 any Unix file system).
1178 Also, make sure that you have proper permissions to this device
1179 file.
1180 </para>
1181 <note>
1182 <para>
1183 This setting is not really important; almost all apps
1184 will have no problem if it remains unspecified. For
1185 CD-ROMs it's quite useful in order to get automatic label
1186 detection, though. If you are unsure about specifying
1187 device names, just leave out this setting for your
1188 drives.
1189 </para>
1190 </note>
1191 <para>
1192 Here are a few sample entries:
1193 <programlisting>
1194 Here is a setup for Drive C, a generic hard drive:
1195 [Drive C]
1200 This is a setup for Drive E, a generic CD-ROM drive:
1201 [Drive E]
1207 And here is a setup for Drive A, a generic floppy drive:
1208 [Drive A]
1215 </programlisting>
1216 </para>
1217 </sect2>
1219 <sect2>
1221 <para>
1223 This tells Wine and Windows programs where the
1225 recommended to have this directory somewhere on your
1227 recommended to just call the directory "windows" (this is
1228 the default setup on Windows, and some stupid programs
1229 might rely on this). So in case you chose a "Windows"
1230 setting of "c:\\windows" and you chose to set up a drive C
1232 corresponding directory would be
1234 if you don't already have one. <emphasis>No trailing slash</emphasis> (<emphasis>not</emphasis>
1236 recommended, as Windows programs always assume write access
1237 to the Windows directory!
1238 </para>
1239 <para>
1241 This sets up where the windows system files are. The Windows
1242 system directory should reside below the directory used for the
1244 Thus when using the example above, the system directory would be
1246 Again, no trailing slash, and write access!
1247 </para>
1248 <para>
1250 be the directory you want your temp files stored in,
1251 /usr/local/wine_c/temp in our example.
1252 Again, no trailing slash, and <emphasis>write
1253 access</emphasis>!!
1254 </para>
1255 <para>
1258 boxes. When wine is run like <userinput>wine
1260 resides in a directory specified in the
1263 current directory, wine will run that one). Make sure it
1265 system directory (For this setup, it must have
1267 </para>
1270 Wine doesn't pass directory symlinks to Windows programs by
1271 default, as doing so may crash some programs that do
1272 recursive lookups of whole subdirectory trees
1273 whenever a directory symlink points back to itself or one of its
1274 parent directories.
1275 That's why we disallowed the use of directory symlinks
1276 and added this setting to reenable ("1") this functionality.
1278 account symlinked directories, then reenable it, but
1280 Windows programs when using the above method! (in other words:
1281 enabling it is certainly not recommended)
1282 </para>
1283 </sect2>
1285 <sect2>
1287 <para>
1288 Windows uses a different (and inferior) way than Unix to describe the
1289 location of files in a computer. Thus Windows programs also expect
1290 to find this different way supported by the system.
1291 Since we intend to run Windows programs on
1292 a Unix system, we're in trouble, as we need to translate
1293 between these different file access techniques.
1294 </para>
1295 <para>
1296 Windows uses drive letters to describe drives or
1297 any other form of storage media and to access files on them.
1298 For example, common drive names are
1301 first floppy drive.
1303 directory separator sign, whereas Unix uses
1305 Thus, an example document on the first data partition in
1306 Windows might be accessed by the name of
1308 </para>
1309 <para>
1310 So much for the Windows way of doing things.
1311 </para>
1312 <para>
1313 Well, the problem is, in Unix there is no such thing as
1315 much better way of having one single uniform directory tree
1316 (starting with the root directory
1318 such as e.g. harddisk partitions appended at various directory
1319 locations within the tree (an example would be
1321 partition mounted/attached to a directory called data1 in the
1323 directory of the data partition file system that's mounted
1325 In Unix, the Windows example document mentioned above could e.g.
1326 be accessed by the name of
1328 provided that the administrator decided to mount (attach) the first
1329 data partition at the directory /data1 inside the Unix
1330 directory tree. Note that in Unix, the administrator can
1334 suitable for the first data partition (here,
1336 change in partition order, Windows automatically
1338 suddenly find yourself with a first data partition at drive
1340 referencing confusion that entails. Thus, the Windows way of
1341 using ever-changing drive letters is <emphasis>clearly
1342 inferior</emphasis> to the Unix way of assigning
1344 data storage medium.
1345 As we'll see soon, fortunately this Windows limitation of
1346 changing drive letters doesn't affect us in Wine at all, since
1347 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).
1348 </para>
1349 <para>
1350 OK, now that we know some theory about Windows and Unix drive
1351 and filename mapping, it's probably time to ask how Wine
1352 achieves the magic of mapping a Unix directory location to a
1353 Windows drive...
1354 </para>
1355 <para>
1356 Wine chose to do the following:
1357 In Wine, you don't assign some real physical storage medium
1358 (such as a harddisk partition or similar) to each drive letter
1359 mapping entry.
1360 Instead, you choose certain sub directory trees inside the Unix
1362 you would like to assign a drive letter to.
1363 </para>
1364 <para>
1365 Note that for every Unix sub directory tree that you intend to
1366 start Windows programs in, it is <emphasis>absolutely
1367 required</emphasis> to have a Wine drive mapping entry:
1368 </para>
1369 <para>
1370 For example, if you had a publicly writable <quote>Windows
1372 able to access this sub directory tree from Wine, you should
1373 have a drive mapping entry that maps a certain drive letter
1375 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.
1376 </para>
1377 </sect2>
1381 <para>
1383 </para>
1384 <para>
1386 </para>
1388 <para>
1389 A major goal of Wine is to allow users to run Windows programs
1390 without having to install Windows on their machine. Wine
1391 implements the functionality of the main DLLs usually
1392 provided with Windows. Therefore, once Wine is finished, you
1393 will not need to have Windows installed to use Wine.
1394 </para>
1395 <para>
1396 Wine has already made enough progress that it may be possible
1397 to run your target programs without Windows installed. If
1398 you want to try it, follow these steps:
1399 </para>
1401 <orderedlist>
1402 <listitem>
1403 <para>
1407 for more information.
1408 The directory to be used for emulating a C: drive will be
1409 the base directory for some Windows specific directories
1410 created below.
1411 Remember to use
1413 </para>
1414 </listitem>
1415 <listitem>
1416 <para>
1417 Within the directory to be used for C:, create empty
1422 directories. Do not point Wine to a
1424 installations and a messy registry. (Wine creates a
1427 Perhaps you have to remove these files).
1428 In one line:
1429 mkdir -p windows windows/system windows/Start\ Menu windows/Start\ Menu/Programs
1430 </para>
1431 </listitem>
1432 <listitem>
1433 <para>
1434 Run and/or install your programs.
1435 </para>
1436 </listitem>
1437 </orderedlist>
1439 <para>
1440 Because Wine is not yet complete, some programs will work
1441 better with native Windows DLLs than with Wine's
1442 replacements. Wine has been designed to make this possible.
1443 Here are some tips by Juergen Schmied (and others) on how to
1444 proceed. This assumes that your
1446 file does not point to a native Windows installation but is in
1450 </para>
1452 <itemizedlist>
1453 <listitem>
1454 <para>
1455 Run the program with <parameter>--debugmsg
1456 +loaddll</parameter> to find out which files are
1457 needed. Copy the required DLLs one by one to the
1459 copy KERNEL/KERNEL32, GDI/GDI32, USER/USER32 or NTDLL. These
1460 implement the core functionality of the Windows API, and
1461 the Wine internal versions must be used.
1462 </para>
1463 </listitem>
1464 <listitem>
1465 <para>
1469 the Windows DLLs you want to use. For more information
1470 about this, see the Wine manpage.
1471 </para>
1472 </listitem>
1473 <listitem>
1474 <para>
1475 Note that some network DLLs are not needed even though
1476 Wine is looking for them. The Windows
1478 must use the internal implementation.
1479 </para>
1480 </listitem>
1481 <listitem>
1482 <para>
1483 Copy SHELL.DLL/SHELL32.DLL, COMMDLG.DLL/COMDLG32.DLL
1484 and COMMCTRL.DLL/COMCTL32.DLL
1485 only as pairs to your Wine directory (these DLLs are
1489 </para>
1490 </listitem>
1491 <listitem>
1492 <para>
1493 Be consistent: Use only DLLs from the same Windows version
1494 together.
1495 </para>
1496 </listitem>
1497 <listitem>
1498 <para>
1503 registry, don't know about
1505 As of now, it might not be necessary any more to use
1506 regedit.exe, since Wine has its own regedit Winelib
1507 application now.
1508 </para>
1509 </listitem>
1510 <listitem>
1511 <para>
1514 to browse through your programs' help function
1515 (or in case Wine's winhelp implementation in programs/winhelp/
1516 is not good enough, for example).
1517 </para>
1518 </listitem>
1519 </itemizedlist>
1520 </sect2>
1524 <para>
1525 Some people intend to use the data of an existing Windows partition
1526 with Wine in order to gain some better compatibility or to run already
1527 installed programs in a setup as original as possible.
1528 Note that many Windows programs assume that they have full write
1529 access to all windows directories.
1531 This means that you either have to configure the Windows
1532 partition mount point for write permission by your Wine user
1534 on how to do that), or you'll have to copy over (some parts of) the Windows
1535 partition content to a directory of a Unix partition and make
1536 sure this directory structure is writable by your user.
1538 write access as a base for Wine!! (some programs, notably
1539 Explorer, corrupt large parts of the Windows partition in case
1540 of an incorrect setup; you've been warned).
1541 Not to mention that NTFS write support in Linux is still very
1543 Windows version using the NTFS file system).
1544 Thus we advise you to go the Unix directory way.
1545 </para>
1546 </sect2>
1550 <para>
1552 </para>
1553 <para>
1555 </para>
1556 <para>
1557 This document describes how FAT and
1558 VFAT file system permissions work in Linux
1559 with a focus on configuring them for Wine.
1560 </para>
1562 <sect3>
1564 <para>
1565 Linux is able to access DOS and Windows file systems using
1566 either the FAT (older 8.3 DOS filesystems) or VFAT (newer
1567 Windows 95 or later long filename filesystems) modules.
1568 Mounted FAT or VFAT filesystems provide the primary means
1569 for which existing programs and their data are accessed
1570 through Wine for dual boot (Linux + Windows) systems.
1571 </para>
1572 <para>
1573 Wine maps mounted FAT filesystems, such as
1578 </para>
1579 <programlisting>
1580 [Drive C]
1583 </programlisting>
1584 <para>
1585 Although VFAT filesystems are preferable to FAT filesystems
1587 will be used throughout the remainder of this document to
1588 refer to FAT filesystems and their derivatives. Also,
1590 examples throughout this document.
1591 </para>
1592 <para>
1593 Most modern Linux distributions either detect or allow
1594 existing FAT file systems to be configured so that they can be
1596 either persistently (on bootup) or on an as needed basis. In
1597 either case, by default, the permissions will probably be
1598 configured so that they look like:
1599 </para>
1600 <screen>
1606 </screen>
1607 <para>
1609 group and are only writable by "root"
1611 that it requires that Wine be run as root in order for
1612 programs to be able to write to any part of the
1613 filesystem.
1614 </para>
1615 <para>
1616 There are three major approaches to overcoming the restrictive
1617 permissions mentioned in the previous paragraph:
1618 </para>
1619 <orderedlist>
1620 <listitem>
1621 <para>
1623 </para>
1624 </listitem>
1625 <listitem>
1626 <para>
1627 Mount the FAT filesystem with less restrictive
1628 permissions
1629 </para>
1630 </listitem>
1631 <listitem>
1632 <para>
1633 Shadow the FAT filesystem by completely or partially
1634 copying it
1635 </para>
1636 </listitem>
1637 </orderedlist>
1638 <para>
1639 Each approach will be discussed in the following sections.
1640 </para>
1641 </sect3>
1643 <sect3>
1645 <para>
1646 Running Wine as root is the easiest and most thorough way of giving
1647 programs that Wine runs unrestricted access to FAT files systems.
1648 Running wine as root also allows programs to do things unrelated
1649 to FAT filesystems, such as listening to ports that are less than
1650 1024. Running Wine as root is dangerous since there is no limit to
1652 </para>
1653 </sect3>
1655 <sect3>
1657 <para>
1658 The FAT filesystem can be mounted with permissions less restrictive
1659 than the default. This can be done by either changing the user that
1660 mounts the FAT filesystem or by explicitly changing the permissions
1661 that the FAT filesystem is mounted with. The permissions are
1662 inherited from the process that mounts the FAT filesystem. Since the
1663 process that mounts the FAT filesystem is usually a startup script
1664 running as root the FAT filesystem inherits root's permissions. This
1665 results in the files on the FAT filesystem having permissions similar
1666 to files created by root. For example:
1667 </para>
1668 <screen>
1674 </screen>
1675 <para>
1676 which matches the owner, group and permissions of files seen
1677 on the FAT filesystem except for the missing 'x's. The
1678 permissions on the FAT filesystem can be changed by changing
1679 root's umask (unset permissions bits). For example:
1680 </para>
1681 <screen>
1692 </screen>
1693 <para>
1694 Mounting the FAT filesystem with a umask of
1696 it. Explicitly specifying the permissions of the FAT
1697 filesystem when it is mounted provides additional control.
1698 There are three mount options that are relevant to FAT
1701 when the filesystem is manually mounted. For example:
1702 </para>
1703 <screen>
1711 </screen>
1712 <para>
1713 which gives "sle" complete control over
1715 made permanent by adding them to the
1717 </para>
1718 <screen>
1720 <computeroutput>/dev/hda1 /c vfat uid=500,gid=500,umask=002,exec,dev,suid,rw 1 1</computeroutput>
1721 </screen>
1722 <para>
1724 the user private group file permission scheme. On FAT file
1725 systems this umask assures that all files are fully
1726 accessible by all users in the specified user group
1728 </para>
1729 </sect3>
1731 <sect3>
1733 <para>
1734 Shadowing provides a finer granularity of control. Parts of
1735 the original FAT filesystem can be copied so that the
1736 program can safely work with those copied parts while
1737 the program continues to directly read the remaining
1738 parts. This is done with symbolic links. For example,
1739 consider a system where a program named
1743 read access to the entire FAT filesystem. On this system
1744 the FAT filesystem has default permissions which should not
1745 be changed for security reasons or can not be changed due to
1746 lack of root access. On this system a shadow directory
1747 might be set up in the following manner:
1748 </para>
1749 <screen>
1757 <prompt>/c_shadow></prompt><userinput>perl -p -i -e 's|/c$|/c_shadow|g' ~/.wine/config</userinput>
1758 </screen>
1759 <para>
1760 The above gives everyone complete read and write access to
1763 write access to all other directories.
1764 </para>
1765 </sect3>
1766 </sect2>
1769 <sect2info>
1770 <authorgroup>
1771 <author>
1774 <affiliation>
1776 </affiliation>
1778 </author>
1779 <author>
1782 <affiliation>
1784 </affiliation>
1786 </author>
1787 </authorgroup>
1788 </sect2info>
1791 <para>
1793 Nov 14 1999
1794 </para>
1795 <para>
1797 Jan 25 2000
1798 </para>
1799 <para>
1801 </para>
1802 <para>
1803 Until now, your only possibility of specifying drive volume
1804 labels and serial numbers was to set them manually in the wine
1805 configuration file. By now, wine can read them directly from the
1806 device as well. This may be useful for many Win 9x games or
1807 for setup programs distributed on CD-ROMs that check for
1808 volume label.
1809 </para>
1811 <sect3>
1816 <thead>
1817 <row>
1821 </row>
1822 </thead>
1823 <tbody>
1824 <row>
1828 </row>
1829 <row>
1833 </row>
1834 </tbody>
1835 </tgroup>
1836 </informaltable>
1838 </sect3>
1840 <sect3>
1842 <para>
1843 Reading labels and serial numbers just works automatically
1846 Note that the device has to exist and must be accessible by the user
1847 running Wine if you do this, though.
1848 </para>
1849 <para>
1850 If you don't want to read labels and serial numbers directly from
1851 the device, then you should give fixed
1854 these entries instead if no device is given. If they don't
1855 exist, then Wine will return default values (label
1858 </para>
1859 <para>
1862 but not for reading the volume info from the device (i.e. you want
1865 to skip the volume reading.
1866 </para>
1867 </sect3>
1869 <sect3>
1871 <para>
1872 Here's a simple example of CD-ROM and floppy; labels will be
1873 read from the device on both CD-ROM and floppy; serial
1874 numbers on floppy only:
1875 </para>
1876 <programlisting>
1877 [Drive A]
1883 [Drive R]
1888 </programlisting>
1889 <para>
1890 Here's an example of overriding the CD-ROM label:
1891 </para>
1892 <programlisting>
1893 [Drive J]
1897 ; note that the device isn't really needed here as we have a fixed label
1900 </programlisting>
1901 </sect3>
1903 <sect3>
1905 <itemizedlist>
1906 <listitem> <para>
1907 The CD-ROM label can be read only if the data track of
1908 the disk resides in the first track and the cdrom is
1909 iso9660.
1910 </para> </listitem>
1911 <listitem> <para>
1912 Better checking for FAT superblock (it now checks only
1913 one byte). </para>
1914 </listitem>
1915 <listitem> <para>
1916 Support for labels/serial nums WRITING.
1917 </para> </listitem>
1918 <listitem> <para>
1920 chars).
1921 </para> </listitem>
1922 <listitem> <para>
1923 What about reading ext2 volume label? ....
1924 </para> </listitem>
1925 </itemizedlist>
1926 </sect3>
1927 </sect2>
1928 </sect1>
1930 ®istry;
1935 <sect2>
1937 <para>
1938 If your programs don't work as expected, then it's often because one
1939 DLL or another is failing. This can often be resolved by changing
1940 certain DLLs from Wine built-in to native Windows DLL file and vice
1941 versa.
1942 </para>
1943 <para>
1944 A very useful help to find out which DLLs are loaded as built-in and
1945 which are loaded as native Windows file can be the debug channel
1946 loaddll, activated via the Wine command line parameter
1948 </para>
1949 </sect2>
1951 <sect2>
1952 <!-- FIXME intro!!! -->
1954 <para>
1955 There are a few things you will need to know before
1956 configuring the DLL sections in your wine configuration
1957 file.
1958 </para>
1959 <sect3>
1961 <para>
1962 Most windows DLL's have a win16 (Windows 3.x) and win32
1963 (Windows 9x/NT) form. The combination of the win16 and
1964 win32 DLL versions are called the "DLL pair". This is a
1965 list of the most common pairs:
1966 </para>
1968 <informaltable>
1970 <thead>
1971 <row>
1974 <entry>
1975 Native
1976 <footnote>
1977 <para>
1978 Is it possible to use native DLL with wine?
1979 (See next section)
1980 </para>
1981 </footnote>
1982 </entry>
1983 </row>
1984 </thead>
1985 <tbody>
1986 <row>
1990 </row>
1991 <row>
1995 </row>
1996 <row>
2000 </row>
2001 <row>
2005 </row>
2006 <row>
2010 </row>
2011 <row>
2015 </row>
2016 </tbody>
2017 </tgroup>
2018 </informaltable>
2019 </sect3>
2021 <sect3>
2023 <para>
2024 There are a few different forms of DLL's wine can load:
2025 <variablelist>
2026 <varlistentry>
2028 <listitem><para>
2029 The DLL's that are included with windows. Many
2030 windows DLL's can be loaded in their native
2031 form. Many times these native versions work
2032 better than their non-Microsoft equivalent --
2033 other times they don't.
2034 </para></listitem>
2035 </varlistentry>
2036 <varlistentry>
2038 <listitem><para>
2039 The most common form of DLL loading. This is
2040 what you will use if the DLL is too system-specific
2041 or error-prone in native form (KERNEL for example),
2042 you don't have the native DLL, or you just want to be
2043 Microsoft-free.
2044 </para></listitem>
2045 </varlistentry>
2046 <varlistentry>
2048 <listitem><para>
2049 Native ELF libraries. Has been deprecated, ignored.
2050 </para></listitem>
2051 </varlistentry>
2052 <varlistentry>
2054 <listitem><para>
2055 ELF encapsulated windows DLL's.
2056 No longer used, ignored.
2057 </para></listitem>
2058 </varlistentry>
2059 </variablelist>
2060 </para>
2061 </sect3>
2062 </sect2>
2067 <para>
2069 </para>
2070 <para>
2072 </para>
2074 <para>
2075 The wine configuration file directives [DllDefaults]
2076 and [DllOverrides] are the subject of some confusion. The
2077 overall purpose of most of these directives are clear enough,
2078 though - given a choice, should Wine use its own built-in
2080 in an existing Windows installation? This document explains
2081 how this feature works.
2082 </para>
2084 <sect3>
2086 <variablelist>
2087 <varlistentry>
2089 <listitem> <para>
2091 written for the real Microsoft Windows.
2092 </para> </listitem>
2093 </varlistentry>
2094 <varlistentry>
2096 <listitem> <para>
2097 A "built-in" DLL is a Wine DLL. These can either be a
2100 that Wine is able to load on demand.
2101 </para> </listitem>
2102 </varlistentry>
2103 </variablelist>
2104 </sect3>
2106 <sect3>
2108 <variablelist>
2109 <varlistentry>
2111 <listitem> <para>
2112 This specifies in what order Wine should search for
2113 available DLL types, if the DLL in question was not
2114 found in the [DllOverrides] section.
2115 </para> </listitem>
2116 </varlistentry>
2117 </variablelist>
2118 </sect3>
2120 <sect3>
2122 <para>
2123 At one time, there was a section called [DllPairs] in the
2124 default configuration file, but this has been obsoleted
2125 because the pairing information has now been embedded into
2126 Wine itself. (The purpose of this section was merely to be
2127 able to issue warnings if the user attempted to pair
2131 </para>
2132 </sect3>
2134 <sect3>
2136 <para>
2137 This section specifies how you want specific DLLs to be
2138 handled, in particular whether you want to use "native" DLLs
2139 or not, if you have some from a real Windows configuration.
2140 Because built-ins do not mix seamlessly with native DLLs yet,
2141 certain DLL dependencies may be problematic, but workarounds
2142 exist in Wine for many popular DLL configurations. Also see
2143 WWN's [16]Status Page to figure out how well your favorite
2144 DLL is implemented in Wine.
2145 </para>
2146 <para>
2147 It is of course also possible to override these settings by
2149 command-line option (see the man page for details). Some
2150 hints for choosing your optimal configuration (listed by
2152 </para>
2153 <variablelist>
2154 <varlistentry>
2156 <listitem> <para>
2157 Native versions of these will never work, so don't try. Leave
2159 </para> </listitem>
2160 </varlistentry>
2161 <varlistentry>
2163 <listitem> <para>
2164 Graphics Device Interface. No effort has been made at trying to
2166 </para> </listitem>
2167 </varlistentry>
2168 <varlistentry>
2170 <listitem> <para>
2171 Window management and standard controls. It was
2173 versions at some point (if all other DLLs that depend
2174 on it, such as comctl32 and comdlg32, were also run
2176 possible after the Address Space Separation, so leave
2178 </para> </listitem>
2179 </varlistentry>
2180 <varlistentry>
2182 <listitem> <para>
2183 NT kernel API. Although badly documented, the
2186 </para> </listitem>
2187 </varlistentry>
2188 <varlistentry>
2190 <listitem> <para>
2192 version will probably never work. Leave at
2194 </para> </listitem>
2195 </varlistentry>
2196 <varlistentry>
2198 <listitem> <para>
2199 Win16 support library for NT. The
2202 </para> </listitem>
2203 </varlistentry>
2204 <varlistentry>
2206 <listitem> <para>
2207 Win16 kernel stuff. Will never work
2210 </para> </listitem>
2211 </varlistentry>
2212 <varlistentry>
2214 <listitem> <para>
2216 </para> </listitem>
2217 </varlistentry>
2218 <varlistentry>
2220 <listitem> <para>
2221 Tool helper routines. This is rarely a source of problems.
2223 </para> </listitem>
2224 </varlistentry>
2225 <varlistentry>
2227 <listitem> <para>
2228 Versioning. Seldom useful to mess with.
2229 </para> </listitem>
2230 </varlistentry>
2231 <varlistentry>
2233 <listitem> <para>
2234 Registry and security features. Trying the
2236 not work.
2237 </para> </listitem>
2238 </varlistentry>
2239 <varlistentry>
2241 <listitem> <para>
2242 Common Dialogs, such as color picker, font dialog,
2243 print dialog, open/save dialog, etc. It is safe to try
2245 </para> </listitem>
2246 </varlistentry>
2247 <varlistentry>
2249 <listitem> <para>
2250 Common Controls. This is toolbars, status bars, list controls,
2252 </para> </listitem>
2253 </varlistentry>
2254 <varlistentry>
2256 <listitem> <para>
2257 Shell interface (desktop, filesystem, etc). Being one of the
2258 most undocumented pieces of Windows, you may have luck with the
2260 </para> </listitem>
2261 </varlistentry>
2262 <varlistentry>
2264 <listitem> <para>
2266 will not work under Wine, so leave at
2268 </para> </listitem>
2269 </varlistentry>
2270 <varlistentry>
2272 <listitem> <para>
2273 ICMP routines for wsock32. As with wsock32, leave at
2275 </para> </listitem>
2276 </varlistentry>
2277 <varlistentry>
2279 <listitem> <para>
2281 to thunking issues. Leave at
2283 </para> </listitem>
2284 </varlistentry>
2285 <varlistentry>
2287 <listitem> <para>
2288 Lempel-Ziv decompression. Wine's
2290 </para> </listitem>
2291 </varlistentry>
2292 <varlistentry>
2294 <listitem> <para>
2295 Advanced SCSI Peripheral Interface. The
2298 </para> </listitem>
2299 </varlistentry>
2300 <varlistentry>
2302 <listitem> <para>
2304 version will easily work better than Wine's on this
2305 one.
2306 </para> </listitem>
2307 </varlistentry>
2308 <varlistentry>
2310 <listitem> <para>
2311 Printer spooler. You are not likely to have more luck
2313 </para> </listitem>
2314 </varlistentry>
2315 <varlistentry>
2317 <listitem> <para>
2318 DirectDraw/Direct3D. Since Wine does not implement the
2320 will not work at this time.
2321 </para> </listitem>
2322 </varlistentry>
2323 <varlistentry>
2325 <listitem> <para>
2327 may or may not work.
2328 </para> </listitem>
2329 </varlistentry>
2330 <varlistentry>
2332 <listitem> <para>
2333 DirectSound. It may be possible to run this
2335 </para> </listitem>
2336 </varlistentry>
2337 <varlistentry>
2339 <listitem> <para>
2341 ought to work best on this, if at all.
2342 </para> </listitem>
2343 </varlistentry>
2344 <varlistentry>
2346 <listitem> <para>
2348 version is not likely to work. Leave at
2350 </para> </listitem>
2351 </varlistentry>
2352 <varlistentry>
2354 <listitem> <para>
2355 Audio Compression Manager. The
2357 set msacm.drv to the same.
2358 </para> </listitem>
2359 </varlistentry>
2360 <varlistentry>
2362 <listitem> <para>
2363 Video for Windows. It is safe (and recommended) to try
2365 </para> </listitem>
2366 </varlistentry>
2367 <varlistentry>
2369 <listitem> <para>
2370 CD Audio MCI driver.
2371 </para> </listitem>
2372 </varlistentry>
2373 <varlistentry>
2375 <listitem> <para>
2377 playback).
2378 </para> </listitem>
2379 </varlistentry>
2380 <varlistentry>
2382 <listitem> <para>
2384 </para> </listitem>
2385 </varlistentry>
2386 <varlistentry>
2388 <listitem> <para>
2391 </para> </listitem>
2392 </varlistentry>
2393 <varlistentry>
2395 <listitem> <para>
2396 Animation MCI driver.
2397 </para> </listitem>
2398 </varlistentry>
2399 <varlistentry>
2401 <listitem> <para>
2402 Audio Compression Manager. Set to same as msacm32.
2403 </para> </listitem>
2404 </varlistentry>
2405 <varlistentry>
2407 <listitem> <para>
2408 MIDI Mapper.
2409 </para> </listitem>
2410 </varlistentry>
2411 <varlistentry>
2413 <listitem> <para>
2414 This is a pseudo-DLL used by Wine for thunking
2416 doesn't exist.
2417 </para> </listitem>
2418 </varlistentry>
2419 </variablelist>
2420 </sect3>
2421 </sect2>
2425 <para>
2426 The Wine team has determined that it is necessary to create
2427 fake DLL files to trick many programs that check for
2428 file existence to determine whether a particular feature
2429 (such as Winsock and its TCP/IP networking) is available. If
2430 this is a problem for you, you can create empty files in the
2432 to make the program think it's there, and Wine's built-in DLL
2433 will be loaded when the program actually asks for it.
2435 not create such empty files itself.)
2436 </para>
2437 <para>
2438 Applications sometimes also try to inspect the version
2439 resources from the physical files (for example, to determine
2440 the DirectX version). Empty files will not do in this case,
2441 it is rather necessary to install files with complete
2442 version resources. This problem is currently being worked
2443 on. In the meantime, you may still need to grab some real
2444 DLL files to fool these apps with.
2445 </para>
2446 <para>
2447 And there are of course DLLs that wine does not currently
2448 implement very well (or at all). If you do not have a real
2449 Windows you can steal necessary DLLs from, you can always
2450 get some from one of the Windows DLL archive sites
2451 that can be found via internet search engine.
2452 Please make sure to obey any licenses on the DLLs you fetch...
2453 (some are redistributable, some aren't).
2454 </para>
2455 </sect2>
2460 <para>
2462 </para>
2464 <para>
2465 In case Wine complains about a missing DLL, you should check whether
2466 this file is a publicly available DLL or a custom DLL belonging
2467 to your program (by searching for its name on the internet).
2468 If you managed to get hold of the DLL, then you should make sure
2469 that Wine is able to find and load it.
2470 DLLs usually get loaded according to the mechanism of the
2471 SearchPath() function.
2472 This function searches directories in the following order:
2474 <orderedlist>
2475 <listitem>
2476 <para>
2477 The directory the program was started from.
2478 </para>
2479 </listitem>
2480 <listitem>
2481 <para>
2482 The current directory.
2483 </para>
2484 </listitem>
2485 <listitem>
2486 <para>
2487 The Windows system directory.
2488 </para>
2489 </listitem>
2490 <listitem>
2491 <para>
2492 The Windows directory.
2493 </para>
2494 </listitem>
2495 <listitem>
2496 <para>
2497 The PATH variable directories.
2498 </para>
2499 </listitem>
2500 </orderedlist>
2502 In short: either put the required DLL into your program
2503 directory (might be ugly), or usually put it into the Windows system
2504 directory. Just find out its directory by having a look at the Wine
2505 configuration file variable "System" (which indicates the location of the
2506 Windows system directory) and the associated drive entry.
2507 Note that you probably shouldn't use NT-based native DLLs,
2508 since Wine's NT API support is somewhat weaker than its Win9x
2509 API support (thus leading to even worse compatibility with NT DLLs
2510 than with a no-windows setup!), so better use Win9x native DLLs
2511 instead or no native DLLs at all.
2512 </para>
2513 </sect2>
2518 <para>
2520 </para>
2522 <para>
2524 extract native Windows .dll files from .cab files that are to be
2525 found on many Windows installation CDs.
2526 </para>
2527 </sect2>
2528 </sect1>
2533 <para>
2534 Wine currently supports several different display subsystems
2535 (graphics / text) that are available on various operating
2536 systems today.
2537 For each of these, Wine implements its own interfacing driver.
2538 This section explains how to select one of these drivers
2539 and how to further configure the respective driver.
2540 Once you're finished with that, you can consider your Wine installation
2541 to be finished.
2542 </para>
2544 <para>
2545 The display drivers currently implemented in Wine are:
2546 x11drv, which is used for interfacing to X11 graphics
2547 (the one you'll most likely want to use) and ttydrv
2548 (used for text mode console apps mainly that don't really need
2549 any graphics output).
2550 Once you have decided which display driver to use, it is chosen
2553 </para>
2555 <sect2>
2558 <para>
2560 </para>
2561 <para>
2563 </para>
2565 <sect3>
2568 <para>
2569 The x11drv driver consists of two conceptually distinct
2570 pieces, the graphics driver (GDI part), and the windowing
2571 driver (USER part). Both of these are linked into the
2574 Wine, running on X11, the graphics driver must draw on
2575 drawables (window interiors) provided by the windowing
2576 driver. This differs a bit from the Windows model, where the
2577 windowing system creates and configures device contexts
2578 controlled by the graphics driver, and programs are
2579 allowed to hook into this relationship anywhere they like.
2580 Thus, to provide any reasonable tradeoff between
2581 compatibility and usability, the x11drv has three different
2582 modes of operation.
2583 </para>
2585 <variablelist>
2586 <varlistentry>
2588 <listitem>
2589 <para>
2591 wine configuration file option (see below).
2592 Ordinary top-level frame windows with thick borders,
2593 title bars, and system menus will be managed by your
2594 window manager. This lets these programs integrate
2595 better with the rest of your desktop, but may not
2596 always work perfectly (a rewrite of this mode of
2597 operation, to make it more robust and less patchy, is
2598 currently being done, though, and it's planned to be
2599 finished before the Wine 1.0 release).
2600 </para>
2601 </listitem>
2602 </varlistentry>
2603 <varlistentry>
2605 <listitem>
2606 <para>
2607 Window manager independent (any running
2608 window manager is ignored completely). Window
2609 decorations (title bars, borders, etc) are drawn by
2610 Wine to look and feel like the real Windows. This is
2611 compatible with programs that depend on being able
2612 to compute the exact sizes of any such decorations, or
2613 that want to draw their own.
2614 Unmanaged mode is only used if both Managed and Desktop
2615 are set to disabled.
2616 </para>
2617 </listitem>
2618 </varlistentry>
2619 <varlistentry>
2621 <listitem>
2622 <para>
2624 wine configuration file option (see below).
2626 for a such-sized desktop, or
2628 automatically position the desktop at the upper-left
2629 corner of the display). This is the mode most
2630 compatible with the Windows model. All program
2631 windows will just be Wine-drawn windows inside the
2632 Wine-provided desktop window (which will itself be
2633 managed by your window manager), and Windows
2634 programs can roam freely within this virtual
2635 workspace and think they own it all, without
2636 disturbing your other X apps.
2637 Note: currently there's one desktop window for every
2638 program; this will be fixed at some time.
2639 </para>
2640 </listitem>
2641 </varlistentry>
2642 </variablelist>
2643 </sect3>
2645 <sect3>
2648 <variablelist>
2649 <varlistentry>
2651 <listitem>
2652 <para>
2653 Wine can let frame windows be managed by your window
2654 manager. This option specifies whether you want that
2655 by default.
2656 </para>
2657 </listitem>
2658 </varlistentry>
2659 <varlistentry>
2661 <listitem>
2662 <para>
2663 Creates a main desktop window of a specified size
2664 to display all Windows programs in.
2665 The size argument could e.g. be "800x600".
2666 </para>
2667 </listitem>
2668 </varlistentry>
2669 <varlistentry>
2671 <listitem>
2672 <para>
2673 If you don't use DGA, you may want an alternative
2674 means to convince the mouse cursor to stay within the
2675 game window. This option does that. Of course, as with
2676 DGA, if Wine crashes, you're in trouble (although not
2677 as badly as in the DGA case, since you can still use
2678 the keyboard to get out of X).
2679 </para>
2680 </listitem>
2681 </varlistentry>
2682 <varlistentry>
2684 <listitem>
2685 <para>
2686 This specifies whether you want DirectDraw to use
2687 XFree86's <firstterm>Direct Graphics
2688 Architecture</firstterm> (DGA), which is able to
2689 take over the entire display and run the game
2690 full-screen at maximum speed. (With DGA1 (XFree86
2691 3.x), you still have to configure the X server to the
2692 game's requested bpp first, but with DGA2 (XFree86
2693 4.x), runtime depth-switching may be possible,
2694 depending on your driver's capabilities.) But be aware
2695 that if Wine crashes while in DGA mode, it may not be
2696 possible to regain control over your computer without
2697 rebooting. DGA normally requires either root
2698 privileges or read/write access to
2700 </para>
2701 </listitem>
2702 </varlistentry>
2703 <varlistentry>
2705 <listitem>
2706 <para>
2707 Applies only if you use the
2709 to run in a desktop window. Specifies whether to
2710 create the desktop window with a double-buffered
2711 visual, something most OpenGL games need to run
2712 correctly.
2713 </para>
2714 </listitem>
2715 </varlistentry>
2716 <varlistentry>
2718 <listitem>
2719 <para>
2720 Applies only if you have a palette-based display, i.e.
2721 if your X server is set to a depth of 8bpp, and if you
2722 haven't requested a private color map. It specifies
2723 the maximum number of shared colormap cells (palette
2724 entries) Wine should occupy. The higher this value,
2725 the less colors will be available to other
2726 programs.
2727 </para>
2728 </listitem>
2729 </varlistentry>
2730 <varlistentry>
2732 <listitem>
2733 <para>
2734 Applies only if you have a palette-based display, i.e.
2735 if your X server is set to a depth of 8bpp. It
2736 specifies that you don't want to use the shared color
2737 map, but a private color map, where all 256 colors are
2738 available. The disadvantage is that Wine's private
2739 color map is only seen while the mouse pointer is
2740 inside a Wine window, so psychedelic flashing and
2741 funky colors will become routine if you use the mouse
2742 a lot.
2743 </para>
2744 </listitem>
2745 </varlistentry>
2746 <varlistentry>
2748 <listitem>
2749 <para>
2750 To be used for debugging X11 operations.
2751 If Wine crashes with an X11 error, then you should enable
2752 Synchronous mode to disable X11 request caching in order
2753 to make sure that the X11 error happens directly after
2754 the corresponding X11 call in the log file appears.
2755 Will slow down X11 output!
2756 </para>
2757 </listitem>
2758 </varlistentry>
2759 <varlistentry>
2761 <listitem>
2762 <para>
2763 Applies only to multi-depth displays. It specifies
2764 which of the available depths Wine should use (and
2765 tell Windows apps about).
2766 </para>
2767 </listitem>
2768 </varlistentry>
2769 <varlistentry>
2771 <listitem>
2772 <para>
2773 This specifies which X11 display to use, and if
2774 specified, will override the
2776 </para>
2777 </listitem>
2778 </varlistentry>
2779 <varlistentry>
2781 <listitem>
2782 <para>
2783 This option only determines whether fast X11 routines
2784 or exact Wine routines will be used for certain ROP
2785 codes in blit operations. Most users won't notice any
2786 difference.
2787 </para>
2788 </listitem>
2789 </varlistentry>
2790 </variablelist>
2791 </sect3>
2792 </sect2>
2794 <sect2>
2796 <para>
2797 Currently, the ttydrv doesn't have any special configuration
2798 options to set in the configuration file.
2799 </para>
2800 </sect2>
2802 </sect1>
2808 <para>
2810 Oct 18 2002
2811 </para>
2813 <para>
2814 The windows and DOS version value a program gets e.g. by calling the
2815 Windows function GetVersion() plays a very important role:
2816 If your Wine installation for whatever reason fails to provide
2817 to your program the correct version value that it expects,
2818 then the program might assume some very bad things and fail (in
2819 the worst case even silently!).
2821 Fortunately Wine contains some more or less intelligent Windows
2822 version guessing algorithm that will try to guess the Windows
2823 version a program might expect and pass that one on to the
2824 program.
2826 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.
2827 </para>
2829 <sect2>
2830 <title>How to configure the Windows and DOS version value Wine
2831 should return</title>
2833 <para>
2834 The version values can be configured in the wine configuration file in
2835 the [Version] section.
2836 </para>
2838 <variablelist>
2839 <varlistentry>
2841 <listitem>
2842 <para>
2843 default: none; chosen by semi-intelligent detection
2844 mechanism based on DLL environment.
2845 Used to specify which Windows version to return to
2846 programs (forced value, overrides standard detection
2849 Also valid as an
2851 setting (recommended/preferred use).
2852 </para>
2853 </listitem>
2854 </varlistentry>
2855 <varlistentry>
2857 <listitem>
2858 <para>
2859 Used to specify the DOS version that should be returned
2860 to programs. Only takes effect in case Wine acts as
2861 "win31" Windows version! Common DOS version settings
2863 Also valid as an
2865 setting (recommended/preferred use).
2866 </para>
2867 </listitem>
2868 </varlistentry>
2869 </variablelist>
2870 </sect2>
2871 </sect1>
2873 &fonts;
2874 &printing;
2878 <para>
2880 </para>
2881 <para>
2883 </para>
2884 <para>
2885 Win95/Win98 interface code is being introduced.
2886 </para>
2887 <para>
2888 Instead of compiling Wine for Win3.1 vs. Win95 using
2890 special [Tweak.Layout] section of
2894 </para>
2895 <para>
2896 A few new sections and a number of entries have been added to
2898 debugging the Win95 tweaks only and may be removed in a future
2899 release! These entries/sections are:
2900 </para>
2901 <programlisting>
2902 [Tweak.Fonts]
2908 "OEMFixed.xxx" # Same parameters for the OEM fixed typeface
2909 "AnsiFixed.xxx" # Same parameters for the Ansi fixed typeface
2910 "AnsiVar.xxx" # Same parameters for the Ansi variable typeface
2911 "SystemFixed.xxx" # Same parameters for the System fixed typeface
2913 [Tweak.Layout]
2915 </programlisting>
2916 </sect1>
2921 <para>
2923 </para>
2924 <para>
2926 </para>
2928 <para>
2929 Wine now needs to know about your keyboard layout. This
2930 requirement comes from a need from many apps to have the
2931 correct scancodes available, since they read these directly,
2932 instead of just taking the characters returned by the X
2933 server. This means that Wine now needs to have a mapping from
2934 X keys to the scancodes these programs expect.
2935 </para>
2936 <para>
2937 On startup, Wine will try to recognize the active X layout by
2938 seeing if it matches any of the defined tables. If it does,
2939 everything is alright. If not, you need to define it.
2940 </para>
2941 <para>
2942 To do this, open the file
2944 at the existing tables. Make a backup copy of it, especially
2945 if you don't use CVS.
2946 </para>
2947 <para>
2948 What you really would need to do, is find out which scancode
2949 each key needs to generate. Find it in the
2951 this:
2952 </para>
2953 <programlisting>
2954 static const int main_key_scan[MAIN_LEN] =
2955 {
2956 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
2962 };
2963 </programlisting>
2964 <para>
2965 Next, assign each scancode the characters imprinted on the
2966 keycaps. This was done (sort of) for the US 101-key keyboard,
2967 which you can find near the top in
2969 is no 102nd key, you can skip that.
2970 </para>
2971 <para>
2972 However, for most international 102-key keyboards, we have
2973 done it easy for you. The scancode layout for these already
2974 pretty much matches the physical layout in the
2976 to go through all the keys that generate characters on your
2977 main keyboard (except spacebar), and stuff those into an
2978 appropriate table. The only exception is that the 102nd key,
2979 which is usually to the left of the first key of the last line
2981 line after the last line.
2982 </para>
2983 <para>
2984 For example, my Norwegian keyboard looks like this
2985 </para>
2986 <screen>
2987 § ! " # ¤ % & / ( ) = ? ` Back-
2988 | 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
2990 Tab Q W E R T Y U I O P Å ^
2991 ¨~
2992 Enter
2993 Caps A S D F G H J K L Ø Æ *
2994 Lock '
2996 Sh- > Z X C V B N M ; : _ Shift
2997 ift < , . -
2999 Ctrl Alt Spacebar AltGr Ctrl
3000 </screen>
3001 <para>
3002 Note the 102nd key, which is the <keycap><></keycap> key, to
3003 the left of <keycap>Z</keycap>. The character to the right of
3004 the main character is the character generated by
3005 <keycap>AltGr</keycap>.
3006 </para>
3007 <para>
3008 This keyboard is defined as follows:
3009 </para>
3010 <programlisting>
3011 static const char main_key_NO[MAIN_LEN][4] =
3012 {
3017 "<>"
3018 };
3019 </programlisting>
3020 <para>
3021 Except that " and \ needs to be quoted with a backslash, and
3022 that the 102nd key is on a separate line, it's pretty
3023 straightforward.
3024 </para>
3025 <para>
3026 After you have written such a table, you need to add it to the
3027 <function>main_key_tab[]</function> layout index table. This
3028 will look like this:
3029 </para>
3030 <programlisting>
3031 static struct {
3032 WORD lang, ansi_codepage, oem_codepage;
3033 const char (*key)[MAIN_LEN][4];
3034 } main_key_tab[]={
3035 ...
3036 ...
3037 {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
3038 ...
3039 </programlisting>
3040 <para>
3041 After you have added your table, recompile Wine and test that
3042 it works. If it fails to detect your table, try running
3043 </para>
3044 <screen>
3045 wine --debugmsg +key,+keyboard >& key.log
3046 </screen>
3047 <para>
3048 and look in the resulting <filename>key.log</filename> file to
3049 find the error messages it gives for your layout.
3050 </para>
3051 <para>
3052 Note that the <constant>LANG_*</constant> and
3053 <constant>SUBLANG_*</constant> definitions are in
3054 <filename>include/winnls.h</filename>, which you might need to
3055 know to find out which numbers your language is assigned, and
3056 find it in the debugmsg output. The numbers will be
3057 <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
3058 the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
3059 <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
3060 <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
3061 could look for <literal>0414</literal> in the debugmsg output
3062 to find out why my keyboard won't detect.
3063 </para>
3064 <para>
3065 Once it works, submit it to the Wine project. If you use CVS,
3066 you will just have to do
3067 </para>
3068 <screen>
3069 cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff
3070 </screen>
3071 <para>
3072 from your main Wine directory, then submit
3073 <filename>layout.diff</filename> to
3074 <email>wine-patches@winehq.com</email> along with a brief note
3075 of what it is.
3076 </para>
3077 <para>
3078 If you don't use CVS, you need to do
3079 </para>
3080 <screen>
3081 diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff
3082 </screen>
3083 <para>
3084 and submit it as explained above.
3085 </para>
3086 <para>
3087 If you did it right, it will be included in the next Wine
3088 release, and all the troublesome programs (especially
3089 remote-control programs) and games that use scancodes will
3090 be happily using your keyboard layout, and you won't get those
3091 annoying fixme messages either.
3092 </para>
3093 <para>
3094 Good luck.
3095 </para>
3096 </sect1>
3099 <title>SCSI Support</title>
3100 <para>
3101 Written by &name-bruce-milner; <email>&email-bruce-milner;</email>;
3102 Additions by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
3103 </para>
3104 <para>
3105 (Extracted from <filename>wine/documentation/aspi</filename>)
3106 </para>
3108 <para>
3109 This file describes setting up the Windows ASPI interface.
3110 </para>
3112 <para>
3113 <warning><title>Warning/Warning/Warning!!!!!!</title>
3114 <para>This may trash your system if used incorrectly. It may
3115 even trash your system when used <emphasis>correctly</>!
3116 </para>
3117 </warning>
3118 </para>
3120 <para>
3121 Now that I have said that. ASPI is a direct link to SCSI devices from
3122 windows programs. ASPI just forwards the SCSI commands that programs send
3123 to it to the SCSI bus.
3124 </para>
3125 <para>
3126 If you use the wrong SCSI device in your setup file, you can send
3127 completely bogus commands to the wrong device - An example would be
3128 formatting your hard drives (assuming the device gave you permission -
3129 if you're running as root, all bets are off).
3130 </para>
3131 <para>
3132 So please make sure that <emphasis>all</emphasis> SCSI devices not needed by the program
3133 have their permissions set as restricted as possible!
3134 </para>
3136 <para>
3137 Cookbook for setting up scanner: (At least how mine is to work)
3138 (well, for other devices such as CD burners, MO drives, ..., too)
3139 </para>
3141 <sect2>
3142 <title>Windows requirements</title>
3143 <orderedlist>
3144 <listitem>
3145 <para>
3147 compatible drivers (ASPI). At least with Mustek, they
3148 allow you the choice of using the built-in card or the
3150 any other way. Software that accesses the scanner via a
3151 DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM]
3152 </para>
3153 </listitem>
3154 <listitem>
3155 <para>
3156 You probably need a real windows install of the software
3157 to set the LUN's/SCSI id's up correctly. I'm not exactly
3158 sure.
3159 </para>
3160 </listitem>
3161 </orderedlist>
3162 </sect2>
3164 <sect2>
3165 <title>Linux requirements</title>
3166 <orderedlist>
3167 <listitem>
3168 <para>
3169 Your SCSI card must be supported under Linux. This will
3170 not work with an unknown SCSI card. Even for cheap'n
3172 drivers exist on the net.
3173 If you intend to use your IDE device, you need to use the
3174 ide-scsi emulation.
3175 Read
3177 http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html</ulink>
3178 for ide-scsi setup instructions.
3179 </para>
3180 </listitem>
3181 <listitem>
3182 <para>
3183 Compile generic SCSI drivers into your kernel.
3184 </para>
3185 </listitem>
3186 <listitem>
3187 <para>
3188 This seems to be not required any more for newer (2.2.x) kernels:
3189 Linux by default uses smaller SCSI buffers than Windows.
3190 There is a kernel build define <literal>SG_BIG_BUFF</literal> (in
3191 <filename>sg.h</filename>) that is by default set too
3192 low. The SANE project recommends
3193 <literal>130560</literal> and this seems to work just
3194 fine. This does require a kernel rebuild.
3195 </para>
3196 </listitem>
3197 <listitem>
3198 <para>
3199 Make the devices for the scanner (generic SCSI devices)
3200 - look at the SCSI programming HOWTO at
3202 http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html</ulink>
3203 for device numbering.
3204 </para>
3205 </listitem>
3206 <listitem>
3207 <para>
3208 I would recommend making the scanner device writable by
3209 a group. I made a group called
3210 <literal>scanner</literal> and added myself to it.
3211 Running as root increases your risk of sending bad SCSI
3212 commands to the wrong device. With a regular user, you
3213 are better protected.
3214 </para>
3215 </listitem>
3216 <listitem>
3217 <para>
3218 For Win32 software (WNASPI32), Wine has auto-detection in place.
3219 For Win16 software (WINASPI), you need to add a SCSI device entry
3220 for your particular scanner to ~/.wine/config. The format is
3221 <literal>[scsi cCtTdD]</literal> where
3224 </para>
3225 <para>
3226 For example, I set mine up as controller <literal>0</literal>,
3227 Target <literal>6</literal>, LUN <literal>0</literal>.
3228 <programlisting>
3229 [scsi c0t6d0]
3231 </programlisting>
3232 Yours will vary with your particular SCSI setup.
3233 </para>
3234 </listitem>
3235 </orderedlist>
3236 </sect2>
3238 <sect2>
3239 <title>General Information</title>
3240 <para>
3241 The mustek scanner I have was shipped with a package
3243 to access scanners.
3244 </para>
3245 <para>
3246 (TWAIN MANAGER)
3247 </para>
3248 <para>
3249 <programlisting>
3250 ipplus.exe <-> (TWAIN INTERFACE) <-> (TWAIN DATA SOURCE.ASPI) -> WINASPI
3251 </programlisting>
3252 </para>
3253 </sect2>
3255 <sect2>
3256 <title>NOTES/BUGS</title>
3257 <para>
3258 The biggest drawback is that it only works under Linux at the moment.
3259 </para>
3260 <para>
3261 The ASPI code has only been tested with:
3262 </para>
3263 <itemizedlist>
3264 <listitem>
3265 <para>
3266 a Mustek 800SP with a Buslogic controller under Linux [BM]
3267 </para>
3268 </listitem>
3269 <listitem>
3270 <para>
3271 a Siemens Nixdorf 9036 with Adaptec AVA-1505 under Linux
3272 accessed via DOSASPI. Note that I had color problems,
3273 though (barely readable result) [AM]
3274 </para>
3275 </listitem>
3276 <listitem>
3277 <para>
3278 a Fujitsu M2513A MO drive (640MB) using generic SCSI
3279 drivers. Formatting and ejecting worked perfectly.
3280 Thanks to Uwe Bonnes for access to the hardware! [AM]
3281 </para>
3282 </listitem>
3283 </itemizedlist>
3284 <para>
3285 I make no warranty to the ASPI code. It makes my scanner
3286 work. Your devices may explode. I have no way of determining
3287 this. I take zero responsibility!
3288 </para>
3289 </sect2>
3290 </sect1>
3293 <title>Using ODBC</title>
3294 <para>
3295 This section describes how ODBC works within Wine and how to configure
3296 it to do what you want (if it can do what you want).
3297 </para>
3298 <para>
3299 The ODBC system within Wine, as with the printing system, is designed
3300 to hook across to the Unix system at a high level. Rather than
3301 ensuring that all the windows code works under wine it uses a suitable
3302 Unix ODBC provider, such as UnixODBC. Thus if you configure Wine to
3303 use the built-in odbc32.dll, that Wine DLL will interface to your
3304 Unix ODBC package and let that do the work, whereas if you configure
3305 Wine to use the native odbc32.dll it will try to use the native
3306 ODBC32 drivers etc.
3307 </para>
3308 <sect2>
3309 <title>Using a Unix ODBC system with Wine</title>
3310 <para>
3311 The first step in using a Unix ODBC system with Wine is, of course,
3312 to get the Unix ODBC system working itself. This may involve
3313 downloading code or RPMs etc. There are several Unix ODBC systems
3314 available; the one the author is used to is unixODBC (with the
3315 IBM DB2 driver). Typically such systems will include a tool, such
3316 as <command>isql</command>, which will allow you to access the data from the command
3317 line so that you can check that the system is working.
3318 </para>
3319 <para>
3320 The next step is to hook the Unix ODBC library to the wine built-in
3321 odbc32 DLL. The built-in odbc32 (currently) looks to the
3322 environment variable <emphasis>LIB_ODBC_DRIVER_MANAGER</emphasis>
3323 for the name of the ODBC library. For example in the author's
3324 .bashrc file is the line:
3325 </para>
3326 <programlisting>
3327 export LIB_ODBC_DRIVER_MANAGER=/usr/lib/libodbc.so.1.0.0
3328 </programlisting>
3329 <para>
3330 If that environment variable is not set then it looks for a
3331 library called libodbc.so and so you can add a symbolic link to
3332 equate that to your own library. For example as root you could
3333 run the commands:
3334 </para>
3335 <screen>
3336 <prompt># </prompt><userinput>ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so</userinput>
3337 <prompt># </prompt><userinput>/sbin/ldconfig</userinput>
3338 </screen>
3339 <para>
3340 The last step in configuring this is to ensure that Wine is set up
3341 to run the built-in version of odbc32.dll, by modifying the DLL
3342 configuration. This built-in DLL merely acts as a stub between the
3343 calling code and the Unix ODBC library.
3344 </para>
3345 <para>
3346 If you have any problems then you can use the debugmsg channel
3347 odbc32 to trace what is happening. One word of warning. Some
3348 programs actually cheat a little and bypass the ODBC library. For
3349 example the Crystal Reports engine goes to the registry to check on
3350 the DSN. The fix for this is documented at unixODBC's site where
3351 there is a section on using unixODBC with Wine.
3352 </para>
3353 </sect2>
3354 <sect2>
3355 <title>Using Windows ODBC drivers</title>
3356 <para>
3357 Does anyone actually have any experience of this and anything to
3358 add?
3359 </para>
3360 </sect2>
3361 </sect1>
3363 </chapter>
3365 <!-- Keep this comment at the end of the file
3366 Local variables:
3367 mode: sgml
3369 End:
3370 -->