- implement _dup, _dup2, and _pipe
[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 DEPENDENCIES
46 ~~~~~~~~~~~~
47
48 There are two types of dependencies: hard and soft dependencies.
49
50 A hard dependency must be available at runtime for Wine to function,
51 if  compiled into the code. Soft dependencies on the other hand
52 will degrade gracefully at runtime if unavailable on the runtime system.
53 Ideally, we should eliminate all hard dependencies in favor of
54 soft dependencies.
55
56 To enable a soft dependency, it must be available at compile time.
57 As a packager, please do your best to make sure that as many soft 
58 dependencies  are available during compilation. Failing to have a 
59 soft dependency available means that users cannot benefit
60 from a Wine capability.
61
62 Here is a list of the soft dependencies. We suggest packagers
63 install each and every last of those before building the package. 
64 These libraries are not dependencies in the RPM sense. In DEB packages, 
65 they should appear as "Suggests" or "Recommends", as the case may be.
66     * FreeType: http://www.freetype.org
67       This library is used for direct rendering of fonts. It provides 
68       better support of fonts than using the X11 fonts engine. It is 
69       only needed for the X11 back end engine. Used from GDI.
70
71     * fontconfig
72       Used to find TrueType fonts for rendering with freetype. Used by
73       GDI.
74
75     * Alsa: http://sourceforge.net/projects/alsa (Linux only)
76       This library gives sound support to the Windows environment.
77
78     * JACK: http://jackit.sourceforge.net
79       Similar to Alsa, it allow Wine to use the JACK audio server.
80
81     * CUPS: http://www.cups.org
82       This library allows Windows to see CUPS defined printers. Used
83       by WINEPS and WINSPOOL.
84
85     * OpenGL
86       This is used for both OpenGL and Direct3D (and some other 
87       DirectX functions as well) support in Wine. There are many many 
88       libraries for providing this functionality. It is enough for one
89       of them to be available when compiling Wine. Wine can work with 
90       any other library during runtime.
91       If no library is available, packagers are encouraged to compile 
92       Wine with Mesa3D (http://www.mesa3d.org), which requires no 
93       hardware support to install.
94
95     * LittleCMS: http://www.littlecms.com
96       This library is used to implement MSCMS (Color Management System)
97       which is needed by an increasing number of graphics applications.
98     
99     * libjpeg
100       This library is used to load JPEG files within OLE automation.
101
102     * libungif or gif_lib
103       One of these two libraries is used to load GIF files within OLE
104       automation.
105
106     * ICU
107       Used for bidirectional character output. Linked statically, used
108       by GDI.
109
110     * sane
111       Used for basic scanner support in our TWAIN32 library.
112
113     * openssl
114       Used for some cryptographic support in ADVAPI32.
115  
116     * Xrandr, Xrender, Xi, Xext
117       X11 extension libraries used by the x11drv.
118       Xrandr - resolution switching
119       Xrender - client side font rendering
120       Xi - X Input handling (for asian input methods mostly)
121       Xext - X extensions
122
123 GOALS
124 ~~~~~
125
126 An installation from a Wine package should:
127     * Install quickly and simply:
128         The initial installation should require no user input.  An 
129                 'rpm -i wine.rpm' or 'apt-get install wine'
130         should suffice for initial installation.
131                 
132     * Work quickly and simply:
133         The user should be able to launch Solitaire within seconds
134         of downloading the Wine package.
135               
136     * Comply with File system Hierarchy Standard
137         A Wine installation should, as much as possible, comply
138         with the FHS standard (http://www.pathname.com/fhs/).
139                 
140     * Preserve flexibility
141         None of the flexibility built into Wine should
142         be hidden from the end user.
143
144     * Easy configuration
145         Come as preconfigured as possible, so the user does
146         not need to change any configuration files.
147
148     * Small footprint
149         Use only as much disk space as needed per user.
150
151     * Reduce support requirements.
152         A packaged version of Wine should be sufficiently easy to use and
153         have quick and easy access to FAQs and documentation such that 
154         requests to the newsgroup and development group go down.
155         Further, it should be easy for users to capture good bug reports.
156
157 REQUIREMENTS
158 ~~~~~~~~~~~~
159
160 Successfully installing Wine requires:
161
162     * Install the RPM.
163
164     * No longer: A configuration file
165
166         Wine will run without a configuration file at this time.  Wine
167         provides a sample config file and it can be found in
168         documentation/samples.
169
170         Some packagers may attempt to provide (or dynamically generate) a 
171         default configuration file. Some packagers may copy this on
172         startup, but it is no longer necessary.
173
174     * No longer: Preparing a fake windows setup.
175
176         If WINEPREFIX is not present, wine will generate a setup
177         by itself by calling wineprefixcreate.
178
179         This will load all default registry entries, and register dlls
180         where necessary. A special "wine.inf" file is provided with
181         the WINE sources and installed to /usr/share/wine/.
182
183 WINE COMPONENTS
184 ~~~~~~~~~~~~~~~
185
186    * Executable Files
187         - notepad : The windows Notepad replacement.
188         - progman : A Program Manager replacement.
189         - regedit : A graphical tool to edit your registry or for 
190                 importing a windows registry to Wine.
191         - regsvr32 : A program to register/unregister .DLL's and .OCX files. 
192                 Only works on those dlls that can self-register.
193         - taskmgr : A clone of the windows taskmgr, used for debugging and
194                 managing running Windows and Winlib processes.
195         - uninstaller: A program to uninstall installed Windows programs. 
196                 Like the Add/Remove Program in the windows control panel.
197         - wcmd :  Wine's command line interpreter, a cmd.exe replacement.
198         - widl : Wine IDL compiler compiles (MS-RPC and DCOM) Interface 
199                 Definition Language files.
200         - wine :  The main Wine executable. This program will load a Windows 
201                 binary and run it, relying upon the Wine shared object libraries.
202         - wineboot : This program is executed on startup of the first wine 
203                 process of a particular user.wineboot won't automatically run 
204                 when needed.  Currently you have to manually run it after you 
205                 install something.
206         - winebuild : Winebuild is a tool used for building Winelib applications 
207                 (and by Wine itself) to allow a developer to compile a .spec file 
208                 into a .spec.c file.
209         - wineconsole : Render the output of CUI programs.
210         - winedbg : A application making use of the debugging API to allow 
211                 debugging of Wine or Winelib applications as well as Wine itself 
212                 (kernel and all DLLs).
213         - winedump : Dumps the imports and exports of NE and PE files.
214         - winefile : A clone of the win3x file manager.
215         - winegcc/wineg++: Wrappers for gcc/g++ respectively, to make them behave 
216                 as MinGW's gcc. Used for porting apps over to Winelib.
217         - winemaker : Winemaker is a perl script which is designed to help you 
218                 bootstrap the conversion of your Windows projects to Winelib. 
219         - winemine :  A clone of "Windows Minesweeper" a demo WineLib app.
220         - winepath :  A tool for converting between Windows paths and Unix paths 
221         - wineserver : The Wine server is the process that manages resources, 
222                 coordinates threads, and provides synchronization and interprocess 
223                 communication primitives to Wine processes.
224         - wineshelllink : This shell script can be called by Wine in order to 
225                 propagate Desktop icon and menu creation requests out to a 
226                 GNOME or KDE (or other Window Managers).
227         - winewrap : Takes care of linking winelib applications. Linking with 
228                 Winelib is a complex process, winewrap makes it simple.
229         - winhelp : A Windows Help replacement.
230         - wmc : Wine Message Compiler it allows Windows message files to be 
231                 compiled into a format usable by Wine.
232         - wrc : the Wine Resource Compiler. A clone of Microsoft's rc.
233
234     * Shared Object Library Files
235         To obtain a current list of DLLs, run:
236                 ls dlls/*.so
237         it the root of the Wine _build_ tree, after a successful build.
238
239     * Man Pages
240         To obtain a current list of man files that need to be installed, run:
241                 find . -name "*.man"
242         it the root of the Wine _build_ tree, after you have run ./configure.
243
244     * Include Files
245         An up to date list of includes can be found in the include/Makefile.in
246         file.
247
248     * Documentation files
249         After building the documentation with:
250                 cd documentation; make html
251         install all the files from: wine-user/, wine-devel/ and winelib-user/.
252
253      * Dynamic Wine Files
254         Wine also generates and depends on a number of dynamic
255         files, including user configuration files and registry files.
256
257         At the time of this writing, there was not a clear
258         consensus of where these files should be located, and how
259         they should be handled.  This section attempts
260         to explain the alternatives clearly.
261
262         - WINEPREFIX/config
263             This file is the user local Wine configuration file.
264             At the time of this writing, if this file exists,
265             then no other configuration file is loaded.
266
267         - PREFIX/share/wine.inf
268         
269             This is the global Wine setup information file
270             in the format of a MS Installer .INF file.
271
272     * Registry Files
273             In order to replicate the Windows registry system,
274             Wine stores registry entries in a series of files.
275
276             For an excellent overview of this issue, read this
277             http://www.winehq.org/News/2000-25.html#FTR
278             Wine Weekly News feature.
279
280             The bottom line is that, at Wine server startup,
281             Wine loads all registry entries into memory
282             to create an in memory image of the registry.
283             The order of files which Wine uses to load
284             registry entries is extremely important,
285             as it affects what registry entries are
286             actually present.  The order is roughly that
287             .dat files from a Windows partition are loaded,
288             and then finally local registry settings are
289             loaded from WINEPREFIX.  As each set are loaded,
290             they can override the prior entries.  Thus,
291             the local registry files take precedence.
292
293             Then, at exit (or at periodic intervals),
294             Wine will write either all registry entries
295             (or, with the default setting) changed
296             registry entries to files in the WINEPREFIX.
297
298             - WINEPREFIX/system.reg
299                 This file contains the user's local copy of the 
300                 HKEY_LOCAL_MACHINE registry hive.  In general use, it will
301                 contain only changes made to the default registry values.
302
303             - WINEPREFIX/user.reg
304                 This file contains the user's local copy of the 
305                 HKEY_CURRENT_MACHINE registry hive.  In general use, it will
306                 contain only changes made to the default registry values.
307
308             - WINEPREFIX/userdef.reg
309                 This file contains the user's local copy of the 
310                 HKEY_USERS\.Default registry hive.  In general use, it will
311                 contain only changes made to the default registry values.
312
313             - WINEPREFIX/cachedmetrics.[display]
314                 This file contains font metrics for the given X display.
315                 Generally, this cache is generated once at Wine start time.
316                 cachedmetrics can be generated if absent. 
317                 You should note this can take a long time.
318
319             - ETCDIR/wine.systemreg 
320                 This file contains the global values for HKEY_LOCAL_MACHINE. 
321                 The values in this file can be overridden by the user's 
322                 local settings. The location of this directory is hard coded 
323                 within wine, generally to /etc. 
324
325             - ETCDIR/wine.userreg
326                 This file contains the global values for HKEY_USERS.  
327                 The values in this file can be overridden by the user's 
328                 local settings.  This file is likely to be deprecated in
329                 favor of a global wine.userdef.reg that will only contain 
330                 HKEY_USERS/.Default.
331
332     * Important Files from a Windows Partition
333         Wine has the ability to use files from an installation of the
334         actual Microsoft Windows operating system.  Generally these
335         files are loaded on a VFAT partition that is mounted under Linux.
336
337         This is probably the most important configuration detail.
338         The use of Windows registry and DLL files dramatically alters the 
339         behavior of Wine. If nothing else, packagers have to make this 
340         distinction clear to the end user, so that they can intelligently
341         choose their configuration.
342
343         - WINDOWSDIR/system32/system.dat
344         - WINDOWSDIR/system32/user.dat
345         - WINDOWSDIR/win.ini
346
347     * Windows Dynamic Link Libraries (WINDOWSDIR/system32/*.dll)
348         Wine has the ability to use the actual Windows DLL files
349         when running an application.  An end user can configure
350         Wine so that Wine uses some or all of these DLL files
351         when running a given application.
352
353 PACKAGING STRATEGIES
354 ~~~~~~~~~~~~~~~~~~~~
355
356 There has recently been a lot of discussion on the Wine development
357 mailing list about the best way to build Wine packages.
358
359 There was a lot of discussion, and several diverging points of view.
360 This section of the document attempts to present the areas of common
361 agreement, and also to present the different approaches advocated on
362 the mailing list.
363
364     * Distribution of Wine into packages
365         The most basic question to ask is given the Wine CVS tree,
366         what physical files are you, the packager, going to produce?
367         Are you going to produce only a wine.rpm, or are you going to
368         produce 6 Debian files (libwine, libwine-dev, wine, wine-doc,
369         wine-utils and winesetuptk) as Ove has done?
370         At this point, common practice is to adopt to the conventions
371         of the targeted distribution.
372
373         Also, experience shows that you should not create a huge set
374         of packages, since later upgrades and obsoleting will be
375         painful.
376
377     * Where to install files
378         This question is not really contested.  It will vary
379         by distribution, and is really up to the packager.
380         As a guideline, the current 'make install' process
381         seems to behave such that if we pick a single PREFIX then:
382             - binary files go into PREFIX/bin
383             - library files go into PREFIX/lib/wine
384             - include files go into PREFIX/include/wine
385             - man pages go into PREFIX/share/man
386             - documentation files go into PREFIX/share/doc/wine-VERSION
387
388         You might also want to use the wine wrapper script winelauncher
389         that can be found in tools/ directory, as it has several important
390         advantages over directly invoking the wine binary.
391         See the Executable Files section for details.
392
393     * The question of /opt/wine
394         The FHS 2.2 specification suggests that Wine as a package
395         should be installed to /opt/wine.  None of the existing packages 
396         follow this guideline (today; check again tomorrow).
397
398         (Since most are upgrades of the distro packages, this is still
399          on the safe side I think - Marcus Meissner)
400
401     * What files to create
402         After installing the static and shareable files, the next
403         question the packager needs to ask is how much dynamic
404         configuration will be done, and what configuration
405         files should be created.
406
407         The best current approach to this is:
408         - Leave it alone and make a "wineprefixcreate" call available
409           to the user via a menu item or similar.
410
411         - Setup a fake windows setup automatically.
412                 
413                 This is done by simply calling wineprefixcreate, 
414                 which will setup a fake windows root for the user.
415
416                 If no arguments are passed, defaults will be 
417                 assumed for WINEPREFIX (~/.wine) and similar
418                 variables.
419
420                 After this, WINE is immediately usable by the
421                 end user.
422
423         - Others might be possible.
424
425 IMPLEMENTATION
426 ~~~~~~~~~~~~~~
427
428 This section discusses the implementation of a Red Hat 8.0 .spec file.
429 For a current .spec file, please refer to any one of the existing SRPMs.
430
431 1. Building the package
432
433 Wine is configured the usual way (depending on your build environment). 
434 The PREFIX is chosen using your application placement policy
435 (/usr/, /usr/X11R6/, /opt/wine/, or similar).  The configuration files
436 (wine.conf, wine.userreg, wine.systemreg) are targeted for /etc/wine/
437 (rationale: FHS 2.2, multiple read only configuration files of a package).
438
439 Example (split this into %build and %install section for rpm:
440
441
442         CFLAGS="$RPM_OPT_FLAGS" ./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
443         make
444         BR=$RPM_BUILD_ROOT
445         make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/
446
447 You will need to package the files:
448
449         $prefix/bin/wine*
450         $prefix/lib/libwine*
451         $prefix/lib/wine/*,
452         $prefix/share/wine/wine.inf
453
454         $prefix/man/man1/wine.1
455         $prefix/include/wine/*
456         $prefix/bin/notepad
457         $prefix/bin/progman
458         $prefix/bin/regedit
459         $prefix/bin/rundll32
460         $prefix/bin/regsvr32
461         $prefix/bin/wcmd
462         $prefix/bin/widl
463         $prefix/bin/winhelp
464
465         %config /etc/wine/*
466         %doc ... choose from the top level directory and documentation/
467
468 2. Creating a good default configuration file. 
469
470 This is no longer necessary, most of this work is now done
471 by wineprefixcreate itself.
472
473
474 3. Installing Wine for the system administrator
475                 
476 Install the package using the usual packager 'rpm -i wine.rpm'.
477
478 Adapting the $prefix/share/wine/wine.inf file used by wineprefixcreate is not
479 necessary.
480
481 Note that on Linux you should somehow try to add the unhide mount option
482 (see 'man mount') to the CD-ROM entry in /etc/fstab during package install,
483 as several stupid Windows programs mark some setup (!) files as hidden 
484 (ISO9660) on CD-ROMs, which will greatly confuse users as they won't find 
485 their setup files on the CD-ROMs as they were used on Windows systems when
486 unhide is not set ;-\ And of course the setup program will complain
487 that setup.ins or some other mess is missing... If you choose to do so, 
488 then please make this change verbose to the admin.
489
490 Also make sure that the kernel you use includes the Joliet CD-ROM support, 
491 for the very same reasons as given above (no long filenames due to missing 
492 Joliet, files not found).
493               
494 4. Installing Wine for the user
495
496 The user will need to run a wineprefixcreate before the first invocation
497 of Wine.
498
499 A packager might provide a wrapper for wine to do that automatically,
500 like if the WINEPREFIX directory (~/.wine) is not present.
501
502 Thats it.
503
504 AUTHORS
505 ~~~~~~~
506
507 Written in 1999 by Marcus Meissner <marcus@jet.franken.de>
508 Updated in 2000 by Jeremy White <jwhite@codeweavers.com>
509 Updated in 2002 by Andreas Mohr <andi@rhlx01.fht-esslingen.de>
510 Updated in 2003 by Tom Wickline <twickline2@triad.rr.com>
511 Updated in 2003 by Dimitrie O. Paun <dpaun@rogers.com>
512 Updated in 2004 by Marcus Meissner <marcus@jet.franken.de>