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