Google Git Google Git
Sign in
goma/wine/f4b14106f7c591ada622f60935b78baa174293de/./documentation/packaging.sgml
blob: 9e07f70e23c9bf9e55a38cedff6d4fe940ed5720 [file]
<!-- 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="pkg-authors"> <title>Authors</title>
<para>
Written by &name-marcus-meissner; <email>&email-marcus-meissner;</email>
Updated by &name-jeremy-white; <email>&email-jeremy-white;</email>
</para>
</sect1>
<sect1 id="pkg-date"> <title>Document Revision Date</title>
<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="pkg-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="pkg-goals"> <title>Goals</title>
<para>
An installation from a Wine pacakage should:
</para>
<itemizedlist>
<listitem>
<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>
Comply with Filesystem Hierarchy Standard
</para>
<para>
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>
</sect1>
<sect1 id="pkg-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
structure on a per user basis. Applications do dump
<filename>.ini</filename> files into
<filename>c:\windows</filename>, installers dump
<filename>.exe</filename>, <filename>.dll</filename>
and more into <filename>c:\windows\</filename> and
subdirectories or into <filename>C:\Program
Files\</filename>.
</para>
</listitem>
<listitem>
<para>
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
<filename>.exe</filename> files in the
<filename>windows\system</filename> directory, since
applications directly check for their presence.
</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
<chapter id="pkg-components"><title>Wine Components</title>
<para>
This section lists all files that pertain to Wine.
</para>
<sect1 id="pkg-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="pkg-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=pkg-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>
<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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-openlinux"><title>OpenLinux Sample</title>
<orderedlist inheritnum="inherit">
<listitem>
<para>Building the package</para>
<para>
WINE is configured the usual way (depending on your
build environment). The "prefix" is chosen using your
application placement policy
(<filename>/usr/</filename>,
<filename>/usr/X11R6/</filename>,
<filename>/opt/wine/</filename> or similar). The
configuration files (<filename>wine.conf</filename>,
<filename>wine.userreg</filename>,
<filename>wine.systemreg</filename>) are targeted for
<filename>/etc/wine/</filename> (rationale: FHS 2.0,
multiple readonly configuration files of a package).
</para>
<para>
Example (split this into <literal>%build</literal> and
<literal>%install</literal> section for
<command>rpm</command>):
</para>
<screen>
CFLAGS=$RPM_OPT_FLAGS \
./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
make
BR=$RPM_BUILD_ROOT
make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/
install -d $BR/etc/wine/
install -m 644 wine.ini $BR/etc/wine/wine.conf
# Put all our dlls in a seperate directory. (this works only if
# you have a buildroot)
install -d $BR/usr/X11R6/lib/wine
mv $BR/usr/X11R6/lib/lib* $BR/usr/X11R6/lib/wine/
# the clipboard server is started on demand.
install -m 755 windows/x11drv/wineclipsrv $BR/usr/X11R6/bin/
# The WINE server is needed.
install -m 755 server/wineserver $BR/usr/X11R6/bin/
</screen>
<para>
Here we unfortunately do need to create
<filename>wineuser.reg</filename> and
<filename>winesystem.reg</filename> from the WINE
distributed <filename>winedefault.reg</filename>. This
can be done using <command>./regapi</command> once for
one example user and then reusing his
<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>
</note>
</para>
<screen>
install -m 644 wine.sytemreg $BR/etc/wine/
install -m 644 wine.userreg $BR/etc/wine/
</screen>
<para>
There are now a lot of libraries generated by the
build process, so a seperate library directory should
be used.
</para>
<screen>
install -d 755 $BR/usr/X11R6/lib/
mv $BR/
</screen>
<para>
You will need to package the files:
</para>
<screen>
$prefix/bin/wine, $prefix/bin/dosmod, $prefix/lib/wine/*
$prefix/man/man1/wine.1, $prefix/include/wine/*,
$prefix/bin/wineserver, $prefix/bin/wineclipsrv
%config /etc/wine/*
%doc ... choose from the toplevel directory and documentation/
</screen>
<para>
The post-install script:
</para>
<screen>
if ! grep -q /usr/X11R6/lib/wine /etc/ld.so.conf; then
echo "/usr/X11R6/lib/wine" &gt;&gt; /etc/ld.so.conf
fi
/sbin/ldconfig
</screen>
<para>
The post-uninstall script:
</para>
<screen>
if [ "$1" = 0 ]; then
perl -ni -e 'print unless m:/usr/X11R6/lib/wine:;' /etc/ld.so.conf
fi
/sbin/ldconfig
</screen>
</listitem>
<listitem>
<para>Creating a good default configuration file</para>
<para>
For the rationales of needing as less input from the
user as possible arises the need for a very good
configuration file. The one supplied with WINE is
currently lacking. We need:
</para>
<itemizedlist>
<listitem>
<para>
[Drive X]:
</para>
<itemizedlist>
<listitem>
<para>
A for the floppy. Specify your distributions
default floppy mountpoint here.
</para>
<programlisting>
Path=/auto/floppy
</programlisting>
</listitem>
<listitem>
<para>
C for the <filename>C:\</filename> directory.
Here we use the users homedirectory, for most
applications do see <filename>C:\</filename>
as root-writeable directory of every windows
installation and this basically is it in the
UNIX-user context.
</para>
<programlisting>
Path=${HOME}
</programlisting>
</listitem>
<listitem>
<para>
R for the CD-Rom drive. Specify your
distributions default CD-ROM drives mountpoint
here.
</para>
<programlisting>
Path=/auto/cdrom
</programlisting>
</listitem>
<listitem>
<para>
T for temporary storage. We do use
<filename>/tmp/</filename> (rationale: between
process temporary data belongs to
<filename>/tmp/</filename>, FHS 2.0)
</para>
</listitem>
<listitem>
<para>
W for the original Windows installation. This
drive points to the
<filename>windows\</filename> subdirectory of
the original windows installation. This avoids
problems with renamed
<filename>windows</filename> directories (as
for instance <filename>lose95</filename>,
<filename>win</filename> or
<filename>sys\win95</filename>). During
compile/package/install we leave this to be
<filename>/</filename>, it has to be
configured after the package install.
</para>
</listitem>
<listitem>
<para>
Z for the UNIX Root directory. This avoids any
problems with "could not find drive for
current directory" users occasionaly complain
about in the newsgroup and the ircchannel. It
also makes the whole directory structure
browseable. The type of Z should be network,
so applications expect it to be readonly.
</para>
<programlisting>
Path=/
</programlisting>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
[wine]:
</para>
<screen>
Windows=c:\windows\ (the windows/ subdirectory in the users
homedirectory)
System=c:\windows\system\ (the windows/system subdirectory in the users
homedirectory)
Path=c:\windows;c:\windows\system;c:\windows\system32;w:\;w:\system;w:\system32;
; Using this trick we have in fact two windows installations in one, we
; get the stuff from the readonly installation and can write to our own.
Temp=t:\ (the TEMP directory)
</screen>
</listitem>
<listitem>
<para>[Tweak.Layout]</para>
<screen>
WineLook=win95 (just the coolest look ;)
</screen>
</listitem>
<listitem>
<para>
Possibly modify the [spooler], [serialports] and
[parallelports] sections.
</para>
<note>
<title>FIXME</title>
<para>possibly more, including printer stuff.</para>
</note>
</listitem>
</itemizedlist>
<para>Add this prepared configuration file to the package.</para>
</listitem>
<listitem>
<para>Installing WINE for the system administrator</para>
<para>
Install the package using the usual packager
<command>rpm -i wine.rpm</command>. You may edit
<filename>/etc/wine/wine.conf</filename>, [Drive W],
to point to a possible windows installation right
after the install. That's it.
</para>
<para>
Note that on Linux you should somehow try to add the
<option>unhide</option> mount option (see <command>man
mount</command>) to the CD-ROM entry in
<filename>/etc/fstab</filename> during package
install, as several stupid Windows programs mark some
setup (!) files as hidden (ISO9660) on CD-ROMs, which
will greatly confuse users as they won't find their
setup files on the CD-ROMs as they were used on
Windows systems when <option>unhide</option> is not
set ;-\ And of course the setup program will complain
that <filename>setup.ins</filename> or some other mess
is missing... If you choose to do so, then please make
this change verbose to the admin.
</para>
</listitem>
<listitem>
<para>Installing WINE for the user</para>
<para>
The user will need to run a setup script before the
first invocation of WINE. This script should:
</para>
<itemizedlist>
<listitem>
<para>
Copy <filename>/etc/wine/wine.conf</filename> for
user modification.
</para>
</listitem>
<listitem>
<para>
Allow specification of the original windows
installation to use (which modifies the copied
<filename>wine.conf</filename> file).
</para>
</listitem>
<listitem>
<para>
Create the windows directory structure
(<filename>c:\windows</filename>,
<filename>c:\windows\system</filename>,
<filename>c:\windows\Start Menu\Programs</filename>,
<filename>c:\Program Files</filename>,
<filename>c:\Desktop</filename>, etc.)
</para>
</listitem>
<listitem>
<para>
Symlink all <filename>.dll</filename> and
<filename>.exe</filename> files from the original
windows installation to the
<filename>windows</filename> directory. Why? Some
programs reference "%windowsdir%/file.dll" or
"%systemdir%/file.dll" directly and fail if they
are not present.
</para>
<para>
This will give a huge number of symlinks, yes.
However, if an installer later overwrites on of
those files, it will overwrite the symlink (so
that the file now lies in the
<filename>windows/</filename> subdirectory).
</para>
<note>
<title>FIXME</title>
<para>Not sure this is needed for all files.</para>
</note>
</listitem>
<listitem>
<para>
On later invocation the script might want to
compare regular files in the users windows
directories and in the global windows directories
and replace same files by symlinks (to avoid
diskspace problems).
</para>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
<sect2 id=sample><title>Sample <filename>wine.ini</filename> for OpenLinux 2.x:</title>
<programlisting>
;;
;; MS-DOS drives configuration
;;
;; Each section has the following format:
;; [Drive X]
;; Path=xxx (Unix path for drive root)
;; Type=xxx (supported types are 'floppy', 'hd', 'cdrom' and 'network')
;; Label=xxx (drive label, at most 11 characters)
;; Serial=xxx (serial number, 8 characters hexadecimal number)
;; Filesystem=xxx (supported types are 'msdos'/'dos'/'fat', 'win95'/'vfat', 'unix')
;; This is the FS Wine is supposed to emulate on a certain
;; directory structure.
;; Recommended:
;; - "win95" for ext2fs, VFAT and FAT32
;; - "msdos" for FAT16 (ugly, upgrading to VFAT driver strongly recommended)
;; DON'T use "unix" unless you intend to port programs using Winelib !
;; Device=/dev/xx (only if you want to allow raw device access)
;;
;
;
; Floppy 'A' and 'B'
;
; OpenLinux uses an automounter under /auto/, so we use that too.
;
[Drive A]
Path=/auto/floppy/
Type=floppy
Label=Floppy
Serial=87654321
Device=/dev/fd0
Filesystem=win95
;
; Comment in ONLY if you have a second floppy or the automounter hangs
; for 5 minutes.
;
;[Drive B]
;Path=/auto/floppy2/
;Type=floppy
;Label=Floppy
;Serial=87654321
;Device=/dev/fd1
;Filesystem=win95
;
; Drive 'C' links to the users homedirectory.
;
; This must point to a writeable directory structure (not your readonly
; mounted DOS partitions!) since programs want to dump stuff into
; "Program Files/" "Programme/", "windows/", "windows/system/" etc.
;
; The basic structure is set up using the config script.
;
[Drive C]
Path=${HOME}
Type=hd
Label=MS-DOS
Filesystem=win95
;
; /tmp/ directory
;
; The temp drive (and directory) points to /tmp/. Windows programs fill it
; with junk, so it is approbiate.
;
[Drive T]
Path=/tmp
Type=hd
Label=Tmp Drive
Filesystem=win95
;
; 'U'ser homedirectory
;
; Just in case you want C:\ elsewhere.
;
[Drive U]
Path=${HOME}
Type=hd
Label=Home
Filesystem=win95
;
; CD-'R'OM drive (automounted)
;
; The default cdrom drive.
;
; If an application (or game) wants a specific CD-ROM you might have to
; temporary change the Label to the one of the CD itself.
;
; How to read them is described in /usr/doc/wine-cvs-xxxxx/cdrom-labels.
;
[Drive R]
Path=/auto/cdrom
Type=cdrom
Label=CD-Rom
Filesystem=win95
;
; The drive where the old windows installation resides (it points to the
; windows/ subdirectory).
;
; The Path is modified by the winesetup script.
;
[Drive W]
Path=/
Type=network
Label=Windows
Filesystem=win95
;
; The UNIX Root directory, so all other programs and directories are reachable.
;
; type network is used to tell programs to not write here.
;
[Drive Z]
Path=/
Type=network
Label=ROOT
Filesystem=win95
;
; Standard Windows path entries. WINE will not work if they are incorrect.
;
[wine]
;
; The windows/ directory. It must be writeable, for programs write into it.
;
Windows=c:\windows
;
; The windows/system/ directory. It must be writeable, for especially setup
; programs install dlls in there.
;
System=c:\windows\system
;
; The temp directory. Should be cleaned regulary, since install programs leave
; junk without end in there.
;
Temp=t:\
;
; The dll search path. It should contain at least:
; - the windows and the windows/system directory of the user.
; - the global windows and windows/system directory (from a possible readonly
; windows installation either on msdos filesystems or somewhere in the UNIX
; directory tree)
; - any other windows style directories you want to add.
;
Path=c:\windows;c:\windows\system;c:\windows\system32;t:\;w:\;w:\system;w:\system32
;
; Outdated and no longer used. (but needs to be present).
;
SymbolTableFile=./wine.sym
# &lt;wineconf&gt;
;
; Dll loadorder defaults. No need to modify.
;
[DllDefaults]
EXTRA_LD_LIBRARY_PATH=${HOME}/wine/cvs/lib
DefaultLoadOrder = native, elfdll, so, builtin
;
; What 32/16 dlls belong to each other (context wise). No need to modify.
;
[DllPairs]
kernel = kernel32
gdi = gdi32
user = user32
commdlg = comdlg32
commctrl= comctl32
ver = version
shell = shell32
lzexpand= lz32
mmsystem= winmm
msvideo = msvfw32
winsock = wsock32
;
; What type of dll to use in their respective loadorder.
;
[DllOverrides]
kernel32, gdi32, user32 = builtin
kernel, gdi, user = builtin
toolhelp = builtin
comdlg32, commdlg = elfdll, builtin, native
version, ver = elfdll, builtin, native
shell32, shell = builtin, native
lz32, lzexpand = builtin, native
commctrl, comctl32 = builtin, native
wsock32, winsock = builtin
advapi32, crtdll, ntdll = builtin, native
mpr, winspool = builtin, native
ddraw, dinput, dsound = builtin, native
winmm, mmsystem = builtin
msvideo, msvfw32 = builtin, native
mcicda.drv, mciseq.drv = builtin, native
mciwave.drv = builtin, native
mciavi.drv, mcianim.drv = native, builtin
w32skrnl = builtin
wnaspi32, wow32 = builtin
system, display, wprocs = builtin
wineps = builtin
;
; Options section. Does not need to be edited.
;
[options]
; allocate how much system colors on startup. No need to modify.
AllocSystemColors=100
;;
; Font specification. You usually do not need to edit this section.
;
; Read documentation/fonts before adding aliases
;
[fonts]
; The resolution defines what fonts to use (usually either 75 or 100 dpi fonts,
; or nearest match).
Resolution = 96
; Default font
Default = -adobe-times-
;
; serial ports used by "COM1" "COM2" "COM3" "COM4". Useful for applications
; that try to access serial ports.
;
[serialports]
Com1=/dev/ttyS0
Com2=/dev/ttyS1
Com3=/dev/modem,38400
Com4=/dev/modem
;
; parallel port(s) used by "LPT1" etc. Useful for applications that try to
; access these ports.
;
[parallelports]
Lpt1=/dev/lp0
;
; What spooling program to use on printing.
; Use "|program" or "filename", where the output will be dumped into.
;
[spooler]
LPT1:=|lpr
LPT2:=|gs -sDEVICE=bj200 -sOutputFile=/tmp/fred -q -
LPT3:=/dev/lp3
;
; Allow port access to WINE started by the root user. Useful for some
; supported devices, but it can make the system unstable.
; Read /usr/doc/wine-cvs-xxxxx/ioport-trace-hints.
;
[ports]
;read=0x779,0x379,0x280-0x2a0
;write=0x779,0x379,0x280-0x2a0
; debugging, not need to be modified.
[spy]
Exclude=WM_SIZE;WM_TIMER;
;
; What names for the registry datafiles, no need to modify.
;
[Registry]
; Paths must be given in /dir/dir/file.reg format.
; Wine will not understand dos file names here...
;UserFileName=xxx ; alternate registry file name (user.reg)
;LocalMachineFileName=xxx ; (system.reg)
;
; Layout/Look modifications. Here you can switch with a single line between
; windows 3.1 and windows 95 style.
; This does not change WINE behaviour or reported versions, just the look!
;
[Tweak.Layout]
;; WineLook=xxx (supported styles are 'Win31'(default), 'Win95', 'Win98')
WineLook=Win95
;
; What programs to start on WINE startup. (you should probably leave it empty)
;
[programs]
Default=
Startup=
; defunct section.
[Console]
;XtermProg=nxterm
;InitialRows=25
;InitialColumns=80
;TerminalType=nxterm
# &lt;/wineconf&gt;
</programlisting>
</sect2>
</sect1>
</chapter>
<chapter id="pkg-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" "")
End:
-->