11.5. Configuring WINE Installation

With an understanding of what WINE is and how it works at a high level, the next step to effectively using it on FreeBSD is becoming familiar with its configuration. The following sections will describe the key concept of the WINE prefix, and illustrate how it is used to control the behavior of applications run through WINE.

11.5.1. WINE Prefixes

A WINE prefix is a directory, usually located beneath the default location of $HOME/.wine though it can be located elsewhere. The prefix is a set of configurations and support files used by the wine to configure and run the Windows® environment a given application needs. By default, a brand new WINE installation will create the following structure when first launched by a user:

  • .update-timestamp: contains the last modified date of file /usr/share/wine/wine.inf. It is used by WINE to determine if a prefix is out of date, and automatically update it if needed.

  • dosdevices/: contains information on mappings of Windows® resources to resources on the host FreeBSD system. For example, after a new WINE installation, this should contain at least two entries which enable access to the FreeBSD filesystem using Windows®-style drive letters:

    • c:@: A link to drive_c described below.

    • z:@: A link to the root directory of the system.

  • drive_c/: emulates the main (i.e., C:) drive of a Windows® system. It contains a directory structure and associated files mirroring that of standard Windows® systems. A fresh WINE prefix will contain Windows® 10 directories such as Users and Windows that holds the OS itself. Furthermore, applications installed within a prefix will be located in either Program Files or Program Files (x86), depending on their architecture.

  • system.reg: This Registry file contains information on the Windows® installation, which in the case of WINE is the environment in drive_c.

  • user.reg: This Registry file contains the current user's personal configurations, made either by varous software or through the use of the Registry Editor.

  • userdef.reg: This Registry file is a default set of configurations for newly-created users.

11.5.2. Creating and Using WINE Prefixes

While WINE will create a default prefix in the user's $HOME/.wine/, it is possible to set up multiple prefixes. There are a few reasons to do this:

  • The most common reason is to emulate different versions of Windows®, according to the compatibility needs of the software in question.

  • In addition, it is common to encounter software that does not work correctly in the default environment, and requires special configuration. it is useful to isolate these in their own, custom prefixes, so the changes do not impact other applications.

  • Similarly, copying the default or "main" prefix into a separate "testing" one in order to evaluate an application's compatibility can reduce the chance of corruption.

Creating a prefix from the terminal requires the following command:

% WINEPREFIX="/home/username/.wine-new" winecfg

This will run the winecfg program, which can be used to configure wine prefixes (more on this in a later section). But by providing a directory path value for the WINEPREFIX environment variable, a new prefix is created at that location if one does not already exist.

Supplying the same variable to the wine program will similarly cause the selected program to be run with the specified prefix:

% WINEPREFIX="/home/username/.wine-new" wine program.exe

11.5.3. Configuring WINE Prefixes with winecfg

As described above WINE includes a tool called winecfg to configure prefixes from within a GUI. It contains a variety of functions, which are detailed in the sections below. When winecfg is run from within a prefix, or provided the location of a prefix within the WINEPREFIX variable, it enables the configuration of the selected prefix as described in the below sections.

Selections made on the Applications tab will affect the scope of changes made in the Libraries and Graphics tabs, which will be limited to the application selected. See the section on Using Winecfg in the WINE Wiki for more details. Applications

The Applications contains controls enabling the association of programs with a particular version of Windows®. On first start-up the Application settings section will contain a single entry: Default Settings. This corresponds to all the default configurations of the prefix, which (as the disabled Remove application button implies) cannot be deleted.

But additional applications can be added with the following process:

  1. Click the Add application button.

  2. Use the provided dialog to select the desired program's executable.

  3. Select the version of Windows® to be used with the selected program. Libraries

WINE provides a set of open source library files as part of its distribution that provide the same functions as their Windows® counterparts. However, as noted earlier in this chapter, the WINE project is always trying to keep pace with new updates to these libraries. As a result, the versions that ship with WINE may be missing functionality that the latest Windows® programs are expecting.

However, winecfg makes it possible specify overrides for the built-in libraries, particularly there is a version of Windows® available on the same machine as the host FreeBSD installation. For each library to be overridden, do the following:

  1. Open the New override for library drop-down and select the library to be replaced.

  2. Click the Add button.

  3. The new override will appear in the Existing overrides list, notice the native, builtin designation in parentheses.

  4. Click to select the library.

  5. Click the Edit button.

  6. Use the provided dialog to select a corresponding library to be used in place of the built-in one.

Be sure to select a file that is truly the corresponding version of the built-in one, otherwise there may be unexpected behavior. Graphics

The Graphics tab provides some options to make the windows of programs run via WINE operate smoothly with FreeBSD

  • Automatic mouse capture when windows are full-screen.

  • Allowing the FreeBSD window manager to decorate the windows, such as their title bars, for programs running via WINE.

  • Allowing the window manager to control windows for programs running via WINE, such as running resizing functions on them.

  • Create an emulated virtual desktop, within which all WINE programs will run. If this item is selected, the size of the virtual desktop can be specified using the Desktop size input boxes.

  • Setting the screen resolution for programs running via WINE. Desktop Integration

This tab allows configuration of the following items:

  • The theme and related visual settings to be used for programs running via WINE.

  • Whether the WINE sub-system should manage MIME types (used to determine which application opens a particular file type) internally.

  • Mappings of directories in the host FreeBSD system to useful folders within the Windows® environment. To change an existing association, select the desired item and click Browse, then use the provided dialog to select a directory. Drives

The Drives tab allows linking of directories in the host FreeBSD system to drive letters in the Windows® environment. The default values in this tab should look familiar, as they're displaying the contents of dosdevices/ in the current WINE prefix. Changes made via this dialog will reflect in dosdevices, and properly-formatted links created in that directory will display in this tab.

To create a new entry, such as for a CD-ROM (mounted at /mnt/cdrom), take the following steps:

  1. Click the Add button.

  2. In the provided dialog, choose a free drive letter.

  3. Click OK.

  4. Fill in the Path input box by either typing the path to the resource, or click Browse and use the provided dialog to select it.

By default WINE will autodetect the type of resource linked, but this can be manually overridden. See the section in the WINE Wiki for more detail on advanced options. Audio

This tab contains some configurable options for routing sound from Windows® programs to the native FreeBSD sound system, including:

  • Driver selection

  • Default device selection

  • Sound test About

The final tab contains information on the WINE project, including a link to the website. It also allows entry of (entirely optional) user information, although this is not sent anywhere as it is in other operating systems.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.