documentation/configuring.sgml

   1   <chapter id="configuring">
   2     <title>Configuring Wine</title>
   3     <para>Setting up config files, etc.</para>
   4
   5     <sect1 id="config">
   6       <title>General Configuration</title>
   7       <para>
   8         Copyright 1999 &name-adam-sacarny; <email>&email-adam-sacarny;</email>
   9       </para>
  10       <para>
  11         (Extracted from <filename>wine/documentation/config</filename>)
  12       </para>
  13
  14       <sect2>
  15         <title>The Wine Config File</title>
  16         <para>
  17           The Wine config file stores various settings for Wine. These include:
  18           <itemizedlist>
  19             <listitem>
  20               <para>
  21                 Drives and Information about them
  22               </para>
  23             </listitem>
  24             <listitem>
  25               <para>
  26                 Directory Settings
  27               </para>
  28             </listitem>
  29             <listitem>
  30               <para>
  31                 Port Settings
  32               </para>
  33             </listitem>
  34             <listitem>
  35               <para>
  36                 The Wine look and feel
  37               </para>
  38             </listitem>
  39             <listitem>
  40               <para>
  41                 Wine's DLL Usage
  42               </para>
  43             </listitem>
  44           </itemizedlist>
  45         </para>
  46       </sect2>
  47
  48       <sect2>
  49         <title>How Do I Make One?</title>
  50         <para>
  51           This section will guide you through the process of making a
  52           config file. Take a look at the file <filename>&lt;dirs to
  53           wine>/wine.ini</filename>. It is organized by section.
  54         </para>
  55
  56         <informaltable frame="all">
  57           <tgroup cols="3">
  58             <thead>
  59               <row>
  60                 <entry>Section Name</entry>
  61                 <entry>Needed?</entry>
  62                 <entry>What it Does</entry>
  63               </row>
  64             </thead>
  65             <tbody>
  66               <row>
  67                 <entry>[Drive X]</entry>
  68                 <entry>yes</entry>
  69                 <entry>Sets up drives recognized by wine</entry>
  70               </row>
  71               <row>
  72                 <entry>[wine]</entry>
  73                 <entry>yes</entry>
  74                 <entry>Settings for wine directories</entry>
  75               </row>
  76               <row>
  77                 <entry>[DllDefaults]</entry>
  78                 <entry>recmd</entry>
  79                 <entry>Defaults for loading DLL's</entry>
  80               </row>
  81               <row>
  82                 <entry>[DllPairs]</entry>
  83                 <entry>recmd</entry>
  84                 <entry>Sanity checkers for DLL's</entry>
  85               </row>
  86               <row>
  87                 <entry>[DllOverrides]</entry>
  88                 <entry>recmd</entry>
  89                 <entry>Overides defaults for DLL loading</entry>
  90               </row>
  91               <row>
  92                 <entry>[options]</entry>
  93                 <entry>no</entry>
  94                 <entry>No one seems to know</entry>
  95               </row>
  96               <row>
  97                 <entry>[fonts]</entry>
  98                 <entry>yes</entry>
  99                 <entry>Font appearance and recognition</entry>
 100               </row>
 101               <row>
 102                 <entry>[serialports]</entry>
 103                 <entry>no</entry>
 104                 <entry>COM ports seen by wine</entry>
 105               </row>
 106               <row>
 107                 <entry>[parallelports]</entry>
 108                 <entry>no</entry>
 109                 <entry>LPT ports seen by wine</entry>
 110               </row>
 111               <row>
 112                 <entry>[spooler]</entry>
 113                 <entry>no</entry>
 114                 <entry>Print spooling</entry>
 115               </row>
 116               <row>
 117                 <entry>[ports]</entry>
 118                 <entry>no</entry>
 119                 <entry>Direct port access</entry>
 120               </row>
 121               <row>
 122                 <entry>[spy]</entry>
 123                 <entry>no</entry>
 124                 <entry>What to do with certain debug messages</entry>
 125               </row>
 126               <row>
 127                 <entry>[Registry]</entry>
 128                 <entry>no</entry>
 129                 <entry>Specifies locations of windows registry files</entry>
 130               </row>
 131               <row>
 132                 <entry>[tweak.layout]</entry>
 133                 <entry>recmd</entry>
 134                 <entry>Appearance of wine</entry>
 135               </row>
 136               <row>
 137                 <entry>[programs]</entry>
 138                 <entry>no</entry>
 139                 <entry>Programs to be run automatically</entry>
 140               </row>
 141               <row>
 142                 <entry>[Console]</entry>
 143                 <entry>no</entry>
 144                 <entry>Console settings</entry>
 145               </row>
 146             </tbody>
 147           </tgroup>
 148         </informaltable>
 149
 150         <sect3>
 151           <title>The [Drive X] Section</title>
 152           <para>
 153             It should be pretty self explanatory, but here is an
 154             in-depth tutorial about them. There are up to 6 lines for
 155             each drive in Wine.
 156           </para>
 157           <para>
 158             <programlisting>[Drive X]</programlisting>
 159             The above line begins the section for a drive whose letter is X.
 160           </para>
 161           <para>
 162             <programlisting>Path=/dir/to/path</programlisting> This
 163             path is where the drive will begin. When Wine is browsing
 164             in drive X, it will see the files that are in the
 165             directory <filename>/dir/to/path</filename>. Don't forget
 166             to leave off the trailing slash!
 167           </para>
 168           <para>
 169             <programlisting>
 170 Type=floppy|hd|cdrom|network &lt;--- the |'s mean Type=&lt;one of the options>
 171             </programlisting>
 172           </para>
 173           <para>
 174             Sets up the type of drive Wine will see it as. Type must
 175             equal one of the four <literal>floppy</literal>,
 176             <literal>hd</literal>, <literal>cdrom</literal>, or
 177             <literal>network</literal>. They are self-explanatory.
 178           </para>
 179           <para>
 180             <programlisting>Label=blah</programlisting> Defines the
 181             drive label. Generally only needed for programs that look
 182             for a special CD-ROM. Info on finding the lable is in
 183             <literal>&lt;dirs to wine>/documentation/cdrom-labels</literal>.
 184             The label may be up to 11 characters.
 185           </para>
 186           <para>
 187             <programlisting>Serial=deadbeef</programlisting>
 188             Tells Wine the serial number of the drive. A few programs with
 189             intense protection for pirating might need this, but otherwise
 190             don't use it. Up to 8 characters and hexadecimal.
 191           </para>
 192           <para>
 193             <programlisting>Filesystem=msdos|win95|unix</programlisting>
 194             Sets up the way Wine looks at files on the drive.
 195           </para>
 196
 197           <variablelist>
 198             <varlistentry>
 199               <term><literal>msdos</literal></term>
 200               <listitem>
 201                 <para>
 202                   Case insensitive filesystem. Alike to DOS and
 203                   Windows 3.x. <literal>8.3</literal> is the maximum
 204                   length of files (eightdot.123) - longer ones will be
 205                   truncated. (NOTE: this is a very bad choice if you
 206                   plan on running apps that use long filenames. win95
 207                   should work fine with apps that were designed to run
 208                   under the msdos system. In other words, you might
 209                   not want to use this.)
 210                 </para>
 211               </listitem>
 212             </varlistentry>
 213             <varlistentry>
 214               <term><literal>win95</literal></term>
 215               <listitem>
 216                 <para>
 217                   Case insensitive. Alike to Windows 9x/NT 4. This is
 218                   the long filename filesystem you are probably used
 219                   to working with. The filesystem of choice for most
 220                   applications to be run under wine.  PROBABLY THE ONE
 221                   YOU WANT!
 222                 </para>
 223               </listitem>
 224             </varlistentry>
 225             <varlistentry>
 226               <term><literal>unix</literal></term>
 227               <listitem>
 228                 <para>
 229                   Case sensitive. This filesystem has almost no use
 230                   (Windows apps expect case insensitive filenames).
 231                   Try it if you dare, but win95 is a  much better
 232                   choice.
 233                 </para>
 234               </listitem>
 235             </varlistentry>
 236           </variablelist>
 237
 238           <programlisting>Device=/dev/xx</programlisting>
 239           <para>
 240             Use this ONLY for floppy and cdrom devices. Using it on
 241             Extended2 partitions can have dire results (when a windows
 242             app tries to do a lowlevel write, they do it in a FAT way
 243             -- FAT does not mix with Extended2).
 244           </para>
 245           <note>
 246             <para>
 247               This setting is not really important; almost all apps
 248               will have no problem if it remains unspecified. For
 249               CD-ROMs you might want to add it to get automatic label
 250               detection, though. If you are unsure about specifying
 251               device names, just leave out this setting for your
 252               drives.
 253             </para>
 254           </note>
 255           <para>
 256             Here is a setup for Drive X, a generic hard drive:
 257             <programlisting>
 258 [Drive X]
 259 Path=/dos-a
 260 Type=hd
 261 Label=Hard Drive
 262 Filesystem=win95
 263 This is a setup for Drive X, a generic CD-ROM drive:
 264 [Drive X]
 265 Path=/dos-d
 266 Type=cdrom
 267 Label=Total Annihilation
 268 Filesystem=win95
 269 Device=/dev/hdc
 270 And here is a setup for Drive X, a generic floppy drive:
 271 [Drive X]
 272 Type=floppy
 273 Path=/mnt/floppy
 274 Label=Floppy Drive
 275 Serial=87654321
 276 Filesystem=win95
 277 Device=/dev/fd0
 278             </programlisting>
 279           </para>
 280         </sect3>
 281
 282         <sect3>
 283           <title>The [wine] Section </title>
 284           <para>
 285             The [wine] section of the configuration file contains
 286             information wine uses for directories. When specifying the
 287             directories for the settings, make them as they would
 288             appear in wine. If your drive <medialabel>C</medialabel>
 289             has a path of <filename>/dos</filename>, and your
 290             <filename>windows</filename> directory is located in
 291             <filename>/dos/windows</filename>, then use:
 292             <programlisting>Windows=c:\windows</programlisting>
 293           </para>
 294           <para>
 295             This sets up the <filename>windows</filename> directory.
 296             Make one if you don't already have one. NO TRAILING SLASH
 297             (NOT <filename>C:\windows\</filename>)!
 298           </para>
 299           <para>
 300             <programlisting>System=c:\windows\system</programlisting>
 301             This sets up where the windows system files are. Should
 302             reside in the directory used for the
 303             <literal>Windows</literal> setting. If you don't have
 304             <filename>windows</filename> then this is where the system
 305             files will go. Again, NO TRAILING SLASH!
 306           </para>
 307           <para>
 308             <programlisting>Temp=c:\temp</programlisting> This should
 309             be the directory you want your temp files stored in. YOU
 310             MUST HAVE WRITE ACCESS TO IT.
 311           </para>
 312           <para>
 313             <programlisting>
 314 Path=c:\windows;c:\windows\system;c:\blanco
 315             </programlisting>
 316           </para>
 317           <para>
 318             Behaves like the <envar>PATH</envar> setting on UNIX
 319             boxes. When wine is run like <userinput>wine
 320               sol.exe</userinput>, if <filename>sol.exe</filename>
 321             resides in a directory specified in the
 322             <literal>Path</literal> setting, wine will run it (Of
 323             course, if <filename>sol.exe</filename> resides in the
 324             current directory, wine will run that one). Make sure it
 325             always has your <filename>windows</filename> directory and
 326             system directory (For this setup, it must have
 327             <filename>c:\windows;c:\windows\system</filename>).
 328           </para>
 329           <para>
 330             <programlisting>SymbolTableFile=wine.sym</programlisting>
 331             Sets up the symbol table file for the wine debugger. You
 332             probably don't need to fiddle with this. May be useful if
 333             your wine is stripped.
 334           </para>
 335           <para>
 336             <programlisting>printer=off|on</programlisting> Tells wine
 337             whether to allow printer drivers and printing to work.
 338             Using these things are pretty alpha, so you might want to
 339             watch out. Some people might find it useful, however. If
 340             you're not planning on working on printing, don't even add
 341             this to your <filename>wine.ini</filename> (It probably
 342             isn't already in it). Check out the [spooler] and
 343             [parallelports] sections too.
 344           </para>
 345         </sect3>
 346
 347         <sect3>
 348           <title>Introduction To DLL Sections</title>
 349           <para>
 350             There are a few things you will need to know before
 351             configuring the DLL sections in your wine configuration
 352             file.
 353           </para>
 354           <sect4>
 355             <title>Windows DLL Pairs</title>
 356             <para>
 357               Most windows DLL's have a win16 (Windows 3.x) and win32
 358               (Windows 9x/NT) form.  The combination of the win16 and
 359               win32 DLL versions are called the "DLL pair". This is a
 360               list of the most common pairs:
 361             </para>
 362
 363             <informaltable>
 364               <tgroup cols="3">
 365                 <thead>
 366                   <row>
 367                     <entry>Win16</entry>
 368                     <entry>Win32</entry>
 369                     <entry>
 370                       Native
 371                       <footnote>
 372                         <para>
 373                           Is it possible to use native dll with wine?
 374                           (See next section)
 375                         </para>
 376                       </footnote>
 377                     </entry>
 378                   </row>
 379                 </thead>
 380                 <tbody>
 381                   <row>
 382                     <entry>KERNEL</entry>
 383                     <entry>KERNEL32</entry>
 384                     <entry>No!</entry>
 385                   </row>
 386                   <row>
 387                     <entry>USER</entry>
 388                     <entry>USER32</entry>
 389                     <entry>No!</entry>
 390                   </row>
 391                   <row>
 392                     <entry>SHELL</entry>
 393                     <entry>SHELL32</entry>
 394                     <entry>Yes</entry>
 395                   </row>
 396                   <row>
 397                     <entry>GDI</entry>
 398                     <entry>GDI32</entry>
 399                     <entry>No!</entry>
 400                   </row>
 401                   <row>
 402                     <entry>COMMDLG</entry>
 403                     <entry>COMDLG32</entry>
 404                     <entry>Yes</entry>
 405                   </row>
 406                   <row>
 407                     <entry>VER</entry>
 408                     <entry>VERSION</entry>
 409                     <entry>Yes</entry>
 410                   </row>
 411                 </tbody>
 412               </tgroup>
 413             </informaltable>
 414           </sect4>
 415
 416           <sect4>
 417             <title>Different Forms Of DLL's</title>
 418             <para>
 419               There are a few different forms of DLL's wine can load:
 420               <variablelist>
 421                 <varlistentry>
 422                   <term>native</term>
 423                   <listitem><para>
 424                       The DLL's that are included with windows. Many
 425                       windows DLL's can be loaded in their native
 426                       form. Many times these native versions work
 427                       better than their non-Microsoft equivalent --
 428                       other times they don't.
 429                     </para></listitem>
 430                 </varlistentry>
 431                 <varlistentry>
 432                   <term>elfdll</term>
 433                   <listitem><para>
 434                       ELF encapsulated windows DLL's. This is currently
 435                       experimental (Not working yet).
 436                     </para></listitem>
 437                 </varlistentry>
 438                 <varlistentry>
 439                   <term>so</term>
 440                   <listitem><para>
 441                       Native ELF libraries. Will not work yet.
 442                     </para></listitem>
 443                 </varlistentry>
 444                 <varlistentry>
 445                   <term>builtin</term>
 446                   <listitem><para>
 447                       The most common form of DLL loading. This is
 448                       what you will use if the DLL is error-prone in
 449                       native form (KERNEL for example), you don't have
 450                       the native DLL, or you just want to be
 451                       Microsoft-free.
 452                     </para></listitem>
 453                 </varlistentry>
 454               </variablelist>
 455             </para>
 456           </sect4>
 457         </sect3>
 458
 459         <sect3>
 460           <title>The [DllDefaults] Section</title>
 461           <para>
 462             These settings provide wine's default handling of DLL loading.
 463           </para>
 464           <para>
 465             <programlisting>EXTRA_LD_LIBRARY_PATH=/dirs</programlisting>
 466           </para>
 467           <para>
 468             The directory specified here is appended to the normal search
 469             path for certain forms of DLL's (elfdll and .so).
 470           </para>
 471           <para>
 472             <programlisting>DefaultLoadOrder = native, elfdll, so, builtin</programlisting>
 473           </para>
 474           <para>
 475             This setting is a comma-delimited list of which order to
 476             attempt loading DLL's. If the first option fails, it will
 477             try the second, and so on. The order specified above is
 478             probably the best in most conditions.
 479           </para>
 480         </sect3>
 481
 482         <sect3>
 483           <title>The [DllPairs] Section</title>
 484           <para>
 485             This section is optional, but strongly recommended. If you
 486             try to use native SHELL32, but builtin SHELL, you could
 487             have some big problems (native and builtin/so/elfdll do
 488             certain things in different ways). Using different forms
 489             of a pair is a *very*, **very** bad idea. By specifying
 490             DLL pairs here, wine will print out a message if you use
 491             different forms of a pair. You shouldn't need to change
 492             anything in this section, the following should work fine
 493             in all cases:
 494           </para>
 495           <programlisting>
 496 [DllPairs]
 497 kernel  = kernel32
 498 gdi     = gdi32
 499 user    = user32
 500 commdlg = comdlg32
 501 commctrl= comctl32
 502 ver     = version
 503 shell   = shell32
 504 lzexpand= lz32
 505 winsock = wsock32
 506           </programlisting>
 507         </sect3>
 508
 509         <sect3>
 510           <title>The [DllOverrides] Section</title>
 511           <para>
 512             The format for this section is the same for each line:
 513             <programlisting>
 514 &lt;DLL>{,&lt;DLL>,&lt;DLL>...} = &lt;FORM>{,&lt;FORM>,&lt;FORM>...}
 515             </programlisting>
 516           </para>
 517           <para>
 518             For example, to load builtin KERNEL pair (case doesn't
 519             matter here):
 520             <programlisting>
 521 kernel,kernel32 = builtin
 522             </programlisting>
 523           </para>
 524           <para>
 525             To load the native COMMDLG pair, but if that doesn't work
 526             try builtin:
 527             <programlisting>
 528 commdlg,comdlg32 = native,builtin
 529             </programlisting>
 530           </para>
 531           <para>
 532             To load the native COMCTL32:
 533             <programlisting>
 534 comctl32 = native
 535             </programlisting>
 536           </para>
 537           <para>
 538             Here is a good generic setup (As it is defined in wine.ini
 539             that was included with your wine package):
 540             <programlisting>
 541 [DllOverrides]
 542 kernel32, gdi32, user32 = builtin
 543 kernel, gdi, user       = builtin
 544 toolhelp                = builtin
 545 comdlg32, commdlg       = elfdll, builtin, native
 546 version, ver            = elfdll, builtin, native
 547 shell32, shell          = builtin, native
 548 lz32, lzexpand          = builtin, native
 549 commctrl, comctl32      = builtin, native
 550 wsock32, winsock        = builtin
 551 advapi32, crtdll, ntdll = builtin, native
 552 mpr, winspool           = builtin, native
 553 ddraw, dinput, dsound   = builtin, native
 554 winmm, w32skrnl, msvfw32= builtin
 555 wnaspi32, wow32         = builtin
 556 system, display, wprocs = builtin
 557 wineps                  = builtin
 558             </programlisting>
 559           </para>
 560           <note>
 561             <para>
 562               You see that elfdll or so is the first option for a few
 563               of these dll's. This will fail for you, but you won't
 564               notice it as wine will just use the second or third
 565               option.
 566             </para>
 567           </note>
 568         </sect3>
 569
 570         <sect3>
 571           <title>The [options] Section</title>
 572           <para>
 573             No one seems to know what this section is...
 574           </para>
 575           <para>
 576             <programlisting>
 577 AllocSystemColors=100
 578             </programlisting>
 579             System colors to allocate? Just leave it at 100.
 580           </para>
 581         </sect3>
 582
 583         <sect3>
 584           <title>The [fonts] Section</title>
 585           <para>
 586             This section sets up wine's font handling.
 587           </para>
 588           <para>
 589             <programlisting>Resolution = 96</programlisting>
 590           </para>
 591           <para>
 592             Since the way X handles fonts is different from the way
 593             Windows does, wine uses a special mechanism to deal with
 594             them. It must scale them using the number defined in the
 595             "Resolution" setting. 60-120 are reasonable values, 96 is
 596             a nice in the middle one. If you have the real windows
 597             fonts available (<filename>&lt;dirs to
 598               wine>/documentation/ttfserver</filename> and
 599             <filename>fonts</filename>), this parameter will not be as
 600             important. Of course, it's always good to get your X fonts
 601             working acceptably in wine.
 602           </para>
 603           <para>
 604             <programlisting>Default = -adobe-times-</programlisting>
 605             The default font wine uses. Fool around with it if you'd like.
 606           </para>
 607           <para>
 608 OPTIONAL:
 609           </para>
 610           <para>
 611             The <literal>Alias</literal> setting allows you to map an X font to a font
 612             used in wine. This is good for apps that need a special font you don't have,
 613             but a good replacement exists. The syntax is like so:
 614             <programlisting>
 615 AliasX = [Fake windows name],[Real X name]&lt;,optional "masking" section>
 616             </programlisting>
 617           </para>
 618           <para>
 619             Pretty straightforward. Replace "AliasX" with "Alias0",
 620             then "Alias1" and so on. The fake windows name is the name
 621             that the font will be under a windows app in wine. The
 622             real X name is the font name as seen by X (Run
 623             "xfontsel"). The optional "masking" section allows you to
 624             utilize the fake windows name you define. If it is not
 625             used, then wine will just try to extract the fake windows
 626             name itself and not use the value you enter.
 627           </para>
 628           <para>
 629             Here is an example of an alias without masking. The font will show up in windows
 630             apps as "Google". When defining an alias in a config file, forget about my
 631             comment text (The "&lt;-- blah" stuff)
 632             <programlisting>
 633 Alias0 = Foo,--google-      &lt;-- Note the no spaces after the " = ". Important!
 634             </programlisting>
 635           </para>
 636           <para>
 637             Here is an example with masking enabled. The font will show up as "Foo" in
 638             windows apps.
 639             <programlisting>
 640 Alias1 = Foo,--google-,subst
 641             </programlisting>
 642           </para>
 643           <para>
 644             For more info check out <filename>&lt;dirs to wine>/documentation/fonts</filename>
 645           </para>
 646         </sect3>
 647
 648         <sect3>
 649           <title>The [serialports], [parallelports], [spooler], and [ports] Sections</title>
 650           <para>
 651             Even though it sounds like a lot of sections, these are
 652             all closely related. They are all for communications and
 653             parallel ports.
 654           </para>
 655           <para>
 656             The [serialports] section tells wine what serial ports it
 657             is allowed to use.
 658             <programlisting>ComX=/dev/cuaY</programlisting>
 659           </para>
 660           <para>
 661             Replace <literal>X</literal> with the number of the COM
 662             port in Windows (1-8) and <literal>Y</literal> with the
 663             number of it in <literal>X</literal> (Usually the number
 664             of the port in Windows minus 1). <literal>ComX</literal>
 665             can actually equal any device
 666             (<medialabel>/dev/modem</medialabel> is acceptable). It is
 667             not always necessary to define any COM ports (An optional
 668             setting). Here is an example:
 669             <programlisting>Com1=/dev/cua0</programlisting>
 670           </para>
 671           <para>
 672             Use as many of these as you like in the section to define
 673             all of the COM ports you need.
 674           </para>
 675           <para>
 676             The [parallelports] section sets up any parallel ports
 677             that will be allowed access under wine.
 678             <programlisting>LptX=/dev/lpY</programlisting>
 679           </para>
 680           <para>
 681             Sounds familiar? Syntax is just like the COM port setting.
 682             Replace <literal>X</literal> with a value from 1-4 as it
 683             is in Windows and <literal>Y</literal> with a value from
 684             0-3 (<literal>Y</literal> is usually the value in windows
 685             minus 1, just like for COM ports). You don't always need
 686             to define a parallel port (AKA, it's optional). As with
 687             the other section, LptX can equal  any device (Maybe
 688             <medialabel>/dev/printer</medialabel>). Here is an
 689             example:  <programlisting>Lpt1=/dev/lp0</programlisting>
 690           </para>
 691           <para>
 692             The [spooler] section will inform wine where to spool
 693             print jobs. Use this if you want to try printing. Wine
 694             docs claim that spooling is "rather primitive" at this
 695             time, so it won't work perfectly. IT IS OPTIONAL. The only
 696             setting you use in this section works to map a port (LPT1,
 697             for example) to a file or a command. Here is an example,
 698             mapping LPT1 to the file <filename>out.ps</filename>:
 699             <programlisting>LPT1:=out.ps</programlisting>
 700           </para>
 701           <para>
 702             The following command maps printing jobs to LPT1 to the
 703             command <command>lpr</command>. Notice  the |:
 704             <programlisting>LPT1:=|lpr</programlisting>
 705           </para>
 706           <para>
 707             The [ports] section is usually useful only for people who
 708             need direct port access for programs requiring dongles or
 709             scanners. IF YOU DON'T NEED IT, DON'T USE IT!
 710           </para>
 711           <para>
 712             <programlisting>read=0x779,0x379,0x280-0x2a0</programlisting>
 713             Gives direct read access to those IO's.
 714           </para>
 715           <para>
 716             <programlisting>write=0x779,0x379,0x280-0x2a0</programlisting>
 717             Gives direct write access to those IO's. It's probably a
 718             good idea to keep the values of the
 719             <literal>read</literal> and <literal>write</literal>
 720             settings the same. This stuff will only work when you're
 721             root.
 722           </para>
 723         </sect3>
 724
 725         <sect3>
 726           <title>The [spy], [Registry], [tweak.layout], and [programs] Sections</title>
 727           <para>
 728             [spy] is used to include or exclude debug messages, and to
 729             output them to a file. The latter is rarely used. THESE
 730             ARE ALL OPTIONAL AND YOU PROBABLY DON'T NEED TO ADD OR
 731             REMOVE ANYTHING IN THIS SECTION TO YOUR CONFIG.
 732           </para>
 733           <para>
 734             <programlisting>File=/blanco</programlisting>
 735             Sets the logfile for wine. Set to CON to log to standard out.
 736             THIS IS RARELY USED.
 737           </para>
 738           <para>
 739             <programlisting>Exclude=WM_SIZE;WM_TIMER;</programlisting>
 740             Excludes debug messages about <constant>WM_SIZE</constant>
 741             and <constant>WM_TIMER</constant> in the logfile.
 742           </para>
 743           <para>
 744             <programlisting>Include=WM_SIZE;WM_TIMER;</programlisting>
 745             Includes debug messages about <constant>WM_SIZE</constant>
 746             and <constant>WM_TIMER</constant> in the logfile.
 747           </para>
 748           <para>
 749             [Registry] can be used to tell wine where your old windows
 750             registry files exist. This section is completely optional
 751             and useless to people using wine without an existing
 752             windows installation.
 753           </para>
 754           <para>
 755             <programlisting>UserFileName=/dirs/to/user.reg</programlisting>
 756             The location of your old <filename>user.reg</filename> file.
 757           </para>
 758           <para>
 759             <programlisting>LocalMachineFileName=/dirs/to/system.reg</programlisting>
 760             The location of your old <filename>system.reg</filename> file.
 761           </para>
 762           <para>
 763             [tweak.layout] is devoted to wine's look. There is only
 764             one setting for it.
 765           </para>
 766           <para>
 767             <programlisting>WineLook=win31|win95|win98</programlisting>
 768             Will change the look of wine from Windows 3.1 to Windows 95.
 769             The <literal>win98</literal> setting behaves
 770             just like <literal>win95</literal> most of the time.
 771           </para>
 772           <para>
 773             [programs] can be used to say what programs run under
 774             special conditions.
 775           </para>
 776           <para>
 777             <programlisting>Default=/program/to/execute.exe</programlisting>
 778             Sets the program to be run if wine is started without specifying a program.
 779           </para>
 780           <para>
 781             <programlisting>Startup=/program/to/execute.exe</programlisting>
 782             Sets the program to automatically be run at startup every time.
 783           </para>
 784         </sect3>
 785       </sect2>
 786
 787       <sect2>
 788         <title>Where Do I Put It?</title>
 789         <para>
 790           The wine config file can go in two places.
 791         </para>
 792         <variablelist>
 793           <varlistentry>
 794             <term><filename>/usr/local/etc/wine.conf</filename></term>
 795             <listitem><para>
 796                 A systemwide config file, used for anyone who doesn't
 797                 have their own.
 798             </para></listitem>
 799           </varlistentry>
 800           <varlistentry>
 801             <term><filename>$HOME/.winerc</filename></term>
 802             <listitem><para>
 803                 Your own config file, that only is used for your user.
 804             </para></listitem>
 805           </varlistentry>
 806         </variablelist>
 807         <para>
 808           So copy your version of the <filename>wine.conf</filename> file to
 809           <filename>/usr/local/etc/wine.conf</filename> or
 810           <filename>$HOME/.winerc</filename> for wine to recognize it.
 811         </para>
 812       </sect2>
 813
 814       <sect2>
 815         <title>What If It Doesn't Work?</title>
 816         <para>
 817           There is always a chance that things will go wrong. If the
 818           unthinkable happens,  try the newsgroup,
 819           <systemitem>comp.emulators.ms-windows.wine</systemitem>,
 820           or the IRCnet channel <systemitem>#WineHQ</systemitem>.
 821           Make sure that you have looked over this document thoroughly,
 822           and have also read:
 823         </para>
 824         <itemizedlist>
 825           <listitem>
 826             <para><filename>README</filename></para>
 827           </listitem>
 828           <listitem>
 829             <para>
 830               <filename>http://www.la-sorciere.de/wine/index.html</filename>
 831               (optional but recommended)
 832             </para>
 833           </listitem>
 834         </itemizedlist>
 835         <para>
 836           If indeed it looks like you've done your research, be
 837           prepared for helpful suggestions. If you haven't, brace
 838           yourself for heaving flaming.
 839         </para>
 840       </sect2>
 841     </sect1>
 842
 843     <sect1 id="win95look">
 844       <title>Win95/98 Look</title>
 845       <para>
 846         Written by &name-david-cuthbert; <email>&email-david-cuthbert;</email>
 847       </para>
 848       <para>
 849         (Extracted from <filename>wine/documentation/win95look</filename>)
 850       </para>
 851       <para>
 852         Win95/Win98 interface code is being introduced.
 853       </para>
 854       <para>
 855         Instead of compiling Wine for Win3.1 vs. Win95 using
 856         <constant>#define</constant> switches, the code now looks in a
 857         special [Tweak.Layout] section of
 858         <filename>wine.conf</filename> for a
 859         <literal>WineLook=Win95</literal> or
 860         <literal>WineLook=Win98</literal> entry.
 861       </para>
 862       <para>
 863         A few new sections and a number of entries have been added to
 864         the <filename>wine.conf file</filename> -- these are for
 865         debugging the Win95 tweaks only and may be removed in a future
 866         release!  These entries/sections are:
 867       </para>
 868       <programlisting>
 869 [Tweak.Fonts]
 870 System.Height=&lt;point size>    # Sets the height of the system typeface
 871 System.Bold=[true|false]      # Whether the system font should be boldfaced
 872 System.Italic=[true|false]    # Whether the system font should be italicized
 873 System.Underline=[true|false] # Whether the system font should be underlined
 874 System.StrikeOut=[true|false] # Whether the system font should be struck out
 875 OEMFixed.xxx                  # Same parameters for the OEM fixed typeface
 876 AnsiFixed.xxx                 # Same parameters for the Ansi fixed typeface
 877 AnsiVar.xxx                   # Same parameters for the Ansi variable typeface
 878 SystemFixed.xxx               # Same parameters for the System fixed typeface
 879
 880 [Tweak.Layout]
 881 WineLook=[Win31|Win95|Win98]  # Changes Wine's look and feel
 882       </programlisting>
 883     </sect1>
 884
 885     <sect1 id="x11drv">
 886       <title>Configuring the x11drv Driver</title>
 887
 888       <para>
 889         Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
 890       </para>
 891       <para>
 892         (Extracted from <filename>wine/documentation/cdrom-labels</filename>)
 893       </para>
 894
 895       <para>
 896         Most Wine users run Wine under the windowing system known as
 897         X11. During most of Wine's history, this was the only display
 898         driver available, but in recent years, parts of Wine has been
 899         reorganized to allow for other display drivers (although the
 900         only alternative currently available is Patrik Stridvall's
 901         ncurses-based ttydrv, which he claims works for displaying
 902         calc.exe). The display driver is chosen with the
 903         <literal>GraphicsDriver</literal> option in the [wine] section
 904         of <filename>wine.conf</filename> or
 905         <filename>.winerc</filename>, but I will only cover the x11drv
 906         driver in this article.
 907       </para>
 908
 909       <sect2>
 910         <title>x11drv modes of operation</title>
 911
 912         <para>
 913           The x11drv driver consists of two conceptually distinct
 914           pieces, the graphics driver (GDI part), and the windowing
 915           driver (USER part). Both of these are linked into the
 916           <filename>libx11drv.so</filename> module, though (which you
 917           load with the <literal>GraphicsDriver</literal> option). In
 918           Wine, running on X11, the graphics driver must draw on
 919           drawables (window interiors) provided by the windowing
 920           driver. This differs a bit from the Windows model, where the
 921           windowing system creates and configures device contexts
 922           controlled by the graphics driver, and applications are
 923           allowed to hook into this relationship anywhere they like.
 924           Thus, to provide any reasonable tradeoff between
 925           compatibility and usability, the x11drv has three different
 926           modes of operation.
 927         </para>
 928
 929         <variablelist>
 930           <varlistentry>
 931             <term>Unmanaged/Normal</term>
 932             <listitem>
 933               <para>
 934                 The default. Window-manager-independent (any running
 935                 window manager is ignored completely). Window
 936                 decorations (title bars, borders, etc) are drawn by
 937                 Wine to look and feel like the real Windows. This is
 938                 compatible with applications that depend on being able
 939                 to compute the exact sizes of any such decorations, or
 940                 that want to draw their own.
 941               </para>
 942             </listitem>
 943           </varlistentry>
 944           <varlistentry>
 945             <term>Managed</term>
 946             <listitem>
 947               <para>
 948                 Specified by using the
 949                 <parameter>--managed</parameter> command-line option
 950                 or the <literal>Managed</literal>
 951                 <filename>wine.conf</filename> option (see below).
 952                 Ordinary top-level frame windows with thick borders,
 953                 title bars, and system menus will be managed by your
 954                 window manager. This lets these applications integrate
 955                 better with the rest of your desktop, but may not
 956                 always work perfectly. (A rewrite of this mode of
 957                 operation, to make it more robust and less patchy, is
 958                 highly desirable, though, and is planned to be done
 959                 before the Wine 1.0 release.)
 960               </para>
 961             </listitem>
 962           </varlistentry>
 963           <varlistentry>
 964             <term>Desktop-in-a-Box</term>
 965             <listitem>
 966               <para>
 967                 Specified by using the
 968                 <parameter>--desktop</parameter> command-line option
 969                 (with a geometry, e.g. <parameter>--desktop
 970                   800x600</parameter> for a such-sized desktop, or
 971                 even <parameter>--desktop 800x600+0+0</parameter> to
 972                 automatically position the desktop at the upper-left
 973                 corner of the display). This is the mode most
 974                 compatible with the Windows model. All application
 975                 windows will just be Wine-drawn windows inside the
 976                 Wine-provided desktop window (which will itself be
 977                 managed by your window manager), and Windows
 978                 applications can roam freely within this virtual
 979                 workspace and think they own it all, without
 980                 disturbing your other X apps.
 981               </para>
 982             </listitem>
 983           </varlistentry>
 984         </variablelist>
 985       </sect2>
 986
 987       <sect2>
 988         <title>The [x11drv] section</title>
 989
 990         <variablelist>
 991           <varlistentry>
 992             <term>AllocSystemColors</term>
 993             <listitem>
 994               <para>
 995                 Applies only if you have a palette-based display, i.e.
 996                 if your X server is set to a depth of 8bpp, and if you
 997                 haven't requested a private color map. It specifies
 998                 the maximum number of shared colormap cells (palette
 999                 entries) Wine should occupy. The higher this value,
1000                 the less colors will be available to other
1001                 applications.
1002               </para>
1003             </listitem>
1004           </varlistentry>
1005           <varlistentry>
1006             <term>PrivateColorMap</term>
1007             <listitem>
1008               <para>
1009                 Applies only if you have a palette-based display, i.e.
1010                 if your X server is set to a depth of 8bpp. It
1011                 specifies that you don't want to use the shared color
1012                 map, but a private color map, where all 256 colors are
1013                 available. The disadvantage is that Wine's private
1014                 color map is only seen while the mouse pointer is
1015                 inside a Wine window, so psychedelic flashing and
1016                 funky colors will become routine if you use the mouse
1017                 a lot.
1018               </para>
1019             </listitem>
1020           </varlistentry>
1021           <varlistentry>
1022             <term>PerfectGraphics</term>
1023             <listitem>
1024               <para>
1025                 This option only determines whether fast X11 routines
1026                 or exact Wine routines will be used for certain ROP
1027                 codes in blit operations. Most users won't notice any
1028                 difference.
1029               </para>
1030             </listitem>
1031           </varlistentry>
1032           <varlistentry>
1033             <term>ScreenDepth</term>
1034             <listitem>
1035               <para>
1036                 Applies only to multi-depth displays. It specifies
1037                 which of the available depths Wine should use (and
1038                 tell Windows apps about).
1039               </para>
1040             </listitem>
1041           </varlistentry>
1042           <varlistentry>
1043             <term>Display</term>
1044             <listitem>
1045               <para>
1046                 This specifies which X11 display to use, and if
1047                 specified, will override both the
1048                 <envar>DISPLAY</envar> environment variable and the
1049                 <parameter>--display</parameter> command-line option.
1050               </para>
1051             </listitem>
1052           </varlistentry>
1053           <varlistentry>
1054             <term>Managed</term>
1055             <listitem>
1056               <para>
1057                 Wine can let frame windows be managed by your window
1058                 manager. This option specifies whether you want that
1059                 by default.
1060               </para>
1061             </listitem>
1062           </varlistentry>
1063           <varlistentry>
1064             <term>UseDGA</term>
1065             <listitem>
1066               <para>
1067                 This specifies whether you want DirectDraw to use
1068                 XFree86's <firstterm>Direct Graphics
1069                   Architecture</firstterm> (DGA), which is able to
1070                 take over the entire display and run the game
1071                 full-screen at maximum speed. (With DGA1 (XFree86
1072                 3.x), you still have to configure the X server to the
1073                 game's requested bpp first, but with DGA2 (XFree86
1074                 4.x), runtime depth-switching may be possible,
1075                 depending on your driver's capabilities.) But be aware
1076                 that if Wine crashes while in DGA mode, it may not be
1077                 possible to regain control over your computer without
1078                 rebooting. DGA normally requires either root
1079                 privileges or read/write access to
1080                 <filename>/dev/mem</filename>.
1081               </para>
1082             </listitem>
1083           </varlistentry>
1084           <varlistentry>
1085             <term>UseXShm</term>
1086             <listitem>
1087               <para>
1088                 If you don't want DirectX to use DGA, you can at least
1089                 use X Shared Memory extensions (XShm). It is much
1090                 slower than DGA, since the app doesn't have direct
1091                 access to the physical frame buffer, but using shared
1092                 memory to draw the frame is at least faster than
1093                 sending the data through the standard X11 socket, even
1094                 though Wine's XShm support is still known to crash
1095                 sometimes.
1096               </para>
1097             </listitem>
1098           </varlistentry>
1099           <varlistentry>
1100             <term>DXGrab</term>
1101             <listitem>
1102               <para>
1103                 If you don't use DGA, you may want an alternative
1104                 means to convince the mouse cursor to stay within the
1105                 game window. This option does that. Of course, as with
1106                 DGA, if Wine crashes, you're in trouble (although not
1107                 as badly as in the DGA case, since you can still use
1108                 the keyboard to get out of X).
1109               </para>
1110             </listitem>
1111           </varlistentry>
1112           <varlistentry>
1113             <term>DesktopDoubleBuffered</term>
1114             <listitem>
1115               <para>
1116                 Applies only if you use the
1117                 <parameter>--desktop</parameter> command-line option
1118                 to run in a desktop window. Specifies whether to
1119                 create the desktop window with a double-buffered
1120                 visual, something most OpenGL games need to run
1121                 correctly.
1122               </para>
1123             </listitem>
1124           </varlistentry>
1125         </variablelist>
1126       </sect2>
1127     </sect1>
1128
1129     &registry;
1130
1131     <sect1 id="cdrom-labels">
1132       <sect1info>
1133         <authorgroup>
1134           <author>
1135             <firstname>Petr</firstname>
1136             <surname>Tomasek</surname>
1137             <affiliation>
1138               <address><email>&email-petr-tomasek;</email></address>
1139             </affiliation>
1140             <contrib>Nov 14 1999</contrib>
1141           </author>
1142           <author>
1143             <firstname>Andreas</firstname>
1144             <surname>Mohr</surname>
1145             <affiliation>
1146               <address><email>&email-andreas-mohr;</email></address>
1147             </affiliation>
1148             <contrib>Jan 25 2000</contrib>
1149           </author>
1150         </authorgroup>
1151       </sect1info>
1152
1153       <title>Drive labels and serial numbers with wine</title>
1154       <para>
1155         Written by &name-petr-tomasek; <email>&email-petr-tomasek;</email>
1156         Nov 14 1999
1157       </para>
1158       <para>
1159         Changes by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
1160         Jan 25 2000
1161       </para>
1162       <para>
1163         (Extracted from <filename>wine/documentation/cdrom-labels</filename>)
1164       </para>
1165       <para>
1166         Until now, your only possibility of specifying drive volume
1167         labels and serial numbers was to set them manually in the wine
1168         config file. By now, wine can read them directly from the
1169         device as well. This may be useful for many Win 9x games or
1170         for setup programs distributed on CD-ROMs that check for
1171         volume label.
1172       </para>
1173
1174       <sect2>
1175         <title>What's Supported?</title>
1176
1177         <informaltable frame="all">
1178           <tgroup cols="3">
1179             <thead>
1180               <row>
1181                 <entry>File System</entry>
1182                 <entry>Types</entry>
1183                 <entry>Comment</entry>
1184               </row>
1185             </thead>
1186             <tbody>
1187               <row>
1188                 <entry>FAT systems</entry>
1189                 <entry>hd, floppy</entry>
1190                 <entry>reads labels and serial numbers</entry>
1191               </row>
1192               <row>
1193                 <entry>ISO9660</entry>
1194                 <entry>cdrom</entry>
1195                 <entry>reads labels only</entry>
1196               </row>
1197             </tbody>
1198           </tgroup>
1199         </informaltable>
1200
1201       </sect2>
1202
1203       <sect2>
1204         <title>How To Set Up?</title>
1205         <para>
1206           Reading labels and serial numbers just works automagically
1207           if you specify a <literal>Device=</literal> line in the
1208           [Drive X] section in your <filename>wine.conf</filename>.
1209           Note that the device has to exist and must be accessible if
1210           you do this, though.
1211         </para>
1212         <para>
1213           If you don't do that, then you should give fixed
1214           <literal>Label=</literal> or <literal>Serial=</literal>
1215           entries in <filename>wine.conf</filename>, as Wine returns
1216           these entries instead if no device is given. If they don't
1217           exist, then Wine will return default values (label
1218           <literal>Drive X</literal> and serial
1219           <literal>12345678</literal>).
1220         </para>
1221         <para>
1222           If you want to give a <literal>Device=</literal> entry
1223           <emphasis>only</emphasis> for drive raw sector accesses,
1224           but not for reading the volume info from the device (i.e. you want
1225           a <emphasis>fixed</emphasis>, preconfigured label), you need
1226           to specify <literal>ReadVolInfo=0</literal> to tell Wine to
1227           skip the volume reading.
1228         </para>
1229       </sect2>
1230
1231       <sect2>
1232         <title>EXAMPLES</title>
1233         <para>
1234           Here's a simple example of cdrom and floppy; labels will be
1235           read from the device on both cdrom and floppy; serial
1236           numbers on floppy only:
1237         </para>
1238         <screen>
1239 [Drive A]
1240 Path=/mnt/floppy
1241 Type=floppy
1242 Device=/dev/fd0
1243 Filesystem=msdos
1244
1245 [Drive R]
1246 Path=/mnt/cdrom
1247 Type=cdrom
1248 Device=/dev/hda1
1249 Filesystem=win95
1250         </screen>
1251         <para>
1252           Here's an example of overriding the CD-ROM label:
1253         </para>
1254         <screen>
1255 [Drive J]
1256 Path=/mnt/cdrom
1257 Type=cdrom
1258 Label=X234GCDSE
1259 ; note that the device isn't really needed here as we have a fixed label
1260 Device=/dev/cdrom
1261 Filesystem=msdos
1262         </screen>
1263       </sect2>
1264
1265       <sect2>
1266         <title>Todo / Open Issues</title>
1267         <itemizedlist>
1268           <listitem> <para>
1269               The cdrom label can be read only if the data track of
1270               the disk resides in the first track and the cdrom is
1271               iso9660.
1272             </para> </listitem>
1273           <listitem> <para>
1274               Better checking for FAT superblock (it now checks only
1275               one byte). </para>
1276           </listitem>
1277           <listitem> <para>
1278               Support for labels/serial nums WRITING.
1279             </para> </listitem>
1280           <listitem> <para>
1281               Can the label be longer than 11 chars? (iso9660 has 32
1282               chars).
1283             </para> </listitem>
1284           <listitem> <para>
1285               What about reading ext2 volume label? ....
1286             </para> </listitem>
1287         </itemizedlist>
1288       </sect2>
1289     </sect1>
1290
1291     <sect1 id="dll-overrides">
1292       <title>Dll Overrides</title>
1293
1294       <para>
1295         Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1296       </para>
1297       <para>
1298         (Extracted from <filename>wine/documentation/dll-overrides</filename>)
1299       </para>
1300
1301       <para>
1302         The <filename>wine.conf</filename> directives [DllDefaults]
1303         and [DllOverrides] are the subject of some confusion. The
1304         overall purpose of most of these directives are clear enough,
1305         though - given a choice, should Wine use its own built-in
1306         DLLs, or should it use <filename>.DLL</filename> files found
1307         in an existing Windows installation? This document explains
1308         how this feature works.
1309       </para>
1310
1311       <sect2>
1312         <title>DLL types</title>
1313         <variablelist>
1314           <varlistentry>
1315             <term>native</term>
1316             <listitem> <para>
1317                 A "native" DLL is a <filename>.DLL</filename> file
1318                 written for the real Microsoft Windows.
1319               </para> </listitem>
1320           </varlistentry>
1321           <varlistentry>
1322             <term>builtin</term>
1323             <listitem> <para>
1324                 A "builtin" DLL is a Wine DLL. These can either be a
1325                 part of <filename>libwine.so</filename>, or more
1326                 recently, in a special <filename>.so</filename> file
1327                 that Wine is able to load on demand.
1328               </para> </listitem>
1329           </varlistentry>
1330           <varlistentry>
1331             <term>elfdll</term>
1332             <listitem> <para>
1333                 An "elfdll" is a Wine <filename>.so</filename> file
1334                 with a special Windows-like file structure that is as
1335                 close to Windows as possible, and that can also
1336                 seamlessly link dynamically with "native" DLLs, by
1337                 using special ELF loader and linker tricks. Bertho
1338                 Stultiens did some work on this, but this feature has
1339                 not yet been merged back into Wine (because of
1340                 political reasons and lack of time), so this DLL type
1341                 does not exist in the official Wine at this time. In
1342                 the meantime, the "builtin" DLL type gained some of
1343                 the features of elfdlls (such as dynamic loading), so
1344                 it's possible that "elfdll" functionality will be
1345                 folded into "builtin" at some point.
1346               </para> </listitem>
1347           </varlistentry>
1348           <varlistentry>
1349             <term>so</term>
1350             <listitem> <para>
1351                 A native Unix <filename>.so</filename> file, with
1352                 calling convention conversion thunks generated on the
1353                 fly as the library is loaded. This is mostly useful
1354                 for libraries such as "glide" that have exactly the
1355                 same API on both Windows and Unix.
1356               </para> </listitem>
1357           </varlistentry>
1358         </variablelist>
1359       </sect2>
1360
1361       <sect2>
1362         <title>The [DllDefaults] section</title>
1363         <variablelist>
1364           <varlistentry>
1365             <term>EXTRA_LD_LIBRARY_PATH</term>
1366             <listitem> <para>
1367                 This specifies the location of the Wine's DLL
1368                 <filename>.so</filename> files. Wine will search this
1369                 path when trying to locate a DLL of the type
1370                 <literal>builtin</literal> or
1371                 <literal>elfdll</literal>. (This does not apply to
1372                 <filename>libwine.so</filename>, since
1373                 <filename>libwine.so</filename> is not a DLL in this
1374                 sense.)
1375               </para> </listitem>
1376           </varlistentry>
1377           <varlistentry>
1378             <term>DefaultLoadOrder</term>
1379             <listitem> <para>
1380                 This specifies in what order Wine should search for
1381                 available DLL types, if the DLL in question was not
1382                 found in the [DllOverrides] section.
1383               </para> </listitem>
1384           </varlistentry>
1385         </variablelist>
1386       </sect2>
1387
1388       <sect2>
1389         <title>The [DllPairs] section</title>
1390         <para>
1391           At one time, there was a section called [DllPairs] in the
1392           default configuration file, but this has been obsoleted
1393           because the pairing information has now been embedded into
1394           Wine itself. (The purpose of this section was merely to be
1395           able to issue warnings if the user attempted to pair
1396           codependent 16-bit/32-bit DLLs of different types.) If you
1397           still have this in your <filename>wine.conf</filename> or
1398           <filename>.winerc</filename>, you may safely delete it.
1399         </para>
1400       </sect2>
1401
1402       <sect2>
1403         <title>The [DllOverrides] section</title>
1404         <para>
1405           This section specifies how you want specific DLLs to be
1406           handled, in particular whether you want to use "native" DLLs
1407           or not, if you have some from a real Windows configuration.
1408           Because builtins do not mix seamlessly with native DLLs yet,
1409           certain DLL dependencies may be problematic, but workarounds
1410           exist in Wine for many popular DLL configurations. Also see
1411           WWN's [16]Status Page to figure out how well your favorite
1412           DLL is implemented in Wine.
1413         </para>
1414         <para>
1415           It is of course also possible to override these settings by
1416           explictly using Wine's <parameter>--dll</parameter>
1417           command-line option (see the man page for details).  Some
1418           hints for choosing your optimal configuration (listed by
1419           16/32-bit DLL pair):
1420         </para>
1421         <variablelist>
1422           <varlistentry>
1423             <term>krnl386, kernel32</term>
1424             <listitem> <para>
1425                 Native versions of these will never work, so don't try. Leave
1426                 at <literal>builtin</literal>.
1427               </para> </listitem>
1428           </varlistentry>
1429           <varlistentry>
1430             <term>gdi, gdi32</term>
1431             <listitem> <para>
1432                 Graphics Device Interface. No effort has been made at trying to
1433                 run native GDI. Leave at <literal>builtin</literal>.
1434               </para> </listitem>
1435           </varlistentry>
1436           <varlistentry>
1437             <term>user, user32</term>
1438             <listitem> <para>
1439                 Window management and standard controls. It was
1440                 possible to use Win95's <literal>native</literal>
1441                 versions at some point (if all other DLLs that depend
1442                 on it, such as comctl32 and comdlg32, were also run
1443                 <literal>native</literal>). However, this is no longer
1444                 possible after the Address Space Separation, so leave
1445                 at <literal>builtin</literal>.
1446               </para> </listitem>
1447           </varlistentry>
1448           <varlistentry>
1449             <term>ntdll</term>
1450             <listitem> <para>
1451                 NT kernel API. Although badly documented, the
1452                 <literal>native</literal> version of this will never
1453                 work. Leave at <literal>builtin</literal>.
1454               </para> </listitem>
1455           </varlistentry>
1456           <varlistentry>
1457             <term>w32skrnl</term>
1458             <listitem> <para>
1459                 Win32s (for Win3.x). The <literal>native</literal>
1460                 version will probably never work. Leave at
1461                 <literal>builtin</literal>.
1462               </para> </listitem>
1463           </varlistentry>
1464           <varlistentry>
1465             <term>wow32</term>
1466             <listitem> <para>
1467                 Win16 support library for NT. The
1468                 <literal>native</literal> version will probably never
1469                 work. Leave at <literal>builtin</literal>.
1470               </para> </listitem>
1471           </varlistentry>
1472           <varlistentry>
1473             <term>system</term>
1474             <listitem> <para>
1475                 Win16 kernel stuff. Will never work
1476                 <literal>native</literal>. Leave at
1477                 <literal>builtin</literal>.
1478               </para> </listitem>
1479           </varlistentry>
1480           <varlistentry>
1481             <term>display</term>
1482             <listitem> <para>
1483                 Display driver. Definitely leave at <literal>builtin</literal>.
1484               </para> </listitem>
1485           </varlistentry>
1486           <varlistentry>
1487             <term>toolhelp</term>
1488             <listitem> <para>
1489                 Tool helper routines. This is rarely a source of problems.
1490                 Leave at <literal>builtin</literal>.
1491               </para> </listitem>
1492           </varlistentry>
1493           <varlistentry>
1494             <term>ver, version</term>
1495             <listitem> <para>
1496                 Versioning. Seldom useful to mess with.
1497               </para> </listitem>
1498           </varlistentry>
1499           <varlistentry>
1500             <term>advapi32</term>
1501             <listitem> <para>
1502                 Registry and security features. Trying the
1503                 <literal>native</literal> version of this may or may
1504                 not work.
1505               </para> </listitem>
1506           </varlistentry>
1507           <varlistentry>
1508             <term>commdlg, comdlg32</term>
1509             <listitem> <para>
1510                 Common Dialogs, such as color picker, font dialog,
1511                 print dialog, open/save dialog, etc. It is safe to try
1512                 <literal>native</literal>.
1513               </para> </listitem>
1514           </varlistentry>
1515           <varlistentry>
1516             <term>commctrl, comctl32</term>
1517             <listitem> <para>
1518                 Common Controls. This is toolbars, status bars, list controls,
1519                 the works. It is safe to try <literal>native</literal>.
1520               </para> </listitem>
1521           </varlistentry>
1522           <varlistentry>
1523             <term>shell, shell32</term>
1524             <listitem> <para>
1525                 Shell interface (desktop, filesystem, etc). Being one of the
1526                 most undocumented pieces of Windows, you may have luck with the
1527                 <literal>native</literal> version, should you need it.
1528               </para> </listitem>
1529           </varlistentry>
1530           <varlistentry>
1531             <term>winsock, wsock32</term>
1532             <listitem> <para>
1533                 Windows Sockets. The <literal>native</literal> version
1534                 will not work under Wine, so leave at
1535                 <literal>builtin</literal>.
1536               </para> </listitem>
1537           </varlistentry>
1538           <varlistentry>
1539             <term>icmp</term>
1540             <listitem> <para>
1541                 ICMP routines for wsock32. As with wsock32, leave at
1542                 <literal>builtin</literal>.
1543               </para> </listitem>
1544           </varlistentry>
1545           <varlistentry>
1546             <term>mpr</term>
1547             <listitem> <para>
1548                 The <literal>native</literal> version may not work due
1549                 to thunking issues. Leave at
1550                 <literal>builtin</literal>.
1551               </para> </listitem>
1552           </varlistentry>
1553           <varlistentry>
1554             <term>lzexpand, lz32</term>
1555             <listitem> <para>
1556                 Lempel-Ziv decompression. Wine's
1557                 <literal>builtin</literal> version ought to work fine.
1558               </para> </listitem>
1559           </varlistentry>
1560           <varlistentry>
1561             <term>winaspi, wnaspi32</term>
1562             <listitem> <para>
1563                 Advanced SCSI Peripheral Interface. The
1564                 <literal>native</literal> version will probably never
1565                 work. Leave at <literal>builtin</literal>.
1566               </para> </listitem>
1567           </varlistentry>
1568           <varlistentry>
1569             <term>crtdll</term>
1570             <listitem> <para>
1571                 C Runtime library. The <literal>native</literal>
1572                 version will easily work better than Wine's on this
1573                 one.
1574               </para> </listitem>
1575           </varlistentry>
1576           <varlistentry>
1577             <term>winspool.drv</term>
1578             <listitem> <para>
1579                 Printer spooler. You are not likely to have more luck
1580                 with the <literal>native</literal> version.
1581               </para> </listitem>
1582           </varlistentry>
1583           <varlistentry>
1584             <term>ddraw</term>
1585             <listitem> <para>
1586                 DirectDraw/Direct3D. Since Wine does not implement the
1587                 DirectX HAL, the <literal>native</literal> version
1588                 will not work at this time.
1589               </para> </listitem>
1590           </varlistentry>
1591           <varlistentry>
1592             <term>dinput</term>
1593             <listitem> <para>
1594                 DirectInput. Running this <literal>native</literal>
1595                 may or may not work.
1596               </para> </listitem>
1597           </varlistentry>
1598           <varlistentry>
1599             <term>dsound</term>
1600             <listitem> <para>
1601                 DirectSound. It may be possible to run this
1602                 <literal>native</literal>, but don't count on it.
1603               </para> </listitem>
1604           </varlistentry>
1605           <varlistentry>
1606             <term>dplay/dplayx</term>
1607             <listitem> <para>
1608                 DirectPlay. The <literal>native</literal> version
1609                 ought to work best on this, if at all.
1610               </para> </listitem>
1611           </varlistentry>
1612           <varlistentry>
1613             <term>mmsystem, winmm</term>
1614             <listitem> <para>
1615                 Multimedia system. The <literal>native</literal>
1616                 version is not likely to work. Leave at
1617                 <literal>builtin</literal>.
1618               </para> </listitem>
1619           </varlistentry>
1620           <varlistentry>
1621             <term>msacm, msacm32</term>
1622             <listitem> <para>
1623                 Audio Compression Manager. The
1624                 <literal>builtin</literal> version works best, if you
1625                 set msacm.drv to the same.
1626               </para> </listitem>
1627           </varlistentry>
1628           <varlistentry>
1629             <term>msvideo, msvfw32</term>
1630             <listitem> <para>
1631                 Video for Windows. It is safe (and recommended) to try
1632                 <literal>native</literal>.
1633               </para> </listitem>
1634           </varlistentry>
1635           <varlistentry>
1636             <term>mcicda.drv</term>
1637             <listitem> <para>
1638                 CD Audio MCI driver.
1639               </para> </listitem>
1640           </varlistentry>
1641           <varlistentry>
1642             <term>mciseq.drv</term>
1643             <listitem> <para>
1644                 MIDI Sequencer MCI driver (<filename>.MID</filename>
1645                 playback).
1646               </para> </listitem>
1647           </varlistentry>
1648           <varlistentry>
1649             <term>mciwave.drv</term>
1650             <listitem> <para>
1651                 Wave audio MCI driver (<filename>.WAV</filename> playback).
1652               </para> </listitem>
1653           </varlistentry>
1654           <varlistentry>
1655             <term>mciavi.drv</term>
1656             <listitem> <para>
1657                 AVI MCI driver (<filename>.AVI</filename> video
1658                 playback). Best to use <literal>native</literal>.
1659               </para> </listitem>
1660           </varlistentry>
1661           <varlistentry>
1662             <term>mcianim.drv</term>
1663             <listitem> <para>
1664                 Animation MCI driver.
1665               </para> </listitem>
1666           </varlistentry>
1667           <varlistentry>
1668             <term>msacm.drv</term>
1669             <listitem> <para>
1670                 Audio Compression Manager. Set to same as msacm32.
1671               </para> </listitem>
1672           </varlistentry>
1673           <varlistentry>
1674             <term>midimap.drv</term>
1675             <listitem> <para>
1676                 MIDI Mapper.
1677               </para> </listitem>
1678           </varlistentry>
1679           <varlistentry>
1680             <term>wprocs</term>
1681             <listitem> <para>
1682                 This is a pseudo-DLL used by Wine for thunking
1683                 purposes. A <literal>native</literal> version of this
1684                 doesn't exist.
1685               </para> </listitem>
1686           </varlistentry>
1687         </variablelist>
1688       </sect2>
1689     </sect1>
1690
1691     <sect1 id="keyboard">
1692       <title>Keyboard</title>
1693
1694       <para>
1695         Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
1696       </para>
1697       <para>
1698         (Extracted from <filename>wine/documentation/keyboard</filename>)
1699       </para>
1700
1701       <para>
1702         Wine now needs to know about your keyboard layout. This
1703         requirement comes from a need from many apps to have the
1704         correct scancodes available, since they read these directly,
1705         instead of just taking the characters returned by the X
1706         server. This means that Wine now needs to have a mapping from
1707         X keys to the scancodes these applications expect.
1708       </para>
1709       <para>
1710         On startup, Wine will try to recognize the active X layout by
1711         seeing if it matches any of the defined tables. If it does,
1712         everything is alright. If not, you need to define it.
1713       </para>
1714       <para>
1715         To do this, open the file
1716         <filename>windows/x11drv/keyboard.c</filename> and take a look
1717         at the existing tables. Make a backup copy of it, especially
1718         if you don't use CVS.
1719       </para>
1720       <para>
1721         What you really would need to do, is find out which scancode
1722         each key needs to generate.  Find it in the
1723         <function>main_key_scan</function> table, which looks like
1724         this:
1725       </para>
1726       <programlisting>
1727 static const int main_key_scan[MAIN_LEN] =
1728 {
1729 /* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
1730    0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,
1731    0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,
1732    0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B,
1733    0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
1734    0x56 /* the 102nd key (actually to the right of l-shift) */
1735 };
1736       </programlisting>
1737       <para>
1738         Next, assign each scancode the characters imprinted on the
1739         keycaps. This was done (sort of) for the US 101-key keyboard,
1740         which you can find near the top in
1741         <filename>keyboard.c</filename>. It also shows that if there
1742         is no 102nd key, you can skip that.
1743       </para>
1744       <para>
1745         However, for most international 102-key keyboards, we have
1746         done it easy for you. The scancode layout for these already
1747         pretty much matches the physical layout in the
1748         <function>main_key_scan</function>, so all you need to do is
1749         to go through all the keys that generate characters on your
1750         main keyboard (except spacebar), and stuff those into an
1751         appropriate table. The only exception is that the 102nd key,
1752         which is usually to the left of the first key of the last line
1753         (usually <keycap>Z</keycap>), must be placed on a separate
1754         line after the last line.
1755       </para>
1756       <para>
1757         For example, my Norwegian keyboard looks like this
1758       </para>
1759       <screen>
1760 §  !  "  #  ¤  %  &  /  (  )  =  ?  `  Back-
1761 |  1  2@ 3£ 4$ 5  6  7{ 8[ 9] 0} +  \´ space
1762
1763 Tab Q  W  E  R  T  Y  U  I  O  P  Å  ^
1764                                      ¨~
1765                                         Enter
1766 Caps A  S  D  F  G  H  J  K  L  Ø  Æ  *
1767 Lock                                  '
1768
1769 Sh- > Z  X  C  V  B  N  M  ;  :  _  Shift
1770 ift &lt;                      ,  .  -
1771
1772 Ctrl  Alt       Spacebar       AltGr  Ctrl
1773       </screen>
1774       <para>
1775         Note the 102nd key, which is the <keycap>&lt;></keycap> key, to
1776         the left of <keycap>Z</keycap>. The character to the right of
1777         the main character is the character generated by
1778         <keycap>AltGr</keycap>.
1779       </para>
1780       <para>
1781         This keyboard is defined as follows:
1782       </para>
1783       <programlisting>
1784 static const char main_key_NO[MAIN_LEN][4] =
1785 {
1786  "|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´",
1787  "qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~",
1788  "aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*",
1789  "zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_",
1790  "&lt;>"
1791 };
1792       </programlisting>
1793       <para>
1794         Except that " and \ needs to be quoted with a backslash, and
1795         that the 102nd key is on a separate line, it's pretty
1796         straightforward.
1797       </para>
1798       <para>
1799         After you have written such a table, you need to add it to the
1800         <function>main_key_tab[]</function> layout index table. This
1801         will look like this:
1802       </para>
1803       <programlisting>
1804 static struct {
1805  WORD lang, ansi_codepage, oem_codepage;
1806  const char (*key)[MAIN_LEN][4];
1807 } main_key_tab[]={
1808 ...
1809 ...
1810  {MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT),  1252, 865, &amp;main_key_NO},
1811 ...
1812       </programlisting>
1813       <para>
1814         After you have added your table, recompile Wine and test that
1815         it works. If it fails to detect your table, try running
1816       </para>
1817       <screen>
1818 wine --debugmsg +key,+keyboard >& key.log
1819       </screen>
1820       <para>
1821         and look in the resulting <filename>key.log</filename> file to
1822         find the error messages it gives for your layout.
1823       </para>
1824       <para>
1825         Note that the <constant>LANG_*</constant> and
1826         <constant>SUBLANG_*</constant> definitions are in
1827         <filename>include/winnls.h</filename>, which you might need to
1828         know to find out which numbers your language is assigned, and
1829         find it in the debugmsg output. The numbers will be
1830         <literal>(SUBLANG * 0x400 + LANG)</literal>, so, for example
1831         the combination <literal>LANG_NORWEGIAN (0x14)</literal> and
1832         <literal>SUBLANG_DEFAULT (0x1)</literal> will be (in hex)
1833         <literal>14 + 1*400 = 414</literal>, so since I'm Norwegian, I
1834         could look for <literal>0414</literal> in the debugmsg output
1835         to find out why my keyboard won't detect.
1836       </para>
1837       <para>
1838         Once it works, submit it to the Wine project. If you use CVS,
1839         you will just have to do
1840       </para>
1841       <screen>
1842 cvs -z3 diff -u windows/x11drv/keyboard.c > layout.diff
1843       </screen>
1844       <para>
1845         from your main Wine directory, then submit
1846         <filename>layout.diff</filename> to
1847         <email>wine-patches@winehq.com</email> along with a brief note
1848         of what it is.
1849       </para>
1850       <para>
1851         If you don't use CVS, you need to do
1852       </para>
1853       <screen>
1854 diff -u the_backup_file_you_made windows/x11drv/keyboard.c > layout.diff
1855       </screen>
1856       <para>
1857         and submit it as explained above.
1858       </para>
1859       <para>
1860         If you did it right, it will be included in the next Wine
1861         release, and all the troublesome applications (especially
1862         remote-control applications) and games that use scancodes will
1863         be happily using your keyboard layout, and you won't get those
1864         annoying fixme messages either.
1865       </para>
1866       <para>
1867         Good luck.
1868       </para>
1869     </sect1>
1870   </chapter>
1871
1872 <!-- Keep this comment at the end of the file
1873 Local variables:
1874 mode: sgml
1875 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
1876 End:
1877 -->