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         <para> This list is NOT necessarily current ! </para>
 464
 465         <simplelist columns=5>
 466 <member>advapi32.dll.so</>
 467 <member>avicap32.dll.so</>
 468 <member>avifil32.dll.so</>
 469 <member>avifile.dll.so</>
 470 <member>comctl32.dll.so</>
 471 <member>comdlg32.dll.so</>
 472 <member>comm.dll.so</>
 473 <member>commdlg.dll.so</>
 474 <member>compobj.dll.so</>
 475 <member>crtdll.dll.so</>
 476 <member>crypt32.dll.so</>
 477 <member>dciman32.dll.so</>
 478 <member>ddeml.dll.so</>
 479 <member>ddraw.dll.so</>
 480 <member>devenum.dll.so</>
 481 <member>dinput.dll.so</>
 482 <member>dispdib.dll.so</>
 483 <member>display.dll.so</>
 484 <member>dplay.dll.so</>
 485 <member>dplayx.dll.so</>
 486 <member>dsound.dll.so</>
 487 <member>gdi.exe.so</>
 488 <member>gdi32.dll.so</>
 489 <member>glu32.dll.so</>
 490 <member>icmp.dll.so</>
 491 <member>imaadp32.acm.so</>
 492 <member>imagehlp.dll.so</>
 493 <member>imm.dll.so</>
 494 <member>imm32.dll.so</>
 495 <member>joystick.drv.so</>
 496 <member>kernel32.dll.so</>
 497 <member>keyboard.dll.so</>
 498 <member>krnl386.exe.so</>
 499 <member>libgdi32.dll.so</>
 500 <member>libkernel32.dll.so</>
 501 <member>libntdll.dll.so</>
 502 <member>libuser32.dll.so</>
 503 <member>libwine.so</>
 504 <member>libwine_tsx11.so</>
 505 <member>libwine_unicode.so</>
 506 <member>libwinspool.drv.so</>
 507 <member>lz32.dll.so</>
 508 <member>lzexpand.dll.so</>
 509 <member>mapi32.dll.so</>
 510 <member>mcianim.drv.so</>
 511 <member>mciavi.drv.so</>
 512 <member>mcicda.drv.so</>
 513 <member>mciseq.drv.so</>
 514 <member>mciwave.drv.so</>
 515 <member>midimap.drv.so</>
 516 <member>mmsystem.dll.so</>
 517 <member>mouse.dll.so</>
 518 <member>mpr.dll.so</>
 519 <member>msacm.dll.so</>
 520 <member>msacm.drv.so</>
 521 <member>msacm32.dll.so</>
 522 <member>msdmo.dll.so</>
 523 <member>msg711.drv.so</>
 524 <member>msimg32.dll.so</>
 525 <member>msnet32.dll.so</>
 526 <member>msrle32.dll.so</>
 527 <member>msvcrt.dll.so</>
 528 <member>msvcrt20.dll.so</>
 529 <member>msvfw32.dll.so</>
 530 <member>msvideo.dll.so</>
 531 <member>netapi32.dll.so</>
 532 <member>ntdll.dll.so</>
 533 <member>odbc32.dll.so</>
 534 <member>ole2.dll.so</>
 535 <member>ole2conv.dll.so</>
 536 <member>ole2disp.dll.so</>
 537 <member>ole2nls.dll.so</>
 538 <member>ole2prox.dll.so</>
 539 <member>ole2thk.dll.so</>
 540 <member>ole32.dll.so</>
 541 <member>oleaut32.dll.so</>
 542 <member>olecli.dll.so</>
 543 <member>olecli32.dll.so</>
 544 <member>oledlg.dll.so</>
 545 <member>olepro32.dll.so</>
 546 <member>olesvr.dll.so</>
 547 <member>olesvr32.dll.so</>
 548 <member>opengl32.dll.so</>
 549 <member>psapi.dll.so</>
 550 <member>qcap.dll.so</>
 551 <member>quartz.dll.so</>
 552 <member>rasapi16.dll.so</>
 553 <member>rasapi32.dll.so</>
 554 <member>riched32.dll.so</>
 555 <member>rpcrt4.dll.so</>
 556 <member>serialui.dll.so</>
 557 <member>setupapi.dll.so</>
 558 <member>setupx.dll.so</>
 559 <member>shdocvw.dll.so</>
 560 <member>shell.dll.so</>
 561 <member>shell32.dll.so</>
 562 <member>shfolder.dll.so</>
 563 <member>shlwapi.dll.so</>
 564 <member>sound.dll.so</>
 565 <member>sti.dll.so</>
 566 <member>storage.dll.so</>
 567 <member>stress.dll.so</>
 568 <member>system.dll.so</>
 569 <member>tapi32.dll.so</>
 570 <member>toolhelp.dll.so</>
 571 <member>ttydrv.dll.so</>
 572 <member>twain_32.dll.so</>
 573 <member>typelib.dll.so</>
 574 <member>url.dll.so</>
 575 <member>urlmon.dll.so</>
 576 <member>user.exe.so</>
 577 <member>user32.dll.so</>
 578 <member>ver.dll.so</>
 579 <member>version.dll.so</>
 580 <member>w32skrnl.dll.so</>
 581 <member>w32sys.dll.so</>
 582 <member>win32s16.dll.so</>
 583 <member>win87em.dll.so</>
 584 <member>winaspi.dll.so</>
 585 <member>windebug.dll.so</>
 586 <member>winearts.drv.so</>
 587 <member>winedos.dll.so</>
 588 <member>wineoss.drv.so</>
 589 <member>wineps.dll.so</>
 590 <member>wineps16.dll.so</>
 591 <member>wing.dll.so</>
 592 <member>wininet.dll.so</>
 593 <member>winmm.dll.so</>
 594 <member>winnls.dll.so</>
 595 <member>winnls32.dll.so</>
 596 <member>winsock.dll.so</>
 597 <member>winspool.drv.so</>
 598 <member>wintrust.dll.so</>
 599 <member>wnaspi32.dll.so</>
 600 <member>wow32.dll.so</>
 601 <member>wprocs.dll.so</>
 602 <member>ws2_32.dll.so</>
 603 <member>wsock32.dll.so</>
 604 <member>x11drv.dll.so</>
 605         </simplelist>
 606
 607         </listitem>
 608
 609
 610             <listitem id=manfiles>
 611             <para> Man Pages</para>
 612                 <simplelist columns=1>
 613 <member>wine.man</>
 614 <member>wine.conf.man</>
 615 <member>wmc.man</>
 616 <member>wrc.man</>
 617         </simplelist>
 618
 619         </listitem>
 620
 621
 622             <listitem id=includefiles>
 623             <para> Include Files</para>
 624             <para> This list is NOT necessarily current ! </para>
 625                 <simplelist columns=5>
 626
 627 <member>basetsd.h</>
 628 <member>cderr.h</>
 629 <member>cguid.h</>
 630 <member>commctrl.h</>
 631 <member>commdlg.h</>
 632 <member>compobj.h</>
 633 <member>d3d.h</>
 634 <member>d3dcaps.h</>
 635 <member>d3dtypes.h</>
 636 <member>d3dvec.inl</>
 637 <member>dde.h</>
 638 <member>ddeml.h</>
 639 <member>ddraw.h</>
 640 <member>digitalv.h</>
 641 <member>dinput.h</>
 642 <member>dispdib.h</>
 643 <member>dlgs.h</>
 644 <member>docobj.h</>
 645 <member>dplay.h</>
 646 <member>dplobby.h</>
 647 <member>dsound.h</>
 648 <member>guiddef.h</>
 649 <member>imagehlp.h</>
 650 <member>imm.h</>
 651 <member>initguid.h</>
 652 <member>instance.h</>
 653 <member>lmcons.h</>
 654 <member>lzexpand.h</>
 655 <member>mapidefs.h</>
 656 <member>mcx.h</>
 657 <member>mmreg.h</>
 658 <member>mmsystem.h</>
 659 <member>msacm.h</>
 660 <member>ntsecapi.h</>
 661 <member>oaidl.h</>
 662 <member>objbase.h</>
 663 <member>objidl.h</>
 664 <member>ocidl.h</>
 665 <member>ole2.h</>
 666 <member>ole2ver.h</>
 667 <member>oleauto.h</>
 668 <member>olectl.h</>
 669 <member>oledlg.h</>
 670 <member>oleidl.h</>
 671 <member>poppack.h</>
 672 <member>prsht.h</>
 673 <member>psapi.h</>
 674 <member>pshpack1.h</>
 675 <member>pshpack2.h</>
 676 <member>pshpack4.h</>
 677 <member>pshpack8.h</>
 678 <member>ras.h</>
 679 <member>regstr.h</>
 680 <member>richedit.h</>
 681 <member>rpc.h</>
 682 <member>servprov.h</>
 683 <member>shellapi.h</>
 684 <member>shlguid.h</>
 685 <member>shlobj.h</>
 686 <member>shlwapi.h</>
 687 <member>sql.h</>
 688 <member>sqlext.h</>
 689 <member>sqltypes.h</>
 690 <member>storage.h</>
 691 <member>tapi.h</>
 692 <member>tlhelp32.h</>
 693 <member>unknwn.h</>
 694 <member>urlmon.h</>
 695 <member>ver.h</>
 696 <member>vfw.h</>
 697 <member>winbase.h</>
 698 <member>wincon.h</>
 699 <member>wincrypt.h</>
 700 <member>windef.h</>
 701 <member>windows.h</>
 702 <member>windowsx.h</>
 703 <member>wine/exception.h</>
 704 <member>wine/icmpapi.h</>
 705 <member>wine/ipexport.h</>
 706 <member>wine/obj_base.h</>
 707 <member>wine/obj_cache.h</>
 708 <member>wine/obj_channel.h</>
 709 <member>wine/obj_clientserver.h</>
 710 <member>wine/obj_commdlgbrowser.h</>
 711 <member>wine/obj_connection.h</>
 712 <member>wine/obj_contextmenu.h</>
 713 <member>wine/obj_control.h</>
 714 <member>wine/obj_dataobject.h</>
 715 <member>wine/obj_dockingwindowframe.h</>
 716 <member>wine/obj_dragdrop.h</>
 717 <member>wine/obj_enumidlist.h</>
 718 <member>wine/obj_errorinfo.h</>
 719 <member>wine/obj_extracticon.h</>
 720 <member>wine/obj_inplace.h</>
 721 <member>wine/obj_marshal.h</>
 722 <member>wine/obj_misc.h</>
 723 <member>wine/obj_moniker.h</>
 724 <member>wine/obj_oleaut.h</>
 725 <member>wine/obj_olefont.h</>
 726 <member>wine/obj_oleobj.h</>
 727 <member>wine/obj_oleundo.h</>
 728 <member>wine/obj_oleview.h</>
 729 <member>wine/obj_picture.h</>
 730 <member>wine/obj_property.h</>
 731 <member>wine/obj_propertystorage.h</>
 732 <member>wine/obj_queryassociations.h</>
 733 <member>wine/obj_shellbrowser.h</>
 734 <member>wine/obj_shellextinit.h</>
 735 <member>wine/obj_shellfolder.h</>
 736 <member>wine/obj_shelllink.h</>
 737 <member>wine/obj_shellview.h</>
 738 <member>wine/obj_storage.h</>
 739 <member>wine/unicode.h</>
 740 <member>winerror.h</>
 741 <member>wingdi.h</>
 742 <member>wininet.h</>
 743 <member>winioctl.h</>
 744 <member>winnetwk.h</>
 745 <member>winnls.h</>
 746 <member>winnt.h</>
 747 <member>winreg.h</>
 748 <member>winresrc.h</>
 749 <member>winsock.h</>
 750 <member>winsock2.h</>
 751 <member>winspool.h</>
 752 <member>winsvc.h</>
 753 <member>winuser.h</>
 754 <member>winver.h</>
 755 <member>wnaspi32.h</>
 756 <member>wownt32.h</>
 757 <member>wtypes.h</>
 758 <member>zmouse.h</>
 759         </simplelist>
 760
 761         </listitem>
 762
 763         <listitem id=docfiles>
 764         <para>
 765         Documentation files.
 766         </para>
 767         <para>
 768         At the time of this writing, I do not have a
 769         definitive list of documentation files to
 770         be installed.  However, they do include
 771         the HTML files generated from the SGML in the Wine CVS tree.
 772         </para>
 773         </listitem>
 774
 775
 776         </orderedlist>
 777
 778         </sect1>
 779
 780
 781         <sect1 id="pkg-nonstatic"><title>Dynamic Wine Files</title>
 782
 783         <para>
 784         Wine also generates and depends on a number of dynamic
 785         files, including user configuration files and registry files.
 786         </para>
 787
 788         <para>
 789         At the time of this writing, there was not a clear
 790         consensus of where these files should be located, and how
 791         they should be handled.  This section attempts
 792         to explain the alternatives clearly.
 793         </para>
 794
 795         <orderedlist>
 796
 797             <listitem>
 798                 <variablelist><title>Configuration File</title>
 799                   <varlistentry id=winerc><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/config</filename></term>
 800                     <listitem>
 801                     <para>
 802                     This file is the user local Wine configuration file.
 803                     At the time of this writing, if this file exists,
 804                     then no other configuration file is loaded.
 805                     </para>
 806                     </listitem>
 807                   </varlistentry>
 808
 809                   <varlistentry><term>
 810                     <filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.conf</filename></term>
 811                     <listitem>
 812                     <para>
 813                     This is the global Wine configuration file.  It
 814                     is only used if the user running Wine has
 815                     no local configuration file.
 816                     </para>
 817                     <para>
 818                     Some packagers feel that this file should not
 819                     be supplied, and that only a wine.conf.default
 820                     should be given here.
 821                     </para>
 822                     <para>
 823                     Other packagers feel that this file should
 824                     be the predominant file used, and that
 825                     users should only shift to a local configuration
 826                     file if they need to.  An argument has been
 827                     made that the local configuration file
 828                     should inherit the global configuration file.
 829                     At this time, Wine does not do this;
 830                     please refer to the WineHQ discussion
 831                     archives for the debate concerning this.
 832                     </para>
 833                     <para>
 834                     This debate is addressed more completely
 835                     below, in <link linkend=pkg-strategy endterm=strategy.id></link>.
 836                     </para>
 837                     </listitem>
 838                   </varlistentry>
 839                 </variablelist>
 840
 841             </listitem>
 842
 843         <listitem>
 844
 845                 <para>Registry Files</para>
 846
 847                 <para>
 848                 In order to replicate the Windows registry system,
 849                 Wine stores registry entries in a series of files.
 850
 851                 For an excellent overview of this issue, read
 852                 this
 853                 <ulink url="http://www.winehq.com/News/2000-25.html#FTR">
 854                 Wine Weekly News feature.</ulink>
 855
 856                 </para>
 857
 858                 <para>
 859                 The bottom line is that, at Wine server startup,
 860                 Wine loads all registry entries into memory
 861                 to create an in memory image of the registry.
 862                 The order of files which Wine uses to load
 863                 registry entries is extremely important,
 864                 as it affects what registry entries are
 865                 actually present.  The order is roughly that
 866                 .dat files from a Windows partion are loaded,
 867                 then global registry settings from <link linkend=ETCDIR endterm=etcdir.id></link>,
 868                 and then finally local registry settings are
 869                 loaded from <link linkend=WINECONFDIR endterm=wineconfdir.id></link>
 870                 .  As each set are loaded,
 871                 they can override the prior entries.  Thus,
 872                 the local registry files take precedence.
 873                 </para>
 874
 875                 <para>
 876                 Then, at exit (or at periodic intervals),
 877                 Wine will write either all registry entries
 878                 (or, with the default setting) changed
 879                 registry entries to files in the
 880                 <link linkend=WINECONFDIR endterm=wineconfdir.id></link>.
 881                 </para>
 882
 883                 <variablelist>
 884                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/system.reg</filename></term>
 885                     <listitem>
 886                     <para>
 887                     This file contains the user's local copy of
 888                     the HKEY_LOCAL_MACHINE registry hive.  In general
 889                     use, it will contain only changes made to the
 890                     default registry values.
 891                     </para>
 892                     </listitem>
 893                   </varlistentry>
 894
 895                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/user.reg</filename></term>
 896                     <listitem>
 897                     <para>
 898                     This file contains the user's local copy of
 899                     the HKEY_CURRENT_USER registry hive.  In
 900                     general use, it will contain only changes made to the
 901                     default registry values.
 902                     </para>
 903                     </listitem>
 904                   </varlistentry>
 905
 906                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/userdef.reg</filename></term>
 907                     <listitem>
 908                     <para>
 909                     This file contains the user's local copy of
 910                     the HKEY_USERS\.Default registry hive.  In
 911                     general use, it will contain only changes made to the
 912                     default registry values.
 913                     </para>
 914                     </listitem>
 915                   </varlistentry>
 916
 917                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/wine.userreg</filename></term>
 918                     <listitem>
 919                     <para>
 920                     This file is being deprecated.  It is only read
 921                     if there is no user.reg or wine.userreg, and
 922                     it supplied the contents of HKEY_USERS.
 923                     </para>
 924                     </listitem>
 925                   </varlistentry>
 926
 927                   <varlistentry><term><filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.systemreg</filename></term>
 928                     <listitem>
 929                     <para>
 930                     This file contains the global values for
 931                     HKEY_LOCAL_MACHINE.  The values in this file
 932                     can be overridden by the user's local settings.
 933                     </para>
 934                     <note>
 935                     <para>
 936                     The location of this directory is hardcoded within
 937                     wine, generally to /etc.  This will hopefully be
 938                     fixed at some point in the future.
 939                     </para>
 940                     </note>
 941                     </listitem>
 942                   </varlistentry>
 943
 944
 945                   <varlistentry><term><filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.userreg</filename></term>
 946                     <listitem>
 947                     <para>
 948                     This file contains the global values for
 949                     HKEY_USERS.  The values in this file
 950                     can be overridden by the user's local settings.
 951                     This file is likely to be deprecated in
 952                     favor of a global wine.userdef.reg that will
 953                     only contain HKEY_USERS/.Default.
 954                     </para>
 955                     </listitem>
 956                   </varlistentry>
 957
 958                 </variablelist>
 959
 960
 961         </listitem>
 962
 963         <listitem>
 964                 <variablelist><title>Other files in <link linkend=WINECONFDIR endterm=wineconfdir.id></link></title>
 965                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/wineserver-[hostname]</filename></term>
 966                     <listitem>
 967                     <para>
 968                     This directory contains files used by Wine and the Wineserver
 969                     to communicate.  A packager may want to have a facility
 970                     for the user to erase files in this directory,
 971                     as a crash in the wineserver resulting in a bogus lock
 972                     file can render wine unusable.
 973                     </para>
 974                     </listitem>
 975                   </varlistentry>
 976
 977                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/cachedmetrics.[display]</filename></term>
 978                     <listitem>
 979                     <para>
 980                     This file contains font metrics for the given X display.
 981                     Generally, this cache is generated once at Wine start time.
 982                     </para>
 983                     </listitem>
 984                   </varlistentry>
 985
 986                 </variablelist>
 987         </listitem>
 988
 989
 990         </orderedlist>
 991
 992
 993         </sect1>
 994
 995         <sect1 id="pkg-winpartition"><title>Important Files from a Windows Partition</title>
 996         <para>
 997         Wine has the ability to use files from an installation of the
 998         actual Microsoft Windows operating system.  Generally these
 999         files are loaded on a VFAT partition that is mounted
