Note: this information is largely out of date and is going through a near total review/rehash at the moment (april 14th)

INTRODUCTION

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

It expresses the basic principles that the Wine developers have agreed 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 can understand the different alternatives that have been considered and their rationales.

TERMS

There are several terms and paths used in this document as place holders 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.
  • The current default is /usr/local. This results in binary installation into /usr/local/bin, library installation into /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 prefix is /opt/wine. Ideally, a packager would also allow the 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 their registry settings. Generally speaking, this directory is either set to point at ~/.wine/drive_c. NOTE: It is extremely important that the packager understand the
    • importance of WINDOWSDIR and convey this information and choice to the end user.

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. Ideally, we should eliminate all hard dependencies in favor of soft dependencies.

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

Here is a list of the soft dependencies. We suggest packagers install each and every last of those before building the package. These libraries are not dependencies in the RPM sense. In DEB packages, they should appear as "Suggests" or "Recommends", as the case may be.

• Alsa: http://sourceforge.net/projects/alsa (Linux only)

  • This library gives sound support to the Windows environment.
• capi4linux
  • Used to implement our capi2032.dll.

• CUPS: http://www.cups.org

  • This library allows Windows to see CUPS defined printers. Used by WINEPS and WINSPOOL.
• fontconfig

  • Used to find TrueType fonts for rendering with freetype. Used by GDI.

• fontforge: http://sourceforge.net/projects/fontforge/

  • Used by WINE to create our own set of TrueType fonts during build.

• FreeType: http://www.freetype.org

  • This library is used for direct rendering of fonts. It provides better support of fonts than using the X11 fonts engine. It is only needed for the X11 back end engine. Used from GDI.
• hal, dbus-1
  • Used to implement CD mount handling (via explorer.exe).
• libgphoto2
  • Used to implement our gphoto2.ds (TWAIN datasource).
• libjpeg
  • This library is used to load JPEG files within OLE automation.
• 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.
• libungif or gif_lib
  • One of these two libraries is used to load GIF files within OLE automation.
• libxml2, libxslt
  • These two libraries are used for our msxml3.dll implementation.

