Documentation update.
diff --git a/documentation/packaging.sgml b/documentation/packaging.sgml
index 1f8fb56..6e5b3db 100644
--- a/documentation/packaging.sgml
+++ b/documentation/packaging.sgml
@@ -1,78 +1,222 @@
- <chapter id="packaging">
- <title>Packaging Wine</title>
+<!-- Wine Packaging guidelines. This is a rough outline only,
+ and much of this was up for open debate on wine-devel. -->
+
+ <chapter id="pkg-preface"> <title>Preface</title>
- <sect1 id="distributing">
- <title>A Small WINE Distribution Guide</title>
+ <sect1 id="Authors"> <title>Authors</title>
- <para>
- written by Marcus Meissner <Marcus.Meissner@caldera.de>
- </para>
- <para>
- (Extracted from <filename>wine/documentation/distributors</filename>)
- </para>
-
- <para>
- While packaging WINE for one of the Linux distributions I came
- across several points which have not been clarified yet.
- Particularly a how-to for WINE packaging distributors is
- missing. This document tries to give a brief overview over the
- rationales I thought up and how I tried to implement it.
- (While the examples use <command>rpm</command> most of this
- stuff can be applied to other packagers too.)
- </para>
-
- <note>
<para>
- YOU SHOULD RECHECK THIS FILE EVERY TWO MONTHS OR SO
- (<command>diff -uN</command> comes to my mind here...).
- We'll be adding stuff constantly here in order to improve
- the Wine environment !
+ Written by &name-marcus-meissner; <email>&email-marcus-meissner;</email>
+ Updated by &name-jeremy-white; <email>&email-jeremy-white;</email>
</para>
- </note>
+ </sect1>
- <orderedlist>
- <listitem>
+ <sect1 id="Date"> <title>Document Revision Date</title>
- <para>Rationales</para>
- <para>
- A WINE install should:
- </para>
+
+ <para>
+ The information contained in this document is extremely
+ time sensitive. <emphasis>It is vital that a packager
+ stay current with changes in Wine. </>
+ </para>
+ <para>
+ This document was last revised on November 2, 2000.</para>
+
+ </sect1>
+
+ <sect1 id="Terms"> <title>Terms used in this document</title>
+
+ <para>There are several terms and paths used in this
+ document as place holders for configurable values.
+ Those terms are described here.
+ </para>
+
+ <orderedlist>
+ <listitem id=WINECONFDIR><para id=wineconfdir.id><EnVar>WINECONFDIR</EnVar></para>
+ <para>
+ <envar>WINECONFDIR</envar> is the users Wine configuration directory.
+ This is almost always ~/.wine, but can be overridden
+ by the user by setting the <EnVar>WINECONFDIR</EnVar> environment
+ variable.
+ </para>
+ </listitem>
+
+ <listitem id=PREFIX><para id=prefix.id><EnVar>PREFIX</EnVar></para>
+ <para>
+ <envar>PREFIX</envar> is the prefix used when selecting
+ an installation target. The current default is /usr.
+ This results in binary installation into /usr/bin,
+ library installation into /usr/wine/lib, and so forth.
+ This value can be overridden by the packager.
+ In fact, <ulink url="http://www.pathname.com/fhs/">FHS 2.1</ulink>
+ specifications suggest that a better
+ prefix is /opt/wine. Ideally, a packager would also
+ allow the installer to override this value.
+ </para>
+ </listitem>
+
+ <listitem id=ETCDIR><para id=etcdir.id><EnVar>ETCDIR</EnVar></para>
+ <para>
+ <envar>ETCDIR</envar> is the prefix that Wine uses
+ to find the global configuration directory.
+ This can be changed by the configure option sysconfdir.
+ The current default is /etc.
+ </para>
+ </listitem>
+
+ <listitem id=WINDOWSDIR><para id=windowsdir.id><EnVar>WINDOWSDIR</EnVar></para>
+ <para>
+ <envar>WINDOWSDIR</envar> is an important concept
+ to Wine. This directory specifies what directory
+ corresponds to the root Windows directory
+ (e.g. C:\WINDOWS).
+ </para>
+ <para>
+ This directory is specified by the user, in
+ the users <link linkend=winerc>configuration file</link>.
+ </para>
+ <para>
+ Generally speaking, this directory is either set
+ to point at an empty directory, or it is set
+ to point at a Windows partition that has been
+ mounted through the vfat driver.
+ </para>
+ <para>
+ <emphasis>It is extremely important that the packager
+ understand the importance of <envar>WINDOWSDIR</envar>
+ and convey this information and choice to the end
+ user</emphasis>.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+
+ </sect1>
+
+ </chapter>
+
+
+
+ <chapter id="pkg-introduction"> <title>Introduction</title>
+
+ <para>
+ This document attempts to establish guidelines
+ for people making binary packages of Wine.
+ </para>
+
+ <para>
+ It expresses the basic principles that the
+ Wine developers have agreed should be
+ used when building Wine.
+ It also attempts to highlight the areas
+ where there are different approaches
+ to packaging Wine, so that the packager
+ can understand the different alternatives
+ that have been considered and their rationales.
+ </para>
+
+ <sect1 id="Goals"> <title>Goals</title>
+ <para>
+ An installation from a Wine pacakage should:
+ </para>
<itemizedlist>
+
<listitem>
- <para>Not have a world writeable directory (-tree).</para>
+ <para>
+ Install quickly and simply.
+ </para>
+ <para>
+ The initial installation should require no user
+ input. An rpm -i wine.rpm or apt get wine
+ should suffice for initial installation.
+ </para>
</listitem>
+
+ <listitem>
+ <para>
+ Work quickly and simply
+ </para>
+ <para>
+ The user should be able to launch Solitaire
+ within minutes of downloading the Wine package.
+ </para>
+ </listitem>
+
<listitem>
<para>
- Require only as much user input as needed. It would be
- very good if it would not require any at all. Just let
- the system administrator do <command>rpm -i
- wine.rpm</command> and let any user be able to run
- <command>wine sol.exe</command> instantly.
+ Comply with Filesystem Hierarchy Standard
</para>
- </listitem>
- <listitem>
<para>
- Give the user as much flexibility as possible to
- install his own applications, do his own configuring
- etc.
+ A Wine installation should, as much as possible, comply
+ with the
+ <ulink url="http://www.pathname.com/fhs/">FHS standard</ulink>.
</para>
</listitem>
+
+ <listitem>
+ <para>
+ Preserve flexibility
+ </para>
+ <para>
+ None of the flexibility built into Wine should
+ be hidden from the end user.
+ </para>
+ </listitem>
+
<listitem>
<para>
Come as preconfigured as possible, so the user does
not need to change any configuration files.
</para>
</listitem>
+
<listitem>
<para>Use only as much diskspace as needed per user.</para>
</listitem>
+
+ <listitem>
+ <para>
+ Reduce support requirements.
+ </para>
+ <para>
+ A packaged version of Wine should be sufficiently easy
+ to use and have quick and easy access to FAQs and
+ documentation such that requests to the
+ newsgroup and development group go down.
+ Further, it should be easy for users to capture
+ good bug reports.
+ </para>
+ </listitem>
+
</itemizedlist>
- <para>
- A WINE install needs:
- </para>
+
+ </sect1>
+
+ <sect1 id="Requirements"> <title>Requirements</title>
+ <para>
+ Successfully installing Wine requires:
+ </para>
<itemizedlist>
+ <listitem>
+ <para>Much thought and work from the packager (1x)</para>
+ </listitem>
+ <listitem>
+ <para>
+ A configuration file
+ </para>
+ <para>
+ Wine will not run with out a configuration file. Further,
+ no default is currently provided by Wine. Some packagers may attempt
+ to provide (or dynamically generate) a default configuration
+ file. Some packagers may wish to
+ rely on winecfg to generate the configuration file.
+ </para>
+ </listitem>
+
+
<listitem>
<para>
A writeable <filename>C:\</filename> directory
@@ -85,13 +229,27 @@
Files\</filename>.
</para>
</listitem>
+
+
<listitem>
<para>
- The <filename>.exe</filename> and
- <filename>.dll</filename> from a global read-only
- Windows installation to be found by applications.
+ An initial set of registry entries.
</para>
+ <para>
+ The current Wine standard is to use the regapi tool
+ against the 'winedefault.reg' file to generate
+ a default registry.
+ </para>
+ <para>
+ There are several other choices that could be made;
+ registries can be imported from a Windows partition.
+ At this time, Wine does not completely support
+ a complex multi user installation, ala Windows NT,
+ but it could fairly readily.
+ </para>
</listitem>
+
+
<listitem>
<para>
Some special <filename>.dll</filename> and
@@ -100,14 +258,879 @@
applications directly check for their presence.
</para>
</listitem>
- <listitem>
- <para>Some special program environment.</para>
- </listitem>
</itemizedlist>
+
+ </sect1>
+
+
+ </chapter>
+
+
+
+
+ <chapter id="Components"><title>Wine Components</title>
+
+ <para>
+ This section lists all files that pertain to Wine.
+ </para>
+
+ <sect1 id=static><title>Wine Static and Shareable Files</title>
+
+ <para>
+ At the time of this writing, the following components
+ are installed through a standard 'make install'
+ of Wine.
+
+ <caution>
+ <para>
+ It is vital that a packager check for
+ changes in Wine. This list will likely be out
+ of date by the time this document is committed to CVS.
+ </para>
+ </caution>
+
+ </para>
+
+ <orderedlist>
+
+ <listitem id=binfiles>
+ <variablelist><title>Executable Files</title>
+
+ <varlistentry><term><filename>wine</filename></term>
+ <listitem>
+ <para>
+ The main Wine executable. This program will load
+ a Windows binary and run it, relying upon
+ the Wine shared object libraries.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename>wineserver</filename></term>
+ <listitem>
+ <para>
+ The Wine server is critical to Wine; it is the
+ process that coordinates all shared Windows
+ resources.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename>wineclipsrv</filename></term>
+ <listitem>
+ <para>
+ The Wine Clipboard Server is a standalone XLib
+ application whose purpose is to manage the X selection
+ when Wine exits.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename>winedbg</filename></term>
+ <listitem>
+ <para>
+ Winedbg is the Wine built in debugger.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename>winecfg</filename></term>
+ <listitem>
+ <para>
+ This is a Tcl/Tk based front end that provides
+ a user friendly tool to edit and configure
+ the <link linkend=WINECONFDIR endterm=wineconfdir.id></link>/config file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename>wineshelllink</filename></term>
+ <listitem>
+ <para>
+ This shell script can be called by Wine in order
+ to propogate Desktop icon and menu creation
+ requests out to a GNOME or KDE (or other
+ Window Managers).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename>winebuild</filename></term>
+ <listitem>
+ <para>
+ Winebuild is a tool used for Winelib applications
+ (and by Wine itself) to allow a developer to
+ compile a .spec file into a .spec.c file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><filename>wmc</filename></term>
+ <listitem>
+ <para>
+ The wmc tools is the Wine Message Compiler. It
+ allows Windows message files to be compiled
+ into a format usable by Wine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><filename>wrc</filename></term>
+ <listitem>
+ <para>
+ The wrc tool is the Wine Resource Compiler.
+ It allows Winelib programmers (and Wine itself)
+ to compile Windows style resource files
+ into a form usable by Wine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><filename>fnt2bdf</filename></term>
+ <listitem>
+ <para>
+ The fnt2bdf utility extracts fonts from .fnt or
+ .dll files and stores then in .dbf format files.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><filename>dosmod</filename></term>
+ <listitem>
+ <para>
+ DOS Virtual Machine.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+
+ <listitem id=libfiles>
+ <para> Shared Object Library Files </para>
+
+ <simplelist columns=5>
+
+<member>libwine.so.1.0</>
+<member>libddraw.so.1.0</>
+<member>libopengl32.so.1.0</>
+<member>libx11drv.so.1.0</>
+<member>libadvapi32.so.1.0</>
+<member>libavifil32.so.1.0</>
+<member>libcomctl32.so.1.0</>
+<member>libcomdlg32.so.1.0</>
+<member>libcrtdll.so.1.0</>
+<member>libdciman32.so.1.0</>
+<member>libdinput.so.1.0</>
+<member>libdplay.so.1.0</>
+<member>libdplayx.so.1.0</>
+<member>libdsound.so.1.0</>
+<member>libgdi32.so.1.0</>
+<member>libicmp.so.1.0</>
+<member>libimagehlp.so.1.0</>
+<member>libimm32.so.1.0</>
+<member>libkernel32.so.1.0</>
+<member>liblz32.so.1.0</>
+<member>libmpr.so.1.0</>
+<member>libmsacm32.so.1.0</>
+<member>libmsnet32.so.1.0</>
+<member>libmsvfw32.so.1.0</>
+<member>libodbc32.so.1.0</>
+<member>libole32.so.1.0</>
+<member>liboleaut32.so.1.0</>
+<member>libolecli32.so.1.0</>
+<member>liboledlg.so.1.0</>
+<member>libolepro32.so.1.0</>
+<member>libolesvr32.so.1.0</>
+<member>libpsapi.so.1.0</>
+<member>librasapi32.so.1.0</>
+<member>libriched32.so.1.0</>
+<member>librpcrt4.so.1.0</>
+<member>libserialui.so.1.0</>
+<member>libsetupapi.so.1.0</>
+<member>libshell32.so.1.0</>
+<member>libshfolder.so.1.0</>
+<member>libshlwapi.so.1.0</>
+<member>libtapi32.so.1.0</>
+<member>libttydrv.so.1.0</>
+<member>liburlmon.so.1.0</>
+<member>libuser32.so.1.0</>
+<member>libversion.so.1.0</>
+<member>libw32skrnl.so.1.0</>
+<member>libwnaspi32.so.1.0</>
+<member>libwineps.so.1.0</>
+<member>libwininet.so.1.0</>
+<member>libjoystick.drv.so.1.0</>
+<member>libwinmm.so.1.0</>
+<member>libmcianim.drv.so.1.0</>
+<member>libmciavi.drv.so.1.0</>
+<member>libmcicda.drv.so.1.0</>
+<member>libmciseq.drv.so.1.0</>
+<member>libmciwave.drv.so.1.0</>
+<member>libmidimap.drv.so.1.0</>
+<member>libmsacm.drv.so.1.0</>
+<member>libwineoss.drv.so.1.0</>
+<member>libws2_32.so.1.0</>
+<member>libwinspool.drv.so.1.0</>
+<member>libwow32.so.1.0</>
+<member>libwsock32.so.1.0</>
+<member>libwine_unicode.so.1.0</>
+ </simplelist>
+
+ </listitem>
+
+
+ <listitem id=manfiles>
+ <para> Man Pages</para>
+ <simplelist columns=1>
+<member>wine.man</>
+<member>wine.conf.man</>
+<member>wmc.man</>
+<member>wrc.man</>
+ </simplelist>
+
+ </listitem>
+
+
+ <listitem id=includefiles>
+ <para> Include Files</para>
+ <simplelist columns=5>
+
+<member>basetsd.h</>
+<member>cderr.h</>
+<member>cguid.h</>
+<member>commctrl.h</>
+<member>commdlg.h</>
+<member>compobj.h</>
+<member>d3d.h</>
+<member>d3dcaps.h</>
+<member>d3dtypes.h</>
+<member>d3dvec.inl</>
+<member>dde.h</>
+<member>ddeml.h</>
+<member>ddraw.h</>
+<member>digitalv.h</>
+<member>dinput.h</>
+<member>dispdib.h</>
+<member>dlgs.h</>
+<member>docobj.h</>
+<member>dplay.h</>
+<member>dplobby.h</>
+<member>dsound.h</>
+<member>guiddef.h</>
+<member>imagehlp.h</>
+<member>imm.h</>
+<member>initguid.h</>
+<member>instance.h</>
+<member>lmcons.h</>
+<member>lzexpand.h</>
+<member>mapidefs.h</>
+<member>mcx.h</>
+<member>mmreg.h</>
+<member>mmsystem.h</>
+<member>msacm.h</>
+<member>ntsecapi.h</>
+<member>oaidl.h</>
+<member>objbase.h</>
+<member>objidl.h</>
+<member>ocidl.h</>
+<member>ole2.h</>
+<member>ole2ver.h</>
+<member>oleauto.h</>
+<member>olectl.h</>
+<member>oledlg.h</>
+<member>oleidl.h</>
+<member>poppack.h</>
+<member>prsht.h</>
+<member>psapi.h</>
+<member>pshpack1.h</>
+<member>pshpack2.h</>
+<member>pshpack4.h</>
+<member>pshpack8.h</>
+<member>ras.h</>
+<member>regstr.h</>
+<member>richedit.h</>
+<member>rpc.h</>
+<member>servprov.h</>
+<member>shellapi.h</>
+<member>shlguid.h</>
+<member>shlobj.h</>
+<member>shlwapi.h</>
+<member>sql.h</>
+<member>sqlext.h</>
+<member>sqltypes.h</>
+<member>storage.h</>
+<member>tapi.h</>
+<member>tlhelp32.h</>
+<member>unknwn.h</>
+<member>urlmon.h</>
+<member>ver.h</>
+<member>vfw.h</>
+<member>winbase.h</>
+<member>wincon.h</>
+<member>wincrypt.h</>
+<member>windef.h</>
+<member>windows.h</>
+<member>windowsx.h</>
+<member>wine/exception.h</>
+<member>wine/icmpapi.h</>
+<member>wine/ipexport.h</>
+<member>wine/obj_base.h</>
+<member>wine/obj_cache.h</>
+<member>wine/obj_channel.h</>
+<member>wine/obj_clientserver.h</>
+<member>wine/obj_commdlgbrowser.h</>
+<member>wine/obj_connection.h</>
+<member>wine/obj_contextmenu.h</>
+<member>wine/obj_control.h</>
+<member>wine/obj_dataobject.h</>
+<member>wine/obj_dockingwindowframe.h</>
+<member>wine/obj_dragdrop.h</>
+<member>wine/obj_enumidlist.h</>
+<member>wine/obj_errorinfo.h</>
+<member>wine/obj_extracticon.h</>
+<member>wine/obj_inplace.h</>
+<member>wine/obj_marshal.h</>
+<member>wine/obj_misc.h</>
+<member>wine/obj_moniker.h</>
+<member>wine/obj_oleaut.h</>
+<member>wine/obj_olefont.h</>
+<member>wine/obj_oleobj.h</>
+<member>wine/obj_oleundo.h</>
+<member>wine/obj_oleview.h</>
+<member>wine/obj_picture.h</>
+<member>wine/obj_property.h</>
+<member>wine/obj_propertystorage.h</>
+<member>wine/obj_queryassociations.h</>
+<member>wine/obj_shellbrowser.h</>
+<member>wine/obj_shellextinit.h</>
+<member>wine/obj_shellfolder.h</>
+<member>wine/obj_shelllink.h</>
+<member>wine/obj_shellview.h</>
+<member>wine/obj_storage.h</>
+<member>wine/unicode.h</>
+<member>winerror.h</>
+<member>wingdi.h</>
+<member>wininet.h</>
+<member>winioctl.h</>
+<member>winnetwk.h</>
+<member>winnls.h</>
+<member>winnt.h</>
+<member>winreg.h</>
+<member>winresrc.h</>
+<member>winsock.h</>
+<member>winsock2.h</>
+<member>winspool.h</>
+<member>winsvc.h</>
+<member>winuser.h</>
+<member>winver.h</>
+<member>wnaspi32.h</>
+<member>wownt32.h</>
+<member>wtypes.h</>
+<member>zmouse.h</>
+ </simplelist>
+
+ </listitem>
+
+ <listitem id=docfiles>
+ <para>
+ Documentation files.
+ </para>
+ <para>
+ At the time of this writing, I do not have a
+ definitive list of documentation files to
+ be installed. However, they do include
+ the HTML files generated from the SGML in the Wine CVS tree.
+ </para>
+ </listitem>
+
+
+ </orderedlist>
+
+ </sect1>
+
+
+ <sect1 id=nonstatic><title>Dynamic Wine Files</title>
+
+ <para>
+ Wine also generates and depends on a number of dynamic
+ files, including user configuration files and registry files.
+ </para>
+
+ <para>
+ At the time of this writing, there was not a clear
+ consensus of where these files should be located, and how
+ they should be handled. This section attempts
+ to explain the alternatives clearly.
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <variablelist><title>Configuration File</title>
+ <varlistentry id=winerc><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/config</filename></term>
+ <listitem>
+ <para>
+ This file is the user local Wine configuration file.
+ At the time of this writing, if this file exists,
+ then no other configuration file is loaded.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>
+ <filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.conf</filename></term>
+ <listitem>
+ <para>
+ This is the global Wine configuration file. It
+ is only used if the user running Wine has
+ no local configuration file.
+ </para>
+ <para>
+ Some packagers feel that this file should not
+ be supplied, and that only a wine.conf.default
+ should be given here.
+ </para>
+ <para>
+ Other packagers feel that this file should
+ be the predominant file used, and that
+ users should only shift to a local configuration
+ file if they need to. An argument has been
+ made that the local configuration file
+ should inherit the global configuration file.
+ At this time, Wine does not do this;
+ please refer to the WineHQ discussion
+ archives for the debate concerning this.
+ </para>
+ <para>
+ This debate is addressed more completely
+ below, in <link linkend=strategy endterm=strategy.id></link>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </listitem>
+
+ <listitem>
+
+ <para>Registry Files</para>
+
+ <para>
+ In order to replicate the Windows registry system,
+ Wine stores registry entries in a series of files.
+
+ For an excellent overview of this issue, read
+ this
+ <ulink url="http://www.winehq.com/News/2000-25.html#FTR">
+ Wine Weekly News feature.</ulink>
+
+ </para>
+
+ <para>
+ The bottom line is that, at Wine server startup,
+ Wine loads all registry entries into memory
+ to create an in memory image of the registry.
+ The order of files which Wine uses to load
+ registry entries is extremely important,
+ as it affects what registry entries are
+ actually present. The order is roughly that
+ .dat files from a Windows partion are loaded,
+ then global registry settings from <link linkend=ETCDIR endterm=etcdir.id></link>,
+ and then finally local registry settings are
+ loaded from <link linkend=WINECONFDIR endterm=wineconfdir.id></link>
+ . As each set are loaded,
+ they can override the prior entries. Thus,
+ the local registry files take precedence.
+ </para>
+
+ <para>
+ Then, at exit (or at periodic intervals),
+ Wine will write either all registry entries
+ (or, with the default setting) changed
+ registry entries to files in the
+ <link linkend=WINECONFDIR endterm=wineconfdir.id></link>.
+ </para>
+
+ <variablelist>
+ <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/system.reg</filename></term>
+ <listitem>
+ <para>
+ This file contains the users local copy of
+ the HKEY_LOCAL_MACHINE registry hive. In general
+ use, it will contain only changes made to the
+ default registry values.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/user.reg</filename></term>
+ <listitem>
+ <para>
+ This file contains the users local copy of
+ the HKEY_CURRENT_USER registry hive. In
+ general use, it will contain only changes made to the
+ default registry values.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/userdef.reg</filename></term>
+ <listitem>
+ <para>
+ This file contains the users local copy of
+ the HKEY_USERS\.Default registry hive. In
+ general use, it will contain only changes made to the
+ default registry values.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/wine.userreg</filename></term>
+ <listitem>
+ <para>
+ This file is being deprecated. It is only read
+ if there is no user.reg or wine.userreg, and
+ it supplied the contents of HKEY_USERS.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.systemreg</filename></term>
+ <listitem>
+ <para>
+ This file contains the global values for
+ HKEY_LOCAL_MACHINE. The values in this file
+ can be overriden by the users local settings.
+ </para>
+ <note>
+ <para>
+ The location of this directory is hard coded within
+ wine, generally to /etc. This will hopefully be
+ fixed at some point in the future.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry><term><filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.userreg</filename></term>
+ <listitem>
+ <para>
+ This file contains the global values for
+ HKEY_USERS. The values in this file
+ can be overriden by the users local settings.
+ This file is likely to be deprecated in
+ favor of a global wine.userdef.reg that will
+ only contain HKEY_USERS/.Default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+
</listitem>
<listitem>
- <para>Implementation</para>
+ <variablelist><title>Other files in <link linkend=WINECONFDIR endterm=wineconfdir.id></link></title>
+ <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/wineserver-[username]</filename></term>
+ <listitem>
+ <para>
+ This directory contains files used by Wine and the Wineserver
+ to communicate. A packager may want to have a facility
+ for the user to erase files in this directory,
+ as a crash in the wineserver resulting in a bogus lock
+ file can render wine unusable.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/cachedmetrics.[display]</filename></term>
+ <listitem>
+ <para>
+ This file contains font metrics for the given X display.
+ Generally, this cache is generated once at Wine start time.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+
+
+ </orderedlist>
+
+
+ </sect1>
+
+ <sect1 id=winpartition><title>Important Files from a Windows Partition</title>
+ <para>
+ Wine has the ability to use files from an installation of the
+ actual Microsoft Windows operating system. Generally these
+ files are loaded on a VFAT partition that is mounted
+ under Linux.
+ </para>
+ <para>
+ This is probably the most important configuration detail.
+ The use of Windows registry and DLL files dramatically
+ alters the behaviour of Wine. If nothing else,
+ pacakager have to make this distinction clear
+ to the end user, so that they can intelligently
+ choose their configuration.
+ </para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <variablelist><title>Registry Files</title>
+ <varlistentry><term><filename>[WINDOWSDIR]/system32/system.dat</filename></term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename>[WINDOWSDIR]/system32/user.dat</filename></term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename>[WINDOWSDIR]/win.ini</filename></term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </listitem>
+
+ <listitem>
+ <para>
+ Windows Dynamic Link Libraries ([WINDOWSDIR]/system32/*.dll)
+ </para>
+ <para>
+ Wine has the ability to use the actuall Windows DLL files
+ when running an application. An end user can configure
+ Wine so that Wine uses some or all of these DLL files
+ when running a given application.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ </sect1>
+
+ </chapter>
+
+ <chapter id=strategy><title id=strategy.id>Packaging Strategies</title>
+
+ <para>
+ There has recently been a lot of discussion on the Wine
+ development mailing list about the best way to
+ build Wine packages.
+ </para>
+ <para>
+ There was a lot of discussion, and several diverging
+ points of view. This section of the document
+ attempts to present the areas of common agreement,
+ and also to present the different approaches
+ advocated on the mailing list.
+ </para>
+
+ <sect1 id=whatfiles><title>Distribution of Wine into packages</title>
+ <para>
+ The most basic question to ask is given the Wine CVS tree,
+ what physical files are you, the packager, going to produce?
+ Are you going to produce only a wine.rpm (as Marcus has done),
+ or are you going to produce 5 debian files
+ (libwine-dev, libwine, wine-doc, wine-utils, and wine) as
+ Ove has done?
+ </para>
+ <para>
+ At this point, there is no consensus
+ amongst the wine-devel community on this subject.
+ </para>
+ </sect1>
+
+ <sect1 id=wherefiles><title>Where to install files</title>
+ <para>
+ This question is not really contested. It will vary
+ by distribution, and is really up to the packager.
+ As a guideline, the current 'make install' process
+ seems to behave such that
+ if we pick a single <link linkend=PREFIX endterm=prefix.id></link>,
+ then :
+ </para>
+ <orderedlist>
+
+ <listitem>
+ <para>
+ all <link linkend=binfiles>binary files</link> go into
+ <link linkend=PREFIX endterm=prefix.id></link>/bin,
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ all <link linkend=libfiles>library files</link> go into
+ <link linkend=PREFIX endterm=prefix.id></link>/lib,
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ all <link linkend=includefiles>include files</link> go into
+ <link linkend=PREFIX endterm=prefix.id></link>/include,
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ all <link linkend=docfiles>documentation files</link> go into
+ <link linkend=PREFIX endterm=prefix.id></link>/doc/wine,
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ and <link linkend=manfiles>man pages</link> go into
+ <link linkend=PREFIX endterm=prefix.id></link>/man,
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ Refer to the specific information on the Debian package
+ and the OpenLinux package for specific details on how
+ those packages are built.
+ </para>
+
+ <sect2 id=opt><title>The question of /opt/wine</title>
+ <para>
+ The FHS 2.1 specification suggests that Wine as a package
+ should be installed to /opt/wine. None of the
+ existing packages follow this guideline (today;
+ check again tomorrow).
+ </para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id=whattomake><title>What files to create</title>
+ <para>
+ After installing the static and shareable files, the next
+ question the packager needs to ask is how much dynamic
+ configuration will be done, and what configuration
+ files should be created.
+ </para>
+ <para>
+ There are several approaches to this:
+ <orderedlist>
+ <listitem>
+ <para>
+ Rely completely on user file space - install nothing
+ </para>
+ <para>
+ This approach relies upon the new winecfg utility and
+ the new ability of Wine to launch winecfg if no configuration file is found.
+ The basic concept is that no global configuration files
+ are created at install time.
+ Instead, Wine configuration files are created on the
+ fly by the winecfg program when Wine is invoked.
+ Further, winecfg creates default Windows directories
+ and paths that are stored completely in
+ the users <link linkend=WINECONFDIR endterm=wineconfdir.id></link>.
+ </para>
+ <para>
+ This approach has the benefit of simplicity in that all
+ Wine files are either stored under /opt/wine or under
+ ~/.wine. Further, there is only ever one Wine
+ configuration file.
+ </para>
+ <para>
+ This approach, however, adds another level of complexity.
+ It does not allow Wine to run Solitaire 'out of the box';
+ the user must run the configuration program first. Further,
+ winecfg requires Tcl/Tk, a requirement not beloved by some.
+ Additionally, this approach closes the door on multi
+ user configurations and presumes a single user approach.
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ Build a reasonable set of defaults for the global wine.conf,
+ facilitate creation of a user's local Wine configuration.
+ </para>
+ <para>
+ This approach, best shown by Marcus, causes the
+ installation process to auto scan the system,
+ and generate a global wine.conf file with best
+ guess defaults. The OpenLinux packages follow
+ this behaviour.
+ </para>
+ <para>
+ The keys to this approach are always putting
+ an existing Windows partition into the
+ path, and being able to run Solitaire
+ right out of the box.
+ Another good thing that Marcus does is he
+ detects a first time installation and
+ does some clever things to improve the
+ user's Wine experience.
+ </para>
+ <para>
+ A flaw with this approach, however, is it doesn't
+ give the user an obvious way to choose not to
+ use a Windows partition.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Build a reasonable set of defaults for the global wine.conf,
+ and ask the user if possible
+ </para>
+ <para>
+ This approach, demonstrated by Ove, causes the
+ installation process to auto scan the system,
+ and generate a global wine.conf file with best
+ guess defaults. Because Ove built a Debian
+ package, he was able to further query debconf and
+ get permission to ask the user some questions,
+ allowing the user to decide whether or not to
+ use a Windows partition.
+ </para>
+ </listitem>
+
+
+ </orderedlist>
+ </para>
+
+ </sect1>
+
+
+ <sect1 id=wineconf><title>What to put into the wine config file</title>
+ <para>
+ The next hard question is what the Wine config should look like.
+ The current best practices seems to involve using drives from M to Z.
+ </para>
+ <caution><para>This isn't done yet! Fix it, Jer!</para></caution>
+ </sect1>
+
+
+ </chapter>
+
+
+
+
+ <chapter id="pkg-Implementation"> <title>Implementation</title>
+
+ <sect1 id=OpenLinux><title>OpenLinux Sample</title>
<orderedlist inheritnum="inherit">
<listitem>
@@ -157,8 +1180,8 @@
distributed <filename>winedefault.reg</filename>. This
can be done using <command>./regapi</command> once for
one example user and then reusing his
- <filename>.wine/user.reg</filename> and
- <filename>.wine/system.reg</filename> files.
+ <filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/user.reg</filename> and
+ <filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/system.reg</filename> files.
<note>
<title>FIXME</title>
<para>this needs to be done better</para>
@@ -359,6 +1382,8 @@
The user will need to run a setup script before the
first invocation of WINE. This script should:
</para>
+
+
<itemizedlist>
<listitem>
<para>
@@ -415,43 +1440,17 @@
</para>
</listitem>
</itemizedlist>
+
+
</listitem>
</orderedlist>
- </listitem>
- </orderedlist>
-
- <para>Done.</para>
-
- <para>
- This procedure requires:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>Much thought and work from the packager (1x)</para>
- </listitem>
- <listitem>
- <para>
- No work for the sysadmin. Well except one <command>rpm
- -i</command> and possible one edit of the configuration
- file.
- </para>
- </listitem>
- <listitem>
- <para>
- Some or no work from the user, except running the per-user
- setup script once.
- </para>
- </listitem>
- <listitem>
- <para>It scales well and suffices most of the rationales.</para>
- </listitem>
- </itemizedlist>
- <bridgehead>Sample <filename>wine.ini</filename> for OpenLinux 2.x:</bridgehead>
+ <sect2 id=sample><title>Sample <filename>wine.ini</filename> for OpenLinux 2.x:</title>
- <programlisting>
+<programlisting>
+
+
;;
;; MS-DOS drives configuration
;;
@@ -749,12 +1748,122 @@
# </wineconf>
</programlisting>
- </sect1>
- </chapter>
+
+ </sect2>
+ </sect1>
+
+</chapter>
+
+<chapter id=todo><Title>Work to be done</title>
+
+ <para>
+ In preparing this document, it became clear that there were
+ still a range of action items to be done in Wine
+ that would improve this packaging process.
+ For lack of a better place, I record them here.
+ <emphasis>This list is almost certain to be obsolete;
+ check bugzilla for a better list.</emphasis>
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Remove duplication of code between winecfg and
+ wineconf/wineinstall.
+ </para>
+ <para>
+ Currently, winecfg duplicates all of the code contained
+ in wineconf.
+ </para>
+ <para>
+ Instead, wineconf should be improved to generate
+ the new style config file, and then winecfg should
+ rely on wineconf to generate the default
+ configuration file.
+ </para>
+ <para>
+ Similarly, there is functionality such as creating
+ the default registry files that is now done by
+ both winecfg and wineinstall.
+ </para>
+ <para>
+ At this time, it seems like the right thing to do
+ is to break up or parameterize wineinstall, so that
+ it can be used for single function actions,
+ and then have winecfg call those functions.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Enhance winecfg to support W: drive generation.
+ </para>
+ <para>
+ The best practices convention now seems to be
+ to generate a set of drives from M: through W:.
+ At this point, winecfg does not generate
+ a default wine config file that follows
+ these conventions. It should.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Enhance Wine to allow more dynamic switching
+ between the use of a real Windows partition
+ and an empty one.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Write a winelauncher utility application.
+ </para>
+ <para>
+ Currently, Wine really requires a user to launch it
+ from a command line, so that the user can look for
+ error messages and warnings. However, eventually, we will
+ want users to be able to launch Wine from a more
+ friendly GUI launcher. The launcher should have the
+ ability to allow the end user to turn on debugging
+ messages and capture those traces for bug reporting
+ purposes. Also, if we make it possible to
+ switch between use of a Windows partition or not
+ automatically, that option should be controlled here.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Get Marcus's winesetup facilities into CVS
+ </para>
+ <para>
+ Along the lines of the changes to winecfg,
+ and the consolidation of wineconf and wineinstall,
+ we should extract the good stuff from Marcus's
+ winesetup script, and get it into CVS.
+ Again, perhaps we should have a set of scripts
+ that perform discrete functions, or maybe
+ one script with parameters.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Finish this document
+ </para>
+ <para>
+ This document is pretty rough itself. Many hard
+ things aren't addressed, and lots of stuff was missed.
+ </para>
+ </listitem>
+ </orderedlist>
+</chapter>
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
-sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
+sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
End:
-->
