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