documentation/packaging.sgml

   1 <!-- Wine Packaging guidelines.  This is a rough outline only,
   2      and much of this was up for open debate on wine-devel.  -->
   3
   4     <chapter id="pkg-preface"> <title>Preface</title>
   5
   6         <sect1 id="pkg-authors"> <title>Authors</title>
   7
   8         <para>
   9           Written by &name-marcus-meissner; <email>&email-marcus-meissner;</email>
  10           Updated by &name-jeremy-white; <email>&email-jeremy-white;</email>
  11         </para>
  12     </sect1>
  13
  14     <sect1 id="pkg-date"> <title>Document Revision Date</title>
  15
  16
  17       <para>
  18       The information contained in this document is extremely
  19       time sensitive.  <emphasis>It is vital that a packager
  20       stay current with changes in Wine. </>
  21       </para>
  22       <para>
  23       This document was last revised on November 2, 2000.</para>
  24
  25       </sect1>
  26
  27     <sect1 id="pkg-terms"> <title>Terms used in this document</title>
  28
  29         <para>There are several terms and paths used in this
  30         document as place holders for configurable values.
  31         Those terms are described here.
  32         </para>
  33
  34         <orderedlist>
  35             <listitem id=WINECONFDIR><para id=wineconfdir.id><EnVar>WINECONFDIR</EnVar></para>
  36                 <para>
  37                 <envar>WINECONFDIR</envar> is the users Wine configuration directory.
  38                 This is almost always ~/.wine, but can be overridden
  39                 by the user by setting the <EnVar>WINECONFDIR</EnVar> environment
  40                 variable.
  41                 </para>
  42             </listitem>
  43
  44             <listitem id=PREFIX><para id=prefix.id><EnVar>PREFIX</EnVar></para>
  45                 <para>
  46                 <envar>PREFIX</envar> is the prefix used when selecting
  47                 an installation target.  The current default is /usr.
  48                 This results in binary installation into /usr/bin,
  49                 library installation into /usr/wine/lib, and so forth.
  50                 This value can be overridden by the packager.
  51                 In fact, <ulink url="http://www.pathname.com/fhs/">FHS 2.1</ulink>
  52                 specifications suggest that a better
  53                 prefix is /opt/wine.  Ideally, a packager would also
  54                 allow the installer to override this value.
  55                 </para>
  56             </listitem>
  57
  58             <listitem id=ETCDIR><para id=etcdir.id><EnVar>ETCDIR</EnVar></para>
  59                 <para>
  60                 <envar>ETCDIR</envar> is the prefix that Wine uses
  61                 to find the global configuration directory.
  62                 This can be changed by the configure option sysconfdir.
  63                 The current default is /etc.
  64                 </para>
  65             </listitem>
  66
  67             <listitem id=WINDOWSDIR><para id=windowsdir.id><EnVar>WINDOWSDIR</EnVar></para>
  68                 <para>
  69                 <envar>WINDOWSDIR</envar> is an important concept
  70                 to Wine.  This directory specifies what directory
  71                 corresponds to the root Windows directory
  72                 (e.g. C:\WINDOWS).
  73                 </para>
  74                 <para>
  75                 This directory is specified by the user, in
  76                 the users <link linkend=winerc>configuration file</link>.
  77                 </para>
  78                 <para>
  79                 Generally speaking, this directory is either set
  80                 to point at an empty directory, or it is set
  81                 to point at a Windows partition that has been
  82                 mounted through the vfat driver.
  83                 </para>
  84                 <para>
  85                 <emphasis>It is extremely important that the packager
  86                 understand the importance of <envar>WINDOWSDIR</envar>
  87                 and convey this information and choice to the end
  88                 user</emphasis>.
  89                 </para>
  90             </listitem>
  91
  92         </orderedlist>
  93
  94
  95     </sect1>
  96
  97   </chapter>
  98
  99
 100
 101     <chapter id="pkg-introduction"> <title>Introduction</title>
 102
 103     <para>
 104         This document attempts to establish guidelines
 105         for people making binary packages of Wine.
 106     </para>
 107
 108     <para>
 109         It expresses the basic principles that the
 110         Wine developers have agreed should be
 111         used when building Wine.
 112         It also attempts to highlight the areas
 113         where there are different approaches
 114         to packaging Wine, so that the packager
 115         can understand the different alternatives
 116         that have been considered and their rationales.
 117     </para>
 118
 119         <sect1 id="pkg-goals"> <title>Goals</title>
 120         <para>
 121             An installation from a Wine pacakage should:
 122         </para>
 123           <itemizedlist>
 124
 125             <listitem>
 126                 <para>
 127                 Install quickly and simply.
 128                 </para>
 129                 <para>
 130                 The initial installation should require no user
 131                 input.  An rpm -i wine.rpm or apt get wine
 132                 should suffice for initial installation.
 133                 </para>
 134             </listitem>
 135
 136             <listitem>
 137                 <para>
 138                 Work quickly and simply
 139                 </para>
 140                 <para>
 141                 The user should be able to launch Solitaire
 142                 within minutes of downloading the Wine package.
 143                 </para>
 144             </listitem>
 145
 146             <listitem>
 147               <para>
 148               Comply with Filesystem Hierarchy Standard
 149               </para>
 150               <para>
 151               A Wine installation should, as much as possible, comply
 152               with the
 153                 <ulink url="http://www.pathname.com/fhs/">FHS standard</ulink>.
 154               </para>
 155             </listitem>
 156
 157             <listitem>
 158                 <para>
 159                 Preserve flexibility
 160                 </para>
 161                 <para>
 162                 None of the flexibility built into Wine should
 163                 be hidden from the end user.
 164                 </para>
 165             </listitem>
 166
 167             <listitem>
 168               <para>
 169                 Come as preconfigured as possible, so the user does
 170                 not need to change any configuration files.
 171               </para>
 172             </listitem>
 173
 174             <listitem>
 175               <para>Use only as much diskspace as needed per user.</para>
 176             </listitem>
 177
 178             <listitem>
 179               <para>
 180               Reduce support requirements.
 181               </para>
 182               <para>
 183               A packaged version of Wine should be sufficiently easy
 184               to use and have quick and easy access to FAQs and
 185               documentation such that requests to the
 186               newsgroup and development group go down.
 187               Further, it should be easy for users to capture
 188               good bug reports.
 189               </para>
 190             </listitem>
 191
 192           </itemizedlist>
 193
 194
 195         </sect1>
 196
 197         <sect1 id="pkg-requirements"> <title>Requirements</title>
 198       <para>
 199         Successfully installing Wine requires:
 200       </para>
 201
 202           <itemizedlist>
 203         <listitem>
 204           <para>Much thought and work from the packager (1x)</para>
 205         </listitem>
 206         <listitem>
 207           <para>
 208           A configuration file
 209           </para>
 210           <para>
 211           Wine will not run with out a configuration file.  Further,
 212           no default is currently provided by Wine.  Some packagers may attempt
 213           to provide (or dynamically generate) a default configuration
 214           file.  Some packagers may wish to
 215           rely on winecfg to generate the configuration file.
 216           </para>
 217         </listitem>
 218
 219
 220             <listitem>
 221               <para>
 222                 A writeable <filename>C:\</filename> directory
 223                 structure on a per user basis. Applications do dump
 224                 <filename>.ini</filename> files into
 225                 <filename>c:\windows</filename>, installers dump
 226                 <filename>.exe</filename>, <filename>.dll</filename>
 227                 and more into <filename>c:\windows\</filename> and
 228                 subdirectories or into <filename>C:\Program
 229                   Files\</filename>.
 230               </para>
 231             </listitem>
 232
 233
 234             <listitem>
 235               <para>
 236                 An initial set of registry entries.
 237               </para>
 238                 <para>
 239                 The current Wine standard is to use the regapi tool
 240                 against the 'winedefault.reg' file to generate
 241                 a default registry.
 242                 </para>
 243                 <para>
 244                 There are several other choices that could be made;
 245                 registries can be imported from a Windows partition.
 246                 At this time, Wine does not completely support
 247                 a complex multi user installation, ala Windows NT,
 248                 but it could fairly readily.
 249                 </para>
 250             </listitem>
 251
 252
 253             <listitem>
 254               <para>
 255                 Some special <filename>.dll</filename> and
 256                 <filename>.exe</filename> files in the
 257                 <filename>windows\system</filename> directory, since
 258                 applications directly check for their presence.
 259               </para>
 260             </listitem>
 261           </itemizedlist>
 262
 263         </sect1>
 264
 265
 266     </chapter>
 267
 268
 269
 270
 271     <chapter id="pkg-components"><title>Wine Components</title>
 272
 273     <para>
 274         This section lists all files that pertain to Wine.
 275     </para>
 276
 277         <sect1 id="pkg-static"><title>Wine Static and Shareable Files</title>
 278
 279         <para>
 280         At the time of this writing, the following components
 281         are installed through a standard 'make install'
 282         of Wine.
 283
 284         <caution>
 285         <para>
 286         It is vital that a packager check for
 287         changes in Wine.  This list will likely be out
 288         of date by the time this document is committed to CVS.
 289         </para>
 290         </caution>
 291
 292         </para>
 293
 294         <orderedlist>
 295
 296             <listitem id=binfiles>
 297                 <variablelist><title>Executable Files</title>
 298
 299                   <varlistentry><term><filename>wine</filename></term>
 300                     <listitem>
 301                     <para>
 302                     The main Wine executable.  This program will load
 303                     a Windows binary and run it, relying upon
 304                     the Wine shared object libraries.
 305                     </para>
 306                     </listitem>
 307                   </varlistentry>
 308
 309                   <varlistentry><term><filename>wineserver</filename></term>
 310                     <listitem>
 311                     <para>
 312                     The Wine server is critical to Wine; it is the
 313                     process that coordinates all shared Windows
 314                     resources.
 315                     </para>
 316                     </listitem>
 317                   </varlistentry>
 318
 319                   <varlistentry><term><filename>wineclipsrv</filename></term>
 320                     <listitem>
 321                     <para>
 322                     The Wine Clipboard Server is a standalone XLib
 323                     application whose purpose is to manage the X selection
 324                     when Wine exits.
 325                     </para>
 326                     </listitem>
 327                   </varlistentry>
 328
 329                   <varlistentry><term><filename>winedbg</filename></term>
 330                     <listitem>
 331                     <para>
 332                     Winedbg is the Wine built in debugger.
 333                     </para>
 334                     </listitem>
 335                   </varlistentry>
 336
 337                   <varlistentry><term><filename>winecfg</filename></term>
 338                     <listitem>
 339                     <para>
 340                     This is a Tcl/Tk based front end that provides
 341                     a user friendly tool to edit and configure
 342                     the <link linkend=WINECONFDIR endterm=wineconfdir.id></link>/config file.
 343                     </para>
 344                     </listitem>
 345                   </varlistentry>
 346
 347                   <varlistentry><term><filename>wineshelllink</filename></term>
 348                     <listitem>
 349                     <para>
 350                     This shell script can be called by Wine in order
 351                     to propogate Desktop icon and menu creation
 352                     requests out to a GNOME or KDE (or other
 353                     Window Managers).
 354                     </para>
 355                     </listitem>
 356                   </varlistentry>
 357
 358                   <varlistentry><term><filename>winebuild</filename></term>
 359                     <listitem>
 360                     <para>
 361                     Winebuild is a tool used for Winelib applications
 362                     (and by Wine itself) to allow a developer to
 363                     compile a .spec file into a .spec.c file.
 364                     </para>
 365                     </listitem>
 366                   </varlistentry>
 367                   <varlistentry><term><filename>wmc</filename></term>
 368                     <listitem>
 369                     <para>
 370                     The wmc tools is the Wine Message Compiler.  It
 371                     allows Windows message files to be compiled
 372                     into a format usable by Wine.
 373                     </para>
 374                     </listitem>
 375                   </varlistentry>
 376                   <varlistentry><term><filename>wrc</filename></term>
 377                     <listitem>
 378                     <para>
 379                     The wrc tool is the Wine Resource Compiler.
 380                     It allows Winelib programmers (and Wine itself)
 381                     to compile Windows style resource files
 382                     into a form usable by Wine.
 383                     </para>
 384                     </listitem>
 385                   </varlistentry>
 386                   <varlistentry><term><filename>fnt2bdf</filename></term>
 387                     <listitem>
 388                     <para>
 389                     The fnt2bdf utility extracts fonts from .fnt or
 390                     .dll files and stores then in .dbf format files.
 391                     </para>
 392                     </listitem>
 393                   </varlistentry>
 394                   <varlistentry><term><filename>dosmod</filename></term>
 395                     <listitem>
 396                     <para>
 397                     DOS Virtual Machine.
 398                     </para>
 399                     </listitem>
 400                   </varlistentry>
 401
 402                 </variablelist>
 403             </listitem>
 404
 405         <listitem id=libfiles>
 406         <para> Shared Object Library Files </para>
 407
 408         <simplelist columns=5>
 409
 410 <member>libwine.so.1.0</>
 411 <member>libddraw.so.1.0</>
 412 <member>libopengl32.so.1.0</>
 413 <member>libx11drv.so.1.0</>
 414 <member>libadvapi32.so.1.0</>
 415 <member>libavifil32.so.1.0</>
 416 <member>libcomctl32.so.1.0</>
 417 <member>libcomdlg32.so.1.0</>
 418 <member>libcrtdll.so.1.0</>
 419 <member>libdciman32.so.1.0</>
 420 <member>libdinput.so.1.0</>
 421 <member>libdplay.so.1.0</>
 422 <member>libdplayx.so.1.0</>
 423 <member>libdsound.so.1.0</>
 424 <member>libgdi32.so.1.0</>
 425 <member>libicmp.so.1.0</>
 426 <member>libimagehlp.so.1.0</>
 427 <member>libimm32.so.1.0</>
 428 <member>libkernel32.so.1.0</>
 429 <member>liblz32.so.1.0</>
 430 <member>libmpr.so.1.0</>
 431 <member>libmsacm32.so.1.0</>
 432 <member>libmsnet32.so.1.0</>
 433 <member>libmsvfw32.so.1.0</>
 434 <member>libodbc32.so.1.0</>
 435 <member>libole32.so.1.0</>
 436 <member>liboleaut32.so.1.0</>
 437 <member>libolecli32.so.1.0</>
 438 <member>liboledlg.so.1.0</>
 439 <member>libolepro32.so.1.0</>
 440 <member>libolesvr32.so.1.0</>
 441 <member>libpsapi.so.1.0</>
 442 <member>librasapi32.so.1.0</>
 443 <member>libriched32.so.1.0</>
 444 <member>librpcrt4.so.1.0</>
 445 <member>libserialui.so.1.0</>
 446 <member>libsetupapi.so.1.0</>
 447 <member>libshell32.so.1.0</>
 448 <member>libshfolder.so.1.0</>
 449 <member>libshlwapi.so.1.0</>
 450 <member>libtapi32.so.1.0</>
 451 <member>libttydrv.so.1.0</>
 452 <member>liburlmon.so.1.0</>
 453 <member>libuser32.so.1.0</>
 454 <member>libversion.so.1.0</>
 455 <member>libw32skrnl.so.1.0</>
 456 <member>libwnaspi32.so.1.0</>
 457 <member>libwineps.so.1.0</>
 458 <member>libwininet.so.1.0</>
 459 <member>libjoystick.drv.so.1.0</>
 460 <member>libwinmm.so.1.0</>
 461 <member>libmcianim.drv.so.1.0</>
 462 <member>libmciavi.drv.so.1.0</>
 463 <member>libmcicda.drv.so.1.0</>
 464 <member>libmciseq.drv.so.1.0</>
 465 <member>libmciwave.drv.so.1.0</>
 466 <member>libmidimap.drv.so.1.0</>
 467 <member>libmsacm.drv.so.1.0</>
 468 <member>libwineoss.drv.so.1.0</>
 469 <member>libws2_32.so.1.0</>
 470 <member>libwinspool.drv.so.1.0</>
 471 <member>libwow32.so.1.0</>
 472 <member>libwsock32.so.1.0</>
 473 <member>libwine_unicode.so.1.0</>
 474         </simplelist>
 475
 476         </listitem>
 477
 478
 479             <listitem id=manfiles>
 480             <para> Man Pages</para>
 481                 <simplelist columns=1>
 482 <member>wine.man</>
 483 <member>wine.conf.man</>
 484 <member>wmc.man</>
 485 <member>wrc.man</>
 486         </simplelist>
 487
 488         </listitem>
 489
 490
 491             <listitem id=includefiles>
 492             <para> Include Files</para>
 493                 <simplelist columns=5>
 494
 495 <member>basetsd.h</>
 496 <member>cderr.h</>
 497 <member>cguid.h</>
 498 <member>commctrl.h</>
 499 <member>commdlg.h</>
 500 <member>compobj.h</>
 501 <member>d3d.h</>
 502 <member>d3dcaps.h</>
 503 <member>d3dtypes.h</>
 504 <member>d3dvec.inl</>
 505 <member>dde.h</>
 506 <member>ddeml.h</>
 507 <member>ddraw.h</>
 508 <member>digitalv.h</>
 509 <member>dinput.h</>
 510 <member>dispdib.h</>
 511 <member>dlgs.h</>
 512 <member>docobj.h</>
 513 <member>dplay.h</>
 514 <member>dplobby.h</>
 515 <member>dsound.h</>
 516 <member>guiddef.h</>
 517 <member>imagehlp.h</>
 518 <member>imm.h</>
 519 <member>initguid.h</>
 520 <member>instance.h</>
 521 <member>lmcons.h</>
 522 <member>lzexpand.h</>
 523 <member>mapidefs.h</>
 524 <member>mcx.h</>
 525 <member>mmreg.h</>
 526 <member>mmsystem.h</>
 527 <member>msacm.h</>
 528 <member>ntsecapi.h</>
 529 <member>oaidl.h</>
 530 <member>objbase.h</>
 531 <member>objidl.h</>
 532 <member>ocidl.h</>
 533 <member>ole2.h</>
 534 <member>ole2ver.h</>
 535 <member>oleauto.h</>
 536 <member>olectl.h</>
 537 <member>oledlg.h</>
 538 <member>oleidl.h</>
 539 <member>poppack.h</>
 540 <member>prsht.h</>
 541 <member>psapi.h</>
 542 <member>pshpack1.h</>
 543 <member>pshpack2.h</>
 544 <member>pshpack4.h</>
 545 <member>pshpack8.h</>
 546 <member>ras.h</>
 547 <member>regstr.h</>
 548 <member>richedit.h</>
 549 <member>rpc.h</>
 550 <member>servprov.h</>
 551 <member>shellapi.h</>
 552 <member>shlguid.h</>
 553 <member>shlobj.h</>
 554 <member>shlwapi.h</>
 555 <member>sql.h</>
 556 <member>sqlext.h</>
 557 <member>sqltypes.h</>
 558 <member>storage.h</>
 559 <member>tapi.h</>
 560 <member>tlhelp32.h</>
 561 <member>unknwn.h</>
 562 <member>urlmon.h</>
 563 <member>ver.h</>
 564 <member>vfw.h</>
 565 <member>winbase.h</>
 566 <member>wincon.h</>
 567 <member>wincrypt.h</>
 568 <member>windef.h</>
 569 <member>windows.h</>
 570 <member>windowsx.h</>
 571 <member>wine/exception.h</>
 572 <member>wine/icmpapi.h</>
 573 <member>wine/ipexport.h</>
 574 <member>wine/obj_base.h</>
 575 <member>wine/obj_cache.h</>
 576 <member>wine/obj_channel.h</>
 577 <member>wine/obj_clientserver.h</>
 578 <member>wine/obj_commdlgbrowser.h</>
 579 <member>wine/obj_connection.h</>
 580 <member>wine/obj_contextmenu.h</>
 581 <member>wine/obj_control.h</>
 582 <member>wine/obj_dataobject.h</>
 583 <member>wine/obj_dockingwindowframe.h</>
 584 <member>wine/obj_dragdrop.h</>
 585 <member>wine/obj_enumidlist.h</>
 586 <member>wine/obj_errorinfo.h</>
 587 <member>wine/obj_extracticon.h</>
 588 <member>wine/obj_inplace.h</>
 589 <member>wine/obj_marshal.h</>
 590 <member>wine/obj_misc.h</>
 591 <member>wine/obj_moniker.h</>
 592 <member>wine/obj_oleaut.h</>
 593 <member>wine/obj_olefont.h</>
 594 <member>wine/obj_oleobj.h</>
 595 <member>wine/obj_oleundo.h</>
 596 <member>wine/obj_oleview.h</>
 597 <member>wine/obj_picture.h</>
 598 <member>wine/obj_property.h</>
 599 <member>wine/obj_propertystorage.h</>
 600 <member>wine/obj_queryassociations.h</>
 601 <member>wine/obj_shellbrowser.h</>
 602 <member>wine/obj_shellextinit.h</>
 603 <member>wine/obj_shellfolder.h</>
 604 <member>wine/obj_shelllink.h</>
 605 <member>wine/obj_shellview.h</>
 606 <member>wine/obj_storage.h</>
 607 <member>wine/unicode.h</>
 608 <member>winerror.h</>
 609 <member>wingdi.h</>
 610 <member>wininet.h</>
 611 <member>winioctl.h</>
 612 <member>winnetwk.h</>
 613 <member>winnls.h</>
 614 <member>winnt.h</>
 615 <member>winreg.h</>
 616 <member>winresrc.h</>
 617 <member>winsock.h</>
 618 <member>winsock2.h</>
 619 <member>winspool.h</>
 620 <member>winsvc.h</>
 621 <member>winuser.h</>
 622 <member>winver.h</>
 623 <member>wnaspi32.h</>
 624 <member>wownt32.h</>
 625 <member>wtypes.h</>
 626 <member>zmouse.h</>
 627         </simplelist>
 628
 629         </listitem>
 630
 631         <listitem id=docfiles>
 632         <para>
 633         Documentation files.
 634         </para>
 635         <para>
 636         At the time of this writing, I do not have a
 637         definitive list of documentation files to
 638         be installed.  However, they do include
 639         the HTML files generated from the SGML in the Wine CVS tree.
 640         </para>
 641         </listitem>
 642
 643
 644         </orderedlist>
 645
 646         </sect1>
 647
 648
 649         <sect1 id="pkg-nonstatic"><title>Dynamic Wine Files</title>
 650
 651         <para>
 652         Wine also generates and depends on a number of dynamic
 653         files, including user configuration files and registry files.
 654         </para>
 655
 656         <para>
 657         At the time of this writing, there was not a clear
 658         consensus of where these files should be located, and how
 659         they should be handled.  This section attempts
 660         to explain the alternatives clearly.
 661         </para>
 662
 663         <orderedlist>
 664
 665             <listitem>
 666                 <variablelist><title>Configuration File</title>
 667                   <varlistentry id=winerc><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/config</filename></term>
 668                     <listitem>
 669                     <para>
 670                     This file is the user local Wine configuration file.
 671                     At the time of this writing, if this file exists,
 672                     then no other configuration file is loaded.
 673                     </para>
 674                     </listitem>
 675                   </varlistentry>
 676
 677                   <varlistentry><term>
 678                     <filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.conf</filename></term>
 679                     <listitem>
 680                     <para>
 681                     This is the global Wine configuration file.  It
 682                     is only used if the user running Wine has
 683                     no local configuration file.
 684                     </para>
 685                     <para>
 686                     Some packagers feel that this file should not
 687                     be supplied, and that only a wine.conf.default
 688                     should be given here.
 689                     </para>
 690                     <para>
 691                     Other packagers feel that this file should
 692                     be the predominant file used, and that
 693                     users should only shift to a local configuration
 694                     file if they need to.  An argument has been
 695                     made that the local configuration file
 696                     should inherit the global configuration file.
 697                     At this time, Wine does not do this;
 698                     please refer to the WineHQ discussion
 699                     archives for the debate concerning this.
 700                     </para>
 701                     <para>
 702                     This debate is addressed more completely
 703                     below, in <link linkend=pkg-strategy endterm=strategy.id></link>.
 704                     </para>
 705                     </listitem>
 706                   </varlistentry>
 707                 </variablelist>
 708
 709             </listitem>
 710
 711         <listitem>
 712
 713                 <para>Registry Files</para>
 714
 715                 <para>
 716                 In order to replicate the Windows registry system,
 717                 Wine stores registry entries in a series of files.
 718
 719                 For an excellent overview of this issue, read
 720                 this
 721                 <ulink url="http://www.winehq.com/News/2000-25.html#FTR">
 722                 Wine Weekly News feature.</ulink>
 723
 724                 </para>
 725
 726                 <para>
 727                 The bottom line is that, at Wine server startup,
 728                 Wine loads all registry entries into memory
 729                 to create an in memory image of the registry.
 730                 The order of files which Wine uses to load
 731                 registry entries is extremely important,
 732                 as it affects what registry entries are
 733                 actually present.  The order is roughly that
 734                 .dat files from a Windows partion are loaded,
 735                 then global registry settings from <link linkend=ETCDIR endterm=etcdir.id></link>,
 736                 and then finally local registry settings are
 737                 loaded from <link linkend=WINECONFDIR endterm=wineconfdir.id></link>
 738                 .  As each set are loaded,
 739                 they can override the prior entries.  Thus,
 740                 the local registry files take precedence.
 741                 </para>
 742
 743                 <para>
 744                 Then, at exit (or at periodic intervals),
 745                 Wine will write either all registry entries
 746                 (or, with the default setting) changed
 747                 registry entries to files in the
 748                 <link linkend=WINECONFDIR endterm=wineconfdir.id></link>.
 749                 </para>
 750
 751                 <variablelist>
 752                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/system.reg</filename></term>
 753                     <listitem>
 754                     <para>
 755                     This file contains the users local copy of
 756                     the HKEY_LOCAL_MACHINE registry hive.  In general
 757                     use, it will contain only changes made to the
 758                     default registry values.
 759                     </para>
 760                     </listitem>
 761                   </varlistentry>
 762
 763                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/user.reg</filename></term>
 764                     <listitem>
 765                     <para>
 766                     This file contains the users local copy of
 767                     the HKEY_CURRENT_USER registry hive.  In
 768                     general use, it will contain only changes made to the
 769                     default registry values.
 770                     </para>
 771                     </listitem>
 772                   </varlistentry>
 773
 774                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/userdef.reg</filename></term>
 775                     <listitem>
 776                     <para>
 777                     This file contains the users local copy of
 778                     the HKEY_USERS\.Default registry hive.  In
 779                     general use, it will contain only changes made to the
 780                     default registry values.
 781                     </para>
 782                     </listitem>
 783                   </varlistentry>
 784
 785                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/wine.userreg</filename></term>
 786                     <listitem>
 787                     <para>
 788                     This file is being deprecated.  It is only read
 789                     if there is no user.reg or wine.userreg, and
 790                     it supplied the contents of HKEY_USERS.
 791                     </para>
 792                     </listitem>
 793                   </varlistentry>
 794
 795                   <varlistentry><term><filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.systemreg</filename></term>
 796                     <listitem>
 797                     <para>
 798                     This file contains the global values for
 799                     HKEY_LOCAL_MACHINE.  The values in this file
 800                     can be overriden by the users local settings.
 801                     </para>
 802                     <note>
 803                     <para>
 804                     The location of this directory is hard coded within
 805                     wine, generally to /etc.  This will hopefully be
 806                     fixed at some point in the future.
 807                     </para>
 808                     </note>
 809                     </listitem>
 810                   </varlistentry>
 811
 812
 813                   <varlistentry><term><filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.userreg</filename></term>
 814                     <listitem>
 815                     <para>
 816                     This file contains the global values for
 817                     HKEY_USERS.  The values in this file
 818                     can be overriden by the users local settings.
 819                     This file is likely to be deprecated in
 820                     favor of a global wine.userdef.reg that will
 821                     only contain HKEY_USERS/.Default.
 822                     </para>
 823                     </listitem>
 824                   </varlistentry>
 825
 826                 </variablelist>
 827
 828
 829         </listitem>
 830
 831         <listitem>
 832                 <variablelist><title>Other files in <link linkend=WINECONFDIR endterm=wineconfdir.id></link></title>
 833                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/wineserver-[username]</filename></term>
 834                     <listitem>
 835                     <para>
 836                     This directory contains files used by Wine and the Wineserver
 837                     to communicate.  A packager may want to have a facility
 838                     for the user to erase files in this directory,
 839                     as a crash in the wineserver resulting in a bogus lock
 840                     file can render wine unusable.
 841                     </para>
 842                     </listitem>
 843                   </varlistentry>
 844
 845                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/cachedmetrics.[display]</filename></term>
 846                     <listitem>
 847                     <para>
 848                     This file contains font metrics for the given X display.
 849                     Generally, this cache is generated once at Wine start time.
 850                     </para>
 851                     </listitem>
 852                   </varlistentry>
 853
 854                 </variablelist>
 855         </listitem>
 856
 857
 858         </orderedlist>
 859
 860
 861         </sect1>
 862
 863         <sect1 id="pkg-winpartition"><title>Important Files from a Windows Partition</title>
 864         <para>
 865         Wine has the ability to use files from an installation of the
 866         actual Microsoft Windows operating system.  Generally these
 867         files are loaded on a VFAT partition that is mounted
 868         under Linux.
 869         </para>
 870         <para>
 871         This is probably the most important configuration detail.
 872         The use of Windows registry and DLL files dramatically
 873         alters the behaviour of Wine.  If nothing else,
 874         pacakager have to make this distinction clear
 875         to the end user, so that they can intelligently
 876         choose their configuration.
 877         </para>
 878
 879
 880         <orderedlist>
 881
 882             <listitem>
 883                 <variablelist><title>Registry Files</title>
 884                   <varlistentry><term><filename>[WINDOWSDIR]/system32/system.dat</filename></term>
 885                     <listitem>
 886                     <para>
 887                     </para>
 888                     </listitem>
 889                   </varlistentry>
 890
 891                   <varlistentry><term><filename>[WINDOWSDIR]/system32/user.dat</filename></term>
 892                     <listitem>
 893                     <para>
 894                     </para>
 895                     </listitem>
 896                   </varlistentry>
 897
 898                   <varlistentry><term><filename>[WINDOWSDIR]/win.ini</filename></term>
 899                     <listitem>
 900                     <para>
 901                     </para>
 902                     </listitem>
 903                   </varlistentry>
 904
 905                 </variablelist>
 906
 907             </listitem>
 908
 909             <listitem>
 910                 <para>
 911                 Windows Dynamic Link Libraries ([WINDOWSDIR]/system32/*.dll)
 912                 </para>
 913                 <para>
 914                 Wine has the ability to use the actuall Windows DLL files
 915                 when running an application.  An end user can configure
 916                 Wine so that Wine uses some or all of these DLL files
 917                 when running a given application.
 918                 </para>
 919             </listitem>
 920
 921         </orderedlist>
 922
 923         </sect1>
 924
 925     </chapter>
 926
 927     <chapter id="pkg-strategy"><title id=strategy.id>Packaging Strategies</title>
 928
 929         <para>
 930         There has recently been a lot of discussion on the Wine
 931         development mailing list about the best way to
 932         build Wine packages.
 933         </para>
 934         <para>
 935         There was a lot of discussion, and several diverging
 936         points of view.  This section of the document
 937         attempts to present the areas of common agreement,
 938         and also to present the different approaches
 939         advocated on the mailing list.
 940         </para>
 941
 942         <sect1 id="pkg-whatfiles"><title>Distribution of Wine into packages</title>
 943         <para>
 944         The most basic question to ask is given the Wine CVS tree,
 945         what physical files are you, the packager, going to produce?
 946         Are you going to produce only a wine.rpm (as Marcus has done),
 947         or are you going to produce 5 debian files
 948         (libwine-dev, libwine, wine-doc, wine-utils, and wine) as
 949         Ove has done?
 950         </para>
 951         <para>
 952         At this point, there is no consensus
 953         amongst the wine-devel community on this subject.
 954         </para>
 955         </sect1>
 956
 957         <sect1 id="pkg-wherefiles"><title>Where to install files</title>
 958         <para>
 959         This question is not really contested.  It will vary
 960         by distribution, and is really up to the packager.
 961         As a guideline, the current 'make install' process
 962         seems to behave such that
 963         if we pick a single <link linkend=PREFIX endterm=prefix.id></link>,
 964         then :
 965         </para>
 966         <orderedlist>
 967
 968             <listitem>
 969             <para>
 970             all <link linkend=binfiles>binary files</link> go into
 971             <link linkend=PREFIX endterm=prefix.id></link>/bin,
 972             </para>
 973             </listitem>
 974
 975             <listitem>
 976             <para>
 977             all <link linkend=libfiles>library files</link> go into
 978             <link linkend=PREFIX endterm=prefix.id></link>/lib,
 979             </para>
 980             </listitem>
 981
 982             <listitem>
 983             <para>
 984             all <link linkend=includefiles>include files</link> go into
 985             <link linkend=PREFIX endterm=prefix.id></link>/include,
 986             </para>
 987             </listitem>
 988
 989             <listitem>
 990             <para>
 991             all <link linkend=docfiles>documentation files</link> go into
 992             <link linkend=PREFIX endterm=prefix.id></link>/doc/wine,
 993             </para>
 994             </listitem>
 995
 996             <listitem>
 997             <para>
 998             and <link linkend=manfiles>man pages</link> go into
 999             <link linkend=PREFIX endterm=prefix.id></link>/man,
1000             </para>
1001             </listitem>
1002
1003         </orderedlist>
1004
1005         <para>
1006         Refer to the specific information on the Debian package
1007         and the OpenLinux package for specific details on how
1008         those packages are built.
1009         </para>
1010
1011         <sect2 id=opt><title>The question of /opt/wine</title>
1012         <para>
1013         The FHS 2.1 specification suggests that Wine as a package
1014         should be installed to /opt/wine.  None of the
1015         existing packages follow this guideline (today;
1016         check again tomorrow).
1017         </para>
1018         </sect2>
1019
1020         </sect1>
1021
1022         <sect1 id="pkg-whattomake"><title>What files to create</title>
1023         <para>
1024         After installing the static and shareable files, the next
1025         question the packager needs to ask is how much dynamic
1026         configuration will be done, and what configuration
1027         files should be created.
1028         </para>
1029         <para>
1030         There are several approaches to this:
1031         <orderedlist>
1032             <listitem>
1033                 <para>
1034                 Rely completely on user file space - install nothing
1035                 </para>
1036                 <para>
1037                 This approach relies upon the new winecfg utility and
1038                 the new ability of Wine to launch winecfg if no configuration file is found.
1039                 The basic concept is that no global configuration files
1040                 are created at install time.
1041                 Instead, Wine configuration files are created on the
1042                 fly by the winecfg program when Wine is invoked.
1043                 Further, winecfg creates default Windows directories
1044                 and paths that are stored completely in
1045                 the users <link linkend=WINECONFDIR endterm=wineconfdir.id></link>.
1046                 </para>
1047                 <para>
1048                 This approach has the benefit of simplicity in that all
1049                 Wine files are either stored under /opt/wine or under
1050                 ~/.wine.  Further, there is only ever one Wine
1051                 configuration file.
1052                 </para>
1053                 <para>
1054                 This approach, however, adds another level of complexity.
1055                 It does not allow Wine to run Solitaire 'out of the box';
1056                 the user must run the configuration program first.  Further,
1057                 winecfg requires Tcl/Tk, a requirement not beloved by some.
1058                 Additionally, this approach closes the door on multi
1059                 user configurations and presumes a single user approach.
1060                 </para>
1061             </listitem>
1062
1063
1064             <listitem>
1065                 <para>
1066                 Build a reasonable set of defaults for the global wine.conf,
1067                 facilitate creation of a user's local Wine configuration.
1068                 </para>
1069                 <para>
1070                 This approach, best shown by Marcus, causes the
1071                 installation process to auto scan the system,
1072                 and generate a global wine.conf file with best
1073                 guess defaults.  The OpenLinux packages follow
1074                 this behaviour.
1075                 </para>
1076                 <para>
1077                 The keys to this approach are always putting
1078                 an existing Windows partition into the
1079                 path, and being able to run Solitaire
1080                 right out of the box.
1081                 Another good thing that Marcus does is he
1082                 detects a first time installation and
1083                 does some clever things to improve the
1084                 user's Wine experience.
1085                 </para>
1086                 <para>
1087                 A flaw with this approach, however, is it doesn't
1088                 give the user an obvious way to choose not to
1089                 use a Windows partition.
1090                 </para>
1091             </listitem>
1092
1093             <listitem>
1094                 <para>
1095                 Build a reasonable set of defaults for the global wine.conf,
1096                 and ask the user if possible
1097                 </para>
1098                 <para>
1099                 This approach, demonstrated by Ove, causes the
1100                 installation process to auto scan the system,
1101                 and generate a global wine.conf file with best
1102                 guess defaults.  Because Ove built a Debian
1103                 package, he was able to further query debconf and
1104                 get permission to ask the user some questions,
1105                 allowing the user to decide whether or not to
1106                 use a Windows partition.
1107                 </para>
1108             </listitem>
1109
1110
1111             </orderedlist>
1112         </para>
1113
1114         </sect1>
1115
1116
1117         <sect1 id="pkg-wineconf"><title>What to put into the wine config file</title>
1118         <para>
1119         The next hard question is what the Wine config should look like.
1120         The current best practices seems to involve using drives from M to Z.
1121         </para>
1122         <caution><para>This isn't done yet!  Fix it, Jer!</para></caution>
1123         </sect1>
1124
1125
1126     </chapter>
1127
1128
1129
1130
1131     <chapter id="pkg-implementation"> <title>Implementation</title>
1132
1133     <sect1 id="pkg-openlinux"><title>OpenLinux Sample</title>
1134
1135           <orderedlist inheritnum="inherit">
1136             <listitem>
1137               <para>Building the package</para>
1138               <para>
1139                 WINE is configured the usual way (depending on your
1140                 build environment). The "prefix" is chosen using your
1141                 application placement policy
1142                 (<filename>/usr/</filename>,
1143                 <filename>/usr/X11R6/</filename>,
1144                 <filename>/opt/wine/</filename> or similar).  The
1145                 configuration files (<filename>wine.conf</filename>,
1146                 <filename>wine.userreg</filename>,
1147                 <filename>wine.systemreg</filename>) are targeted for
1148                 <filename>/etc/wine/</filename> (rationale: FHS 2.0,
1149                 multiple readonly configuration files of a package).
1150               </para>
1151               <para>
1152                 Example (split this into <literal>%build</literal> and
1153                 <literal>%install</literal> section for
1154                 <command>rpm</command>):
1155               </para>
1156               <screen>
1157 CFLAGS=$RPM_OPT_FLAGS \
1158 ./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
1159 make
1160 BR=$RPM_BUILD_ROOT
1161 make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/
1162 install -d $BR/etc/wine/
1163 install -m 644 wine.ini $BR/etc/wine/wine.conf
1164
1165 # Put all our dlls in a seperate directory. (this works only if
1166 # you have a buildroot)
1167 install -d $BR/usr/X11R6/lib/wine
1168 mv $BR/usr/X11R6/lib/lib* $BR/usr/X11R6/lib/wine/
1169
1170 # the clipboard server is started on demand.
1171 install -m 755 windows/x11drv/wineclipsrv $BR/usr/X11R6/bin/
1172
1173 # The WINE server is needed.
1174 install -m 755 server/wineserver $BR/usr/X11R6/bin/
1175               </screen>
1176               <para>
1177                 Here we unfortunately do need to create
1178                 <filename>wineuser.reg</filename> and
1179                 <filename>winesystem.reg</filename> from the WINE
1180                 distributed <filename>winedefault.reg</filename>. This
1181                 can be done using <command>./regapi</command> once for
1182                 one example user and then reusing his
1183                 <filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/user.reg</filename> and
1184                 <filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/system.reg</filename> files.
1185                 <note>
1186                   <title>FIXME</title>
1187                   <para>this needs to be done better</para>
1188                 </note>
1189               </para>
1190               <screen>
1191 install -m 644 wine.sytemreg $BR/etc/wine/
1192 install -m 644 wine.userreg $BR/etc/wine/
1193               </screen>
1194               <para>
1195                 There are now a lot of libraries generated by the
1196                 build process, so a seperate library directory should
1197                 be used.
1198               </para>
1199               <screen>
1200 install -d 755 $BR/usr/X11R6/lib/
1201 mv $BR/
1202               </screen>
1203               <para>
1204                 You will need to package the files:
1205               </para>
1206               <screen>
1207 $prefix/bin/wine, $prefix/bin/dosmod, $prefix/lib/wine/*
1208 $prefix/man/man1/wine.1, $prefix/include/wine/*,
1209 $prefix/bin/wineserver, $prefix/bin/wineclipsrv
1210
1211 %config /etc/wine/*
1212 %doc ... choose from the toplevel directory and documentation/
1213               </screen>
1214               <para>
1215                 The post-install script:
1216               </para>
1217               <screen>
1218 if ! grep -q /usr/X11R6/lib/wine /etc/ld.so.conf; then
1219     echo "/usr/X11R6/lib/wine" &gt;&gt; /etc/ld.so.conf
1220 fi
1221 /sbin/ldconfig
1222               </screen>
1223               <para>
1224                 The post-uninstall script:
1225               </para>
1226               <screen>
1227 if [ "$1" = 0 ]; then
1228     perl -ni -e 'print unless m:/usr/X11R6/lib/wine:;' /etc/ld.so.conf
1229 fi
1230 /sbin/ldconfig
1231               </screen>
1232             </listitem>
1233             <listitem>
1234               <para>Creating a good default configuration file</para>
1235               <para>
1236                 For the rationales of needing as less input from the
1237                 user as possible  arises the need for a very good
1238                 configuration file. The one supplied with WINE is
1239                 currently lacking. We need:
1240               </para>
1241               <itemizedlist>
1242                 <listitem>
1243                   <para>
1244                     [Drive X]:
1245                   </para>
1246                   <itemizedlist>
1247                     <listitem>
1248                       <para>
1249                         A for the floppy. Specify your distributions
1250                         default floppy mountpoint here.
1251                       </para>
1252                       <programlisting>
1253 Path=/auto/floppy
1254                       </programlisting>
1255                     </listitem>
1256                     <listitem>
1257                       <para>
1258                         C for the <filename>C:\</filename> directory.
1259                         Here we use the users homedirectory, for most
1260                         applications do see <filename>C:\</filename>
1261                         as root-writeable directory of every windows
1262                         installation and this basically is it in the
1263                         UNIX-user context.
1264                         </para>
1265                       <programlisting>
1266 Path=${HOME}
1267                       </programlisting>
1268                     </listitem>
1269                     <listitem>
1270                       <para>
1271                         R for the CD-Rom drive. Specify your
1272                         distributions default CD-ROM drives mountpoint
1273                         here.
1274                         </para>
1275                       <programlisting>
1276 Path=/auto/cdrom
1277                       </programlisting>
1278                     </listitem>
1279                     <listitem>
1280                       <para>
1281                         T for temporary storage. We do use
1282                         <filename>/tmp/</filename> (rationale: between
1283                         process temporary data belongs to
1284                         <filename>/tmp/</filename>, FHS 2.0)
1285                       </para>
1286                     </listitem>
1287                     <listitem>
1288                       <para>
1289                         W for the original Windows installation. This
1290                         drive points to the
1291                         <filename>windows\</filename> subdirectory of
1292                         the original windows installation. This avoids
1293                         problems with renamed
1294                         <filename>windows</filename> directories (as
1295                         for instance <filename>lose95</filename>,
1296                         <filename>win</filename> or
1297                         <filename>sys\win95</filename>). During
1298                         compile/package/install we leave this  to be
1299                         <filename>/</filename>, it has to be
1300                         configured after the package install.
1301                       </para>
1302                     </listitem>
1303                     <listitem>
1304                       <para>
1305                         Z for the UNIX Root directory. This avoids any
1306                         problems with "could not find drive for
1307                         current directory" users occasionaly complain
1308                         about in the newsgroup and the ircchannel. It
1309                         also makes the whole directory structure
1310                         browseable. The type of Z should be network,
1311                         so applications expect it to be readonly.
1312                       </para>
1313                       <programlisting>
1314 Path=/
1315                       </programlisting>
1316                     </listitem>
1317                   </itemizedlist>
1318                 </listitem>
1319                 <listitem>
1320                   <para>
1321                     [wine]:
1322                   </para>
1323                   <screen>
1324   Windows=c:\windows\           (the windows/ subdirectory in the users
1325                                  homedirectory)
1326   System=c:\windows\system\     (the windows/system subdirectory in the users
1327                                  homedirectory)
1328   Path=c:\windows;c:\windows\system;c:\windows\system32;w:\;w:\system;w:\system32;
1329   ; Using this trick we have in fact two windows installations in one, we
1330   ; get the stuff from the readonly installation and can write to our own.
1331   Temp=t:\                      (the TEMP directory)
1332                   </screen>
1333                 </listitem>
1334                 <listitem>
1335                   <para>[Tweak.Layout]</para>
1336                   <screen>
1337   WineLook=win95                (just the coolest look ;)
1338                   </screen>
1339                 </listitem>
1340                 <listitem>
1341                   <para>
1342                     Possibly modify the [spooler], [serialports] and
1343                     [parallelports] sections.
1344                   </para>
1345                   <note>
1346                     <title>FIXME</title>
1347                     <para>possibly more, including printer stuff.</para>
1348                   </note>
1349                 </listitem>
1350               </itemizedlist>
1351
1352               <para>Add this prepared configuration file to the package.</para>
1353             </listitem>
1354             <listitem>
1355               <para>Installing WINE for the system administrator</para>
1356               <para>
1357                 Install the package using the usual packager
1358                 <command>rpm -i wine.rpm</command>. You may edit
1359                 <filename>/etc/wine/wine.conf</filename>, [Drive W],
1360                 to point to a possible windows installation right
1361                 after the install. That's it.
1362               </para>
1363               <para>
1364                 Note that on Linux you should somehow try to add the
1365                 <option>unhide</option> mount option (see <command>man
1366                   mount</command>) to the CD-ROM entry in
1367                 <filename>/etc/fstab</filename> during package
1368                 install, as several stupid Windows programs mark some
1369                 setup (!) files as hidden (ISO9660) on CD-ROMs, which
1370                 will greatly confuse users as they won't find their
1371                 setup files on the CD-ROMs as they were used on
1372                 Windows systems when <option>unhide</option> is not
1373                 set ;-\ And of course the setup program will complain
1374                 that <filename>setup.ins</filename> or some other mess
1375                 is missing... If you choose to do so, then please make
1376                 this change verbose to the admin.
1377               </para>
1378             </listitem>
1379             <listitem>
1380               <para>Installing WINE for the user</para>
1381               <para>
1382                 The user will need to run a setup script before the
1383                 first invocation of WINE. This script should:
1384               </para>
1385
1386
1387               <itemizedlist>
1388                 <listitem>
1389                   <para>
1390                     Copy <filename>/etc/wine/wine.conf</filename> for
1391                     user modification.
1392                   </para>
1393                 </listitem>
1394                 <listitem>
1395                   <para>
1396                     Allow specification of the original windows
1397                     installation to use (which modifies the copied
1398                     <filename>wine.conf</filename> file).
1399                   </para>
1400                 </listitem>
1401                 <listitem>
1402                   <para>
1403                     Create the windows directory structure
1404                     (<filename>c:\windows</filename>,
1405                     <filename>c:\windows\system</filename>,
1406                     <filename>c:\windows\Start Menu\Programs</filename>,
1407                     <filename>c:\Program Files</filename>,
1408                     <filename>c:\Desktop</filename>, etc.)
1409                   </para>
1410                 </listitem>
1411                 <listitem>
1412                   <para>
1413                     Symlink all <filename>.dll</filename> and
1414                     <filename>.exe</filename> files from the original
1415                     windows installation to the
1416                     <filename>windows</filename> directory. Why? Some
1417                     programs reference "%windowsdir%/file.dll" or
1418                     "%systemdir%/file.dll" directly and fail if they
1419                     are not present.
1420                   </para>
1421                   <para>
1422                     This will give a huge number of symlinks, yes.
1423                     However, if an installer later overwrites on of
1424                     those files, it will overwrite the symlink (so
1425                     that the file now lies in the
1426                     <filename>windows/</filename> subdirectory).
1427                   </para>
1428                   <note>
1429                     <title>FIXME</title>
1430                     <para>Not sure this is needed for all files.</para>
1431                   </note>
1432                 </listitem>
1433                 <listitem>
1434                   <para>
1435                     On later invocation the script might want to
1436                     compare regular files in  the users windows
1437                     directories and in the global windows directories
1438                     and replace same files by symlinks (to avoid
1439                     diskspace problems).
1440                   </para>
1441                 </listitem>
1442               </itemizedlist>
1443
1444
1445             </listitem>
1446           </orderedlist>
1447
1448
1449       <sect2 id=sample><title>Sample <filename>wine.ini</filename> for OpenLinux 2.x:</title>
1450
1451 <programlisting>
1452
1453
1454 ;;
1455 ;; MS-DOS drives configuration
1456 ;;
1457 ;; Each section has the following format:
1458 ;; [Drive X]
1459 ;; Path=xxx       (Unix path for drive root)
1460 ;; Type=xxx       (supported types are 'floppy', 'hd', 'cdrom' and 'network')
1461 ;; Label=xxx      (drive label, at most 11 characters)
1462 ;; Serial=xxx     (serial number, 8 characters hexadecimal number)
1463 ;; Filesystem=xxx (supported types are 'msdos'/'dos'/'fat', 'win95'/'vfat', 'unix')
1464 ;;   This is the FS Wine is supposed to emulate on a certain
1465 ;;   directory structure.
1466 ;;   Recommended:
1467 ;;   - "win95" for ext2fs, VFAT and FAT32
1468 ;;   - "msdos" for FAT16 (ugly, upgrading to VFAT driver strongly recommended)
1469 ;;   DON'T use "unix" unless you intend to port programs using Winelib !
1470 ;; Device=/dev/xx (only if you want to allow raw device access)
1471 ;;
1472
1473 ;
1474 ;
1475 ; Floppy 'A' and 'B'
1476 ;
1477 ; OpenLinux uses an automounter under /auto/, so we use that too.
1478 ;
1479 [Drive A]
1480 Path=/auto/floppy/
1481 Type=floppy
1482 Label=Floppy
1483 Serial=87654321
1484 Device=/dev/fd0
1485 Filesystem=win95
1486
1487 ;
1488 ; Comment in ONLY if you have a second floppy or the automounter hangs
1489 ; for 5 minutes.
1490 ;
1491 ;[Drive B]
1492 ;Path=/auto/floppy2/
1493 ;Type=floppy
1494 ;Label=Floppy
1495 ;Serial=87654321
1496 ;Device=/dev/fd1
1497 ;Filesystem=win95
1498
1499
1500 ;
1501 ; Drive 'C' links to the users homedirectory.
1502 ;
1503 ; This must point to a writeable directory structure (not your readonly
1504 ; mounted DOS partitions!) since programs want to dump stuff into
1505 ; "Program Files/" "Programme/", "windows/", "windows/system/" etc.
1506 ;
1507 ; The basic structure is set up using the config script.
1508 ;
1509 [Drive C]
1510 Path=${HOME}
1511 Type=hd
1512 Label=MS-DOS
1513 Filesystem=win95
1514
1515 ;
1516 ; /tmp/ directory
1517 ;
1518 ; The temp drive (and directory) points to /tmp/. Windows programs fill it
1519 ; with junk, so it is approbiate.
1520 ;
1521 [Drive T]
1522 Path=/tmp
1523 Type=hd
1524 Label=Tmp Drive
1525 Filesystem=win95
1526
1527 ;
1528 ; 'U'ser homedirectory
1529 ;
1530 ; Just in case you want C:\ elsewhere.
1531 ;
1532 [Drive U]
1533 Path=${HOME}
1534 Type=hd
1535 Label=Home
1536 Filesystem=win95
1537
1538 ;
1539 ; CD-'R'OM drive (automounted)
1540 ;
1541 ; The default cdrom drive.
1542 ;
1543 ; If an application (or game) wants a specific CD-ROM you might have to
1544 ; temporary change the Label to the one of the CD itself.
1545 ;
1546 ; How to read them is described in /usr/doc/wine-cvs-xxxxx/cdrom-labels.
1547 ;
1548 [Drive R]
1549 Path=/auto/cdrom
1550 Type=cdrom
1551 Label=CD-Rom
1552 Filesystem=win95
1553
1554 ;
1555 ; The drive where the old windows installation resides (it points to the
1556 ; windows/ subdirectory).
1557 ;
1558 ; The Path is modified by the winesetup script.
1559 ;
1560 [Drive W]
1561 Path=/
1562 Type=network
1563 Label=Windows
1564 Filesystem=win95
1565 ;
1566 ; The UNIX Root directory, so all other programs and directories are reachable.
1567 ;
1568 ; type network is used to tell programs to not write here.
1569 ;
1570 [Drive Z]
1571 Path=/
1572 Type=network
1573 Label=ROOT
1574 Filesystem=win95
1575
1576 ;
1577 ; Standard Windows path entries. WINE will not work if they are incorrect.
1578 ;
1579 [wine]
1580 ;
1581 ; The windows/ directory. It must be writeable, for programs write into it.
1582 ;
1583 Windows=c:\windows
1584 ;
1585 ; The windows/system/ directory. It must be writeable, for especially setup
1586 ; programs install dlls in there.
1587 ;
1588 System=c:\windows\system
1589 ;
1590 ; The temp directory. Should be cleaned regulary, since install programs leave
1591 ; junk without end in there.
1592 ;
1593 Temp=t:\
1594 ;
1595 ; The dll search path. It should contain at least:
1596 ; - the windows and the windows/system directory of the user.
1597 ; - the global windows and windows/system directory (from a possible readonly
1598 ;   windows installation either on msdos filesystems or somewhere in the UNIX
1599 ;   directory tree)
1600 ; - any other windows style directories you want to add.
1601 ;
1602 Path=c:\windows;c:\windows\system;c:\windows\system32;t:\;w:\;w:\system;w:\system32
1603 ;
1604 ; Outdated and no longer used. (but needs to be present).
1605 ;
1606 SymbolTableFile=./wine.sym
1607
1608 # &lt;wineconf&gt;
1609
1610 ;
1611 ; Dll loadorder defaults. No need to modify.
1612 ;
1613 [DllDefaults]
1614 EXTRA_LD_LIBRARY_PATH=${HOME}/wine/cvs/lib
1615 DefaultLoadOrder = native, elfdll, so, builtin
1616
1617 ;
1618 ; What 32/16 dlls belong to each other (context wise). No need to modify.
1619 ;
1620 [DllPairs]
1621 kernel  = kernel32
1622 gdi     = gdi32
1623 user    = user32
1624 commdlg = comdlg32
1625 commctrl= comctl32
1626 ver     = version
1627 shell   = shell32
1628 lzexpand= lz32
1629 mmsystem= winmm
1630 msvideo = msvfw32
1631 winsock = wsock32
1632
1633 ;
1634 ; What type of dll to use in their respective loadorder.
1635 ;
1636 [DllOverrides]
1637 kernel32, gdi32, user32 = builtin
1638 kernel, gdi, user       = builtin
1639 toolhelp                = builtin
1640 comdlg32, commdlg       = elfdll, builtin, native
1641 version, ver            = elfdll, builtin, native
1642 shell32, shell          = builtin, native
1643 lz32, lzexpand          = builtin, native
1644 commctrl, comctl32      = builtin, native
1645 wsock32, winsock        = builtin
1646 advapi32, crtdll, ntdll = builtin, native
1647 mpr, winspool           = builtin, native
1648 ddraw, dinput, dsound   = builtin, native
1649 winmm, mmsystem         = builtin
1650 msvideo, msvfw32        = builtin, native
1651 mcicda.drv, mciseq.drv  = builtin, native
1652 mciwave.drv             = builtin, native
1653 mciavi.drv, mcianim.drv = native, builtin
1654 w32skrnl                = builtin
1655 wnaspi32, wow32         = builtin
1656 system, display, wprocs = builtin
1657 wineps                  = builtin
1658
1659 ;
1660 ; Options section. Does not need to be edited.
1661 ;
1662 [options]
1663 ; allocate how much system colors on startup. No need to modify.
1664 AllocSystemColors=100
1665
1666 ;;
1667 ; Font specification. You usually do not need to edit this section.
1668 ;
1669 ; Read documentation/fonts before adding aliases
1670 ;
1671 [fonts]
1672 ; The resolution defines what fonts to use (usually either 75 or 100 dpi fonts,
1673 ; or nearest match).
1674 Resolution = 96
1675 ; Default font
1676 Default = -adobe-times-
1677
1678 ;
1679 ; serial ports used by "COM1" "COM2" "COM3" "COM4". Useful for applications
1680 ; that try to access serial ports.
1681 ;
1682 [serialports]
1683 Com1=/dev/ttyS0
1684 Com2=/dev/ttyS1
1685 Com3=/dev/modem,38400
1686 Com4=/dev/modem
1687
1688 ;
1689 ; parallel port(s) used by "LPT1" etc. Useful for applications that try to
1690 ; access these ports.
1691 ;
1692 [parallelports]
1693 Lpt1=/dev/lp0
1694
1695 ;
1696 ; What spooling program to use on printing.
1697 ; Use "|program" or "filename", where the output will be dumped into.
1698 ;
1699 [spooler]
1700 LPT1:=|lpr
1701 LPT2:=|gs -sDEVICE=bj200 -sOutputFile=/tmp/fred -q -
1702 LPT3:=/dev/lp3
1703
1704 ;
1705 ; Allow port access to WINE started by the root user. Useful for some
1706 ; supported devices, but it can make the system unstable.
1707 ; Read /usr/doc/wine-cvs-xxxxx/ioport-trace-hints.
1708 ;
1709 [ports]
1710 ;read=0x779,0x379,0x280-0x2a0
1711 ;write=0x779,0x379,0x280-0x2a0
1712
1713 ; debugging, not need to be modified.
1714 [spy]
1715 Exclude=WM_SIZE;WM_TIMER;
1716
1717 ;
1718 ; What names for the registry datafiles, no need to modify.
1719 ;
1720 [Registry]
1721 ; Paths must be given in /dir/dir/file.reg format.
1722 ; Wine will not understand dos file names here...
1723 ;UserFileName=xxx               ; alternate registry file name (user.reg)
1724 ;LocalMachineFileName=xxx       ; (system.reg)
1725
1726 ;
1727 ; Layout/Look modifications. Here you can switch with a single line between
1728 ; windows 3.1 and windows 95 style.
1729 ; This does not change WINE behaviour or reported versions, just the look!
1730 ;
1731 [Tweak.Layout]
1732 ;; WineLook=xxx  (supported styles are 'Win31'(default), 'Win95', 'Win98')
1733 WineLook=Win95
1734
1735 ;
1736 ; What programs to start on WINE startup. (you should probably leave it empty)
1737 ;
1738 [programs]
1739 Default=
1740 Startup=
1741
1742 ; defunct section.
1743 [Console]
1744 ;XtermProg=nxterm
1745 ;InitialRows=25
1746 ;InitialColumns=80
1747 ;TerminalType=nxterm
1748
1749 # &lt;/wineconf&gt;
1750       </programlisting>
1751
1752       </sect2>
1753   </sect1>
1754
1755 </chapter>
1756
1757 <chapter id="pkg-todo"><Title>Work to be done</title>
1758
1759     <para>
1760     In preparing this document, it became clear that there were
1761     still a range of action items to be done in Wine
1762     that would improve this packaging process.
1763     For lack of a better place, I record them here.
1764     <emphasis>This list is almost certain to be obsolete;
1765     check bugzilla for a better list.</emphasis>
1766     </para>
1767
1768     <orderedlist>
1769         <listitem>
1770             <para>
1771             Remove duplication of code between winecfg and
1772             wineconf/wineinstall.
1773             </para>
1774             <para>
1775             Currently, winecfg duplicates all of the code contained
1776             in wineconf.
1777             </para>
1778             <para>
1779             Instead, wineconf should be improved to generate
1780             the new style config file, and then winecfg should
1781             rely on wineconf to generate the default
1782             configuration file.
1783             </para>
1784             <para>
1785             Similarly, there is functionality such as creating
1786             the default registry files that is now done by
1787             both winecfg and wineinstall.
1788             </para>
1789             <para>
1790             At this time, it seems like the right thing to do
1791             is to break up or parameterize wineinstall, so that
1792             it can be used for single function actions,
1793             and then have winecfg call those functions.
1794             </para>
1795         </listitem>
1796
1797         <listitem>
1798             <para>
1799             Enhance winecfg to support W: drive generation.
1800             </para>
1801             <para>
1802             The best practices convention now seems to be
1803             to generate a set of drives from M: through W:.
1804             At this point, winecfg does not generate
1805             a default wine config file that follows
1806             these conventions. It should.
1807             </para>
1808         </listitem>
1809
1810         <listitem>
1811             <para>
1812             Enhance Wine to allow more dynamic switching
1813             between the use of a real Windows partition
1814             and an empty one.
1815             </para>
1816         </listitem>
1817
1818         <listitem>
1819             <para>
1820             Write a winelauncher utility application.
1821             </para>
1822             <para>
1823             Currently, Wine really requires a user to launch it
1824             from a command line, so that the user can look for
1825             error messages and warnings.  However, eventually, we will
1826             want users to be able to launch Wine from a more
1827             friendly GUI launcher.  The launcher should have the
1828             ability to allow the end user to turn on debugging
1829             messages and capture those traces for bug reporting
1830             purposes.  Also, if we make it possible to
1831             switch between use of a Windows partition or not
1832             automatically, that option should be controlled here.
1833             </para>
1834         </listitem>
1835
1836         <listitem>
1837             <para>
1838             Get Marcus's winesetup facilities into CVS
1839             </para>
1840             <para>
1841             Along the lines of the changes to winecfg,
1842             and the consolidation of wineconf and wineinstall,
1843             we should extract the good stuff from Marcus's
1844             winesetup script, and get it into CVS.
1845             Again, perhaps we should have a set of scripts
1846             that perform discrete functions, or maybe
1847             one script with parameters.
1848             </para>
1849         </listitem>
1850
1851         <listitem>
1852             <para>
1853             Finish this document
1854             </para>
1855             <para>
1856             This document is pretty rough itself.  Many hard
1857             things aren't addressed, and lots of stuff was missed.
1858             </para>
1859         </listitem>
1860     </orderedlist>
1861 </chapter>
1862
1863
1864 <!-- Keep this comment at the end of the file
1865 Local variables:
1866 mode: sgml
1867 sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
1868 End:
1869 -->