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