1 <!-- Wine Packaging guidelines. This is a rough outline only,
2 and much of this was up for open debate on wine-devel. -->
4 <chapter id="pkg-preface"> <title>Preface</title>
6 <sect1 id="pkg-authors"> <title>Authors</title>
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>
15 <sect1 id="pkg-date"> <title>Document Revision Date</title>
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).
30 This document was last revised on November 14, 2001.</para>
34 <sect1 id="pkg-terms"> <title>Terms used in this document</title>
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.
42 <listitem id=WINECONFDIR><para id=wineconfdir.id><EnVar>WINECONFDIR</EnVar></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
51 <listitem id=PREFIX><para id=prefix.id><EnVar>PREFIX</EnVar></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.
65 <listitem id=ETCDIR><para id=etcdir.id><EnVar>ETCDIR</EnVar></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.
74 <listitem id=WINDOWSDIR><para id=windowsdir.id><EnVar>WINDOWSDIR</EnVar></para>
76 <envar>WINDOWSDIR</envar> is an important concept
77 to Wine. This directory specifies what directory
78 corresponds to the root Windows directory
82 This directory is specified by the user, in
83 the user's <link linkend=winerc>configuration file</link>.
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.
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
108 <chapter id="pkg-introduction"> <title>Introduction</title>
111 This document attempts to establish guidelines
112 for people making binary packages of Wine.
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.
126 <sect1 id="pkg-goals"> <title>Goals</title>
128 An installation from a Wine package should:
134 Install quickly and simply.
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.
145 Work quickly and simply
148 The user should be able to launch Solitaire
149 within minutes of downloading the Wine package.
155 Comply with Filesystem Hierarchy Standard
158 A Wine installation should, as much as possible, comply
160 <ulink url="http://www.pathname.com/fhs/">FHS standard</ulink>.
169 None of the flexibility built into Wine should
170 be hidden from the end user.
176 Come as preconfigured as possible, so the user does
177 not need to change any configuration files.
182 <para>Use only as much diskspace as needed per user.</para>
187 Reduce support requirements.
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
204 <sect1 id="pkg-requirements"> <title>Requirements</title>
206 Successfully installing Wine requires:
211 <para>Much thought and work from the packager (1x)</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.
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>.
242 An initial set of registry entries.
245 The current Wine standard is to use the regapi tool
246 against the 'winedefault.reg' file to generate
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.
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.
277 <chapter id="pkg-components"><title>Wine Components</title>
280 This section lists all files that pertain to Wine.
283 <sect1 id="pkg-static"><title>Wine Static and Shareable Files</title>
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.
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.
302 <listitem id=binfiles>
303 <variablelist><title>Executable Files</title>
305 <varlistentry><term><filename>wine</filename></term>
308 The main Wine executable. This program will load
309 a Windows binary and run it, relying upon
310 the Wine shared object libraries.
315 <varlistentry><term><filename>wineserver</filename></term>
318 The Wine server is critical to Wine; it is the
319 process that coordinates all shared Windows
325 <varlistentry><term><filename>winebootup</filename></term>
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*,
339 <varlistentry><term><filename>wineclipsrv</filename></term>
342 The Wine Clipboard Server is a standalone XLib
343 application whose purpose is to manage the X selection
349 <varlistentry><term><filename>winedbg</filename></term>
352 Winedbg is the Wine built in debugger.
357 <varlistentry><term><filename>winelauncher</filename></term>
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.
377 <varlistentry><term><filename>winesetup</filename></term>
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.
387 <varlistentry><term><filename>wineshelllink</filename></term>
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
398 <varlistentry><term><filename>winebuild</filename></term>
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.
407 <varlistentry><term><filename>wmc</filename></term>
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.
416 <varlistentry><term><filename>wrc</filename></term>
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.
426 <varlistentry><term><filename>fnt2bdf</filename></term>
429 The fnt2bdf utility extracts fonts from .fnt or
430 .dll files and stores them in .bdf format files.
434 <varlistentry><term><filename>dosmod</filename></term>
442 <varlistentry><term><filename>uninstaller</filename></term>
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.
461 <listitem id=libfiles>
462 <para> Shared Object Library Files </para>
464 <simplelist columns=5>
466 <member>libadvapi32.so.1.0</>
467 <member>libavicap32.so.1.0</>
468 <member>libavifil32.so.1.0</>
469 <member>libcomctl32.so.1.0</>
470 <member>libcomdlg32.so.1.0</>
471 <member>libcrtdll.so.1.0</>
472 <member>libdciman32.so.1.0</>
473 <member>libddraw.so.1.0</>
474 <member>libdevenum.so.1.0</>
475 <member>libdinput.so.1.0</>
476 <member>libdplay.so.1.0</>
477 <member>libdplayx.so.1.0</>
478 <member>libdsound.so.1.0</>
479 <member>libgdi32.so.1.0</>
480 <member>libicmp.so.1.0</>
481 <member>libimagehlp.so.1.0</>
482 <member>libimm32.so.1.0</>
483 <member>libjoystick.drv.so.1.0</>
484 <member>libkernel32.so.1.0</>
485 <member>liblz32.so.1.0</>
486 <member>libmapi.so.1.0</>
487 <member>libmcianim.drv.so.1.0</>
488 <member>libmciavi.drv.so.1.0</>
489 <member>libmcicda.drv.so.1.0</>
490 <member>libmciseq.drv.so.1.0</>
491 <member>libmciwave.drv.so.1.0</>
492 <member>libmidimap.drv.so.1.0</>
493 <member>libmpr.so.1.0</>
494 <member>libmsacm.drv.so.1.0</>
495 <member>libmsacm32.so.1.0</>
496 <member>libmsdmo.so.1.0</>
497 <member>libmsimg32.so.1.0</>
498 <member>libmsnet32.so.1.0</>
499 <member>libmsrle32.so.1.0</>
500 <member>libmsvcrt.so.1.0</>
501 <member>libmsvfw32.so.1.0</>
502 <member>libnetapi32.so.1.0</>
503 <member>libntdll.so.1.0</>
504 <member>libodbc32.so.1.0</>
505 <member>libole32.so.1.0</>
506 <member>liboleaut32.so.1.0</>
507 <member>libolecli32.so.1.0</>
508 <member>liboledlg.so.1.0</>
509 <member>libolepro32.so.1.0</>
510 <member>libolesvr32.so.1.0</>
511 <member>libopengl32.so.1.0</>
512 <member>libpsapi.so.1.0</>
513 <member>libqcap.so.1.0</>
514 <member>libquartz.so.1.0</>
515 <member>librasapi32.so.1.0</>
516 <member>libriched32.so.1.0</>
517 <member>librpcrt4.so.1.0</>
518 <member>libserialui.so.1.0</>
519 <member>libsetupapi.so.1.0</>
520 <member>libshdocvw.so.1.0</>
521 <member>libshell32.so.1.0</>
522 <member>libshfolder.so.1.0</>
523 <member>libshlwapi.so.1.0</>
524 <member>libsti.so.1.0</>
525 <member>libtapi32.so.1.0</>
526 <member>libttydrv.so.1.0</>
527 <member>liburl.so.1.0</>
528 <member>liburlmon.so.1.0</>
529 <member>libuser32.so.1.0</>
530 <member>libversion.so.1.0</>
531 <member>libw32skrnl.so.1.0</>
532 <member>libwine.so.1.0</>
533 <member>libwine_unicode.so.1.0</>
534 <member>libwinedos.so.1.0</>
535 <member>libwineoss.drv.so.1.0</>
536 <member>libwineps.so.1.0</>
537 <member>libwininet.so.1.0</>
538 <member>libwinmm.so.1.0</>
539 <member>libwinnls32.so.1.0</>
540 <member>libwinspool.drv.so.1.0</>
541 <member>libwintrust.so.1.0</>
542 <member>libwnaspi32.so.1.0</>
543 <member>libwow32.so.1.0</>
544 <member>libws2_32.so.1.0</>
545 <member>libwsock32.so.1.0</>
546 <member>libx11drv.so.1.0</>
552 <listitem id=manfiles>
553 <para> Man Pages</para>
554 <simplelist columns=1>
556 <member>wine.conf.man</>
564 <listitem id=includefiles>
565 <para> Include Files</para>
566 <simplelist columns=5>
571 <member>commctrl.h</>
576 <member>d3dtypes.h</>
577 <member>d3dvec.inl</>
581 <member>digitalv.h</>
590 <member>imagehlp.h</>
592 <member>initguid.h</>
593 <member>instance.h</>
595 <member>lzexpand.h</>
596 <member>mapidefs.h</>
599 <member>mmsystem.h</>
601 <member>ntsecapi.h</>
615 <member>pshpack1.h</>
616 <member>pshpack2.h</>
617 <member>pshpack4.h</>
618 <member>pshpack8.h</>
621 <member>richedit.h</>
623 <member>servprov.h</>
624 <member>shellapi.h</>
630 <member>sqltypes.h</>
633 <member>tlhelp32.h</>
640 <member>wincrypt.h</>
643 <member>windowsx.h</>
644 <member>wine/exception.h</>
645 <member>wine/icmpapi.h</>
646 <member>wine/ipexport.h</>
647 <member>wine/obj_base.h</>
648 <member>wine/obj_cache.h</>
649 <member>wine/obj_channel.h</>
650 <member>wine/obj_clientserver.h</>
651 <member>wine/obj_commdlgbrowser.h</>
652 <member>wine/obj_connection.h</>
653 <member>wine/obj_contextmenu.h</>
654 <member>wine/obj_control.h</>
655 <member>wine/obj_dataobject.h</>
656 <member>wine/obj_dockingwindowframe.h</>
657 <member>wine/obj_dragdrop.h</>
658 <member>wine/obj_enumidlist.h</>
659 <member>wine/obj_errorinfo.h</>
660 <member>wine/obj_extracticon.h</>
661 <member>wine/obj_inplace.h</>
662 <member>wine/obj_marshal.h</>
663 <member>wine/obj_misc.h</>
664 <member>wine/obj_moniker.h</>
665 <member>wine/obj_oleaut.h</>
666 <member>wine/obj_olefont.h</>
667 <member>wine/obj_oleobj.h</>
668 <member>wine/obj_oleundo.h</>
669 <member>wine/obj_oleview.h</>
670 <member>wine/obj_picture.h</>
671 <member>wine/obj_property.h</>
672 <member>wine/obj_propertystorage.h</>
673 <member>wine/obj_queryassociations.h</>
674 <member>wine/obj_shellbrowser.h</>
675 <member>wine/obj_shellextinit.h</>
676 <member>wine/obj_shellfolder.h</>
677 <member>wine/obj_shelllink.h</>
678 <member>wine/obj_shellview.h</>
679 <member>wine/obj_storage.h</>
680 <member>wine/unicode.h</>
681 <member>winerror.h</>
684 <member>winioctl.h</>
685 <member>winnetwk.h</>
689 <member>winresrc.h</>
691 <member>winsock2.h</>
692 <member>winspool.h</>
696 <member>wnaspi32.h</>
704 <listitem id=docfiles>
709 At the time of this writing, I do not have a
710 definitive list of documentation files to
711 be installed. However, they do include
712 the HTML files generated from the SGML in the Wine CVS tree.
722 <sect1 id="pkg-nonstatic"><title>Dynamic Wine Files</title>
725 Wine also generates and depends on a number of dynamic
726 files, including user configuration files and registry files.
730 At the time of this writing, there was not a clear
731 consensus of where these files should be located, and how
732 they should be handled. This section attempts
733 to explain the alternatives clearly.
739 <variablelist><title>Configuration File</title>
740 <varlistentry id=winerc><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/config</filename></term>
743 This file is the user local Wine configuration file.
744 At the time of this writing, if this file exists,
745 then no other configuration file is loaded.
751 <filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.conf</filename></term>
754 This is the global Wine configuration file. It
755 is only used if the user running Wine has
756 no local configuration file.
759 Some packagers feel that this file should not
760 be supplied, and that only a wine.conf.default
761 should be given here.
764 Other packagers feel that this file should
765 be the predominant file used, and that
766 users should only shift to a local configuration
767 file if they need to. An argument has been
768 made that the local configuration file
769 should inherit the global configuration file.
770 At this time, Wine does not do this;
771 please refer to the WineHQ discussion
772 archives for the debate concerning this.
775 This debate is addressed more completely
776 below, in <link linkend=pkg-strategy endterm=strategy.id></link>.
786 <para>Registry Files</para>
789 In order to replicate the Windows registry system,
790 Wine stores registry entries in a series of files.
792 For an excellent overview of this issue, read
794 <ulink url="http://www.winehq.com/News/2000-25.html#FTR">
795 Wine Weekly News feature.</ulink>
800 The bottom line is that, at Wine server startup,
801 Wine loads all registry entries into memory
802 to create an in memory image of the registry.
803 The order of files which Wine uses to load
804 registry entries is extremely important,
805 as it affects what registry entries are
806 actually present. The order is roughly that
807 .dat files from a Windows partion are loaded,
808 then global registry settings from <link linkend=ETCDIR endterm=etcdir.id></link>,
809 and then finally local registry settings are
810 loaded from <link linkend=WINECONFDIR endterm=wineconfdir.id></link>
811 . As each set are loaded,
812 they can override the prior entries. Thus,
813 the local registry files take precedence.
817 Then, at exit (or at periodic intervals),
818 Wine will write either all registry entries
819 (or, with the default setting) changed
820 registry entries to files in the
821 <link linkend=WINECONFDIR endterm=wineconfdir.id></link>.
825 <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/system.reg</filename></term>
828 This file contains the user's local copy of
829 the HKEY_LOCAL_MACHINE registry hive. In general
830 use, it will contain only changes made to the
831 default registry values.
836 <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/user.reg</filename></term>
839 This file contains the user's local copy of
840 the HKEY_CURRENT_USER registry hive. In
841 general use, it will contain only changes made to the
842 default registry values.
847 <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/userdef.reg</filename></term>
850 This file contains the user's local copy of
851 the HKEY_USERS\.Default registry hive. In
852 general use, it will contain only changes made to the
853 default registry values.
858 <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/wine.userreg</filename></term>
861 This file is being deprecated. It is only read
862 if there is no user.reg or wine.userreg, and
863 it supplied the contents of HKEY_USERS.
868 <varlistentry><term><filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.systemreg</filename></term>
871 This file contains the global values for
872 HKEY_LOCAL_MACHINE. The values in this file
873 can be overridden by the user's local settings.
877 The location of this directory is hardcoded within
878 wine, generally to /etc. This will hopefully be
879 fixed at some point in the future.
886 <varlistentry><term><filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.userreg</filename></term>
889 This file contains the global values for
890 HKEY_USERS. The values in this file
891 can be overridden by the user's local settings.
892 This file is likely to be deprecated in
893 favor of a global wine.userdef.reg that will
894 only contain HKEY_USERS/.Default.
905 <variablelist><title>Other files in <link linkend=WINECONFDIR endterm=wineconfdir.id></link></title>
906 <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/wineserver-[hostname]</filename></term>
909 This directory contains files used by Wine and the Wineserver
910 to communicate. A packager may want to have a facility
911 for the user to erase files in this directory,
912 as a crash in the wineserver resulting in a bogus lock
913 file can render wine unusable.
918 <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/cachedmetrics.[display]</filename></term>
921 This file contains font metrics for the given X display.
922 Generally, this cache is generated once at Wine start time.
936 <sect1 id="pkg-winpartition"><title>Important Files from a Windows Partition</title>
938 Wine has the ability to use files from an installation of the
939 actual Microsoft Windows operating system. Generally these
940 files are loaded on a VFAT partition that is mounted
944 This is probably the most important configuration detail.
945 The use of Windows registry and DLL files dramatically
946 alters the behaviour of Wine. If nothing else,
947 pacakager have to make this distinction clear
948 to the end user, so that they can intelligently
949 choose their configuration.
956 <variablelist><title>Registry Files</title>
957 <varlistentry><term><filename>[WINDOWSDIR]/system32/system.dat</filename></term>
964 <varlistentry><term><filename>[WINDOWSDIR]/system32/user.dat</filename></term>
971 <varlistentry><term><filename>[WINDOWSDIR]/win.ini</filename></term>
984 Windows Dynamic Link Libraries ([WINDOWSDIR]/system32/*.dll)
987 Wine has the ability to use the actual Windows DLL files
988 when running an application. An end user can configure
989 Wine so that Wine uses some or all of these DLL files
990 when running a given application.
1000 <chapter id="pkg-strategy"><title id=strategy.id>Packaging Strategies</title>
1003 There has recently been a lot of discussion on the Wine
1004 development mailing list about the best way to
1005 build Wine packages.
1008 There was a lot of discussion, and several diverging
1009 points of view. This section of the document
1010 attempts to present the areas of common agreement,
1011 and also to present the different approaches
1012 advocated on the mailing list.
1015 <sect1 id="pkg-whatfiles"><title>Distribution of Wine into packages</title>
1017 The most basic question to ask is given the Wine CVS tree,
1018 what physical files are you, the packager, going to produce?
1019 Are you going to produce only a wine.rpm (as Marcus has done),
1020 or are you going to produce 6 Debian files
1021 (libwine, libwine-dev, wine, wine-doc, wine-utils and winesetuptk) as
1025 At this point, there is no consensus
1026 amongst the wine-devel community on this subject.
1030 <sect1 id="pkg-wherefiles"><title>Where to install files</title>
1032 This question is not really contested. It will vary
1033 by distribution, and is really up to the packager.
1034 As a guideline, the current 'make install' process
1035 seems to behave such that
1036 if we pick a single <link linkend=PREFIX endterm=prefix.id></link>,
1043 all <link linkend=binfiles>binary files</link> go into
1044 <link linkend=PREFIX endterm=prefix.id></link>/bin,
1050 all <link linkend=libfiles>library files</link> go into
1051 <link linkend=PREFIX endterm=prefix.id></link>/lib,
1057 all <link linkend=includefiles>include files</link> go into
1058 <link linkend=PREFIX endterm=prefix.id></link>/include,
1064 all <link linkend=docfiles>documentation files</link> go into
1065 <link linkend=PREFIX endterm=prefix.id></link>/doc/wine,
1071 and <link linkend=manfiles>man pages</link> go into
1072 <link linkend=PREFIX endterm=prefix.id></link>/man,
1079 Refer to the specific information on the Debian package
1080 and the OpenLinux package for specific details on how
1081 those packages are built.
1084 You might also want to use the wine wrapper script winelauncher
1085 that can be found in tools/ directory, as it has several important
1086 advantages over directly invoking the wine binary.
1087 See the <link linkend=binfiles>Executable Files</link> section
1090 <sect2 id=opt><title>The question of /opt/wine</title>
1092 The FHS 2.1 specification suggests that Wine as a package
1093 should be installed to /opt/wine. None of the
1094 existing packages follow this guideline (today;
1095 check again tomorrow).
1101 <sect1 id="pkg-whattomake"><title>What files to create</title>
1103 After installing the static and shareable files, the next
1104 question the packager needs to ask is how much dynamic
1105 configuration will be done, and what configuration
1106 files should be created.
1109 There are several approaches to this:
1113 Rely completely on user file space - install nothing
1116 This approach relies upon the new winesetup utility and
1117 the new ability of Wine to launch winesetup if no configuration file is found.
1118 The basic concept is that no global configuration files
1119 are created at install time.
1120 Instead, Wine configuration files are created on the
1121 fly by the winesetup program when Wine is invoked.
1122 Further, winesetup creates default Windows directories
1123 and paths that are stored completely in
1124 the user's <link linkend=WINECONFDIR endterm=wineconfdir.id></link>.
1127 This approach has the benefit of simplicity in that all
1128 Wine files are either stored under /opt/wine or under
1129 ~/.wine. Further, there is only ever one Wine
1133 This approach, however, adds another level of complexity.
1134 It does not allow Wine to run Solitaire 'out of the box';
1135 the user must run the configuration program first. Further,
1136 winesetup requires Tcl/Tk, a requirement not beloved by some.
1137 Additionally, this approach closes the door on multi
1138 user configurations and presumes a single user approach.
1145 Build a reasonable set of defaults for the global wine.conf,
1146 facilitate creation of a user's local Wine configuration.
1149 This approach, best shown by Marcus, causes the
1150 installation process to auto scan the system,
1151 and generate a global wine.conf file with best
1152 guess defaults. The OpenLinux packages follow
1156 The keys to this approach are always putting
1157 an existing Windows partition into the
1158 path, and being able to run Solitaire
1159 right out of the box.
1160 Another good thing that Marcus does is he
1161 detects a first time installation and
1162 does some clever things to improve the
1163 user's Wine experience.
1166 A flaw with this approach, however, is it doesn't
1167 give the user an obvious way to choose not to
1168 use a Windows partition.
1174 Build a reasonable set of defaults for the global wine.conf,
1175 and ask the user if possible
1178 This approach, demonstrated by Ove, causes the
1179 installation process to auto scan the system,
1180 and generate a global wine.conf file with best
1181 guess defaults. Because Ove built a Debian
1182 package, he was able to further query debconf and
1183 get permission to ask the user some questions,
1184 allowing the user to decide whether or not to
1185 use a Windows partition.
1196 <sect1 id="pkg-wineconf"><title>What to put into the wine config file</title>
1198 The next hard question is what the Wine config should look like.
1199 The current best practices seems to involve using drives from M to Z.
1201 <caution><para>This isn't done yet! Fix it, Jer!</para></caution>
1210 <chapter id="pkg-implementation"> <title>Implementation</title>
1212 <sect1 id="pkg-openlinux"><title>OpenLinux Sample</title>
1214 <orderedlist inheritnum="inherit">
1216 <para>Building the package</para>
1218 WINE is configured the usual way (depending on your
1219 build environment). The "prefix" is chosen using your
1220 application placement policy
1221 (<filename>/usr/</filename>,
1222 <filename>/usr/X11R6/</filename>,
1223 <filename>/opt/wine/</filename> or similar). The
1224 configuration files (<filename>wine.conf</filename>,
1225 <filename>wine.userreg</filename>,
1226 <filename>wine.systemreg</filename>) are targeted for
1227 <filename>/etc/wine/</filename> (rationale: FHS 2.0,
1228 multiple readonly configuration files of a package).
1231 Example (split this into <literal>%build</literal> and
1232 <literal>%install</literal> section for
1233 <command>rpm</command>):
1236 CFLAGS=$RPM_OPT_FLAGS \
1237 ./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
1240 make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/
1241 install -d $BR/etc/wine/
1242 install -m 644 wine.ini $BR/etc/wine/wine.conf
1244 # Put all our dlls in a seperate directory. (this works only if
1245 # you have a buildroot)
1246 install -d $BR/usr/X11R6/lib/wine
1247 mv $BR/usr/X11R6/lib/lib* $BR/usr/X11R6/lib/wine/
1249 # the clipboard server is started on demand.
1250 install -m 755 windows/x11drv/wineclipsrv $BR/usr/X11R6/bin/
1252 # The WINE server is needed.
1253 install -m 755 server/wineserver $BR/usr/X11R6/bin/
1256 Here we unfortunately do need to create
1257 <filename>wineuser.reg</filename> and
1258 <filename>winesystem.reg</filename> from the WINE
1259 distributed <filename>winedefault.reg</filename>. This
1260 can be done using <command>./regapi</command> once for
1261 one example user and then reusing his
1262 <filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/user.reg</filename> and
1263 <filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/system.reg</filename> files.
1265 <title>FIXME</title>
1266 <para>this needs to be done better</para>
1270 install -m 644 wine.sytemreg $BR/etc/wine/
1271 install -m 644 wine.userreg $BR/etc/wine/
1274 There are now a lot of libraries generated by the
1275 build process, so a seperate library directory should
1279 install -d 755 $BR/usr/X11R6/lib/
1283 You will need to package the files:
1286 $prefix/bin/wine, $prefix/bin/dosmod, $prefix/lib/wine/*
1287 $prefix/man/man1/wine.1, $prefix/include/wine/*,
1288 $prefix/bin/wineserver, $prefix/bin/wineclipsrv
1291 %doc ... choose from the toplevel directory and documentation/
1294 The post-install script:
1297 if ! grep -q /usr/X11R6/lib/wine /etc/ld.so.conf; then
1298 echo "/usr/X11R6/lib/wine" >> /etc/ld.so.conf
1303 The post-uninstall script:
1306 if [ "$1" = 0 ]; then
1307 perl -ni -e 'print unless m:/usr/X11R6/lib/wine:;' /etc/ld.so.conf
1313 <para>Creating a good default configuration file</para>
1315 For the rationales of needing as less input from the
1316 user as possible arises the need for a very good
1317 configuration file. The one supplied with WINE is
1318 currently lacking. We need:
1328 A for the floppy. Specify your distribution's
1329 default floppy mountpoint here.
1337 C for the <filename>C:\</filename> directory.
1338 Here we use the user's home directory, for most
1339 applications do see <filename>C:\</filename>
1340 as root-writeable directory of every windows
1341 installation and this basically is it in the
1350 R for the CD-Rom drive. Specify your
1351 distribution's default CD-ROM drives mountpoint
1360 T for temporary storage. We do use
1361 <filename>/tmp/</filename> (rationale: between
1362 process temporary data belongs to
1363 <filename>/tmp/</filename>, FHS 2.0)
1368 W for the original Windows installation. This
1370 <filename>windows\</filename> subdirectory of
1371 the original windows installation. This avoids
1372 problems with renamed
1373 <filename>windows</filename> directories (as
1374 for instance <filename>lose95</filename>,
1375 <filename>win</filename> or
1376 <filename>sys\win95</filename>). During
1377 compile/package/install we leave this to be
1378 <filename>/</filename>, it has to be
1379 configured after the package install.
1384 Z for the UNIX Root directory. This avoids any
1385 problems with "could not find drive for
1386 current directory" users occasionally complain
1387 about in the newsgroup and the irc channel. It
1388 also makes the whole directory structure
1389 browseable. The type of Z should be network,
1390 so applications expect it to be readonly.
1403 Windows=c:\windows\ (the windows/ subdirectory in the user's
1405 System=c:\windows\system\ (the windows/system subdirectory in the user's
1407 Path=c:\windows;c:\windows\system;c:\windows\system32;w:\;w:\system;w:\system32;
1408 ; Using this trick we have in fact two windows installations in one, we
1409 ; get the stuff from the readonly installation and can write to our own.
1410 Temp=t:\ (the TEMP directory)
1414 <para>[Tweak.Layout]</para>
1416 WineLook=win95 (just the coolest look ;)
1421 Possibly modify the [spooler], [serialports] and
1422 [parallelports] sections.
1425 <title>FIXME</title>
1426 <para>possibly more, including printer stuff.</para>
1431 <para>Add this prepared configuration file to the package.</para>
1434 <para>Installing WINE for the system administrator</para>
1436 Install the package using the usual packager
1437 <command>rpm -i wine.rpm</command>. You may edit
1438 <filename>/etc/wine/wine.conf</filename>, [Drive W],
1439 to point to a possible windows installation right
1440 after the install. That's it.
1443 Note that on Linux you should somehow try to add the
1444 <option>unhide</option> mount option (see <command>man
1445 mount</command>) to the CD-ROM entry in
1446 <filename>/etc/fstab</filename> during package
1447 install, as several stupid Windows programs mark some
1448 setup (!) files as hidden (ISO9660) on CD-ROMs, which
1449 will greatly confuse users as they won't find their
1450 setup files on the CD-ROMs as they were used on
1451 Windows systems when <option>unhide</option> is not
1452 set ;-\ And of course the setup program will complain
1453 that <filename>setup.ins</filename> or some other mess
1454 is missing... If you choose to do so, then please make
1455 this change verbose to the admin.
1456 Also make sure that the kernel you use includes the Joliet
1457 CD-ROM support, for the very same reasons as given above
1458 (no long filenames due to missing Joliet, files not found).
1462 <para>Installing WINE for the user</para>
1464 The user will need to run a setup script before the
1465 first invocation of WINE. This script should:
1472 Copy <filename>/etc/wine/wine.conf</filename> for
1478 Allow specification of the original windows
1479 installation to use (which modifies the copied
1480 <filename>wine.conf</filename> file).
1485 Create the windows directory structure
1486 (<filename>c:\windows</filename>,
1487 <filename>c:\windows\system</filename>,
1488 <filename>c:\windows\Start Menu\Programs</filename>,
1489 <filename>c:\Program Files</filename>,
1490 <filename>c:\Desktop</filename>, etc.)
1495 Symlink all <filename>.dll</filename> and
1496 <filename>.exe</filename> files from the original
1497 windows installation to the
1498 <filename>windows</filename> directory. Why? Some
1499 programs reference "%windowsdir%/file.dll" or
1500 "%systemdir%/file.dll" directly and fail if they
1504 This will give a huge number of symlinks, yes.
1505 However, if an installer later overwrites one of
1506 those files, it will overwrite the symlink (so
1507 that the file now lies in the
1508 <filename>windows/</filename> subdirectory).
1511 <title>FIXME</title>
1512 <para>Not sure this is needed for all files.</para>
1517 On later invocation the script might want to
1518 compare regular files in the user's windows
1519 directories and in the global windows directories
1520 and replace same files by symlinks (to avoid
1521 diskspace problems).
1531 <sect2 id=sample><title>Sample <filename>wine.ini</filename> for OpenLinux 2.x (outdated, for review purposes only !):</title>
1537 ;; MS-DOS drives configuration
1539 ;; Each section has the following format:
1541 ;; Path=xxx (Unix path for drive root)
1542 ;; Type=xxx (supported types are 'floppy', 'hd', 'cdrom' and 'network')
1543 ;; Label=xxx (drive label, at most 11 characters)
1544 ;; Serial=xxx (serial number, 8 characters hexadecimal number)
1545 ;; Filesystem=xxx (supported types are 'msdos'/'dos'/'fat', 'win95'/'vfat', 'unix')
1546 ;; This is the FS Wine is supposed to emulate on a certain
1547 ;; directory structure.
1549 ;; - "win95" for ext2fs, VFAT and FAT32
1550 ;; - "msdos" for FAT16 (ugly, upgrading to VFAT driver strongly recommended)
1551 ;; DON'T use "unix" unless you intend to port programs using Winelib !
1552 ;; Device=/dev/xx (only if you want to allow raw device access)
1557 ; Floppy 'A' and 'B'
1559 ; OpenLinux uses an automounter under /auto/, so we use that too.
1570 ; Comment in ONLY if you have a second floppy or the automounter hangs
1574 ;Path=/auto/floppy2/
1583 ; Drive 'C' links to the user's homedirectory.
1585 ; This must point to a writeable directory structure (not your readonly
1586 ; mounted DOS partitions!) since programs want to dump stuff into
1587 ; "Program Files/" "Programme/", "windows/", "windows/system/" etc.
1589 ; The basic structure is set up using the config script.
1600 ; The temp drive (and directory) points to /tmp/. Windows programs fill it
1601 ; with junk, so it is approbiate.
1610 ; 'U'ser homedirectory
1612 ; Just in case you want C:\ elsewhere.
1621 ; CD-'R'OM drive (automounted)
1623 ; The default cdrom drive.
1625 ; If an application (or game) wants a specific CD-ROM you might have to
1626 ; temporary change the Label to the one of the CD itself.
1628 ; How to read them is described in /usr/doc/wine-cvs-xxxxx/cdrom-labels.
1637 ; The drive where the old windows installation resides (it points to the
1638 ; windows/ subdirectory).
1640 ; The Path is modified by the winesetup script.
1648 ; The UNIX Root directory, so all other programs and directories are reachable.
1650 ; type network is used to tell programs to not write here.
1659 ; Standard Windows path entries. WINE will not work if they are incorrect.
1663 ; The windows/ directory. It must be writeable, for programs write into it.
1667 ; The windows/system/ directory. It must be writeable, for especially setup
1668 ; programs install dlls in there.
1670 System=c:\windows\system
1672 ; The temp directory. Should be cleaned regulary, since install programs leave
1673 ; junk without end in there.
1677 ; The dll search path. It should contain at least:
1678 ; - the windows and the windows/system directory of the user.
1679 ; - the global windows and windows/system directory (from a possible readonly
1680 ; windows installation either on msdos filesystems or somewhere in the UNIX
1682 ; - any other windows style directories you want to add.
1684 Path=c:\windows;c:\windows\system;c:\windows\system32;t:\;w:\;w:\system;w:\system32
1686 ; Outdated and no longer used. (but needs to be present).
1688 SymbolTableFile=./wine.sym
1693 ; Dll loadorder defaults. No need to modify.
1696 EXTRA_LD_LIBRARY_PATH=${HOME}/wine/cvs/lib
1697 DefaultLoadOrder = native, elfdll, so, builtin
1700 ; What 32/16 dlls belong to each other (context wise). No need to modify.
1716 ; What type of dll to use in their respective loadorder.
1719 kernel32, gdi32, user32 = builtin
1720 kernel, gdi, user = builtin
1722 comdlg32, commdlg = elfdll, builtin, native
1723 version, ver = elfdll, builtin, native
1724 shell32, shell = builtin, native
1725 lz32, lzexpand = builtin, native
1726 commctrl, comctl32 = builtin, native
1727 wsock32, winsock = builtin
1728 advapi32, crtdll, ntdll = builtin, native
1729 mpr, winspool = builtin, native
1730 ddraw, dinput, dsound = builtin, native
1731 winmm, mmsystem = builtin
1732 msvideo, msvfw32 = builtin, native
1733 mcicda.drv, mciseq.drv = builtin, native
1734 mciwave.drv = builtin, native
1735 mciavi.drv, mcianim.drv = native, builtin
1737 wnaspi32, wow32 = builtin
1738 system, display, wprocs = builtin
1742 ; Options section. Does not need to be edited.
1745 ; allocate how much system colors on startup. No need to modify.
1746 AllocSystemColors=100
1749 ; Font specification. You usually do not need to edit this section.
1751 ; Read documentation/fonts before adding aliases
1754 ; The resolution defines what fonts to use (usually either 75 or 100 dpi fonts,
1755 ; or nearest match).
1758 Default = -adobe-times-
1761 ; serial ports used by "COM1" "COM2" "COM3" "COM4". Useful for applications
1762 ; that try to access serial ports.
1767 Com3=/dev/modem,38400
1771 ; parallel port(s) used by "LPT1" etc. Useful for applications that try to
1772 ; access these ports.
1778 ; What spooling program to use on printing.
1779 ; Use "|program" or "filename", where the output will be dumped into.
1783 LPT2:=|gs -sDEVICE=bj200 -sOutputFile=/tmp/fred -q -
1787 ; Allow port access to WINE started by the root user. Useful for some
1788 ; supported devices, but it can make the system unstable.
1789 ; Read /usr/doc/wine-cvs-xxxxx/ioport-trace-hints.
1792 ;read=0x779,0x379,0x280-0x2a0
1793 ;write=0x779,0x379,0x280-0x2a0
1795 ; debugging, not need to be modified.
1797 Exclude=WM_SIZE;WM_TIMER;
1800 ; What names for the registry datafiles, no need to modify.
1803 ; Paths must be given in /dir/dir/file.reg format.
1804 ; Wine will not understand dos file names here...
1805 ;UserFileName=xxx ; alternate registry file name (user.reg)
1806 ;LocalMachineFileName=xxx ; (system.reg)
1809 ; Layout/Look modifications. Here you can switch with a single line between
1810 ; windows 3.1 and windows 95 style.
1811 ; This does not change WINE behaviour or reported versions, just the look!
1814 ;; WineLook=xxx (supported styles are 'Win31'(default), 'Win95', 'Win98')
1818 ; What programs to start on WINE startup. (you should probably leave it empty)
1829 ;TerminalType=nxterm
1839 <chapter id="pkg-todo"><Title>Work to be done</title>
1842 In preparing this document, it became clear that there were
1843 still a range of action items to be done in Wine
1844 that would improve this packaging process.
1845 For lack of a better place, I record them here.
1846 <emphasis>This list is almost certain to be obsolete;
1847 check bugzilla for a better list.</emphasis>
1853 Remove duplication of code between winesetup and
1854 wineconf/wineinstall.
1857 Currently, winesetup duplicates all of the code contained
1861 Instead, wineconf should be improved to generate
1862 the new style config file, and then winesetup should
1863 rely on wineconf to generate the default
1867 Similarly, there is functionality such as creating
1868 the default registry files that is now done by
1869 both winesetup and wineinstall.
1872 At this time, it seems like the right thing to do
1873 is to break up or parameterize wineinstall, so that
1874 it can be used for single function actions,
1875 and then have winesetup call those functions.
1881 Enhance winesetup to support W: drive generation.
1884 The best practices convention now seems to be
1885 to generate a set of drives from M: through W:.
1886 At this point, winesetup does not generate
1887 a default wine config file that follows
1888 these conventions. It should.
1894 Enhance Wine to allow more dynamic switching
1895 between the use of a real Windows partition
1902 Write a winelauncher utility application.
1905 Currently, Wine really requires a user to launch it
1906 from a command line, so that the user can look for
1907 error messages and warnings. However, eventually, we will
1908 want users to be able to launch Wine from a more
1909 friendly GUI launcher. The launcher should have the
1910 ability to allow the end user to turn on debugging
1911 messages and capture those traces for bug reporting
1912 purposes. Also, if we make it possible to
1913 switch between use of a Windows partition or not
1914 automatically, that option should be controlled here.
1920 Get Marcus's winesetup facilities into CVS
1923 Along the lines of the changes to winesetup,
1924 and the consolidation of wineconf and wineinstall,
1925 we should extract the good stuff from Marcus's
1926 winesetup script, and get it into CVS.
1927 Again, perhaps we should have a set of scripts
1928 that perform discrete functions, or maybe
1929 one script with parameters.
1935 Finish this document
1938 This document is pretty rough itself. Many hard
1939 things aren't addressed, and lots of stuff was missed.
1946 <!-- Keep this comment at the end of the file
1949 sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")