Revert some word-splits to their normal form, e.g. InstallShield.
[wine] / documentation / PACKAGING
1 INTRODUCTION
2 ~~~~~~~~~~~~
3
4 This document attempts to establish guidelines for people making binary 
5 packages of Wine.
6
7 It expresses the basic principles that the Wine developers have agreed 
8 should be used when building Wine. It also attempts to highlight the areas
9 where there are different approaches to packaging Wine, so that the packager
10 can understand the different alternatives that have been considered and their 
11 rationales.
12
13 TERMS
14 ~~~~~
15
16 There are several terms and paths used in this document as place holders 
17 for configurable values. Those terms are described here.
18     * WINEPREFIX: is the user's Wine configuration directory.
19         This is almost always ~/.wine, but can be overridden by
20         the user by setting the WINEPREFIX environment variable.
21
22     * PREFIX: is the prefix used when selecting an installation target.
23         The current default is /usr/local. This results in binary 
24         installation into /usr/local/bin,  library installation into 
25         /usr/local/wine/lib, and so forth.
26         This value can be overridden by the packager. In fact, FHS 2.2
27         (http://www.pathname.com/fhs/) specifications suggest that a better
28         prefix is /opt/wine.  Ideally, a packager would also allow the 
29         installer to override this value.
30
31     * ETCDIR: is the prefix that Wine uses to find the global 
32         configuration directory. This can be changed by the configure 
33         option sysconfdir.  The current default is $PREFIX/etc.
34
35     * WINDOWSDIR: is an important concept to Wine.  This directory specifies
36         what directory corresponds to the root Windows directory
37         (e.g. C:\WINDOWS). This directory is specified by the user, in
38         the user's configuration file.  Generally speaking, this directory 
39         is either set to point at an empty directory, or it is set to point 
40         at a Windows partition that has been mounted through the vfat driver.
41         NOTE:   It is extremely important that the packager understand the 
42                 importance of WINDOWSDIR and convey this information and 
43                 choice to the end user.
44
45 GOALS
46 ~~~~~
47
48 An installation from a Wine package should:
49     * Install quickly and simply:
50         The initial installation should require no user input.  An 
51                 'rpm -i wine.rpm' or 'apt-get install wine'
52         should suffice for initial installation.
53                 
54     * Work quickly and simply:
55         The user should be able to launch Solitaire
56         within minutes of downloading the Wine package.
57               
58     * Comply with Filesystem Hierarchy Standard
59         A Wine installation should, as much as possible, comply
60         with the FHS standard (http://www.pathname.com/fhs/).
61                 
62     * Preserve flexibility
63         None of the flexibility built into Wine should
64         be hidden from the end user.
65
66     * Easy configuration
67         Come as preconfigured as possible, so the user does
68         not need to change any configuration files.
69
70     * Small footprint
71         Use only as much diskspace as needed per user.
72
73     * Reduce support requirements.
74         A packaged version of Wine should be sufficiently easy to use and
75         have quick and easy access to FAQs and documentation such that 
76         requests to the newsgroup and development group go down.
77         Further, it should be easy for users to capture good bug reports.
78
79 REQUIREMENTS
80 ~~~~~~~~~~~~
81
82 Successfully installing Wine requires:
83     * Much thought and work from the packager (1x)
84
85     * A configuration file
86         Wine will not run without a configuration file.  Wine provides a
87         a sample config file and it can be found in documentation/samples.
88         Some packagers may attempt to provide (or dynamically generate) a 
89         default configuration file. Some packagers may wish to rely on 
90         winesetup to generate the configuration file.
91
92     * A writeable C drive
93         A writeable C:\ directory structure on a per-user basis. 
94         Applications do dump .ini file into C:\WINDOWS, installer
95         dump .exe/.dll/etc. files into C:\WINDOWS or C:\Program Files.
96
97     * An initial set of registry entries.
98         The current Wine standard is to use the regedit tool against 
99         the 'winedefault.reg' file to generate a default registry.
100         The current preferred method of configuring/installing
101         Wine is to run /toos/wineinstall.  There are several other 
102         choices that could be made; registries can be imported from 
103         a Windows partition.  At this time, Wine does not completely 
104         support a complex multi-user installation ala Windows NT,
105         but it could fairly readily.
106
107      * Special files
108         Some special .dll and .exe files in the C:\WINDOWS\SYSTEM
109         directory, since applications directly check for their presence.
110
111 WINE COMPONENTS
112 ~~~~~~~~~~~~~~~
113
114    * Executable Files
115         - notepad : The windows Notepad replacement.
116         - progman : A Program Manager replacement.
117         - regedit : A command-line tool to edit your registry or for 
118                 important a windows registry to Wine.
119         - regsvr32 : A program to register/unregister .DLL's and .OCX files. 
120                 Only works on those dlls that can self-register.
121         - uninstaller: A program to uninstall installed Windows programs. 
122                 Like the Add/Remove Program in the windows control panel.
123         - wcmd :  Wine's command line interpreter, a cmd.exe replacement.
124         - widl : Wine IDL compiler compiles (MS-RPC and DCOM) Interface 
125                 Definition Language files.
126         - wine :  The main Wine executable. This program will load a Windows 
127                 binary and run it, relying upon the Wine shared object libraries.
128         - wineboot : This program is executed on startup of the first wine 
129                 process of a particular user.wineboot won't automatically run 
130                 when needed.  Currently you have to manually run it after you 
131                 install something.
132         - winebuild : Winebuild is a tool used for building Winelib applications 
133                 (and by Wine itself) to allow a developer to compile a .spec file 
134                 into a .spec.c file.
135         - wineclipserv : The Wine Clipboard Server is a standalone XLib application
136                 whose purpose is to manage the X selection when Wine exits.
137         - wineconsole : Render the output of CUI programs.
138         - winedbg : A application making use of the debugging API to allow 
139                 debugging of Wine or Winelib applications as well as Wine itself 
140                 (kernel and all DLLs).
141         - winedump : Dumps the imports and exports of NE and PE files.
142         - winefile : A clone of the win3x filemanager.
143         - winegcc/wineg++: Wrappers for gcc/g++ respectively, to make them behave 
144                 as MinGW's gcc. Used for porting apps over to Winelib.
145         - winemaker : Winemaker is a perl script which is designed to help you 
146                 bootstrap the conversion of your Windows projects to Winelib. 
147         - winemine :  A clone of "Windows Minesweeper" a demo WineLib app.
148         - winepath :  A tool for converting between Windows paths and Unix paths 
149         - wineserver : The Wine server is the process that manages resources, 
150                 coordinates threads, and provides synchronization and interprocess 
151                 communication primitives to Wine processes.
152         - wineshelllink : This shell script can be called by Wine in order to 
153                 propagate Desktop icon and menu creation requests out to a 
154                 GNOME or KDE (or other Window Managers).
155         - winewrap : Takes care of linking winelib applications. Linking with 
156                 Winelib is a complex process, winewrap makes it simple.
157         - winhelp : A Windows Help replacement.
158         - wmc : Wine Message Compiler it allows Windows message files to be 
159                 compiled into a format usable by Wine.
160         - wrc : the Wine Resource Compiler. A clone of Microsoft's rc.
161
162     * Shared Object Library Files
163         To obtain a current list of DLLs, run:
164                 ls dlls/*.so
165         it the root of the Wine _build_ tree, after a successful build.
166
167     * Man Pages
168         To obtain a current list of man files that need to be installed, run:
169                 find . -name "*.man"
170         it the root of the Wine _build_ tree, after you have run ./configure.
171
172     * Include Files
173         An up to date list of includes can be found in the include/Makefile.in file.
174
175     * Documentation files
176         After building the documentation with:
177                 cd documentation; make html
178         install all the files from: wine-user/, wine-devel/ and winelib-user/.
179
180      * Dynamic Wine Files
181         Wine also generates and depends on a number of dynamic
182         files, including user configuration files and registry files.
183
184         At the time of this writing, there was not a clear
185         consensus of where these files should be located, and how
186         they should be handled.  This section attempts
187         to explain the alternatives clearly.
188
189         - WINEPREFIX/config
190             This file is the user local Wine configuration file.
191             At the time of this writing, if this file exists,
192             then no other configuration file is loaded.
193
194         - ETCDIR/wine.conf
195             This is the global Wine configuration file. It is only used
196             if the user running Wine has no local configuration file.
197             Global wine configuration is currently not possible;
198             this might get reenabled at some time.
199             Some packagers feel that this file should not be supplied, 
200             and that only a wine.conf.default should be given here.
201             Other packagers feel that this file should be the predominant
202             file used, and that users should only shift to a local 
203             configuration file if they need to.  An argument has been
204             made that the local configuration file should inherit the 
205             global configuration file.  At this time, Wine does not do this;
206             please refer to the WineHQ discussion archives for the debate 
207             concerning this.
208             This debate is addressed more completely below, in the
209             'Packaging Strategy' section.
210
211     * Registry Files
212             In order to replicate the Windows registry system,
213             Wine stores registry entries in a series of files.
214
215             For an excellent overview of this issue, read this
216             http://www.winehq.com/News/2000-25.html#FTR
217             Wine Weekly News feature.
218
219             The bottom line is that, at Wine server startup,
220             Wine loads all registry entries into memory
221             to create an in memory image of the registry.
222             The order of files which Wine uses to load
223             registry entries is extremely important,
224             as it affects what registry entries are
225             actually present.  The order is roughly that
226             .dat files from a Windows partion are loaded,
227             then global registry settings from ETCDIR,
228             and then finally local registry settings are
229             loaded from WINEPREFIX.  As each set are loaded,
230             they can override the prior entries.  Thus,
231             the local registry files take precedence.
232
233             Then, at exit (or at periodic intervals),
234             Wine will write either all registry entries
235             (or, with the default setting) changed
236             registry entries to files in the WINEPREFIX.
237
238             - WINEPREFIX/system.reg
239                 This file contains the user's local copy of the 
240                 HKEY_LOCAL_MACHINE registry hive.  In general use, it will
241                 contain only changes made to the default registry values.
242
243             - WINEPREFIX/user.reg
244                 This file contains the user's local copy of the 
245                 HKEY_CURRENT_MACHINE registry hive.  In general use, it will
246                 contain only changes made to the default registry values.
247
248             - WINEPREFIX/userdef.reg
249                 This file contains the user's local copy of the 
250                 HKEY_USERS\.Default registry hive.  In general use, it will
251                 contain only changes made to the default registry values.
252
253             - WINEPREFIX/cachedmetrics.[display]
254                 This file contains font metrics for the given X display.
255                 Generally, this cache is generated once at Wine start time.
256                 cachedmetrics can be generated if absent. 
257                 You should note this can take a long time.
258
259             - ETCDIR/wine.systemreg 
260                 This file contains the global values for HKEY_LOCAL_MACHINE. 
261                 The values in this file can be overridden by the user's 
262                 local settings. The location of this directory is hardcoded 
263                 within wine, generally to /etc. 
264
265             - ETCDIR/wine.userreg
266                 This file contains the global values for HKEY_USERS.  
267                 The values in this file can be overridden by the user's 
268                 local settings.  This file is likely to be deprecated in
269                 favor of a global wine.userdef.reg that will only contain 
270                 HKEY_USERS/.Default.
271
272     * Important Files from a Windows Partition
273         Wine has the ability to use files from an installation of the
274         actual Microsoft Windows operating system.  Generally these
275         files are loaded on a VFAT partition that is mounted under Linux.
276
277         This is probably the most important configuration detail.
278         The use of Windows registry and DLL files dramatically alters the 
279         behaviour of Wine. If nothing else, pacakager have to make this 
280         distinction clear to the end user, so that they can intelligently
281         choose their configuration.
282
283         - WINDOWSDIR/system32/system.dat
284         - WINDOWSDIR/system32/user.dat
285         - WINDOWSDIR/win.ini
286
287     * Windows Dynamic Link Libraries (WINDOWSDIR/system32/*.dll)
288         Wine has the ability to use the actual Windows DLL files
289         when running an application.  An end user can configure
290         Wine so that Wine uses some or all of these DLL files
291         when running a given application.
292
293 PACKAGING STRATEGIES
294 ~~~~~~~~~~~~~~~~~~~~
295
296 There has recently been a lot of discussion on the Wine
297 development mailing list about the best way to build Wine packages.
298
299 There was a lot of discussion, and several diverging points of view.
300 This section of the document attempts to present the areas of common 
301 agreement, and also to present the different approaches advocated on 
302 the mailing list.
303
304     * Distribution of Wine into packages
305         The most basic question to ask is given the Wine CVS tree,
306         what physical files are you, the packager, going to produce?
307         Are you going to produce only a wine.rpm (as Marcus has done),
308         or are you going to produce 6 Debian files (libwine, libwine-dev,
309         wine, wine-doc, wine-utils and winesetuptk) as Ove has done?
310         At this point, common practice is to adopt to the conventions
311         of the targeted distribution. 
312
313     * Where to install files
314         This question is not really contested.  It will vary
315         by distribution, and is really up to the packager.
316         As a guideline, the current 'make install' process
317         seems to behave such that if we pick a single PREFIX then:
318             - binary files go into PREFIX/bin
319             - library files go into PREFIX/lib/wine
320             - include files go into PREFIX/include/wine
321             - man pages go into PREFIX/share/man
322             - documentation files go into PREFIX/share/doc/wine-VERSION
323
324         You might also want to use the wine wrapper script winelauncher
325         that can be found in tools/ directory, as it has several important
326         advantages over directly invoking the wine binary.
327         See the Executable Files section for details.
328
329     * The question of /opt/wine
330         The FHS 2.2 specification suggests that Wine as a package
331         should be installed to /opt/wine.  None of the existing packages 
332         follow this guideline (today; check again tomorrow).
333
334     * What files to create
335         After installing the static and shareable files, the next
336         question the packager needs to ask is how much dynamic
337         configuration will be done, and what configuration
338         files should be created.
339         There are several approaches to this:
340             - Rely completely on user file space - install nothing
341                 This approach relies upon the new winesetup utility
342                 and the new ability of Wine to launch winesetup if no
343                 configuration file is found.  The basic concept is
344                 that no global configuration files are created at
345                 install time.  Instead, Wine configuration files are
346                 created on the fly by the winesetup program when Wine
347                 is invoked.  Further, winesetup creates default
348                 Windows directories and paths that are stored
349                 completely in the user's WINEPREFIX.  This approach
350                 has the benefit of simplicity in that all Wine files
351                 are either stored under /opt/wine or under ~/.wine.
352                 Further, there is only ever one Wine configuration
353                 file.  This approach, however, adds another level of
354                 complexity.  It does not allow Wine to run Solitaire
355                 'out of the box'; the user must run the configuration
356                 program first.  Further, winesetup requires Tcl/Tk, a
357                 requirement not beloved by some.  Additionally, this
358                 approach closes the door on multi user configurations
359                 and presumes a single user approach.
360
361             - Build a reasonable set of defaults for the global wine.conf,
362               facilitate creation of a user's local Wine configuration.
363                 This approach, best shown by Marcus, causes the
364                 installation process to auto scan the system,
365                 and generate a global wine.conf file with best
366                 guess defaults.  The OpenLinux packages follow
367                 this behaviour.
368                 The keys to this approach are always putting
369                 an existing Windows partition into the
370                 path, and being able to run Solitaire
371                 right out of the box.
372                 Another good thing that Marcus does is he
373                 detects a first time installation and
374                 does some clever things to improve the
375                 user's Wine experience.
376                 A flaw with this approach, however, is it doesn't
377                 give the user an obvious way to choose not to
378                 use a Windows partition.
379
380             - Build a reasonable set of defaults for the global wine.conf,
381               and ask the user if possible
382                 This approach, demonstrated by Ove, causes the
383                 installation process to auto scan the system,
384                 and generate a global wine.conf file with best
385                 guess defaults.  Because Ove built a Debian
386                 package, he was able to further query debconf and
387                 get permission to ask the user some questions,
388                 allowing the user to decide whether or not to
389                 use a Windows partition.
390
391 IMPLEMENTATION
392 ~~~~~~~~~~~~~~
393
394 This section discusses the implementation of a Red Hat 8.0 .spec file.
395 For a current .spec file, please refer to any one of the existing SRPMs.
396
397 1. Building the package
398
399 Wine is configured the usual way (depending on your build environment). 
400 The PREFIX is chosen using your application placement policy
401 (/usr/, /usr/X11R6/, /opt/wine/, or similar).  The configuration files
402 (wine.conf, wine.userreg, wine.systemreg) are targeted for /etc/wine/
403 (rationale: FHS 2.2, multiple readonly configuration files of a package).
404
405 Example (split this into %build and %install section for rpm:
406
407
408         CFLAGS=$RPM_OPT_FLAGS ./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
409         make
410         BR=$RPM_BUILD_ROOT
411         make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/
412         install -d $BR/etc/wine/
413         install -m 644 wine.ini $BR/etc/wine/wine.conf
414
415         # Put all our DLLs in a separate directory. (this works only if you have a buildroot)
416         install -d $BR/usr/X11R6/lib/wine
417         mv $BR/usr/X11R6/lib/lib* $BR/usr/X11R6/lib/wine/
418
419         # the clipboard server is started on demand.
420         install -m 755 dlls/x11drv/wineclipsrv $BR/usr/X11R6/bin/
421
422         # The Wine server is needed.
423         install -m 755 server/wineserver $BR/usr/X11R6/bin/
424
425 Here we unfortunately do need to create wineuser.reg and winesystem.reg
426 from the Wine distributed winedefault.reg. This can be done using regedit
427 once for one example user and then reusing his WINEPREFIX/user.reg and
428 WINEPREFIX/system.reg files.
429 FIXME: this needs to be done better.
430
431         install -m 644 wine.sytemreg $BR/etc/wine/
432         install -m 644 wine.userreg $BR/etc/wine/
433
434 There are now a lot of libraries generated by the build process, so a 
435 separate library directory should be used.
436
437         install -d 755 $BR/usr/X11R6/lib/
438         mv $BR/
439         
440 You will need to package the files:
441
442         $prefix/bin/wine, $prefix/bin/dosmod, $prefix/lib/wine/*
443         $prefix/man/man1/wine.1, $prefix/include/wine/*,
444         $prefix/bin/wineserver, $prefix/bin/wineclipsrv
445
446         %config /etc/wine/*
447         %doc ... choose from the toplevel directory and documentation/
448
449 The post-install script:
450
451         if ! grep /usr/X11R6/lib/wine /etc/ld.so.conf >/dev/null; then
452             echo "/usr/X11R6/lib/wine" >> /etc/ld.so.conf
453         fi
454         /sbin/ldconfig
455
456 The post-uninstall script:
457
458         if [ "$1" = 0 ]; then
459             perl -ni -e 'print unless m:/usr/X11R6/lib/wine:;' /etc/ld.so.conf
460         fi
461         /sbin/ldconfig
462
463 2. Creating a good default configuration file. 
464
465 For the rationales of needing as less input from the user as possible arises 
466 the need for a very good configuration file. The one supplied with Wine is 
467 currently lacking. We need:
468
469     * [Drive X]: 
470         - A for the floppy. Specify your distribution's default floppy mountpoint.
471                 Path=/auto/floppy
472         - C for the C:\ directory. Here we use the user's home directory, for most
473           applications do see C:\ as root-writeable directory of every windows
474           installation and this basically is it in the UNIX-user context.
475           Don't forget to identify environment variables as DOS ones (ie, surrounded by '%').
476                 Path=%HOME%
477         - R for the CD-Rom drive. Specify your distribution's default CD-ROM mountpoint.
478                 Path=/auto/cdrom
479         - T for temporary storage. We do use /tmp/ (rationale: between process 
480           temporary data belongs to /tmp/ , FHS 2.0)
481                 Path=/tmp/
482         - W for the original Windows installation. This drive points to the
483           WINDOWSDIR subdirectory of the original windows installation.
484           This avoids problems with renamed WINDOWSDIR directories (as for 
485           instance lose95, win or sys\win95). During compile/package/install
486           we leave this to be / , it has to be configured after the package install.
487         - Z for the UNIX Root directory. This avoids any roblems with 
488           "could not find drive for current directory" users occasionally complain
489           about in the newsgroup and the irc channel. It also makes the whole 
490           directory structure browseable. The type of Z should be network,
491           so applications expect it to be readonly.
492                 Path=/
493           
494     * [wine]:
495         Windows=c:\windows\             (the windows/ subdirectory in the user's
496                                  home directory)
497         System=c:\windows\system\       (the windows/system subdirectory in the user's
498                                          home directory)
499         Path=c:\windows;c:\windows\system;c:\windows\system32;w:\;w:\system;w:\system32;
500         ; Using this trick we have in fact two windows installations in one, we
501         ; get the stuff from the readonly installation and can write to our own.
502         Temp=t:\                        (the TEMP directory)
503
504     * [Tweak.Layout]
505         WineLook=win95                (just the coolest look ;)
506
507     * Possibly modify the [spooler], [serialports] and [parallelports] sections.
508       FIXME: possibly more, including printer stuff.
509
510 Add this prepared configuration file to the package.
511
512 3. Installing Wine for the system administrator
513                 
514 Install the package using the usual packager 'rpm -i wine.rpm'.
515 You may edit /etc/wine/wine.conf , [Drive W], to point to a
516 possible Windows installation right after the install. That's it.
517
518 Note that on Linux you should somehow try to add the unhide mount optioni
519 (see 'man mount') to the CD-ROM entry in /etc/fstab during package install,
520 as several stupid Windows programs mark some setup (!) files as hidden 
521 (ISO9660) on CD-ROMs, which will greatly confuse users as they won't find 
522 their setup files on the CD-ROMs as they were used on Windows systems when
523 unhide is not set ;-\ And of course the setup program will complain
524 that setup.ins or some other mess is missing... If you choose to do so, 
525 then please make this change verbose to the admin.
526
527 Also make sure that the kernel you use includes the Joliet CD-ROM support, 
528 for the very same reasons as given above (no long filenames due to missing 
529 Joliet, files not found).
530               
531 4. Installing Wine for the user
532
533 The user will need to run a setup script before the first invocation of Wine. 
534 This script should:
535     * Copy /etc/wine/wine.conf for user modification.
536     * Allow specification of the original windows installation to use
537       (which modifies the copied wine.conf file).
538     * Create the windows directory structure (c:\windows, c:\windows\system,
539       c:\windows\Start Menu\Programs, c:\Program Files, c:\Desktop, etc.)
540     * Symlink all .dll and .exe files from the original windows installation
541       to the windows directory. Why? Some programs reference 
542       "%windowsdir%/file.dll" or "%systemdir%/file.dll" directly and fail
543       if they are not present.  This will give a huge number of symlinks, yes.
544       However, if an installer later overwrites one of those files, it will 
545       overwrite the symlink (so that the file now lies in the windows/
546       subdirectory). FIXME: Not sure this is needed for all files.
547     * On later invocation the script might want to compare regular files in 
548       the user's windows directories and in the global windows directories
549       and replace same files by symlinks (to avoid diskspace problems).
550     
551 AUTHORS
552 ~~~~~~~
553
554 Written in 1999 by Marcus Meissner <marcus@jet.franken.de>
555 Updated in 2000 by Jeremy White <jwhite@codeweavers.com>
556 Updated in 2002 by Andreas Mohr <andi@rhlx01.fht-esslingen.de>
557 Updated in 2003 by Tom Wickline <twickline2@triad.rr.com>
558 Updated in 2003 by Dimitrie O. Paun <dpaun@rogers.com>