1000         under Linux.
1001         </para>
1002         <para>
1003         This is probably the most important configuration detail.
1004         The use of Windows registry and DLL files dramatically
1005         alters the behaviour of Wine.  If nothing else,
1006         pacakager have to make this distinction clear
1007         to the end user, so that they can intelligently
1008         choose their configuration.
1009         </para>
1010
1011
1012         <orderedlist>
1013
1014             <listitem>
1015                 <variablelist><title>Registry Files</title>
1016                   <varlistentry><term><filename>[WINDOWSDIR]/system32/system.dat</filename></term>
1017                     <listitem>
1018                     <para>
1019                     </para>
1020                     </listitem>
1021                   </varlistentry>
1022
1023                   <varlistentry><term><filename>[WINDOWSDIR]/system32/user.dat</filename></term>
1024                     <listitem>
1025                     <para>
1026                     </para>
1027                     </listitem>
1028                   </varlistentry>
1029
1030                   <varlistentry><term><filename>[WINDOWSDIR]/win.ini</filename></term>
1031                     <listitem>
1032                     <para>
1033                     </para>
1034                     </listitem>
1035                   </varlistentry>
1036
1037                 </variablelist>
1038
1039             </listitem>
1040
1041             <listitem>
1042                 <para>
1043                 Windows Dynamic Link Libraries ([WINDOWSDIR]/system32/*.dll)
1044                 </para>
1045                 <para>
1046                 Wine has the ability to use the actual Windows DLL files
1047                 when running an application.  An end user can configure
1048                 Wine so that Wine uses some or all of these DLL files
1049                 when running a given application.
1050                 </para>
1051             </listitem>
1052
1053         </orderedlist>
1054
1055         </sect1>
1056
1057     </chapter>
1058
1059     <chapter id="pkg-strategy"><title id=strategy.id>Packaging Strategies</title>
1060
1061         <para>
1062         There has recently been a lot of discussion on the Wine
1063         development mailing list about the best way to
1064         build Wine packages.
1065         </para>
1066         <para>
1067         There was a lot of discussion, and several diverging
1068         points of view.  This section of the document
1069         attempts to present the areas of common agreement,
1070         and also to present the different approaches
1071         advocated on the mailing list.
1072         </para>
1073
1074         <sect1 id="pkg-whatfiles"><title>Distribution of Wine into packages</title>
1075         <para>
1076         The most basic question to ask is given the Wine CVS tree,
1077         what physical files are you, the packager, going to produce?
1078         Are you going to produce only a wine.rpm (as Marcus has done),
1079         or are you going to produce 6 Debian files
1080         (libwine, libwine-dev, wine, wine-doc, wine-utils and winesetuptk) as
1081         Ove has done?
1082         </para>
1083         <para>
1084         At this point, there is no consensus
1085         amongst the wine-devel community on this subject.
1086         </para>
1087         </sect1>
1088
1089         <sect1 id="pkg-wherefiles"><title>Where to install files</title>
1090         <para>
1091         This question is not really contested.  It will vary
1092         by distribution, and is really up to the packager.
1093         As a guideline, the current 'make install' process
1094         seems to behave such that
1095         if we pick a single <link linkend=PREFIX endterm=prefix.id></link>,
1096         then :
1097         </para>
1098         <orderedlist>
1099
1100             <listitem>
1101             <para>
1102             all <link linkend=binfiles>binary files</link> go into
1103             <link linkend=PREFIX endterm=prefix.id></link>/bin,
1104             </para>
1105             </listitem>
1106
1107             <listitem>
1108             <para>
1109             all <link linkend=libfiles>library files</link> go into
1110             <link linkend=PREFIX endterm=prefix.id></link>/lib,
1111             </para>
1112             </listitem>
1113
1114             <listitem>
1115             <para>
1116             all <link linkend=includefiles>include files</link> go into
1117             <link linkend=PREFIX endterm=prefix.id></link>/include,
1118             </para>
1119             </listitem>
1120
1121             <listitem>
1122             <para>
1123             all <link linkend=docfiles>documentation files</link> go into
1124             <link linkend=PREFIX endterm=prefix.id></link>/doc/wine,
1125             </para>
1126             </listitem>
1127
1128             <listitem>
1129             <para>
1130             and <link linkend=manfiles>man pages</link> go into
1131             <link linkend=PREFIX endterm=prefix.id></link>/man,
1132             </para>
1133             </listitem>
1134
1135         </orderedlist>
1136
1137         <para>
1138         Refer to the specific information on the Debian package
1139         and the OpenLinux package for specific details on how
1140         those packages are built.
1141         </para>
1142         <para>
1143         You might also want to use the wine wrapper script winelauncher
1144         that can be found in tools/ directory, as it has several important
1145         advantages over directly invoking the wine binary.
1146         See the <link linkend=binfiles>Executable Files</link> section
1147         for details.
1148         </para>
1149
1150         <sect2 id=opt><title>The question of /opt/wine</title>
1151         <para>
1152         The FHS 2.1 specification suggests that Wine as a package
1153         should be installed to /opt/wine.  None of the
1154         existing packages follow this guideline (today;
1155         check again tomorrow).
1156         </para>
1157         </sect2>
1158
1159         </sect1>
1160
1161         <sect1 id="pkg-whattomake"><title>What files to create</title>
1162         <para>
1163         After installing the static and shareable files, the next
1164         question the packager needs to ask is how much dynamic
1165         configuration will be done, and what configuration
1166         files should be created.
1167         </para>
1168         <para>
1169         There are several approaches to this:
1170         <orderedlist>
1171             <listitem>
1172                 <para>
1173                 Rely completely on user file space - install nothing
1174                 </para>
1175                 <para>
1176                 This approach relies upon the new winesetup utility and
1177                 the new ability of Wine to launch winesetup if no configuration file is found.
1178                 The basic concept is that no global configuration files
1179                 are created at install time.
1180                 Instead, Wine configuration files are created on the
1181                 fly by the winesetup program when Wine is invoked.
1182                 Further, winesetup creates default Windows directories
1183                 and paths that are stored completely in
1184                 the user's <link linkend=WINECONFDIR endterm=wineconfdir.id></link>.
1185                 </para>
1186                 <para>
1187                 This approach has the benefit of simplicity in that all
1188                 Wine files are either stored under /opt/wine or under
1189                 ~/.wine.  Further, there is only ever one Wine
1190                 configuration file.
1191                 </para>
1192                 <para>
1193                 This approach, however, adds another level of complexity.
1194                 It does not allow Wine to run Solitaire 'out of the box';
1195                 the user must run the configuration program first.  Further,
1196                 winesetup requires Tcl/Tk, a requirement not beloved by some.
1197                 Additionally, this approach closes the door on multi
1198                 user configurations and presumes a single user approach.
1199                 </para>
1200             </listitem>
1201
1202
1203             <listitem>
1204                 <para>
1205                 Build a reasonable set of defaults for the global wine.conf,
1206                 facilitate creation of a user's local Wine configuration.
1207                 </para>
1208                 <para>
1209                 This approach, best shown by Marcus, causes the
1210                 installation process to auto scan the system,
1211                 and generate a global wine.conf file with best
1212                 guess defaults.  The OpenLinux packages follow
1213                 this behaviour.
1214                 </para>
1215                 <para>
1216                 The keys to this approach are always putting
1217                 an existing Windows partition into the
1218                 path, and being able to run Solitaire
1219                 right out of the box.
1220                 Another good thing that Marcus does is he
1221                 detects a first time installation and
1222                 does some clever things to improve the
1223                 user's Wine experience.
1224                 </para>
1225                 <para>
1226                 A flaw with this approach, however, is it doesn't
1227                 give the user an obvious way to choose not to
1228                 use a Windows partition.
1229                 </para>
1230             </listitem>
1231
1232             <listitem>
1233                 <para>
1234                 Build a reasonable set of defaults for the global wine.conf,
1235                 and ask the user if possible
1236                 </para>
1237                 <para>
1238                 This approach, demonstrated by Ove, causes the
1239                 installation process to auto scan the system,
1240                 and generate a global wine.conf file with best
1241                 guess defaults.  Because Ove built a Debian
1242                 package, he was able to further query debconf and
1243                 get permission to ask the user some questions,
1244                 allowing the user to decide whether or not to
1245                 use a Windows partition.
1246                 </para>
1247             </listitem>
1248
1249
1250             </orderedlist>
1251         </para>
1252
1253         </sect1>
1254
1255
1256         <sect1 id="pkg-wineconf"><title>What to put into the wine config file</title>
1257         <para>
1258         The next hard question is what the Wine config should look like.
1259         The current best practices seems to involve using drives from M to Z.
1260         </para>
1261         <caution><para>This isn't done yet!  Fix it, Jer!</para></caution>
1262         </sect1>
1263
1264
1265     </chapter>
1266
1267
1268
1269
1270     <chapter id="pkg-implementation"> <title>Implementation</title>
1271
1272     <sect1 id="pkg-openlinux"><title>OpenLinux Sample</title>
1273
1274           <orderedlist inheritnum="inherit">
1275             <listitem>
1276               <para>Building the package</para>
1277               <para>
1278                 WINE is configured the usual way (depending on your
1279                 build environment). The "prefix" is chosen using your
1280                 application placement policy
1281                 (<filename>/usr/</filename>,
1282                 <filename>/usr/X11R6/</filename>,
1283                 <filename>/opt/wine/</filename> or similar).  The
1284                 configuration files (<filename>wine.conf</filename>,
1285                 <filename>wine.userreg</filename>,
1286                 <filename>wine.systemreg</filename>) are targeted for
1287                 <filename>/etc/wine/</filename> (rationale: FHS 2.0,
1288                 multiple readonly configuration files of a package).
1289               </para>
1290               <para>
1291                 Example (split this into <literal>%build</literal> and
1292                 <literal>%install</literal> section for
1293                 <command>rpm</command>):
1294               </para>
1295               <screen>
1296 CFLAGS=$RPM_OPT_FLAGS \
1297 ./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
1298 make
1299 BR=$RPM_BUILD_ROOT
1300 make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/
1301 install -d $BR/etc/wine/
1302 install -m 644 wine.ini $BR/etc/wine/wine.conf
1303
1304 # Put all our dlls in a seperate directory. (this works only if
1305 # you have a buildroot)
1306 install -d $BR/usr/X11R6/lib/wine
1307 mv $BR/usr/X11R6/lib/lib* $BR/usr/X11R6/lib/wine/
1308
1309 # the clipboard server is started on demand.
1310 install -m 755 dlls/x11drv/wineclipsrv $BR/usr/X11R6/bin/
1311
1312 # The WINE server is needed.
1313 install -m 755 server/wineserver $BR/usr/X11R6/bin/
1314               </screen>
1315               <para>
1316                 Here we unfortunately do need to create
1317                 <filename>wineuser.reg</filename> and
1318                 <filename>winesystem.reg</filename> from the WINE
1319                 distributed <filename>winedefault.reg</filename>. This
1320                 can be done using <command>./regapi</command> once for
1321                 one example user and then reusing his
1322                 <filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/user.reg</filename> and
1323                 <filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/system.reg</filename> files.
1324                 <note>
1325                   <title>FIXME</title>
1326                   <para>this needs to be done better</para>
1327                 </note>
1328               </para>
1329               <screen>
1330 install -m 644 wine.sytemreg $BR/etc/wine/
1331 install -m 644 wine.userreg $BR/etc/wine/
1332               </screen>
1333               <para>
1334                 There are now a lot of libraries generated by the
1335                 build process, so a seperate library directory should
1336                 be used.
1337               </para>
1338               <screen>
1339 install -d 755 $BR/usr/X11R6/lib/
1340 mv $BR/
1341               </screen>
1342               <para>
1343                 You will need to package the files:
1344               </para>
1345               <screen>
1346 $prefix/bin/wine, $prefix/bin/dosmod, $prefix/lib/wine/*
1347 $prefix/man/man1/wine.1, $prefix/include/wine/*,
1348 $prefix/bin/wineserver, $prefix/bin/wineclipsrv
1349
1350 %config /etc/wine/*
1351 %doc ... choose from the toplevel directory and documentation/
1352               </screen>
1353               <para>
1354                 The post-install script:
1355               </para>
1356               <screen>
1357 if ! grep -q /usr/X11R6/lib/wine /etc/ld.so.conf; then
1358     echo "/usr/X11R6/lib/wine" &gt;&gt; /etc/ld.so.conf
1359 fi
1360 /sbin/ldconfig
1361               </screen>
1362               <para>
1363                 The post-uninstall script:
1364               </para>
1365               <screen>
1366 if [ "$1" = 0 ]; then
1367     perl -ni -e 'print unless m:/usr/X11R6/lib/wine:;' /etc/ld.so.conf
1368 fi
1369 /sbin/ldconfig
1370               </screen>
1371             </listitem>
1372             <listitem>
1373               <para>Creating a good default configuration file</para>
1374               <para>
1375                 For the rationales of needing as less input from the
1376                 user as possible arises the need for a very good
1377                 configuration file. The one supplied with WINE is
1378                 currently lacking. We need:
1379               </para>
1380               <itemizedlist>
1381                 <listitem>
1382                   <para>
1383                     [Drive X]:
1384                   </para>
1385                   <itemizedlist>
1386                     <listitem>
1387                       <para>
1388                         A for the floppy. Specify your distribution's
1389                         default floppy mountpoint here.
1390                       </para>
1391                       <programlisting>
1392 Path=/auto/floppy
1393                       </programlisting>
1394                     </listitem>
1395                     <listitem>
1396                       <para>
1397                         C for the <filename>C:\</filename> directory.
1398                         Here we use the user's home directory, for most
1399                         applications do see <filename>C:\</filename>
1400                         as root-writeable directory of every windows
1401                         installation and this basically is it in the
1402                         UNIX-user context.
1403                         </para>
1404                       <programlisting>
1405 Path=${HOME}
1406                       </programlisting>
1407                     </listitem>
1408                     <listitem>
1409                       <para>
1410                         R for the CD-Rom drive. Specify your
1411                         distribution's default CD-ROM drives mountpoint
1412                         here.
1413                         </para>
1414                       <programlisting>
1415 Path=/auto/cdrom
1416                       </programlisting>
1417                     </listitem>
1418                     <listitem>
1419                       <para>
1420                         T for temporary storage. We do use
1421                         <filename>/tmp/</filename> (rationale: between
1422                         process temporary data belongs to
1423                         <filename>/tmp/</filename>, FHS 2.0)
1424                       </para>
1425                     </listitem>
1426                     <listitem>
1427                       <para>
1428                         W for the original Windows installation. This
1429                         drive points to the
1430                         <filename>windows\</filename> subdirectory of
1431                         the original windows installation. This avoids
1432                         problems with renamed
1433                         <filename>windows</filename> directories (as
1434                         for instance <filename>lose95</filename>,
1435                         <filename>win</filename> or
1436                         <filename>sys\win95</filename>). During
1437                         compile/package/install we leave this to be
1438                         <filename>/</filename>, it has to be
1439                         configured after the package install.
1440                       </para>
1441                     </listitem>
1442                     <listitem>
1443                       <para>
1444                         Z for the UNIX Root directory. This avoids any
1445                         problems with "could not find drive for
1446                         current directory" users occasionally complain
1447                         about in the newsgroup and the irc channel. It
1448                         also makes the whole directory structure
1449                         browseable. The type of Z should be network,
1450                         so applications expect it to be readonly.
1451                       </para>
1452                       <programlisting>
1453 Path=/
1454                       </programlisting>
1455                     </listitem>
1456                   </itemizedlist>
1457                 </listitem>
1458                 <listitem>
1459                   <para>
1460                     [wine]:
1461                   </para>
1462                   <screen>
1463   Windows=c:\windows\           (the windows/ subdirectory in the user's
1464                                  home directory)
1465   System=c:\windows\system\     (the windows/system subdirectory in the user's
1466                                  home directory)
1467   Path=c:\windows;c:\windows\system;c:\windows\system32;w:\;w:\system;w:\system32;
1468   ; Using this trick we have in fact two windows installations in one, we
1469   ; get the stuff from the readonly installation and can write to our own.
1470   Temp=t:\                      (the TEMP directory)
1471                   </screen>
1472                 </listitem>
1473                 <listitem>
1474                   <para>[Tweak.Layout]</para>
1475                   <screen>
1476   WineLook=win95                (just the coolest look ;)
1477                   </screen>
1478                 </listitem>
1479                 <listitem>
1480                   <para>
1481                     Possibly modify the [spooler], [serialports] and
1482                     [parallelports] sections.
1483                   </para>
1484                   <note>
1485                     <title>FIXME</title>
1486                     <para>possibly more, including printer stuff.</para>
1487                   </note>
1488                 </listitem>
1489               </itemizedlist>
1490
1491               <para>Add this prepared configuration file to the package.</para>
1492             </listitem>
1493             <listitem>
1494               <para>Installing WINE for the system administrator</para>
1495               <para>
1496                 Install the package using the usual packager
1497                 <command>rpm -i wine.rpm</command>. You may edit
1498                 <filename>/etc/wine/wine.conf</filename>, [Drive W],
1499                 to point to a possible windows installation right
1500                 after the install. That's it.
1501               </para>
1502               <para>
1503                 Note that on Linux you should somehow try to add the
1504                 <option>unhide</option> mount option (see <command>man
1505                   mount</command>) to the CD-ROM entry in
1506                 <filename>/etc/fstab</filename> during package
1507                 install, as several stupid Windows programs mark some
1508                 setup (!) files as hidden (ISO9660) on CD-ROMs, which
1509                 will greatly confuse users as they won't find their
1510                 setup files on the CD-ROMs as they were used on
1511                 Windows systems when <option>unhide</option> is not
1512                 set ;-\ And of course the setup program will complain
1513                 that <filename>setup.ins</filename> or some other mess
1514                 is missing... If you choose to do so, then please make
1515                 this change verbose to the admin.
1516                 Also make sure that the kernel you use includes the Joliet
1517                 CD-ROM support, for the very same reasons as given above
1518                 (no long filenames due to missing Joliet, files not found).
1519               </para>
1520             </listitem>
1521             <listitem>
1522               <para>Installing WINE for the user</para>
1523               <para>
1524                 The user will need to run a setup script before the
1525                 first invocation of WINE. This script should:
1526               </para>
1527
1528
1529               <itemizedlist>
1530                 <listitem>
1531                   <para>
1532                     Copy <filename>/etc/wine/wine.conf</filename> for
1533                     user modification.
1534                   </para>
1535                 </listitem>
1536                 <listitem>
1537                   <para>
1538                     Allow specification of the original windows
1539                     installation to use (which modifies the copied
1540                     <filename>wine.conf</filename> file).
1541                   </para>
1542                 </listitem>
1543                 <listitem>
1544                   <para>
1545                     Create the windows directory structure
1546                     (<filename>c:\windows</filename>,
1547                     <filename>c:\windows\system</filename>,
1548                     <filename>c:\windows\Start Menu\Programs</filename>,
1549                     <filename>c:\Program Files</filename>,
1550                     <filename>c:\Desktop</filename>, etc.)
1551                   </para>
1552                 </listitem>
1553                 <listitem>
1554                   <para>
1555                     Symlink all <filename>.dll</filename> and
1556                     <filename>.exe</filename> files from the original
1557                     windows installation to the
1558                     <filename>windows</filename> directory. Why? Some
1559                     programs reference "%windowsdir%/file.dll" or
1560                     "%systemdir%/file.dll" directly and fail if they
1561                     are not present.
1562                   </para>
1563                   <para>
1564                     This will give a huge number of symlinks, yes.
1565                     However, if an installer later overwrites one of
1566                     those files, it will overwrite the symlink (so
1567                     that the file now lies in the
1568                     <filename>windows/</filename> subdirectory).
1569                   </para>
1570                   <note>
1571                     <title>FIXME</title>
1572                     <para>Not sure this is needed for all files.</para>
1573                   </note>
1574                 </listitem>
1575                 <listitem>
1576                   <para>
1577                     On later invocation the script might want to
1578                     compare regular files in the user's windows
1579                     directories and in the global windows directories
1580                     and replace same files by symlinks (to avoid
1581                     diskspace problems).
1582                   </para>
1583                 </listitem>
1584               </itemizedlist>
1585
1586
1587             </listitem>
1588           </orderedlist>
1589
1590
1591       <sect2 id=sample><title>Sample <filename>wine.ini</filename> for OpenLinux 2.x (outdated, for review purposes only !):</title>
1592
1593 <programlisting>
1594
1595
1596 ;;
1597 ;; MS-DOS drives configuration
1598 ;;
1599 ;; Each section has the following format:
1600 ;; [Drive X]
1601 ;; Path=xxx       (Unix path for drive root)
1602 ;; Type=xxx       (supported types are 'floppy', 'hd', 'cdrom' and 'network')
1603 ;; Label=xxx      (drive label, at most 11 characters)
1604 ;; Serial=xxx     (serial number, 8 characters hexadecimal number)
1605 ;; Filesystem=xxx (supported types are 'msdos'/'dos'/'fat', 'win95'/'vfat', 'unix')
1606 ;;   This is the FS Wine is supposed to emulate on a certain
1607 ;;   directory structure.
1608 ;;   Recommended:
1609 ;;   - "win95" for ext2fs, VFAT and FAT32
1610 ;;   - "msdos" for FAT16 (ugly, upgrading to VFAT driver strongly recommended)
1611 ;;   DON'T use "unix" unless you intend to port programs using Winelib !
1612 ;; Device=/dev/xx (only if you want to allow raw device access)
1613 ;;
1614
1615 ;
1616 ;
1617 ; Floppy 'A' and 'B'
1618 ;
1619 ; OpenLinux uses an automounter under /auto/, so we use that too.
1620 ;
1621 [Drive A]
1622 Path=/auto/floppy/
1623 Type=floppy
1624 Label=Floppy
1625 Serial=87654321
1626 Device=/dev/fd0
1627 Filesystem=win95
1628
1629 ;
1630 ; Comment in ONLY if you have a second floppy or the automounter hangs
1631 ; for 5 minutes.
1632 ;
1633 ;[Drive B]
1634 ;Path=/auto/floppy2/
1635 ;Type=floppy
1636 ;Label=Floppy
1637 ;Serial=87654321
1638 ;Device=/dev/fd1
1639 ;Filesystem=win95
1640
1641
1642 ;
1643 ; Drive 'C' links to the user's homedirectory.
1644 ;
1645 ; This must point to a writeable directory structure (not your readonly
1646 ; mounted DOS partitions!) since programs want to dump stuff into
1647 ; "Program Files/" "Programme/", "windows/", "windows/system/" etc.
1648 ;
1649 ; The basic structure is set up using the config script.
1650 ;
1651 [Drive C]
1652 Path=${HOME}
1653 Type=hd
1654 Label=MS-DOS
1655 Filesystem=win95
1656
1657 ;
1658 ; /tmp/ directory
1659 ;
1660 ; The temp drive (and directory) points to /tmp/. Windows programs fill it
1661 ; with junk, so it is approbiate.
1662 ;
1663 [Drive T]
1664 Path=/tmp
1665 Type=hd
1666 Label=Tmp Drive
1667 Filesystem=win95
1668
1669 ;
1670 ; 'U'ser homedirectory
1671 ;
1672 ; Just in case you want C:\ elsewhere.
1673 ;
1674 [Drive U]
1675 Path=${HOME}
1676 Type=hd
1677 Label=Home
1678 Filesystem=win95
1679
1680 ;
1681 ; CD-'R'OM drive (automounted)
1682 ;
1683 ; The default cdrom drive.
1684 ;
1685 ; If an application (or game) wants a specific CD-ROM you might have to
1686 ; temporary change the Label to the one of the CD itself.
1687 ;
1688 ; How to read them is described in /usr/doc/wine-cvs-xxxxx/cdrom-labels.
1689 ;
1690 [Drive R]
1691 Path=/auto/cdrom
1692 Type=cdrom
1693 Label=CD-Rom
1694 Filesystem=win95
1695
1696 ;
1697 ; The drive where the old windows installation resides (it points to the
1698 ; windows/ subdirectory).
1699 ;
1700 ; The Path is modified by the winesetup script.
1701 ;
1702 [Drive W]
1703 Path=/
1704 Type=network
1705 Label=Windows
1706 Filesystem=win95
1707 ;
1708 ; The UNIX Root directory, so all other programs and directories are reachable.
1709 ;
1710 ; type network is used to tell programs to not write here.
1711 ;
1712 [Drive Z]
1713 Path=/
1714 Type=network
1715 Label=ROOT
1716 Filesystem=win95
1717
1718 ;
1719 ; Standard Windows path entries. WINE will not work if they are incorrect.
1720 ;
1721 [wine]
1722 ;
1723 ; The windows/ directory. It must be writeable, for programs write into it.
1724 ;
1725 Windows=c:\windows
1726 ;
1727 ; The windows/system/ directory. It must be writeable, for especially setup
1728 ; programs install dlls in there.
1729 ;
1730 System=c:\windows\system
1731 ;
1732 ; The temp directory. Should be cleaned regulary, since install programs leave
1733 ; junk without end in there.
1734 ;
1735 Temp=t:\
1736 ;
1737 ; The dll search path. It should contain at least:
1738 ; - the windows and the windows/system directory of the user.
1739 ; - the global windows and windows/system directory (from a possible readonly
1740 ;   windows installation either on msdos filesystems or somewhere in the UNIX
1741 ;   directory tree)
1742 ; - any other windows style directories you want to add.
1743 ;
1744 Path=c:\windows;c:\windows\system;c:\windows\system32;t:\;w:\;w:\system;w:\system32
1745 ;
1746 ; Outdated and no longer used. (but needs to be present).
1747 ;
1748 SymbolTableFile=./wine.sym
1749
1750 # &lt;wineconf&gt;
1751
1752 ;
1753 ; Dll loadorder defaults. No need to modify.
1754 ;
1755 [DllDefaults]
1756 EXTRA_LD_LIBRARY_PATH=${HOME}/wine/cvs/lib
1757 DefaultLoadOrder = native, elfdll, so, builtin
1758
1759 ;
1760 ; What 32/16 dlls belong to each other (context wise). No need to modify.
1761 ;
1762 [DllPairs]
1763 kernel  = kernel32
1764 gdi     = gdi32
1765 user    = user32
1766 commdlg = comdlg32
1767 commctrl= comctl32
1768 ver     = version
1769 shell   = shell32
1770 lzexpand= lz32
1771 mmsystem= winmm
1772 msvideo = msvfw32
1773 winsock = wsock32
1774
1775 ;
1776 ; What type of dll to use in their respective loadorder.
1777 ;
1778 [DllOverrides]
1779 kernel32, gdi32, user32 = builtin
1780 kernel, gdi, user       = builtin
1781 toolhelp                = builtin
1782 comdlg32, commdlg       = elfdll, builtin, native
1783 version, ver            = elfdll, builtin, native
1784 shell32, shell          = builtin, native
1785 lz32, lzexpand          = builtin, native
1786 commctrl, comctl32      = builtin, native
1787 wsock32, winsock        = builtin
1788 advapi32, crtdll, ntdll = builtin, native
1789 mpr, winspool           = builtin, native
1790 ddraw, dinput, dsound   = builtin, native
1791 winmm, mmsystem         = builtin
1792 msvideo, msvfw32        = builtin, native
1793 mcicda.drv, mciseq.drv  = builtin, native
1794 mciwave.drv             = builtin, native
1795 mciavi.drv, mcianim.drv = native, builtin
1796 w32skrnl                = builtin
1797 wnaspi32, wow32         = builtin
1798 system, display, wprocs = builtin
1799 wineps                  = builtin
1800
1801 ;
1802 ; Options section. Does not need to be edited.
1803 ;
1804 [options]
1805 ; allocate how much system colors on startup. No need to modify.
1806 AllocSystemColors=100
1807
1808 ;;
1809 ; Font specification. You usually do not need to edit this section.
1810 ;
1811 ; Read documentation/fonts before adding aliases
1812 ;
1813 [fonts]
1814 ; The resolution defines what fonts to use (usually either 75 or 100 dpi fonts,
1815 ; or nearest match).
1816 Resolution = 96
1817 ; Default font
1818 Default = -adobe-times-
1819
1820 ;
1821 ; serial ports used by "COM1" "COM2" "COM3" "COM4". Useful for applications
1822 ; that try to access serial ports.
1823 ;
1824 [serialports]
1825 Com1=/dev/ttyS0
1826 Com2=/dev/ttyS1
1827 Com3=/dev/modem,38400
1828 Com4=/dev/modem
1829
1830 ;
1831 ; parallel port(s) used by "LPT1" etc. Useful for applications that try to
1832 ; access these ports.
1833 ;
1834 [parallelports]
1835 Lpt1=/dev/lp0
1836
1837 ;
1838 ; What spooling program to use on printing.
1839 ; Use "|program" or "filename", where the output will be dumped into.
1840 ;
1841 [spooler]
1842 LPT1:=|lpr
1843 LPT2:=|gs -sDEVICE=bj200 -sOutputFile=/tmp/fred -q -
1844 LPT3:=/dev/lp3
1845
1846 ;
1847 ; Allow port access to WINE started by the root user. Useful for some
1848 ; supported devices, but it can make the system unstable.
1849 ; Read /usr/doc/wine-cvs-xxxxx/ioport-trace-hints.
1850 ;
1851 [ports]
1852 ;read=0x779,0x379,0x280-0x2a0
1853 ;write=0x779,0x379,0x280-0x2a0
1854
1855 ; debugging, not need to be modified.
1856 [spy]
1857 Exclude=WM_SIZE;WM_TIMER;
1858
1859 ;
1860 ; What names for the registry datafiles, no need to modify.
1861 ;
1862 [Registry]
1863 ; Paths must be given in /dir/dir/file.reg format.
1864 ; Wine will not understand dos file names here...
1865 ;UserFileName=xxx               ; alternate registry file name (user.reg)
1866 ;LocalMachineFileName=xxx       ; (system.reg)
1867
1868 ;
1869 ; Layout/Look modifications. Here you can switch with a single line between
1870 ; windows 3.1 and windows 95 style.
1871 ; This does not change WINE behaviour or reported versions, just the look!
1872 ;
1873 [Tweak.Layout]
1874 ;; WineLook=xxx  (supported styles are 'Win31'(default), 'Win95', 'Win98')
1875 WineLook=Win95
1876
1877 ;
1878 ; What programs to start on WINE startup. (you should probably leave it empty)
1879 ;
1880 [programs]
1881 Default=
1882 Startup=
1883
1884 ; defunct section.
1885 [Console]
1886 ;XtermProg=nxterm
1887 ;InitialRows=25
1888 ;InitialColumns=80
1889 ;TerminalType=nxterm
1890
1891 # &lt;/wineconf&gt;
1892       </programlisting>
1893
1894       </sect2>
1895   </sect1>
1896
1897 </chapter>
1898
1899 <chapter id="pkg-todo"><Title>Work to be done</title>
1900
1901     <para>
1902     In preparing this document, it became clear that there were
1903     still a range of action items to be done in Wine
1904     that would improve this packaging process.
1905     For lack of a better place, I record them here.
1906     <emphasis>This list is almost certain to be obsolete;
1907     check bugzilla for a better list.</emphasis>
1908     </para>
1909
1910     <orderedlist>
1911         <listitem>
1912             <para>
1913             Remove duplication of code between winesetup and
1914             wineconf/wineinstall.
1915             </para>
1916             <para>
1917             Currently, winesetup duplicates all of the code contained
1918             in wineconf.
1919             </para>
1920             <para>
1921             Instead, wineconf should be improved to generate
1922             the new style config file, and then winesetup should
1923             rely on wineconf to generate the default
1924             configuration file.
1925             </para>
1926             <para>
1927             Similarly, there is functionality such as creating
1928             the default registry files that is now done by
1929             both winesetup and wineinstall.
1930             </para>
1931             <para>
1932             At this time, it seems like the right thing to do
1933             is to break up or parameterize wineinstall, so that
1934             it can be used for single function actions,
1935             and then have winesetup call those functions.
1936             </para>
1937         </listitem>
1938
1939         <listitem>
1940             <para>
1941             Enhance winesetup to support W: drive generation.
1942             </para>
1943             <para>
1944             The best practices convention now seems to be
1945             to generate a set of drives from M: through W:.
1946             At this point, winesetup does not generate
1947             a default wine config file that follows
1948             these conventions. It should.
1949             </para>
1950         </listitem>
1951
1952         <listitem>
1953             <para>
1954             Enhance Wine to allow more dynamic switching
1955             between the use of a real Windows partition
1956             and an empty one.
1957             </para>
1958         </listitem>
1959
1960         <listitem>
1961             <para>
1962             Write a winelauncher utility application.
1963             </para>
1964             <para>
1965             Currently, Wine really requires a user to launch it
1966             from a command line, so that the user can look for
1967             error messages and warnings.  However, eventually, we will
1968             want users to be able to launch Wine from a more
1969             friendly GUI launcher.  The launcher should have the
1970             ability to allow the end user to turn on debugging
1971             messages and capture those traces for bug reporting
1972             purposes.  Also, if we make it possible to
1973             switch between use of a Windows partition or not
1974             automatically, that option should be controlled here.
1975             </para>
1976         </listitem>
1977
1978         <listitem>
1979             <para>
1980             Get Marcus's winesetup facilities into CVS
1981             </para>
1982             <para>
1983             Along the lines of the changes to winesetup,
1984             and the consolidation of wineconf and wineinstall,
1985             we should extract the good stuff from Marcus's
1986             winesetup script, and get it into CVS.
1987             Again, perhaps we should have a set of scripts
1988             that perform discrete functions, or maybe
1989             one script with parameters.
1990             </para>
1991         </listitem>
1992
1993         <listitem>
1994             <para>
1995             Finish this document
1996             </para>
1997             <para>
1998             This document is pretty rough itself.  Many hard
1999             things aren't addressed, and lots of stuff was missed.
2000             </para>
2001         </listitem>
2002     </orderedlist>
2003 </chapter>
2004
2005
2006 <!-- Keep this comment at the end of the file
2007 Local variables:
2008 mode: sgml
2009 sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
2010 End:
2011 -->