4 This document attempts to establish guidelines for people making binary
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
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.
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.
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.
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.
48 There are two types of dependencies: hard and soft dependencies.
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 favour of
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.
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.
71 * Alsa: http://sourceforge.net/projects/alsa (Linux only)
72 This library gives sound support to the Windows environment.
74 * JACK: http://jackit.sourceforge.net
75 Similar to Alsa, it allow Wine to use the JACK audio server.
77 * CUPS: http://www.cups.org
78 This library allows Windows to see CUPS defined printers.
81 This is used for both OpenGL and Direct3D (and some other
82 DirectX functions as well) support in Wine. There are many many
83 libraries for providing this functionality. It is enough for one
84 of them to be available when compiling Wine. Wine can work with
85 any other library during runtime.
86 If no library is available, packagers are encouraged to compile
87 Wine with Mesa3D (http://www.mesa3d.org), which requires no
88 hardware support to install.
90 * LittleCMS: http://www.littlecms.com
91 This library is used to implement MSCMS (Color Management System)
92 which is needed by an increasing number of graphics applications.
97 An installation from a Wine package should:
98 * Install quickly and simply:
99 The initial installation should require no user input. An
100 'rpm -i wine.rpm' or 'apt-get install wine'
101 should suffice for initial installation.
103 * Work quickly and simply:
104 The user should be able to launch Solitaire
105 within minutes of downloading the Wine package.
107 * Comply with Filesystem Hierarchy Standard
108 A Wine installation should, as much as possible, comply
109 with the FHS standard (http://www.pathname.com/fhs/).
111 * Preserve flexibility
112 None of the flexibility built into Wine should
113 be hidden from the end user.
116 Come as preconfigured as possible, so the user does
117 not need to change any configuration files.
120 Use only as much diskspace as needed per user.
122 * Reduce support requirements.
123 A packaged version of Wine should be sufficiently easy to use and
124 have quick and easy access to FAQs and documentation such that
125 requests to the newsgroup and development group go down.
126 Further, it should be easy for users to capture good bug reports.
131 Successfully installing Wine requires:
132 * Much thought and work from the packager (1x)
134 * A configuration file
135 Wine will not run without a configuration file. Wine provides a
136 a sample config file and it can be found in documentation/samples.
137 Some packagers may attempt to provide (or dynamically generate) a
138 default configuration file. Some packagers may wish to rely on
139 winesetup to generate the configuration file.
141 * A writeable C drive
142 A writeable C:\ directory structure on a per-user basis.
143 Applications do dump .ini file into C:\WINDOWS, installer
144 dump .exe/.dll/etc. files into C:\WINDOWS or C:\Program Files.
146 * An initial set of registry entries.
147 For custom changes to the default registry, tools/wine.inf
148 can be modified as needed. The current preferred method of
149 configuring/installing Wine is to run /tools/wineinstall.
150 There are several other choices that could be made; registries
151 can be imported from a Windows partition. At this time, Wine
152 does not completely support a complex multi-user installation
153 ala Windows NT, but it could fairly readily.
156 Some special .dll and .exe files in the C:\WINDOWS\SYSTEM
157 directory, since applications directly check for their presence.
163 - notepad : The windows Notepad replacement.
164 - progman : A Program Manager replacement.
165 - regedit : A graphical tool to edit your registry or for
166 important a windows registry to Wine.
167 - regsvr32 : A program to register/unregister .DLL's and .OCX files.
168 Only works on those dlls that can self-register.
169 - taskmgr : A clone of the windows taskmgr, used for debugging and
170 managing running Windows and Winlib processes.
171 - uninstaller: A program to uninstall installed Windows programs.
172 Like the Add/Remove Program in the windows control panel.
173 - wcmd : Wine's command line interpreter, a cmd.exe replacement.
174 - widl : Wine IDL compiler compiles (MS-RPC and DCOM) Interface
175 Definition Language files.
176 - wine : The main Wine executable. This program will load a Windows
177 binary and run it, relying upon the Wine shared object libraries.
178 - wineboot : This program is executed on startup of the first wine
179 process of a particular user.wineboot won't automatically run
180 when needed. Currently you have to manually run it after you
182 - winebuild : Winebuild is a tool used for building Winelib applications
183 (and by Wine itself) to allow a developer to compile a .spec file
185 - wineconsole : Render the output of CUI programs.
186 - winedbg : A application making use of the debugging API to allow
187 debugging of Wine or Winelib applications as well as Wine itself
188 (kernel and all DLLs).
189 - winedump : Dumps the imports and exports of NE and PE files.
190 - winefile : A clone of the win3x filemanager.
191 - winegcc/wineg++: Wrappers for gcc/g++ respectively, to make them behave
192 as MinGW's gcc. Used for porting apps over to Winelib.
193 - winemaker : Winemaker is a perl script which is designed to help you
194 bootstrap the conversion of your Windows projects to Winelib.
195 - winemine : A clone of "Windows Minesweeper" a demo WineLib app.
196 - winepath : A tool for converting between Windows paths and Unix paths
197 - wineserver : The Wine server is the process that manages resources,
198 coordinates threads, and provides synchronization and interprocess
199 communication primitives to Wine processes.
200 - wineshelllink : This shell script can be called by Wine in order to
201 propagate Desktop icon and menu creation requests out to a
202 GNOME or KDE (or other Window Managers).
203 - winewrap : Takes care of linking winelib applications. Linking with
204 Winelib is a complex process, winewrap makes it simple.
205 - winhelp : A Windows Help replacement.
206 - wmc : Wine Message Compiler it allows Windows message files to be
207 compiled into a format usable by Wine.
208 - wrc : the Wine Resource Compiler. A clone of Microsoft's rc.
210 * Shared Object Library Files
211 To obtain a current list of DLLs, run:
213 it the root of the Wine _build_ tree, after a successful build.
216 To obtain a current list of man files that need to be installed, run:
218 it the root of the Wine _build_ tree, after you have run ./configure.
221 An up to date list of includes can be found in the include/Makefile.in file.
223 * Documentation files
224 After building the documentation with:
225 cd documentation; make html
226 install all the files from: wine-user/, wine-devel/ and winelib-user/.
229 Wine also generates and depends on a number of dynamic
230 files, including user configuration files and registry files.
232 At the time of this writing, there was not a clear
233 consensus of where these files should be located, and how
234 they should be handled. This section attempts
235 to explain the alternatives clearly.
238 This file is the user local Wine configuration file.
239 At the time of this writing, if this file exists,
240 then no other configuration file is loaded.
243 This is the global Wine configuration file. It is only used
244 if the user running Wine has no local configuration file.
245 Global wine configuration is currently not possible;
246 this might get reenabled at some time.
247 Some packagers feel that this file should not be supplied,
248 and that only a wine.conf.default should be given here.
249 Other packagers feel that this file should be the predominant
250 file used, and that users should only shift to a local
251 configuration file if they need to. An argument has been
252 made that the local configuration file should inherit the
253 global configuration file. At this time, Wine does not do this;
254 please refer to the WineHQ discussion archives for the debate
256 This debate is addressed more completely below, in the
257 'Packaging Strategy' section.
260 In order to replicate the Windows registry system,
261 Wine stores registry entries in a series of files.
263 For an excellent overview of this issue, read this
264 http://www.winehq.org/News/2000-25.html#FTR
265 Wine Weekly News feature.
267 The bottom line is that, at Wine server startup,
268 Wine loads all registry entries into memory
269 to create an in memory image of the registry.
270 The order of files which Wine uses to load
271 registry entries is extremely important,
272 as it affects what registry entries are
273 actually present. The order is roughly that
274 .dat files from a Windows partion are loaded,
275 then global registry settings from ETCDIR,
276 and then finally local registry settings are
277 loaded from WINEPREFIX. As each set are loaded,
278 they can override the prior entries. Thus,
279 the local registry files take precedence.
281 Then, at exit (or at periodic intervals),
282 Wine will write either all registry entries
283 (or, with the default setting) changed
284 registry entries to files in the WINEPREFIX.
286 - WINEPREFIX/system.reg
287 This file contains the user's local copy of the
288 HKEY_LOCAL_MACHINE registry hive. In general use, it will
289 contain only changes made to the default registry values.
291 - WINEPREFIX/user.reg
292 This file contains the user's local copy of the
293 HKEY_CURRENT_MACHINE registry hive. In general use, it will
294 contain only changes made to the default registry values.
296 - WINEPREFIX/userdef.reg
297 This file contains the user's local copy of the
298 HKEY_USERS\.Default registry hive. In general use, it will
299 contain only changes made to the default registry values.
301 - WINEPREFIX/cachedmetrics.[display]
302 This file contains font metrics for the given X display.
303 Generally, this cache is generated once at Wine start time.
304 cachedmetrics can be generated if absent.
305 You should note this can take a long time.
307 - ETCDIR/wine.systemreg
308 This file contains the global values for HKEY_LOCAL_MACHINE.
309 The values in this file can be overridden by the user's
310 local settings. The location of this directory is hardcoded
311 within wine, generally to /etc.
313 - ETCDIR/wine.userreg
314 This file contains the global values for HKEY_USERS.
315 The values in this file can be overridden by the user's
316 local settings. This file is likely to be deprecated in
317 favor of a global wine.userdef.reg that will only contain
320 * Important Files from a Windows Partition
321 Wine has the ability to use files from an installation of the
322 actual Microsoft Windows operating system. Generally these
323 files are loaded on a VFAT partition that is mounted under Linux.
325 This is probably the most important configuration detail.
326 The use of Windows registry and DLL files dramatically alters the
327 behaviour of Wine. If nothing else, pacakager have to make this
328 distinction clear to the end user, so that they can intelligently
329 choose their configuration.
331 - WINDOWSDIR/system32/system.dat
332 - WINDOWSDIR/system32/user.dat
335 * Windows Dynamic Link Libraries (WINDOWSDIR/system32/*.dll)
336 Wine has the ability to use the actual Windows DLL files
337 when running an application. An end user can configure
338 Wine so that Wine uses some or all of these DLL files
339 when running a given application.
344 There has recently been a lot of discussion on the Wine
345 development mailing list about the best way to build Wine packages.
347 There was a lot of discussion, and several diverging points of view.
348 This section of the document attempts to present the areas of common
349 agreement, and also to present the different approaches advocated on
352 * Distribution of Wine into packages
353 The most basic question to ask is given the Wine CVS tree,
354 what physical files are you, the packager, going to produce?
355 Are you going to produce only a wine.rpm (as Marcus has done),
356 or are you going to produce 6 Debian files (libwine, libwine-dev,
357 wine, wine-doc, wine-utils and winesetuptk) as Ove has done?
358 At this point, common practice is to adopt to the conventions
359 of the targeted distribution.
361 * Where to install files
362 This question is not really contested. It will vary
363 by distribution, and is really up to the packager.
364 As a guideline, the current 'make install' process
365 seems to behave such that if we pick a single PREFIX then:
366 - binary files go into PREFIX/bin
367 - library files go into PREFIX/lib/wine
368 - include files go into PREFIX/include/wine
369 - man pages go into PREFIX/share/man
370 - documentation files go into PREFIX/share/doc/wine-VERSION
372 You might also want to use the wine wrapper script winelauncher
373 that can be found in tools/ directory, as it has several important
374 advantages over directly invoking the wine binary.
375 See the Executable Files section for details.
377 * The question of /opt/wine
378 The FHS 2.2 specification suggests that Wine as a package
379 should be installed to /opt/wine. None of the existing packages
380 follow this guideline (today; check again tomorrow).
382 * What files to create
383 After installing the static and shareable files, the next
384 question the packager needs to ask is how much dynamic
385 configuration will be done, and what configuration
386 files should be created.
387 There are several approaches to this:
388 - Rely completely on user file space - install nothing
389 This approach relies upon the new winesetup utility
390 and the new ability of Wine to launch winesetup if no
391 configuration file is found. The basic concept is
392 that no global configuration files are created at
393 install time. Instead, Wine configuration files are
394 created on the fly by the winesetup program when Wine
395 is invoked. Further, winesetup creates default
396 Windows directories and paths that are stored
397 completely in the user's WINEPREFIX. This approach
398 has the benefit of simplicity in that all Wine files
399 are either stored under /opt/wine or under ~/.wine.
400 Further, there is only ever one Wine configuration
401 file. This approach, however, adds another level of
402 complexity. It does not allow Wine to run Solitaire
403 'out of the box'; the user must run the configuration
404 program first. Further, winesetup requires Tcl/Tk, a
405 requirement not beloved by some. Additionally, this
406 approach closes the door on multi user configurations
407 and presumes a single user approach.
409 - Build a reasonable set of defaults for the global wine.conf,
410 facilitate creation of a user's local Wine configuration.
411 This approach, best shown by Marcus, causes the
412 installation process to auto scan the system,
413 and generate a global wine.conf file with best
414 guess defaults. The OpenLinux packages follow
416 The keys to this approach are always putting
417 an existing Windows partition into the
418 path, and being able to run Solitaire
419 right out of the box.
420 Another good thing that Marcus does is he
421 detects a first time installation and
422 does some clever things to improve the
423 user's Wine experience.
424 A flaw with this approach, however, is it doesn't
425 give the user an obvious way to choose not to
426 use a Windows partition.
428 - Build a reasonable set of defaults for the global wine.conf,
429 and ask the user if possible
430 This approach, demonstrated by Ove, causes the
431 installation process to auto scan the system,
432 and generate a global wine.conf file with best
433 guess defaults. Because Ove built a Debian
434 package, he was able to further query debconf and
435 get permission to ask the user some questions,
436 allowing the user to decide whether or not to
437 use a Windows partition.
442 This section discusses the implementation of a Red Hat 8.0 .spec file.
443 For a current .spec file, please refer to any one of the existing SRPMs.
445 1. Building the package
447 Wine is configured the usual way (depending on your build environment).
448 The PREFIX is chosen using your application placement policy
449 (/usr/, /usr/X11R6/, /opt/wine/, or similar). The configuration files
450 (wine.conf, wine.userreg, wine.systemreg) are targeted for /etc/wine/
451 (rationale: FHS 2.2, multiple readonly configuration files of a package).
453 Example (split this into %build and %install section for rpm:
456 CFLAGS=$RPM_OPT_FLAGS ./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
459 make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/
460 install -d $BR/etc/wine/
461 install -m 644 wine.ini $BR/etc/wine/wine.conf
463 # Put all our DLLs in a separate directory. (this works only if you have a buildroot)
464 install -d $BR/usr/X11R6/lib/wine
465 mv $BR/usr/X11R6/lib/lib* $BR/usr/X11R6/lib/wine/
467 # The Wine server is needed.
468 install -m 755 server/wineserver $BR/usr/X11R6/bin/
471 There are now a lot of libraries generated by the build process, so a
472 separate library directory should be used.
474 install -d 755 $BR/usr/X11R6/lib/
477 You will need to package the files:
479 $prefix/bin/wine, $prefix/lib/wine/*
480 $prefix/man/man1/wine.1, $prefix/include/wine/*,
481 $prefix/bin/wineserver
484 %doc ... choose from the toplevel directory and documentation/
486 The post-install script:
488 if ! grep /usr/X11R6/lib/wine /etc/ld.so.conf >/dev/null; then
489 echo "/usr/X11R6/lib/wine" >> /etc/ld.so.conf
493 The post-uninstall script:
495 if [ "$1" = 0 ]; then
496 perl -ni -e 'print unless m:/usr/X11R6/lib/wine:;' /etc/ld.so.conf
500 2. Creating a good default configuration file.
502 For the rationales of needing as less input from the user as possible arises
503 the need for a very good configuration file. The one supplied with Wine is
504 currently lacking. We need:
507 - A for the floppy. Specify your distribution's default floppy mountpoint.
509 - C for the C:\ directory. Here we use the user's home directory, for most
510 applications do see C:\ as root-writeable directory of every windows
511 installation and this basically is it in the UNIX-user context.
512 Don't forget to identify environment variables as DOS ones (ie, surrounded by '%').
514 - R for the CD-Rom drive. Specify your distribution's default CD-ROM mountpoint.
516 - T for temporary storage. We do use /tmp/ (rationale: between process
517 temporary data belongs to /tmp/ , FHS 2.0)
519 - W for the original Windows installation. This drive points to the
520 WINDOWSDIR subdirectory of the original windows installation.
521 This avoids problems with renamed WINDOWSDIR directories (as for
522 instance lose95, win or sys\win95). During compile/package/install
523 we leave this to be / , it has to be configured after the package install.
524 - Z for the UNIX Root directory. This avoids any roblems with
525 "could not find drive for current directory" users occasionally complain
526 about in the newsgroup and the irc channel. It also makes the whole
527 directory structure browseable. The type of Z should be network,
528 so applications expect it to be readonly.
532 Windows=c:\windows\ (the windows/ subdirectory in the user's
534 System=c:\windows\system\ (the windows/system subdirectory in the user's
536 Path=c:\windows;c:\windows\system;c:\windows\system32;w:\;w:\system;w:\system32;
537 ; Using this trick we have in fact two windows installations in one, we
538 ; get the stuff from the readonly installation and can write to our own.
539 Temp=t:\ (the TEMP directory)
541 * Possibly modify the [spooler], [serialports] and [parallelports] sections.
542 FIXME: possibly more, including printer stuff.
544 Add this prepared configuration file to the package.
546 3. Installing Wine for the system administrator
548 Install the package using the usual packager 'rpm -i wine.rpm'.
549 You may edit /etc/wine/wine.conf , [Drive W], to point to a
550 possible Windows installation right after the install. That's it.
552 Note that on Linux you should somehow try to add the unhide mount optioni
553 (see 'man mount') to the CD-ROM entry in /etc/fstab during package install,
554 as several stupid Windows programs mark some setup (!) files as hidden
555 (ISO9660) on CD-ROMs, which will greatly confuse users as they won't find
556 their setup files on the CD-ROMs as they were used on Windows systems when
557 unhide is not set ;-\ And of course the setup program will complain
558 that setup.ins or some other mess is missing... If you choose to do so,
559 then please make this change verbose to the admin.
561 Also make sure that the kernel you use includes the Joliet CD-ROM support,
562 for the very same reasons as given above (no long filenames due to missing
563 Joliet, files not found).
565 4. Installing Wine for the user
567 The user will need to run a setup script before the first invocation of Wine.
569 * Copy /etc/wine/wine.conf for user modification.
570 * Allow specification of the original windows installation to use
571 (which modifies the copied wine.conf file).
572 * Create the windows directory structure (c:\windows, c:\windows\system,
573 c:\windows\Start Menu\Programs, c:\Program Files, c:\Desktop, etc.)
574 * Symlink all .dll and .exe files from the original windows installation
575 to the windows directory. Why? Some programs reference
576 "%windowsdir%/file.dll" or "%systemdir%/file.dll" directly and fail
577 if they are not present. This will give a huge number of symlinks, yes.
578 However, if an installer later overwrites one of those files, it will
579 overwrite the symlink (so that the file now lies in the windows/
580 subdirectory). FIXME: Not sure this is needed for all files.
581 * On later invocation the script might want to compare regular files in
582 the user's windows directories and in the global windows directories
583 and replace same files by symlinks (to avoid diskspace problems).
588 Written in 1999 by Marcus Meissner <marcus@jet.franken.de>
589 Updated in 2000 by Jeremy White <jwhite@codeweavers.com>
590 Updated in 2002 by Andreas Mohr <andi@rhlx01.fht-esslingen.de>
591 Updated in 2003 by Tom Wickline <twickline2@triad.rr.com>
592 Updated in 2003 by Dimitrie O. Paun <dpaun@rogers.com>