• 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.
• OpenGL
  • This is used for both OpenGL and Direct3D (and some other DirectX functions as well) support in Wine. There are many many libraries for providing this functionality. It is enough for one of them to be available when compiling Wine. Wine can work with any other library during runtime. If no library is available, packagers are encouraged to compile

    Wine with Mesa3D (http://www.mesa3d.org), which requires no hardware support to install.

• OpenLDAP: http://www.openldap.org

  • Used by WLDAP32 to implement LDAP support.
• openssl
  • Used for some cryptographic support in wininet.dll.
• prelink
  • Used during build to locate WINE at a specific virtual address. (Will build without, but various programs will not work, e.g. copy protected games)
• sane
  • Used for basic scanner support in our TWAIN32 library.

• unixodbc: http://www.unixodbc.org/

  • ODBC support, used for odbc32.dll.
• X11 extensions
  • X11 extension libraries used by the x11drv. libxcomposite - X composite support libxmu - miscellanous X utilities libxt - X toolkit intrinsics libxv - XVideo extension support

    libxxf86vm - XFree86-VidModeExtension support (used for changing video modes) x11proto-render - X Render extension support Xau - X authorization protocol Xcursos - cursor management library Xdmcp - X display manager control protocol Xext - X extensions Xext - X miscellaneous extensions Xext - X miscellaneous fixes Xft - client-side font API for X applications Xinerama - xinerama support (multiple displays) Xi - X Input handling (for Asian input methods mostly) Xrandr - resolution switching Xrender - client side font rendering

    See also: RecommendedPackages <-- Should we cull almost all the content in this whole section and just refer to that page?

GOALS

An installation from a Wine package should:

• Install quickly and simply:
  • The initial installation should require no user input. An
    • 'rpm -i wine.rpm' or 'apt-get install wine'
    should suffice for initial installation.
• Work quickly and simply:
  • The user should be able to launch Solitaire within seconds of downloading the Wine package.
• Comply with File system Hierarchy Standard
  • A Wine installation should, as much as possible, comply

    with the FHS standard (http://www.pathname.com/fhs/).

  • In particular, note that on 64 bit distributions you will probably need to put Wine's 32 bit libraries in /usr/lib32 rather than /usr/lib
• 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
  • Use only as much disk space as needed per user.
• Reduce support requirements.
  • A packaged version of Wine should be sufficiently easy to use and have quick and easy access to FAQs and documentation such that 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:

• Install of the .rpm or .deb package.
  • If WINEPREFIX is not present, wine will generate a setup by itself by calling e.g. winecfg. This will load all default registry entries, and register dlls where necessary.

WINE COMPONENTS

• Executable Files
  • - cmd : Wine's command line interpreter, a cmd.exe replacement. - notepad : The windows Notepad replacement. - progman : A Program Manager replacement. - regedit : A graphical tool to edit your registry or for
    • importing a windows registry to Wine.
    - regsvr32 : A program to register/unregister .DLL and .OCX files.
    • Only works on those dlls that can self-register.
    - taskmgr : A clone of the windows taskmgr, used for debugging and
    • managing running Windows and Winlib processes.
    - uninstaller: A program to uninstall installed Windows programs.
    • Like the Add/Remove Program in the windows control panel.
    - widl : Wine IDL compiler compiles (MS-RPC and DCOM) Interface
    • Definition Language files.
    - wine : The main Wine executable. This program will load a Windows
    • binary and run it, relying upon the Wine shared object libraries.
    - 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 install something.
    - winebuild : Winebuild is a tool used for building Winelib applications
    • (and by Wine itself) to allow a developer to compile a .spec file into a .spec.c file.
    - wineconsole : Render the output of CUI programs. - winedbg : A application making use of the debugging API to allow
    • debugging of Wine or Winelib applications as well as Wine itself (kernel and all DLLs).
    - winedump : Dumps the imports and exports of NE and PE files. - winefile : A clone of the win3x file manager. - winegcc/wineg++: Wrappers for gcc/g++ respectively, to make them behave
    • as MinGW's gcc. Used for porting apps over to Winelib.
    - winemaker : Winemaker is a perl script which is designed to help you
    • bootstrap the conversion of your Windows projects to Winelib.

    - winemine : A clone of "Windows Minesweeper" a demo WineLib app. - 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 communication primitives to Wine processes.
    - wineshelllink : This shell script can be called by Wine in order to
    • propagate Desktop icon and menu creation requests out to a GNOME or KDE (or other Window Managers).
    - winewrap : Takes care of linking winelib applications. Linking with
    • Winelib is a complex process, winewrap makes it simple.
    - winhelp : A Windows Help replacement. - wmc : Wine Message Compiler it allows Windows message files to be
    • 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
      it the root of the Wine _build_ tree, after a successful build.
  • 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
    • An up to date list of includes can be found in the include/Makefile.in file.
  • 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.
        • - PREFIX/share/wine.inf This is the global Wine setup information file in the format of a MS Installer .INF file.
  • 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:

      http://winehq.org/site/docs/wineusr-guide/using-regedit#AEN349 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. 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

      • This file contains the user's local copy of the HKEY_LOCAL_MACHINE registry hive. In general use, it will contain only changes made to the default registry values.
      - WINEPREFIX/user.reg
      • This file contains the user's local copy of the HKEY_CURRENT_MACHINE registry hive. In general use, it will contain only changes made to the default registry values.
      - WINEPREFIX/userdef.reg
      • This file contains the user's local copy of the HKEY_USERS\.Default registry hive. In general use, it will contain only changes made to the default registry values.
  • 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. It is important to note, however, that some DLLs cannot be overriden as they require low-level Windows kernel access that simply doesn't exist within Wine. These DLLs are: gdi32.dll, kernel32.dll, ntdll.dll, and user32.dll.

PACKAGING STRATEGIES

There has recently been a lot of discussion on the Wine development mailing list about the best way to build Wine packages.

There was a lot of discussion, and several diverging points of view. This section of the document attempts to present the areas of common agreement, and also to present the different approaches advocated on 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? 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? At this point, common practice is to adopt to the conventions 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.
• 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
• The question of /opt/wine
  • The FHS 2.2 specification suggests that Wine as a package should be installed to /opt/wine. None of the existing packages follow this guideline (today; check again tomorrow). (Since most are upgrades of the distro packages, this is still on the safe side I think - Marcus Meissner)
• 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. The best current approach to this is:
    • Setup a fake windows setup automatically.
      • This is done by simply calling e.g. winecfg, which will setup a fake windows root for the user. If no arguments are passed, defaults will be assumed for WINEPREFIX (~/.wine) and similar variables. After this, WINE is immediately usable by the end user.
    • Others might be possible.

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

Wine is configured the usual way (depending on your build environment). The PREFIX is chosen using your application placement policy (/usr/, /usr/X11R6/, /opt/wine/, or similar). The configuration files (wine.userreg, wine.systemreg) are targeted for /etc/wine/ (rationale: FHS 2.2, multiple read only configuration files of a package).

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

• CFLAGS="$RPM_OPT_FLAGS" ./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll make BR=$RPM_BUILD_ROOT make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/

You will need to package the files:

• $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 %config /etc/wine/* %doc ... choose from the top level directory and documentation/

2. Installing Wine for the system administrator

Install the package using the usual packager 'rpm -i wine.rpm'.

Note that on Linux you should somehow try to add the unhide mount option (see 'man mount') to the CD-ROM entry in /etc/fstab during package install, 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 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 that setup.ins or some other mess is missing... If you choose to do so, then please make this change verbose to the admin.

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 Joliet, files not found).

3. Installing Wine for the user

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

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

AUTHORS

Written in 1999 by MarcusMeissner - <marcus AT jet DOT franken DOT de>
Updated in 2000 by JeremyWhite - <jwhite AT codeweavers DOT com>
Updated in 2002 by Andreas Mohr - <andi AT rhlx01 DOT fht-esslingen DOT de>
Updated in 2003 by TomWickline - <twickline2 AT triad DOT rr DOT com>
Updated in 2003 by Dimitrie O. Paun - <dpaun AT rogers DOT com>
Updated in 2004,2005 by MarcusMeissner - <marcus AT jet DOT franken DOT de>
Updated in 2008 by AustinEnglish - <austinenglish AT gmail DOT com>