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