PACKAGING 19.4 KB
Newer Older
1 2 3
INTRODUCTION
~~~~~~~~~~~~

4
This document attempts to establish guidelines for people making binary
5 6
packages of Wine.

7
It expresses the basic principles that the Wine developers have agreed
8 9
should be used when building Wine. It also attempts to highlight the areas
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 12 13 14 15
rationales.

TERMS
~~~~~

16
There are several terms and paths used in this document as place holders
17 18 19 20 21 22
for configurable values. Those terms are described here.
    * WINEPREFIX: is the user's Wine configuration directory.
	This is almost always ~/.wine, but can be overridden by
        the user by setting the WINEPREFIX environment variable.

    * PREFIX: is the prefix used when selecting an installation target.
23 24
	The current default is /usr/local. This results in binary
	installation into /usr/local/bin,  library installation into
25 26 27
	/usr/local/wine/lib, and so forth.
        This value can be overridden by the packager. In fact, FHS 2.2
	(http://www.pathname.com/fhs/) specifications suggest that a better
28
        prefix is /opt/wine.  Ideally, a packager would also allow the
29 30 31 32 33
	installer to override this value.

    * WINDOWSDIR: is an important concept to Wine.  This directory specifies
	what directory corresponds to the root Windows directory
        (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 38
        NOTE:   It is extremely important that the packager understand the
		importance of WINDOWSDIR and convey this information and
39 40
		choice to the end user.

41 42 43 44 45 46 47 48
DEPENDENCIES
~~~~~~~~~~~~

There are two types of dependencies: hard and soft dependencies.

A hard dependency must be available at runtime for Wine to function,
if  compiled into the code. Soft dependencies on the other hand
will degrade gracefully at runtime if unavailable on the runtime system.
49
Ideally, we should eliminate all hard dependencies in favor of
50 51 52
soft dependencies.

To enable a soft dependency, it must be available at compile time.
53 54
As a packager, please do your best to make sure that as many soft
dependencies  are available during compilation. Failing to have a
55 56 57 58
soft dependency available means that users cannot benefit
from a Wine capability.

Here is a list of the soft dependencies. We suggest packagers
59 60
install each and every last of those before building the package.
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 64 65 66 67

    * libresolv
      This is the standard Unix domain name resolver library that is
      used to implement DNS support found in dnsapi.dll. resolv.h as
      well as libresolv.so should be present at build time.

68
    * FreeType: http://www.freetype.org
69 70
      This library is used for direct rendering of fonts. It provides
      better support of fonts than using the X11 fonts engine. It is
71 72
      only needed for the X11 back end engine. Used from GDI.

73 74 75
    * fontforge: http://sourceforge.net/projects/fontforge/
      Used by WINE to create our own set of TrueType fonts during build.

76 77 78 79
    * fontconfig
      Used to find TrueType fonts for rendering with freetype. Used by
      GDI.

80
    * Alsa: http://sourceforge.net/projects/alsa (Linux only)
81 82 83 84 85 86
      This library gives sound support to the Windows environment.

    * JACK: http://jackit.sourceforge.net
      Similar to Alsa, it allow Wine to use the JACK audio server.

    * CUPS: http://www.cups.org
87 88
      This library allows Windows to see CUPS defined printers. Used
      by WINEPS and WINSPOOL.
89 90

    * OpenGL
91 92
      This is used for both OpenGL and Direct3D (and some other
      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 97
      If no library is available, packagers are encouraged to compile
      Wine with Mesa3D (http://www.mesa3d.org), which requires no
98 99
      hardware support to install.

100 101 102
    * OpenLDAP: http://www.openldap.org
      Used by WLDAP32 to implement LDAP support.

103 104 105
    * LittleCMS: http://www.littlecms.com
      This library is used to implement MSCMS (Color Management System)
      which is needed by an increasing number of graphics applications.
106

107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
    * libjpeg
      This library is used to load JPEG files within OLE automation.

    * libungif or gif_lib
      One of these two libraries is used to load GIF files within OLE
      automation.

    * ICU
      Used for bidirectional character output. Linked statically, used
      by GDI.

    * sane
      Used for basic scanner support in our TWAIN32 library.

    * openssl
      Used for some cryptographic support in ADVAPI32.
123

124 125 126 127 128 129
    * Xrandr, Xrender, Xi, Xext
      X11 extension libraries used by the x11drv.
      Xrandr - resolution switching
      Xrender - client side font rendering
      Xi - X Input handling (for asian input methods mostly)
      Xext - X extensions
130

131 132 133 134 135 136 137 138 139
    * libxml2, libxslt
      These two libraries are used for our msxml3.dll implementation.

    * prelink
      Used during build to locate WINE at a specific virtual address.

    * capi4linux
      Used to implement our capi2032.dll.

140 141 142 143 144 145
    * libgphoto2
      Used to implement our gphoto2.ds (TWAIN datasource)

    * hal, dbus-1
      Used to implement CD mount handling (via explorer.exe).

146 147 148 149 150
GOALS
~~~~~

An installation from a Wine package should:
    * Install quickly and simply:
151
	The initial installation should require no user input.  An
152 153
		'rpm -i wine.rpm' or 'apt-get install wine'
        should suffice for initial installation.
154

155
    * Work quickly and simply:
156 157
        The user should be able to launch Solitaire within seconds
	of downloading the Wine package.
158

159
    * Comply with File system Hierarchy Standard
160 161
        A Wine installation should, as much as possible, comply
        with the FHS standard (http://www.pathname.com/fhs/).
162

163 164 165 166 167 168 169 170 171
    * Preserve flexibility
        None of the flexibility built into Wine should
        be hidden from the end user.

    * Easy configuration
        Come as preconfigured as possible, so the user does
        not need to change any configuration files.

    * Small footprint
172
        Use only as much disk space as needed per user.
173 174 175

    * Reduce support requirements.
        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 178 179 180 181 182 183 184
	requests to the newsgroup and development group go down.
        Further, it should be easy for users to capture good bug reports.

REQUIREMENTS
~~~~~~~~~~~~

Successfully installing Wine requires:

185
    * Install of the .rpm or .deb package.
186 187 188 189 190 191 192 193 194

    * No longer: Preparing a fake windows setup.

	If WINEPREFIX is not present, wine will generate a setup
	by itself by calling wineprefixcreate.

        This will load all default registry entries, and register dlls
	where necessary. A special "wine.inf" file is provided with
	the WINE sources and installed to /usr/share/wine/.
195 196 197 198 199

WINE COMPONENTS
~~~~~~~~~~~~~~~

   * Executable Files
200
	- cmd  : Wine's command line interpreter, a cmd.exe replacement.
201 202
	- notepad : The windows Notepad replacement.
	- progman : A Program Manager replacement.
203
	- regedit : A graphical tool to edit your registry or for
Jon Griffiths's avatar
Jon Griffiths committed
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 208
	- taskmgr : A clone of the windows taskmgr, used for debugging and
		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 216 217
	- wineboot : This program is executed on startup of the first wine
		process of a particular user.wineboot won't automatically run
		when needed.  Currently you have to manually run it after you
218
		install something.
219 220
	- winebuild : Winebuild is a tool used for building Winelib applications
		(and by Wine itself) to allow a developer to compile a .spec file
221 222
		into a .spec.c file.
	- wineconsole : Render the output of CUI programs.
223 224
	- winedbg : A application making use of the debugging API to allow
		debugging of Wine or Winelib applications as well as Wine itself
225 226
		(kernel and all DLLs).
	- 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 231
	- winemaker : Winemaker is a perl script which is designed to help you
		bootstrap the conversion of your Windows projects to Winelib.
232
	- winemine :  A clone of "Windows Minesweeper" a demo WineLib app.
233 234 235
	- winepath :  A tool for converting between Windows paths and Unix paths
	- wineserver : The Wine server is the process that manages resources,
		coordinates threads, and provides synchronization and interprocess
236
		communication primitives to Wine processes.
237 238
	- wineshelllink : This shell script can be called by Wine in order to
		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 242
		Winelib is a complex process, winewrap makes it simple.
	- winhelp : A Windows Help replacement.
243
	- wmc : Wine Message Compiler it allows Windows message files to be
244 245 246 247 248 249
		compiled into a format usable by Wine.
	- wrc : the Wine Resource Compiler. A clone of Microsoft's rc.

    * Shared Object Library Files
	To obtain a current list of DLLs, run:
		ls dlls/*.so
Francois Gouget's avatar
Francois Gouget committed
250
	it the root of the Wine _build_ tree, after a successful build.
251 252 253 254 255 256 257

    * Man Pages
	To obtain a current list of man files that need to be installed, run:
		find . -name "*.man"
	it the root of the Wine _build_ tree, after you have run ./configure.

    * Include Files
258 259
	An up to date list of includes can be found in the include/Makefile.in
	file.
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275

    * Documentation files
	After building the documentation with:
		cd documentation; make html
	install all the files from: wine-user/, wine-devel/ and winelib-user/.

     * Dynamic Wine Files
        Wine also generates and depends on a number of dynamic
        files, including user configuration files and registry files.

        At the time of this writing, there was not a clear
        consensus of where these files should be located, and how
        they should be handled.  This section attempts
        to explain the alternatives clearly.


276 277 278 279
        - PREFIX/share/wine.inf
	
            This is the global Wine setup information file
	    in the format of a MS Installer .INF file.
280 281 282 283 284 285

    * Registry Files
            In order to replicate the Windows registry system,
            Wine stores registry entries in a series of files.

            For an excellent overview of this issue, read this
286
            http://www.winehq.org/News/2000-25.html#FTR
287 288 289 290 291 292 293 294 295
            Wine Weekly News feature.

            The bottom line is that, at Wine server startup,
            Wine loads all registry entries into memory
            to create an in memory image of the registry.
            The order of files which Wine uses to load
            registry entries is extremely important,
            as it affects what registry entries are
            actually present.  The order is roughly that
296
            .dat files from a Windows partition are loaded,
297 298 299 300 301 302 303 304 305 306 307
            and then finally local registry settings are
            loaded from WINEPREFIX.  As each set are loaded,
            they can override the prior entries.  Thus,
            the local registry files take precedence.

            Then, at exit (or at periodic intervals),
            Wine will write either all registry entries
            (or, with the default setting) changed
            registry entries to files in the WINEPREFIX.

	    - WINEPREFIX/system.reg
308
                This file contains the user's local copy of the
309 310 311 312
		HKEY_LOCAL_MACHINE registry hive.  In general use, it will
		contain only changes made to the default registry values.

	    - WINEPREFIX/user.reg
313
                This file contains the user's local copy of the
314 315 316 317
		HKEY_CURRENT_MACHINE registry hive.  In general use, it will
		contain only changes made to the default registry values.

	    - WINEPREFIX/userdef.reg
318
                This file contains the user's local copy of the
319 320 321 322 323 324
		HKEY_USERS\.Default registry hive.  In general use, it will
		contain only changes made to the default registry values.

	    - WINEPREFIX/cachedmetrics.[display]
                This file contains font metrics for the given X display.
                Generally, this cache is generated once at Wine start time.
325
                cachedmetrics can be generated if absent.
326 327 328 329 330 331 332 333
		You should note this can take a long time.

    * Important Files from a Windows Partition
        Wine has the ability to use files from an installation of the
        actual Microsoft Windows operating system.  Generally these
        files are loaded on a VFAT partition that is mounted under Linux.

        This is probably the most important configuration detail.
334 335
        The use of Windows registry and DLL files dramatically alters the
	behavior of Wine. If nothing else, packagers have to make this
336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351
	distinction clear to the end user, so that they can intelligently
        choose their configuration.

        - WINDOWSDIR/system32/system.dat
        - WINDOWSDIR/system32/user.dat
	- WINDOWSDIR/win.ini

    * Windows Dynamic Link Libraries (WINDOWSDIR/system32/*.dll)
        Wine has the ability to use the actual Windows DLL files
        when running an application.  An end user can configure
        Wine so that Wine uses some or all of these DLL files
        when running a given application.

PACKAGING STRATEGIES
~~~~~~~~~~~~~~~~~~~~

352 353
There has recently been a lot of discussion on the Wine development
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 357
This section of the document attempts to present the areas of common
agreement, and also to present the different approaches advocated on
358 359 360 361 362
the mailing list.

    * Distribution of Wine into packages
        The most basic question to ask is given the Wine CVS tree,
        what physical files are you, the packager, going to produce?
363 364 365
        Are you going to produce only a wine.rpm, or are you going to
	produce 6 Debian files (libwine, libwine-dev, wine, wine-doc,
	wine-utils and winesetuptk) as Ove has done?
366
        At this point, common practice is to adopt to the conventions
367 368 369 370 371
	of the targeted distribution.

	Also, experience shows that you should not create a huge set
	of packages, since later upgrades and obsoleting will be
	painful.
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390

    * Where to install files
        This question is not really contested.  It will vary
        by distribution, and is really up to the packager.
        As a guideline, the current 'make install' process
        seems to behave such that if we pick a single PREFIX then:
            - binary files go into PREFIX/bin
	    - library files go into PREFIX/lib/wine
	    - include files go into PREFIX/include/wine
	    - man pages go into PREFIX/share/man
	    - documentation files go into PREFIX/share/doc/wine-VERSION

	You might also want to use the wine wrapper script winelauncher
	that can be found in tools/ directory, as it has several important
	advantages over directly invoking the wine binary.
	See the Executable Files section for details.

    * The question of /opt/wine
        The FHS 2.2 specification suggests that Wine as a package
391
        should be installed to /opt/wine.  None of the existing packages
392 393
	follow this guideline (today; check again tomorrow).

394 395 396
	(Since most are upgrades of the distro packages, this is still
	 on the safe side I think - Marcus Meissner)

397 398 399 400 401
    * What files to create
        After installing the static and shareable files, the next
        question the packager needs to ask is how much dynamic
        configuration will be done, and what configuration
        files should be created.
402 403 404 405 406 407 408

        The best current approach to this is:
	- Leave it alone and make a "wineprefixcreate" call available
	  to the user via a menu item or similar.

        - Setup a fake windows setup automatically.
		
409
		This is done by simply calling wineprefixcreate,
410 411
		which will setup a fake windows root for the user.

412
		If no arguments are passed, defaults will be
413 414 415 416 417 418 419
		assumed for WINEPREFIX (~/.wine) and similar
		variables.

		After this, WINE is immediately usable by the
		end user.

	- Others might be possible.
420 421 422 423 424 425 426 427 428

IMPLEMENTATION
~~~~~~~~~~~~~~

This section discusses the implementation of a Red Hat 8.0 .spec file.
For a current .spec file, please refer to any one of the existing SRPMs.

1. Building the package

429
Wine is configured the usual way (depending on your build environment).
430 431
The PREFIX is chosen using your application placement policy
(/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 436 437

Example (split this into %build and %install section for rpm:


438
	CFLAGS="$RPM_OPT_FLAGS" ./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
439 440 441 442 443 444
	make
	BR=$RPM_BUILD_ROOT
	make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/

You will need to package the files:

445 446 447 448 449 450 451 452 453 454 455 456 457 458
	$prefix/bin/wine*
	$prefix/lib/libwine*
	$prefix/lib/wine/*,
	$prefix/share/wine/wine.inf

	$prefix/man/man1/wine.1
	$prefix/include/wine/*
	$prefix/bin/notepad
	$prefix/bin/progman
	$prefix/bin/regedit
	$prefix/bin/rundll32
	$prefix/bin/regsvr32
	$prefix/bin/widl
	$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 467
Install the package using the usual packager 'rpm -i wine.rpm'.

468 469 470 471
Adapting the $prefix/share/wine/wine.inf file used by wineprefixcreate is not
necessary.

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 474
as several stupid Windows programs mark some setup (!) files as hidden
(ISO9660) on CD-ROMs, which will greatly confuse users as they won't find
475 476
their setup files on the CD-ROMs as they were used on Windows systems when
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 479
then please make this change verbose to the admin.

480 481
Also make sure that the kernel you use includes the Joliet CD-ROM support,
for the very same reasons as given above (no long filenames due to missing
482 483
Joliet, files not found).

484
3. Installing Wine for the user
485

486 487
If no standard wine prefix was setup, the first call to wine will
create one for the user.
488

489 490
So the user can just click on any setup.exe file and it will work
out of the box.
491

492 493 494 495 496 497 498 499
AUTHORS
~~~~~~~

Written in 1999 by Marcus Meissner <marcus@jet.franken.de>
Updated in 2000 by Jeremy White <jwhite@codeweavers.com>
Updated in 2002 by Andreas Mohr <andi@rhlx01.fht-esslingen.de>
Updated in 2003 by Tom Wickline <twickline2@triad.rr.com>
Updated in 2003 by Dimitrie O. Paun <dpaun@rogers.com>
500
Updated in 2004,2005 by Marcus Meissner <marcus@jet.franken.de>