Differential D27484 Diff 80353 en_US.ISO8859-1/books/handbook/wine/chapter.xml

Changeset View

Standalone View

en_US.ISO8859-1/books/handbook/wine/chapter.xml

				<?xml version="1.0" encoding="iso-8859-1"?>
				<chapter xmlns="http://docbook.org/ns/docbook"
				xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
				xml:id="wine">

				<info>
				<title>WINE</title>

				<authorgroup>
				<author>
				<personname>
				<firstname>Aaron</firstname>
				<surname>Peters</surname>
				</personname>
				<contrib>Contributed by </contrib>
				</author>
				</authorgroup>

				<sect1 xml:id="wine-synopsis">
				<title>Synopsis</title>

				<para><link xlink:href="https://www.winehq.org/">WINE</link>, which
				stands for Wine Is Not an Emulator, is technically a
				software translation layer. It enables to install and run some
				software written for &os.windows; on &os; (and other) systems.</para>

				<para>It operates by intercepting system calls, or requests from the
				software to the operating system, and translating them from
				&os.windows; calls to calls that &os; understands. It will also
				translate any responses as needed into what the &os.windows; software
				is expecting. So in some ways, it <emphasis>emulates</emphasis> a
				&os.windows; environment, in that it provides many of the resources
				&os.windows; applications are expecting.</para>

				<para>However, it's not an emulator in the traditional sense.
				Many of these solutions operate by constructing an entire other
				computer using software processes in place of hardware.
				Virtualization (such as that provided by the
				<package>emulators/qemu</package> port) operates in this way. One of the
				benefits of this approach is the ability to install a full version
				of the OS in question to the emulator. It means that the
				environment won't look any different to applications than a real
				machine, and chances are good that everything will work on it. The
				downside to this approach is the fact that software acting as hardware is
				inherently slower than actual hardware. The computer built in software
				(called the <emphasis>guest</emphasis>) requires resources from the real
				machine (the <emphasis>host</emphasis>), and holds on to those resources
				for as long as it's running.</para>

				<para>The WINE Project, on the other hand, is much lighter on your
				system's resources. It will translate system calls on the fly, so
				while it is difficult to be as fast as a real &os.windows; computer, it
				can come very close. On the other hand, WINE is trying to keep up
				with a moving target in terms of all the different system calls
				and other functionality it needs to support. As a result there may
				be applications that don't work as expected on WINE, won't work at
				all, or won't even install to begin with.</para>

				<para>At the end of the day, WINE provides another option to try to get
				a particular &os.windows; software program running on &os;. It can
				always serve as the first option which, if successful, offers a good
				experience without unnecessarily depleting the host &os; system's
				resources.</para>

				<para>This chapter will describe:</para>

				<itemizedlist>
				<listitem>
				<para>How to install WINE on a &os; system.</para>
				</listitem>

				<listitem>
				<para>How WINE operates, and how it's different from other
				alternatives like virtualizaton.</para>
				</listitem>

				<listitem>
				<para>How to fine-tune WINE to the specific needs of some
				applications.</para>
				</listitem>

				<listitem>
				<para>How to install GUI helpers for WINE.</para>
				</listitem>

				<listitem>
				<para>Common tips and solutions for on &os;.</para>
				</listitem>

				<listitem>
				<para>Considerations for WINE on &os; in terms of the multi-user
				environment.</para>
				</listitem>
				</itemizedlist>

				<para>Before reading this chapter, it will be useful to:</para>

				<itemizedlist>
				<listitem>
				<para>Understand the <link linkend="basics">basics of &unix;
				and &os;</link>.</para>
				</listitem>

				<listitem>
				<para>Know how to <link linkend="bsdinstall">install
				&os;</link>.</para>
				</listitem>

				<listitem>
				<para>Know how to <link linkend="advanced-networking">set up a
				network connection</link>.</para>
				</listitem>

				<listitem>
				<para>Know how to <link linkend="ports">install additional
				third-party software</link>.</para>
				</listitem>

				</itemizedlist>

				</sect1>

				<sect1 xml:id="installing-wine-on-freebsd">
				<title>Installing WINE on &os;</title>

				<para>WINE can be installed via the pkg tool, or by compiling the port(s).</para>

				<sect2 xml:id="wine-prerequistes">
				<title>WINE Prerequistes</title>

				<para>Before installing WINE itself, it's useful to have the following pre-requisites
				installed.</para>

				<itemizedlist>
				<listitem>
				<para>A GUI</para>
				</listitem>
				</itemizedlist>

				<para>Most &os.windows; programs are expecting to have a graphical user
				interface available. If WINE is installed without one present, its
				dependencies will include the Wayland compositor, and so a GUI will
				be installed along with WINE. But it's useful to have the GUI of your
				choice installed, configured, and working correctly before installing
				WINE.</para>

				<itemizedlist>
				<listitem>
				<para>wine-gecko</para>
				</listitem>
				</itemizedlist>

				<para>The &os.windows; operating system has for some time had a default
				web browser pre-installed: Internet Explorer. As a result, some
				applications work under the assumption that there will always be
				something capable of displaying web pages. In order to provide
				this functionality, the WINE layer includes a web browser
				component using the Mozilla project's Gecko engine. When WINE is
				first launched it will offer to download and install this, and there
				are reasons you might want it do so (these will be covered in a
				later chapter). But you can also install it prior to installing
				WINE, or alongside the install of WINE proper.</para>

				<para>Install this package with the following:</para>

				<screen>&prompt.root;<userinput>pkg install wine-gecko</userinput></screen>

				<para>Alternately, compile the port with the following:</para>

				<screen>&prompt.root;<userinput>cd /usr/ports/emulator/wine-gecko</userinput>&prompt.root;<userinput>make install</userinput></screen>

				<itemizedlist>
				<listitem>
				<para>wine-mono</para>
				</listitem>
				</itemizedlist>

				<para>This port installs the MONO framework, an open source
				implementation of Microsoft's .NET. Including this with your
				WINE installation will make it that much more likely that any
				applications written in .NET will install and run on your
				system.</para>

				<para>To install the package:</para>

				<screen>&prompt.root;<userinput>pkg install wine-mono</userinput></screen>

				<para>To compile from the ports collection:</para>

				<screen>&prompt.root;<userinput>cd /usr/ports/emulator/wine-mono</userinput>&prompt.root;<userinput>make install</userinput></screen>
				</sect2>

				<sect2 xml:id="installing-wine">
				<title>Installing WINE via &os; Package Repositories</title>

				<para>With the pre-requisites in place, install WINE via package with
				the following command:</para>

				<screen>&prompt.root;<userinput>pkg install wine</userinput></screen>

				<para>Alternately compile the WINE sub-system from source with
				the following:</para>

				<screen>&prompt.root;<userinput>cd /usr/ports/emulator/wine</userinput>&prompt.root;<userinput>make install</userinput></screen>

				</sect2>

				<sect2 xml:id="32-vs-64-bit-wine">
				<title>Concerns of 32- vs. 64-Bit in WINE Installations</title>

				<para>Like most software, &os.windows; applications made the upgrade from
				the older 32-bit architecture to 64 bits. And most recent
				software is written for 64-bit operating systems, although
				modern OSes can sometimes continue to run older 32-bit programs
				as well. &os; is no different, having had support for 64-bit
				since the 5.x series.</para>

				<para>However, using old software no longer supported by default is a
				common use for emulators, and users commonly turn to WINE to
				play games and use other programs that don't run properly on
				modern hardware. Fortunately, &os; can support all three
				scenarios:</para>

				<itemizedlist>
				<listitem>
				<para>On modern, 64-bit machine and want to run 64-bit &os.windows;
				software, simply install the ports mentioned in the above sections.
				The ports system will automatically install the 64-bit version
				for you.</para>
				</listitem>

				<listitem>
				<para>Alternately, you might have an older 32-bit machine you
				don't want to run with its original, now non-supported
				software. You can install the 32-bit (i386) version of
				&os;, then install the ports in the above sections.
				Again, on a 32-bit machine the ports system will install the
				corresponding 32-bit version of WINE by default.</para>
				</listitem>
				</itemizedlist>

				<para>However, given a 64-bit version of &os; and need to
				run <emphasis role="strong">32-bit</emphasis> &os.windows;
				applications, installing a different port is required to
				enable 32-bit compatibility. To install the pre-compiled
				package, use the following:</para>

				<screen>&prompt.root;<userinput>pkg install i386-wine</userinput></screen>

				<para>Or you can compile the port yourself with the following:</para>

				<screen>&prompt.root;<userinput>cd /usr/ports/emulator/i386-wine</userinput>&prompt.root;<userinput>make install</userinput></screen>
				</sect1>

				<!-- START SECTION 3 -->
				<sect1 xml:id="running-first-wine-program">
				<title>Running a First WINE Program on &os;</title>

				<para>Now that WINE is installed, the next step is to try it out
				by running a simple program. An easy way to do this is to
				download a self-contained application, i.e. one you can simply
				unpack and run without any complex installation process.</para>

				<para>So-called "portable" versions of applications are good
				choices for this test, as are programs that run with only a single
				executable file.</para>

				<sect2 xml:id="running-a-program-from-the-command-line">
				<title>Running a Program from the Command Line</title>

				<para>There are two different methods to launch a Windows program from
				the terminal. The first, and most straightforward is to navigate
				to the directory containing the program's executable (.EXE file)
				and issue the following:</para>

				<screen>&prompt;<userinput>wine program.exe</userinput></screen>

				<para>For applications that take command-line arguments, add them after
				the executable as usual:</para>

				<screen>&prompt;<userinput>wine program2.exe -file file.txt</userinput></screen>

				<para>Alternately, supply the full path to the executable to use it in a
				script, for example:</para>

				<screen>&prompt;<userinput>wine /home/user/bin/program.exe</userinput></screen>
				</sect2>

				<sect2 xml:id="running-a-program-from-a-gui">
				<title>Running a Program from a GUI</title>

				<para>After installation graphical shells should be updated with new
				associations for Windows executable (.EXE) files. It will now be
				possible to browse the system using a file manager, and launch
				the Windows application in the same way as other files and
				programs (either a single- or double-click, depending on the
				desktop's settings).</para>

				<para>On most desktops, check to make sure this association is correct
				by right-clicking on the file, and looking for an entry in the context
				menu to open the file. One of the options (hopefully the default one)
				will be with the <emphasis role="strong">Wine Windows Program Loader
				</emphasis>, as shown in the below screenshot:</para>

				<mediaobject>
				<imageobject>
				<imagedata fileref="wine/wine-run-np++-1.png"/>
				</imageobject>
				</mediaobject>

				<para>In the event the program doesn't run as expected, try launching it
				from the command line and review any messages displayed in the
				terminal to troubleshoot.</para>

				<para>In the event WINE isn't the default application for .EXE files
				after install, check the MIME associate for this extension in the current
				desktop environment, graphical shell, or file manager.</para>
				</sect2>
				</sect1>

				<!-- START SECTION 4 -->
				<sect1 xml:id="wine-overview-concepts">
				<title>WINE Overview & Concepts</title>

				<para>WINE is a complex system, so before running it on a &os;
				system it's worth gaining an understanding of what it is and how
				it works.</para>

				<sect2 xml:id="what-is-wine">
				<title>What is WINE?</title>

				<para>As mentioned in the <link linkend="wine-synopsis">Synopsis</link>
				for this chapter, WINE is a compatiblity layer that allows
				&os.windows; applications to run on other operating systems.
				In theory, it means these programs should run on systems like &os;,
				macOS, and Android.</para>

				<para>When WINE runs a &os.windows; executable, two things
				occur:</para>

				<itemizedlist>
				<listitem>
				<para>Firstly, WINE implements an environment that mimics that
				of various versions of &os.windows;. For example, if
				an application requests access to a resource such as RAM,
				WINE has a memory interface that looks and acts (as far as
				the application is concerned) like &os.windows;.</para>
				</listitem>

				<listitem>
				<para>Then, once that application makes use of that interface,
				WINE takes the incoming request for space in memory and
				translates it to something compatible with the host
				system. In the same way when the application retrieves
				that data, WINE facilitates fetching it from the host
				system and passing it back to the &os.windows;
				application.</para>
				</listitem>
				</itemizedlist>
				</sect2>

				<sect2 xml:id="wine-and-the-os-system">
				<title>WINE and the &os; System</title>

				<para>Installing WINE on a &os; system will entail a few
				different components:</para>

				<itemizedlist>
				<listitem>
				<para>&os; applications for tasks such as running the
				&os.windows; executables, configuring the WINE
				sub-system, or compiling programs with WINE support.</para>
				</listitem>

				<listitem>
				<para>A large number of libraries that implement the core
				functions of &os.windows; (for example the file
				<filename>/lib/wine/api-ms-core-memory-l1-1-1.dll.so</filename>,
				which is part of the aforementioned memory interface).</para>
				</listitem>

				<listitem>
				<para>A number of &os.windows; executables, which are (or
				mimic) common utilities (such as
				<filename>/lib/wine/notepad.exe.so</filename>,which provides
				the standard &os.windows; text editor).</para>
				</listitem>

				<listitem>
				<para>Additional &os.windows; assets, in particular fonts
				(like the Tahoma font, which is stored in the
				<filename>share/wine/fonts/tahoma.ttf</filename> file in the
				install root).</para>
				</listitem>
				</itemizedlist>
				</sect2>

				<sect2 xml:id="graphical-vs.-text-modeterminal-programs-in-wine">
				<title>Graphical vs. Text Mode/Terminal Programs in WINE</title>

				<para>As an operating system where terminal utilities are
				"first-class citizens," it's natural to assume that
				WINE will contain extensive support for text-mode programs.
				However, the majority of applications for &os.windows;,
				especially the most popular ones, are designed with a
				graphical user interface (GUI) in mind. Therefore, WINE's
				utilities are designed by default to launch graphical
				programs.</para>

				<para>However, there are three methods available to run these
				so-called Console User Interface (CUI) programs:</para>

				<itemizedlist>
				<listitem>
				<para>The <emphasis>Bare Streams</emphasis> approach will
				display the output directly to standard output.</para>
				</listitem>

				<listitem>
				<para>The <emphasis>wineconsole</emphasis> utility can be used
				with either the <emphasis>user</emphasis> or
				<emphasis>curses</emphasis> backed to utilize some of the
				enhancements the WINE system provides for CUI
				applications.</para>
				</listitem>
				</itemizedlist>

				<para>These approaches are described in greater detail on the
				<link xlink:href="https://wiki.winehq.org/Wine_User%27s_Guide#Text_mode_programs_.28CUI:_Console_User_Interface.29">WINE Wiki</link>.</para>
				</sect2>

				<sect2 xml:id="wine-derivative-projects">
				<title>WINE Derivative Projects</title>

				<para>WINE itself is a mature open source project, so it's little
				surprise it's used as the foundation of more complex
				solutions.</para>

				<sect3 xml:id="commercial-wine-implementations">
				<title>Commercial WINE Implementations</title>

				<para>A number of companies have taken WINE and made it a core
				of their own, proprietary products (WINE's LGPL license
				permits this). Two of the most famous of these are as
				follows:
				</para>

				<itemizedlist>
				<listitem>
				<para>Codeweavers CrossOver</para>
				</listitem>
				</itemizedlist>

				<para>This solution provides a simplified
				"one-click" installation of WINE, which
				contains additional enhancements and optimizations
				(although the company contributes many of these back
				upstream to the WINE project). One area of focus for
				Codeweavers is to make the most popular applications
				install and run smoothly.</para>

				<para>While the company once produced a native FreeBSD
				version of their CrossOver solution, it appears to
				have long been abandoned. While some resources (such
				as a
				<link xlink:href="https://www.codeweavers.com/compatibility/crossover/forum/freebsd">dedicated
				forum</link>) are still present, they also have seen
				no activity for some time.</para>

				<itemizedlist>
				<listitem>
				<para>Steam Proton</para>
				</listitem>
				</itemizedlist>

				<para>Gaming company Steam also uses WINE to enable
				&os.windows; games to install and run on other
				systems. It's primary target is Linux-based systems,
				although some support exists for macOS as well.</para>

				<para>While Steam does not offer a native &os; client,
				there are several options for using the &linux;
				client using &os;'s Linux Compatibility Layer.</para>
				</sect3>

				<sect3 xml:id="wine-companion-programs">
				<title>WINE Companion Programs</title>
				<para>In addition to proprietary offerings, other projects have
				released applications designed to work in tandem with the
				standard, open source version of WINE. The goals for these
				can range from making installation easier to offering easy
				ways to get popular software installed.</para>

				<para>These solutions are covered in greater detail in the later
				section on <link linkend="wine-management-guis">GUI frontends,
				and include the following:</para>

				<itemizedlist>
				<listitem>
				<para>winetricks</para>
				</listitem>

				<listitem>
				<para>Homura</para>
				</listitem>
				</itemizedlist>
				</sect3>
				</sect2>

				<sect2 xml:id="alternatives-to-wine">
				<title>Alternatives to WINE</title>

				<para>For &os; users, some alternatives to using WINE are as
				follows:</para>

				<itemizedlist>
				<listitem>
				<para>Dual-Booting: A straightforward option is to run desired
				&os.windows; applications natively on that OS. This of
				course means existing &os; in order to boot &os.windows;,
				so this method isn't feasible if access to programs in both
				systems is required simultaneously.</para>
				</listitem>

				<listitem>
				<para>Virtual Machines: Virtual Machines (VMs), as mentioned
				earlier in this chapter, are software processes that
				emulate full sets of hardware, on which additional
				operating systems (including &os.windows;) can be
				installed and run. Modern tools make VMs easy to create
				and manage, but this method comes at a cost. A good
				portion of the host systems resources must be allocated to
				each VM, and those resources can't be reclaimed by the
				host as long as the VM is running. A few examples of VM
				managers include the open source solutions qemu, bhyve,
				and VirtualBox. See the chapter on
				<link linkend="virtualization">Virtualization</link> for
				more detail.</para>
				</listitem>

				<listitem>
				<para>Remote Access: Like many other &os.unix;-like systems,
				&os; can run a variety of applications enabling users
				to remotely access &os.windows; computers and use
				their programs or data. In addtion to clients such as
				<application>xrdp</application> that connect to the
				standard &os.windows; Remote Desktop Protocol, other open
				source standards such as
				<application>vnc</application> can also be
				used (provided a compatible server is present on the other
				side).
				</para>
				</listitem>
				</itemizedlist>
				</sect2>
				</sect1>

				<!--- Start SECTION 5, Configuring WINE Installations --->
				<sect1 xml:id="configuring-wine-installation">
				<title>Configuring WINE Installation</title>

				<para>With an understanding of what WINE is and how it works at a high
				level, the next step to effectively using it on your &os;
				system is becoming familiar with its configuration. The following
				sections will describe the key concept of the <emphasis>WINE
				prefix</emphasis>, and illustrate how it's used to control the
				behavior of applications run through WINE.</para>

				<sect2 xml:id="wine-prefixes">
				<title>WINE Prefixes</title>

				<para>A WINE <emphasis>prefix</emphasis> 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 the
				<application>wine</application> to configure and run
				the &os.windows; environment a given application needs. By
				default, a brand new WINE installation will create the following
				structure when first launched by a user:</para>

				<itemizedlist spacing="compact">
				<listitem>
				<para><filename>.update-timestamp</filename>: This file contains
				the last modified date of the
				<filename>file /usr/share/wine/wine.inf</filename>. It's used
				by WINE to determine if a prefix is out of date, and automatically
				update it if needed.</para>
				</listitem>

				<listitem>
				<para><filename>dosdevices/</filename>: This directory contains
				information on mappings of &os.windows; resources to resources
				on the host &os; system. For example, after a new WINE installation,
				this should contain at least two entries which enable access to the
				&os; filesystem using &os.windows;-style drive letters:</para>

				<itemizedlist>
				<listitem>
				<para><filename>c:@</filename>: A link to the
				<filename>drive_c</filename> directory described below.</para>
				</listitem>

				<listitem>
				<para><filename>z:@</filename>: A link to the root directory of
				the system.</para>
				</listitem>
				</itemizedlist>
				</listitem>

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

				<listitem>
				<para><filename>system.reg</filename>: This Registry file contains information on the
				&os.windows; installation, which in the case of WINE is
				the environment in the drive_c directory.</para>
				</listitem>

				<listitem>
				<para><filename>user.reg</filename>: This Registry file contains the current user's
				personal configurations, made either by varous software or
				through the use of the Registry Editor.</para>
				</listitem>

				<listitem>
				<para><filename>userdef.reg</filename>: This Registry file is a default set of
				configurations for newly-created users.</para>
				</listitem>
				</itemizedlist>
				</sect2>

				<sect2 xml:id="creating-and-using-wine-prefixes">
				<title>Creating and Using WINE Prefixes</title>

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

				<itemizedlist>
				<listitem>
				<para>The most common reason is to emulate different versions of
				&os.windows;, according to the compatibility needs of
				the software in question.</para>
				</listitem>

				<listitem>
				<para>In addition, it's common to encounter software that doesn't
				work correctly in the default environment, and requires
				special configuration. It's useful to isolate these in their
				own, custom prefixes, so the changes don't impact other
				applications.</para>
				</listitem>

				<listitem>
				<para>Similarly, copying the default or "main" prefix
				into a separate "testing" one in order to evaluate
				an application's compatibilty can reduce the chance of
				corruption.</para>
				</listitem>
				</itemizedlist>

				<para>Creating a prefix from the terminal requires the following
				command:</para>

				<screen>&prompt;<userinput>WINEPREFIX="/home/username/.wine-new" winecfg</userinput></screen>

				<para>This will run the <application>winecfg</application>
				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 <varname>WINEPREFIX</varname> environment
				variable, a new prefix is created at that location if one
				doesn't already exist.</para>

				<para>Supplying the same variable to the
				<application>wine</application> program will
				similarly cause the selected program to be run with the
				specified prefix:</para>

				<screen>&prompt;<userinput>WINEPREFIX="/home/username/.wine-new" wine program.exe</userinput></screen>

				</sect2>

				<sect2 xml:id="configuring-wine-prefixes-with-winecfg">
				<title>Configuring WINE Prefixes with winecfg</title>

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

				<para>Selections made on the <emphasis>Applications</emphasis> tab
				will affect the scope of changes made in the
				<emphasis>Libraries</emphasis> and
				<emphasis>Graphics</emphasis> tabs, which will be limited to
				the application selected. See the section on
				<link xlink:href="https://wiki.winehq.org/Wine_User%27s_Guide#Using_Winecfg">Using
				Winecfg</link> in the WINE Wiki for more details.</para>

				<sect3 xml:id="applications">
				<title>Applications</title>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/wine-config-1.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

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

				<para>But additional applications can be added with the following
				process:</para>

				<orderedlist spacing="compact">
				<listitem>
				<para>Click the <emphasis>Add application</emphasis> button.</para>
				</listitem>

				<listitem>
				<para>Use the provided dialog to select the desired program's
				executable.</para>
				</listitem>

				<listitem>
				<para>Select the version of &os.windows; to be used with the
				selected program.</para>
				</listitem>
				</orderedlist>
				</sect3>

				<sect3 xml:id="libraries">
				<title>Libraries</title>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/wine-config-2.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>WINE provides a set of open source library files as part of
				its distribution that provide the same functions as their
				&os.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 &os.windows; programs are expecting.</para>

				<para>However, <application>winecfg</application> makes
				it possible specify overrides for the built-in libraries,
				particularly there is a version of &os.windows; available
				on the same machine as the host &os; installation. For
				each library to be overriden, do the following:</para>

				<orderedlist spacing="compact">
				<listitem>
				<para>Open the <emphasis>New override for library</emphasis>
				drop-down and select the library to be replaced.</para>
				</listitem>

				<listitem>
				<para>Click the <emphasis>Add</emphasis> button.</para>
				</listitem>

				<listitem>
				<para>The new override will appear in the <emphasis>Existing
				overrides</emphasis> list, notice the <emphasis>native,
				builtin</emphasis> designation in parentheses.</para>
				</listitem>

				<listitem>
				<para>Click to select the library.</para>
				</listitem>

				<listitem>
				<para>Click the <emphasis>Edit</emphasis> button.</para>
				</listitem>

				<listitem>
				<para>Use the provided dialog to select a corresponding library
				to be used in place of the built-in one.</para>
				</listitem>
				</orderedlist>

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

				<sect3 xml:id="graphics">
				<title>Graphics</title>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/wine-config-3.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>The <emphasis>Graphics</emphasis> tab provides some options to
				make the windows of programs run via WINE operate smoothly with
				&os;</para>

				<itemizedlist>
				<listitem>
				<para>Automatic mouse capture when windows are full-screen</para>
				</listitem>

				<listitem>
				<para>Allowing the &os; window manager to decorate the
				windows, such as their title bars, for programs running
				via WINE.</para>
				</listitem>

				<listitem>
				<para>Allowing the window manager to control windows for
				programs running via WINE, such as running resizing
				functions on them.</para>
				</listitem>

				<listitem>
				<para>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
				<emphasis>Desktop size</emphasis> input boxes.</para>
				</listitem>

				<listitem>
				<para>Setting the screen resolution for programs running via
				WINE.</para>
				</listitem>
				</itemizedlist>
				</sect3>

				<sect3 xml:id="desktop-integration">
				<title>Desktop Integration</title>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/wine-config-4.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>
				This tab allows configuration of the following items:
				</para>

				<itemizedlist>
				<listitem>
				<para>The theme and related visual settings to be used for
				programs running via WINE.</para>
				</listitem>

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

				<listitem>
				<para>Mappings of directories in the host &os; system to
				useful folders within the &os.windows; environment. To
				change an existing association, select the desired item
				and click <emphasis>Browse</emphasis>, then use the
				provided dialog to select a directory.</para>
				</listitem>
				</itemizedlist>
				</section3>

				<sect3 xml:id="drives">
				<title>Drives</title>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/wine-config-5.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>The <emphasis>Drives</emphasis> tab allows linking of
				directories in the host &os; system to drive letters in
				the &os.windows; environment. The default values in this
				tab should look familiar, as they're displaying the contents
				of dosdevices/ directory in the current WINE prefix. Changes
				made via this dialog will reflect in the
				<fliename>dosdevices/</filename> directory, and properly-
				formatted links created in that directory will display in
				this tab.</para>

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

				<orderedlist>
				<listitem>
				<para>Click the <emphasis>Add </emphasis> button.</para>
				</listitem>

				<listitem>
				<para>In the provided dialog, choose a free drive letter.</para>
				</listitem>

				<listitem>
				<para>Click <emphasis>OK</emphasis>.</para>
				</listitem>

				<listitem>
				<para>Fill in the <emphasis>Path</emphasis> input box by either
				typing the path to the resource, or click
				<emphasis>Browse </emphasis> and use the provided dialog
				to select it.</para>
				</listitem>
				</orderedlist>

				<para>By default WINE will autodetect the type of resource linked,
				but this can be manually overridden. See
				<link xlink:href="https://wiki.winehq.org/Wine_User%27s_Guide#Drive_Settings">the
				section in the WINE Wiki</link> for more detail on advanced
				options.</para>
				</sect3>

				<sect3 xml:id="audio">
				<title>Audio</title>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/wine-config-6.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>This tab contains some configurable options for routing sound
				from &os.windows; programs to the native &os; sound
				system, including:</para>

				<itemizedlist>
				<listitem>
				<>para>Driver selection</para>
				</listitem>

				<listitem>
				<para>Default device selection</para>
				</listitem>

				<listitem>
				<para>Sound test</para>
				</listitem>
				</itemizedlist>
				</sect3>

				<sect3 xml:id="about">
				<title>About</title>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/wine-config-7.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>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.</para>
				</sect3>
				</sect2>
				</sect1>

				<!-- START SECTION 6: WINE MANAGEMENT GUIS -->
				<sect1 xml:id="wine-management-guis">
				<title>WINE Management GUIs</title>

				<para>While the base install of WINE comes with a GUI configuration tool
				in <application>winecfg</application>, it's main purpose is just
				that: strictly configuring an existing WINE prefix. There are, however,
				more advanced applications that will assist in the initial installation
				of applications as well as optimizing their WINE environments. The below
				sections include a selection of the most popular.</para>

				<sect2 xml:id="winetricks">
				<title>winetricks</title>

				<para><application>winetricks</application> is a cross-platform, general
				purpose helper program for WINE. It is not developed by the WINE project
				proper, but rather maintained on <link
				xlink:href="https://github.com/Winetricks/winetricks">Github</link>
				by a group of contributors. It contains some automated
				"recipes" for getting common applications to work on
				WINE, both by optimizing the settings as well as acquiring some
				DLL libraries automatically.</para>

				<sect3 xml:id="installing-winetricks">
				<title>Installing winetricks</title>

				<para>To install <application>winetricks</application> on a &os; using
				binary packages, use the following commands (note
				<application>winetricks</application> requires either the i386-wine
				or i386-wine-devel package, and is therefore not installed automatically
				with other dependencies):</para>

				<screen>&prompt.root;<userinput>pkg install i386-wine
				pkg install winetricks</userinput></screen>

				<para>To compile it from source, issue the following in the
				terminal:</para>

				<screen>&prompt.root;<userinput>cd /usr/ports/emulators/i386-wine
				make install
				cd /usr/ports/emulators/winetricks
				make install</userinput></screen>

				<para>If a manual installation is required, refer to the <link
				xlink:href="https://github.com/Winetricks/winetricks">Github</link>
				account for instructions.</para>
				</sect3>

				<sect3 xml:id="using-winetricks">
				<title>Using winetricks</title>

				<para>Run <application>winetricks</application> with the following
				command:</para>

				<screen>&prompt;<userinput>winetricks</userinput></screen>

				<para>Note you should be in a 32-bit prefix in order to run
				<application>winetricks</application>. Launching
				<application>winetricks</application> displays a
				window with a number of choices, as follows:</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/winetricks-run-1.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>Selecting either <emphasis>Install an application</emphasis>,
				<emphasis>Install a benchmark</emphasis>, or <emphasis>Install
				a game</emphasis> shows a list with supported options, such as
				the one below for applications:</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/winetricks-run-2.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>Selecting one or more items and clicking
				<emphasis>OK</emphasis> will start their installation
				process(es). Initially, some messages that appear to be errors
				may show up, but they're actually informational alerts as
				<application>winetricks</application> configures
				the WINE environment to get around known issues for the
				application:
				</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/winetricks-app-install-1.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>Once these are circumvented, the actual installer for the
				application will be run:</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/winetricks-app-install-2.png" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>Once the installation completes, the new Windows application
				should be available from the desktop environment's standard
				menu (shown in the screenshot below for the LXQT desktop
				environment):
				</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/winetricks-menu-1.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>In order to remove the application, run
				<application>winetricks</application> again, and
				select <emphasis>Run an uninstaller</emphasis>.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/winetricks-uninstall-1.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>A &os.windows;-style dialog will appear with a list of
				installed programs and components. Select the application to
				be removed, then click the <emphasis>Modify/Remove</emphasis>
				button.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/winetricks-uninstall-2.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>This will run the applications built-in installer, which
				should also have the option to uninstall.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/winetricks-uninstall-3.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>
				</sect3>
				</sect2>

				<sect2 xml:id="homura">
				<title>Homura</title>

				<para>Homura is an application similar to
				<application>winetricks</application>, although it was
				inspired by the <link
				xlink:href="https://lutris.net/">Lutris</link> gaming system
				for Linux. But while it is focused on games, there are also
				non-gaming applications available for install through Homura.</para>

				<sect3 xml:id="installing-homura">
				<title>Installing Homura</title>

				<para>To install Homura's binary package, issue the following
				command:</para>

				<screen>&prompt.root;<userinput>pkg install homura</userinput></screen>

				<para>Homura is available in the FreeBSD Ports system. However,
				rather than the <emphasis>emulators</emphasis> section of
				Ports or binary packages, look for it in the
				<emphasis>games</emphasis> section.
				</para>

				<screen>&prompt.root;<userinput>cd /usr/ports/games/homura
				make install</userinput></screen>
				</sect3>

				<sect3 xml:id="using-homura">
				<title>Using Homura</title>

				<para>Homura's usage is quite similar to that of
				<application>winetricks</application>. When using
				it for the first time, launch it from the command line (or a
				desktop environment runner applet) with:</para>

				<screen>&prompt;<userinput>Homura</userinput></screen>

				<para>This should result in a friendly welcome message. Click
				<emphasis>OK</emphasis> to continue.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-launch-1.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>The program will also offer to place a link in the application
				menu of compatible environments:</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-run-2.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>Depending on the setup of the &os; machine, Homura may
				display a message urging the install of native graphics
				drivers.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-run-3.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>The application's window should then appear, which amounts to
				a "main menu" with all its options. Many of the
				items are the same as <application>winetricks</application>,
				although Homura offers some additional, helpful options such as
				opening its data folder (<emphasis>Open Homura Folder</emphasis>)
				or running a specified program (<emphasis>Run a executable in
				prefix</emphasis>).</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-install-1.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>To select one of Homura's supported applications to install,
				select <emphasis>Installation</emphasis>, and click
				<emphasis>OK</emphasis>. This will display a list of
				applications Homura can install automatically. Select one, and
				click <emphasis>OK</emphasis> to start the process.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-install-2.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>As a first step Homura will download the selected program. A
				notification may appear in supported desktop environments.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-install-3.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>The program will also create a new prefix for the application.
				A standard WINE dialog with this message will display.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-install-4.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>Next, Homura will install any prerequisites for the selected
				program. This may involve downloading and extracting a fair
				number of files, the details of which will show in dialogs.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-install-5.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>Downloaded packages are automatically opened and run as
				required.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-install-6.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>The installation may end with a simple desktop notification or
				message in the terminal, depending on how Homura was launched.
				But in either case Homura should return to the main screen. To
				confirm the installation was successful, select
				<emphasis>Launcher</emphasis>, and click
				<emphasis>OK</emphasis>.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-install-7.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>This will display a list of installed applications.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-install-8.png.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>

				<para>To run the new program, select it from the list, and click
				<emphasis>OK</emphasis>. To uninstall the application, select
				<emphasis>Uninstallation</emphasis> from the main screen,
				which will display a similar list. Select the program to be
				removed, and click <emphasis>OK</emphasis>.</para>

				<para>
				<inlinemediaobject>
				<imageobject>
				<imagedata fileref="./includes/homura-uninstall-1.jpg" />
				</imageobject>
				</inlinemediaobject>
				</para>
				</sect3>
				</sect2>

				<sect2 xml:id="running-multiple-management-guis">
				<title>Running Multiple Management GUIs</title>

				<para>It's worth noting that the above solutions are not mutually
				exclusive. It's perfectly acceptable, even advantageous, to have
				both installed at the same time, as they support a different set
				of programs.</para>

				<para>However, it's wise to ensure that they don't access any of the
				same WINE prefixes. Each of these solutions applies workarounds
				and makes changes to the registries based on known workarounds
				to existing WINE issues in order to make a given application run
				smoothly. Allowing both
				<application>winetricks</application> and Homura to
				access the same prefix could lead to some of these being
				overwritten, with the result being some or all applications do
				not work as expected.</para>
				</sect2>
				</sect1>

				<!-- START SECTION 7: WINE FAQ -->
				<sect1 xml:id="wine-on-os-faq">
				<title>WINE on &os; FAQ</title>

				<para>The following section describes some frequently asked questions,
				tips/tricks, or common issues in running WINE on &os;, along
				with their respective answers.</para>

				<sect2 xml:id="basic-installation-and-usage">
				<title>Basic Installation and Usage</title>

				<sect3 xml:id="how-to-install-32-bit-and-64-bit-wine-on-the-same-system">
				<title>How to install 32-bit and 64-bit WINE on the same
				system?</title>

				<para>As described earlier in this section, the
				<application>wine</application> and
				<application>i386-wine</application> packages conflict
				with one another, and therefore can't be installed on
				the same system in the normal way. However, multiple
				installs can be achieved using mechanisms like chroots/jails,
				or by building WINE from source (note this does
				<emphasis>not</emphasis> mean building the port).</para>
				</sect3>

				<sect3 xml:id="can-dos-programs-be-run-on-wine">
				<title>Can DOS Programs Be Run on WINE?</title>

				<para>They can, as "Console User Interface" applications
				as mentioned eariler in this section. However, there is an
				arguably better method for running DOS software:
				<application>DOSBox</application>. On the other
				hand, there's little reason not to at least try it. Simply
				create a new prefix, install the software, and if it doesn't
				work, delete the prefix.</para>
				</sect3>

				<sect3 xml:id="should-the-wine-devel-packageport-be-installed-to-use-the-development-version-of-wine-instead-of-stable">
				<title>Should the "wine-devel" package/port be
				installed to use the development version of WINE instead of
				stable?</title>

				<para>Yes, installing this version will install the
				"development" version of WINE. As with the 32- and
				64-bit versions, they cannot be installed together with the
				stable versions unless additional measures are taken.</para>

				<para>Note that WINE also has a "Staging" version, which
				contains the most recent updates. This was at one time
				available as a &os; port; however, it has since been
				removed. It can be compiled directly from source however.</para>
				</sect3>
				</sect2>

				<sect2 xml:id="install-optimization">
				<title>Install Optimization</title>

				<sect3 xml:id="how-should-os.windows-hardware-e.g.-graphics-drivers-be-handled">
				<title>How should &os.windows; hardware (e.g. graphics) drivers be
				handled?</title>

				<para>Operating system drivers transfer commands between
				applications and hardware. WINE emulates a &os.windows;
				environment, including the drivers, which in turn use
				&os;'s native drivers for this transfer. It's not advisable
				to install &os.windows; drivers, as the WINE system is designed
				to use the host systems drivers. If, for example, you have a
				graphics card that benefits from dedicated drivers, install them
				using the standard &os; methods, not &os.windows; installers.</para>
				</sect3>

				<sect3 xml:id="is-there-a-way-to-make-os.windows-fonts-look-better">
				<title>Is there a way to make &os.windows; fonts look
				better?</title>

				<para>A user on the FreeBSD forums suggests this configuration to
				fix out-of-the-box look of WINE fonts, which can be slightly
				pixelated.</para>

				<para>According to <link xlink:href="https://forums.freebsd.org/threads/make-wine-ui-fonts-look-good.68273/">a post in the FreeBSD Forums</link>,
				adding the following to the
				<filename>.config/fontconfig/fonts.conf</filename> file will
				add anti-aliasing and make text more readable.

				<programlisting><?xml version="1.0"?>
				<!DOCTYPE fontconfig SYSTEM "fonts.dtd">

				<fontconfig>

				<!-- antialias all fonts -->
				<match target="font">
				<edit name="antialias" mode="assign"><bool>true</bool></edit>
				<edit name="hinting" mode="assign"><bool>true</bool></edit>
				<edit name="hintstyle" mode="assign"><const>hintslight</const></edit>
				<edit name="rgba" mode="assign"><const>rgb</const> </edit>
				</match>

				</fontconfig></programlisting>
				</sect3>

				<sect3 xml:id="does-having-os.windows-installed-elsewhere-on-a-system-help-wine-operate">
				<title>Does having &os.windows; installed elsewhere on a
				system help WINE operate?</title>

				<para>It may, depending on the application being run. As mentioned
				in the section describing <application>winecfg</application>, some
				built-in WINE DLLs and other libraries can be overridden by providing
				a path to an alternate version. Provided the &os.windows;
				partition or drive is mounted to the &os; system and
				accessible to the user, configuring some of these overrides
				will use native &os.windows; libraries and may decrease
				the chance of unexpected behavior.</para>
				</sect3>
				</sect2>

				<sect2 xml:id="application-specific">
				<title>Application-Specific</title>

				<sect3 xml:id="where-is-the-best-place-to-see-if-application-x-works-on-wine">
				<title>Where is the best place to see if application X works on
				WINE?</title>

				<para>The first stop in determining compatibiliy should be the
				<link xlink:href="https://appdb.winehq.org/"> WINE AppDB</link>.
				This is a compilation of reports of programs working (or not) on
				all supported platforms, although (as previously mentioned), solutions
				for one platform are often applicable to others.</para>
				</sect3>

				<sect3 xml:id="is-there-anything-that-will-help-games-run-better">
				<title>Is there anything that will help games run
				better?</title>

				<para>Perhaps. Many &os.windows; games rely on DirectX, a
				proprietary Microsoft graphics layer. However there are
				projects in the open source community attempting to implement
				support for this technology.</para>

				<para>The <emphasis>dxvk</emphasis> project, which is an attempt to
				implement DirectX using the &os;-compatible Vulkan
				graphics sub-system, is one such. Although its primary target
				is WINE on Linux,
				<link xlink:href="https://forums.freebsd.org/threads/what-about-gaming-on-freebsd.723/page-9">some
				&os; users report</link> compiling and using dxvk.</para>

				<para>In addition, work is underway on a
				<application>wine-proton</application>
				<link xlink:href="https://www.freshports.org/emulators/wine-proton/">port</link>.
				This will bring the work of Valve, developer of the Steam
				gaming platform, to &os;. Proton is a distribution of WINE
				designed to allow many &os.windows; games to run on other
				operating systems with minimal setup.</para>
				</sect3>

				<sect3 xml:id="is-there-anywhere-freebsd-wine-users-gather-to-exchange-tips-and-tricks">
				<title>Is there anywhere FreeBSD WINE users gather to exchange
				tips and tricks?</title>

				<para>There are plenty of places FreeBSD users discuss issues
				related to WINE that can be searched for solutions:</para>

				<itemizedlist>
				<listitem>
				<para><link xlink:href="https://forums.freebsd.org/">The FreeBSD
				forums</link>, particularly the <emphasis>Installation and
				Maintenance of Ports or Packages</emphasis> or
				<emphasis>Emulation and virtualization</emphasis> forums.</para>
				</listitem>

				<listitem>
				<para><link xlink:href="https://wiki.freebsd.org/IRC/Channels">FreeBSD
				IRC channels</link> including #freebsd (for general
				support), #freebsd-games, and others.</para>
				</listitem>

				<listitem>
				<para><link xlink:href="https://discord.gg/2CCuhCt">The BSD
				World Discord server's</link> channels including
				<emphasis>bsd-desktop</emphasis>,
				<emphasis>bsd-gaming</emphasis>,
				<emphasis>bsd-wine</emphasis>, and others.</para>
				</listitem>
				</itemizedlist>
				</sect3>
				</sect2>

				<sect2 xml:id="other-os-resources">
				<title>Other OS Resources</title>

				<para>There are a number of resources focused on other operating
				systems that may be useful for &os; users:</para>

				<itemizedlist spacing="compact">
				<listitem>
				<para><link xlink:href="https://wiki.winehq.org/">The WINE
				Wiki</link> has a wealth of information on using WINE, much
				of which is applicable across many of WINE's supported
				operating systems.</para>
				</listitem>

				<listitem>
				<para>Similarly, the documentation available from other OS
				projects can also be of good value.
				<link xlink:href="https://wiki.archlinux.org/index.php/wine">The
				WINE page</link> on the Arch Linux Wiki is a particularly
				good example, although some of the "Third-party
				applications" (i.e. "companion applications")
				are obviously not avaialble on &os;.</para>
				</listitem>

				<listitem>
				<para>Finally, Codeweavers (a developer of a commerical version of
				WINE) is an active upstream contributor. Often times answers
				to questions in
				<link xlink:href="https://www.codeweavers.com/support/forums">their
				support forum</link> can be of aid in troubleshooting
				problems with the open source version of WINE.</para>
				</listitem>
				</itemizedlist>
				</sect2>
				</sect1>

				<!-- START SECTION 8: MULTI-USER WINE -->
				<sect1 xml:id="wine-in-multi-user-os-installations">
				<title>WINE in Multi-User &os; Installations</title>

				<sect2 xml:id="issues-with-using-a-common-wine-prefix">
				<title>Issues with Using a Common WINE Prefix</title>

				<para>Like most &os.unix;-like operating systems, &os; is
				designed for multiple users to be logged in and working at the
				same time. On the other hand, &os.windows; is multi-user in
				the sense that there can be multiple user accounts set up on one
				system. But the expectation is that only one will be using the
				physical machine (a desktop or laptop PC) at any given moment.</para>

				<para>More recent consumer versions of &os.windows; have taken
				some steps to improve the OS in multi-user scenarios. But it is
				still largely structured around a single-user experience.
				Furthermore, the measures the WINE project has taken to create a
				compatible environment means, unlike &os; applications
				(including WINE itself), it will resemble this single-user
				environment.</para>

				<para>So it follows that each user will have to maintain his/her own
				set of configurations, which is potentially good. Yet it is
				advantageous to install applications, particularly large ones
				like office suites or games, only once. Two examples of reasons
				to do this are maintenance (software updates need only be
				applied once) and efficiency in storage (no duplicated files).</para>

				<para>There are two strategies to minimze the impact of multiple WINE
				users in the system.</para>
				</sect2>

				<sect2 xml:id="installing-applications-to-a-common-drivesettings">
				<title>Installing Applications to a Common Drive</title>

				<para>As shown in the section on WINE Configuration, WINE provides the
				ability to attach additional drives to a given prefix. In this
				way, applications can be installed to a common location, while
				each user will still have an prefix where individual settings
				may be kept (depending on the program). This is a good setup if
				there are relatively few applications to be shared between
				users, and they are programs that require few custom tweaks
				changes to the prefix in order to function.</para>

				<para>The steps to make install applications in this way are as
				follows:</para>

				<orderedlist>
				<listitem>
				<para>First, set up a shared location on the system where the
				files will be stored, such as <filename>/mnt/windows-drive_d/</filename>.
				Creating new directories is described in man page for the
				<application>mkdir</application> command.</para>
				</listitem>

				<listitem>
				<para>Next, set permissions for this new directory to allow only
				desired users to access it. One approach to this is to
				create a new group such as "windows," add the
				desired users to that group (see the sub-section on groups
				in the Handbook's Users and Basic Account Management
				section), and set to the permissions on the directory to
				"770" (the section on Permissions in the &os;
				Basics chapter of the Handbook illustrates this process).</para>
				</listitem>

				<listitem>
				<para>Finally, add the location as a drive to the user's prefix
				using the <application>winecfg</application> as
				described in the above section on WINE Configuration in this
				chapter.</para>
				</listitem>
				</orderedlist>

				<para>Once complete, applications can be installed to this location,
				and subsequently run using the assigned drive letter (or the
				standard &os.unix;-style directory path). However, as noted
				above, only one user should be running these applications (which
				may be accessing files within their installation directory) at
				the same time. Some applications may also exhibit unexpected
				behavior when run by a user who is not the owner, despite being
				a member of the group that should have full
				"read/write/execute" permissions for the entire
				directory.</para>
				</sect2>

				<sect2 xml:id="using-a-common-installation-of-wine">
				<title>Using a Common Installation of WINE</title>

				<para>If, on the other hand, there are many applications to be shared,
				or they require specific tuning in order to work correctly, a
				different approach may be required. In this method, a completely
				separate user is created specifically for the purposes of
				storing the WINE prefix and all its installed applications.
				Individual users are then granted permission to run programs as
				this user using the <application>su</application>
				command. The result is that these users can launch a WINE
				application as they normally would, only it will act as though
				launched by the newly-created user, and therefore use the
				centrally-maintained prefix containing both settings and
				programs. To accomplish this, take the following steps.</para>

				<para>Create a new user with the following command (as root), which
				will step through the required details:</para>

				<screen>&prompt.root;<userinput>adduser</userinput></screen>

				<para>Enter the username (e.g. "windows") and Full name
				("Microsoft Windows"). Then accept the defaults for
				the remainder of the questions. Next, install the
				<application>sudo</application> utlity using binary
				packages with the following:</para>

				<screen>&prompt.root;<userinput>pkg install sudo</userinput></screen>

				<para>Once installed, edit the<filename>/etc/sudoers</filename> file
				as follows:</para>

				<programlisting># User alias specification

				# define which users can run the wine/windows programs
				User_Alias WINDOWS_USERS = user1,user2

				# define which users can administrate (become root)
				User_Alias ADMIN = user1

				# Cmnd alias specification

				# define which commands the WINDOWS_USERS may run
				Cmnd_Alias WINDOWS = /usr/bin/wine,/usr/bin/winecfg

				# Defaults
				Defaults:WINDOWS_USERS env_reset
				Defaults:WINDOWS_USERS env_keep += DISPLAY
				Defaults:WINDOWS_USERS env_keep += XAUTHORITY
				Defaults !lecture,tty_tickets,!fqdn

				# User privilege specification
				root ALL=(ALL) ALL

				# Members of the admin user_alias, defined above, may gain root privileges
				ADMIN ALL=(ALL) ALL

				# The WINDOWS_USERS may run WINDOWS programs as user windows without a password
				WINDOWS_USERS ALL = (windows) NOPASSWD: WINDOWS</programlisting>

				<para>The result of these changes is the users named in the
				<emphasis>User_Alias</emphasis> section
				are permitted to run the programs listed in the
				<emphasis>Cmnd<subscript>Alias</subscript></emphasis> section
				using the resources listed in the <emphasis>Defaults</emphasis>
				section (the current display) as if they were the user listed in
				the final line of the file. In other words, users designates as
				<emphasis>WINDOWS_USERS</emphasis> can run the <application>wine
				</application> and <application>winecfg</application> applications as
				user <emphasis>windows</emphasis>. As a bonus, the configuration
				here means they will not be required to enter the password for
				the <emphasis>windows</emphasis> user.</para>

				<para>Next provide access to the display back to the
				<emphasis>windows</emphasis> user, as whom the WINE programs
				will be running:
				</para>

				<screen>&prompt;<userinput>xhost +local:windows</userinput></screen>

				<para>This should be added to the list of commands run either at login
				or when the default graphical environment starts. Once all the
				above are complete, a user configured as one of the
				"WINDOW_USERS" in the <filename>sudoers</filename> file can
				run programs using the shared prefix with the followihng command:</para>

				<para>It's worth noting that multiple users accessing this shared
				environment at the same time is still risky. However, consider
				also that the shared environment can itself contain multiple
				prefixes. In this way an administrator can create a tested and
				verified set of programs, each with its own prefix. At the same
				time, one user can play a game while another works with office
				programs without the need for redundant software installations.</para>
				</sect2>
				</sect1>
				</chapter>