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