diff --git a/en_US.ISO8859-1/books/handbook/Makefile b/en_US.ISO8859-1/books/handbook/Makefile
index dc04a1b584..aed69a7d35 100644
--- a/en_US.ISO8859-1/books/handbook/Makefile
+++ b/en_US.ISO8859-1/books/handbook/Makefile
@@ -151,6 +151,42 @@ IMAGES_EN+= virtualization/vmware-freebsd09.png
IMAGES_EN+= virtualization/vmware-freebsd10.png
IMAGES_EN+= virtualization/vmware-freebsd11.png
IMAGES_EN+= virtualization/vmware-freebsd12.png
+IMAGES_EN+= wine/wine-run-np++-1.png
+IMAGES_EN+= wine/wine-config-1.png
+IMAGES_EN+= wine/wine-config-2.png
+IMAGES_EN+= wine/wine-config-3.png
+IMAGES_EN+= wine/wine-config-4.png
+IMAGES_EN+= wine/wine-config-5.png
+IMAGES_EN+= wine/wine-config-6.png
+IMAGES_EN+= wine/wine-config-7.png
+IMAGES_EN+= wine/winetricks-run-1.png
+IMAGES_EN+= wine/winetricks-run-2.png
+IMAGES_EN+= wine/winetricks-menu-1.jpg
+IMAGES_EN+= wine/winetricks-uninstall-1.jpg
+IMAGES_EN+= wine/winetricks-uninstall-2.jpg
+IMAGES_EN+= wine/winetricks-uninstall-3.jpg
+IMAGES_EN+= wine/homura-launch-1.jpg
+IMAGES_EN+= wine/homura-run-2.jpg
+IMAGES_EN+= wine/homura-run-3.jpg
+IMAGES_EN+= wine/homura-install-1.jpg
+IMAGES_EN+= wine/homura-install-2.jpg
+IMAGES_EN+= wine/homura-install-3.jpg
+IMAGES_EN+= wine/homura-install-4.jpg
+IMAGES_EN+= wine/homura-install-5.jpg
+IMAGES_EN+= wine/homura-install-6.jpg
+IMAGES_EN+= wine/homura-install-7.jpg
+IMAGES_EN+= wine/homura-install-8.jpg
+IMAGES_EN+= wine/homura-uninstall-1.jpg
+IMAGES_EN+= wine/homura-run-2.jpg
+IMAGES_EN+= wine/homura-run-3.jpg
+IMAGES_EN+= wine/winetricks-run-1.png
+IMAGES_EN+= wine/winetricks-run-2.png
+IMAGES_EN+= wine/winetricks-app-install-1.png
+IMAGES_EN+= wine/winetricks-app-install-2.png
+IMAGES_EN+= wine/winetricks-menu-1.jpg
+IMAGES_EN+= wine/winetricks-uninstall-1.jpg
+IMAGES_EN+= wine/winetricks-uninstall-2.jpg
+IMAGES_EN+= wine/winetricks-uninstall-3.jpg
# Images from the cross-document image library
IMAGES_LIB= callouts/1.png
@@ -212,6 +248,7 @@ SRCS+= security/chapter.xml
SRCS+= serialcomms/chapter.xml
SRCS+= usb-device-mode/chapter.xml
SRCS+= virtualization/chapter.xml
+SRCS+= wine/chapter.xml
SRCS+= x11/chapter.xml
# Entities
diff --git a/en_US.ISO8859-1/books/handbook/book.xml b/en_US.ISO8859-1/books/handbook/book.xml
index 95de7bab27..97ab915034 100644
--- a/en_US.ISO8859-1/books/handbook/book.xml
+++ b/en_US.ISO8859-1/books/handbook/book.xml
@@ -4,7 +4,6 @@
<!--
The FreeBSD Documentation Project
- $FreeBSD$
-->
<!ENTITY % chapters SYSTEM "chapters.ent">
@@ -224,6 +223,7 @@
&chap.kernelconfig;
&chap.printing;
&chap.linuxemu;
+ &chap.wine;
</part>
<part xml:id="system-administration">
diff --git a/en_US.ISO8859-1/books/handbook/chapters.ent b/en_US.ISO8859-1/books/handbook/chapters.ent
index 2c3402c0af..0a4704c1e9 100644
--- a/en_US.ISO8859-1/books/handbook/chapters.ent
+++ b/en_US.ISO8859-1/books/handbook/chapters.ent
@@ -7,7 +7,6 @@
Chapters should be listed in the order in which they are referenced.
- $FreeBSD$
-->
<!ENTITY chap.preface SYSTEM "preface/preface.xml">
@@ -26,6 +25,7 @@
<!ENTITY chap.kernelconfig SYSTEM "kernelconfig/chapter.xml">
<!ENTITY chap.printing SYSTEM "printing/chapter.xml">
<!ENTITY chap.linuxemu SYSTEM "linuxemu/chapter.xml">
+ <!ENTITY chap.wine SYSTEM "wine/chapter.xml">
<!-- Part Three -->
<!ENTITY chap.config SYSTEM "config/chapter.xml">
diff --git a/en_US.ISO8859-1/books/handbook/preface/preface.xml b/en_US.ISO8859-1/books/handbook/preface/preface.xml
index 427056edf8..b407afb658 100644
--- a/en_US.ISO8859-1/books/handbook/preface/preface.xml
+++ b/en_US.ISO8859-1/books/handbook/preface/preface.xml
@@ -36,6 +36,11 @@
the two volume third edition was published in 2004:</para>
<itemizedlist>
+ <listitem>
+ <para><xref linkend="wine"/> has been added with information
+ about how to run &windows; applications on &os;.</para>
+ </listitem>
+
<listitem>
<para><xref linkend="dtrace"/> has been added with information
about the powerful &dtrace; performance analysis tool.</para>
diff --git a/en_US.ISO8859-1/books/handbook/wine/Makefile b/en_US.ISO8859-1/books/handbook/wine/Makefile
new file mode 100644
index 0000000000..b0c6855e1e
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/wine/Makefile
@@ -0,0 +1,14 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+#
+
+CHAPTERS= wine/chapter.xml
+
+VPATH= ..
+
+MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= ${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/en_US.ISO8859-1/books/handbook/wine/chapter.xml b/en_US.ISO8859-1/books/handbook/wine/chapter.xml
new file mode 100644
index 0000000000..e749793ed2
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/wine/chapter.xml
@@ -0,0 +1,1838 @@
+<?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>
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Benedict</firstname>
+ <surname>Reuschling</surname>
+ </personname>
+ <contrib>DocBook markup edits by </contrib>
+ </author>
+ </authorgroup>
+</info>
+
+ <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 &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
+ &windows; calls to calls that &os; understands. It will also
+ translate any responses as needed into what the &windows;
+ software is expecting. So in some ways, it
+ <emphasis>emulates</emphasis> a &windows; environment, in that
+ it provides many of the resources &windows; applications are
+ expecting.</para>
+
+ <para>However, it is 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 will not 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 is running.</para>
+
+ <para>The WINE Project, on the other hand, is much lighter on
+ system's resources. It will translate system calls on the fly,
+ so while it is difficult to be as fast as a real &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 do not work
+ as expected on WINE, will not work at all, or will not even
+ install to begin with.</para>
+
+ <para>At the end of the day, WINE provides another option to try
+ to get a particular &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 is 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="wine-overview-concepts">
+ <title>WINE Overview & Concepts</title>
+
+ <para>WINE is a complex system, so before running it on a &os;
+ system it is 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 compatibility layer that allows &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 &windows; executable, two things
+ occur:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Firstly, WINE implements an environment that mimics
+ that of various versions of &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 &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 &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
+ &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 &windows; (for example
+ <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 &windows; executables, which are (or
+ mimic) common utilities (such as
+ <filename>/lib/wine/notepad.exe.so</filename>, which
+ provides the standard &windows; text editor).</para>
+ </listitem>
+
+ <listitem>
+ <para>Additional &windows; assets, in particular fonts (like
+ the Tahoma font, which is stored in
+ <filename>share/wine/fonts/tahoma.ttf</filename> in
+ the install root).</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2
+ xml:id="graphical-versus-text-modeterminal-programs-in-wine">
+ <title>Graphical Versus Text Mode/Terminal Programs in
+ WINE</title>
+
+ <para>As an operating system where terminal utilities are
+ <quote>first-class citizens,</quote> it is natural to assume
+ that WINE will contain extensive support for text-mode
+ program. However, the majority of applications for &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 is
+ little surprise it is 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
+ <quote>one-click</quote> 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 <application>CrossOver</application> 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 &windows;
+ games to install and run on other systems. it is primary
+ target is Linux-based systems, though 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</link>, 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 &windows; applications natively on that OS. This
+ of course means existing &os; in order to boot &windows;,
+ so this method is not 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 &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 cannot 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 &unix;-like systems,
+ &os; can run a variety of applications enabling users to
+ remotely access &windows; computers and use their programs
+ or data. In addtion to clients such as
+ <application>xrdp</application> that connect to the
+ standard &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>
+
+ <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 is useful to have the
+ following pre-requisites installed.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A GUI</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Most &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 is
+ useful to have the GUI of choice installed, configured,
+ and working correctly before installing WINE.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>wine-gecko</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The &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 users might want it do
+ so (these will be covered in a later chapter). But they 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 the
+ WINE installation will make it that much more likely that any
+ applications written in .NET will install and run on the
+ 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="thirtytwo-vs-sixtyfour-bit-wine">
+ <title>Concerns of 32- Versus 64-Bit in WINE
+ Installations</title>
+
+ <para>Like most software, &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 do not 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
+ &windows; software, simply install the ports mentioned in
+ the above sections. The ports system will automatically
+ install the 64-bit version.</para>
+ </listitem>
+
+ <listitem>
+ <para>Alternately, users might have an older 32-bit machine
+ that they do not want to run with its original, now
+ non-supported software. They 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> &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 compile the port with the following:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/emulator/i386-wine</userinput>
+&prompt.root; <userinput>make install</userinput></screen>
+ </sect2>
+ </sect1>
+
+ <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 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 (<filename>.EXE</filename>) and
+ issue the following:</para>
+
+ <screen>&prompt.user; <userinput>wine program.exe</userinput></screen>
+
+ <para>For applications that take command-line arguments, add
+ them after the executable as usual:</para>
+
+ <screen>&prompt.user; <userinput>wine <replaceable>program2.exe</replaceable> -file <filename><replaceable>file.txt</replaceable></filename></userinput></screen>
+
+ <para>Alternately, supply the full path to the executable to
+ use it in a script, for example:</para>
+
+ <screen>&prompt.user; <userinput>wine /home/<replaceable>user</replaceable>/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
+ (<filename>.EXE</filename>) 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-run-np++-1"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>In the event the program does not 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 is not the default application for
+ <filename>.EXE</filename> files after install, check the
+ MIME associate for this extension in the current desktop
+ environment, graphical shell, or file manager.</para>
+ </sect2>
+ </sect1>
+
+ <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
+ &os; is becoming familiar with its configuration. The
+ following sections will describe the key concept of the
+ <emphasis>WINE prefix</emphasis>, and illustrate how it is
+ 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
+ <filename>$HOME/.wine</filename> though it can be located
+ elsewhere. The prefix is a set of configurations and
+ support files used by the <application>wine</application> 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:</para>
+
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para><filename>.update-timestamp</filename>: contains the
+ last modified date of
+ <filename>file /usr/share/wine/wine.inf</filename>. It
+ is 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>: contains
+ information on mappings of &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
+ &windows;-style drive letters:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>c:@</filename>: A link to
+ <filename>drive_c</filename> 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>: emulates the main
+ (i.e., <filename>C:</filename>) 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
+ <emphasis>Users</emphasis> and
+ <emphasis>Windows</emphasis> that holds the OS itself.
+ Furthermore, applications installed within a prefix will
+ be located in either <emphasis>Program Files</emphasis>
+ or <emphasis>Program Files (x86)</emphasis>, depending
+ on their architecture.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>system.reg</filename>: This Registry file
+ contains information on the &windows; installation,
+ which in the case of WINE is the environment in
+ <filename>drive_c</filename>.</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
+ <filename>$HOME/.wine/</filename>, it is 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 &windows;, according to the compatibility
+ needs of the software in question.</para>
+ </listitem>
+
+ <listitem>
+ <para>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.</para>
+ </listitem>
+
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Creating a prefix from the terminal requires the
+ following command:</para>
+
+ <screen>&prompt.user; <userinput>WINEPREFIX="/home/<replaceable>username</replaceable>/.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
+ does not 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.user; <userinput>WINEPREFIX="/home/<replaceable>username</replaceable>/.wine-new" wine program.exe</userinput></screen>
+ </sect2>
+
+ <sect2 xml:id="configuring-wine-prefixes-with-winecfg">
+ <title>Configuring WINE Prefixes with
+ <application>winecfg</application></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="wine-config-1.png" />
+ </imageobject>
+ </inlinemediaobject></para>
+
+ <para>The <emphasis>Applications</emphasis> contains
+ controls enabling the association of programs with a
+ particular version of &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 &windows; to be used
+ with the selected program.</para>
+ </listitem>
+ </orderedlist>
+ </sect3>
+
+ <sect3 xml:id="libraries">
+ <title>Libraries</title>
+
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="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 &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.</para>
+
+ <para>However, <application>winecfg</application>
+ 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
+ &os; installation. For each library to be
+ overridden, 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="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="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 &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>
+ </sect3>
+
+ <sect3 xml:id="drives">
+ <title>Drives</title>
+
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="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 &windows; environment. The
+ default values in this tab should look familiar,
+ as they're displaying the contents of
+ <filename>dosdevices/</filename> in the current
+ WINE prefix. Changes made via this dialog will
+ reflect in <filename>dosdevices</filename>, 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="wine-config-6.png" />
+ </imageobject>
+ </inlinemediaobject></para>
+
+ <para>This tab contains some configurable options
+ for routing sound from &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="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>
+
+ <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 is 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
+ <application>winetricks</application></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 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
+&prompt.root; make install
+&prompt.root; cd /usr/ports/emulators/winetricks
+&prompt.root; 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
+ <application>winetricks</application></title>
+
+ <para>Run <application>winetricks</application> with
+ the following command:</para>
+
+ <screen>&prompt.user; <userinput>winetricks</userinput></screen>
+
+ <para>Note: this should be in a 32-bit prefix
+ 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="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="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="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="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="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="winetricks-uninstall-1.jpg" />
+ </imageobject>
+ </inlinemediaobject></para>
+
+ <para>A &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="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="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, 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
+&prompt.root; 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.user; <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="homura-launch-1.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="homura-run-2.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="homura-run-3.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="homura-install-1.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="homura-install-2.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="homura-install-3.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="homura-install-4.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="homura-install-5.jpg" />
+ </imageobject>
+ </inlinemediaobject></para>
+
+ <para>Downloaded packages are automatically opened and run
+ as required.</para>
+
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata
+ fileref="homura-install-6.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="homura-install-7.jpg" />
+ </imageobject>
+ </inlinemediaobject></para>
+
+ <para>This will display a list of installed
+ applications.</para>
+
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata
+ fileref="homura-install-8.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="homura-uninstall-1.jpg" />
+ </imageobject>
+ </inlinemediaobject></para>
+ </sect3>
+ </sect2>
+
+ <sect2 xml:id="running-multiple-management-guis">
+ <title>Running Multiple Management GUIs</title>
+
+ <para>it is worth noting that the above solutions are not
+ mutually exclusive. it is perfectly acceptable, even
+ advantageous, to have both installed at the same time, as
+ they support a different set of programs.</para>
+
+ <para>However, it is wise to ensure that they do not 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>
+
+ <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 &unix;-like operating systems, &os; is
+ designed for multiple users to be logged in and working at
+ the same time. On the other hand, &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 &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 acompatible 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 their
+ 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
+ <literal>770</literal> (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 &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.,
+ <replaceable>windows</replaceable>) 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 <filename>/etc/sudoers</filename>
+ 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.user; <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
+ <literal>WINDOW_USERS</literal> in
+ <filename>sudoers</filename> can run programs using the
+ shared prefix with the following command:</para>
+
+ <para>it is 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>
+
+ <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 cannot 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 does not 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-windows-hardware-graphics-drivers-be-handled">
+ <title>How Should &windows; Hardware (e.g., Graphics) Drivers
+ be Handled?</title>
+
+ <para>Operating system drivers transfer commands between
+ applications and hardware. WINE emulates a &windows;
+ environment, including the drivers, which in turn use
+ &os;'s native drivers for this transfer. it is not advisable
+ to install &windows; drivers, as the WINE system is designed
+ to use the host systems drivers. If, for example,
+ a graphics card that benefits from dedicated drivers,
+ install them using the standard &os; methods, not &windows;
+ installers.</para>
+ </sect3>
+
+ <sect3 xml:id="is-there-a-way-to-make-windows-fonts-look-better">
+ <title>Is There a way to Make &windows; Fonts Look
+ Better?</title>
+
+ <para>A user on the &os; 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
+ <filename>.config/fontconfig/fonts.conf</filename>
+ will add anti-aliasing and make text more readable.</para>
+
+ <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-windows-installed-elsewhere-on-a-system-help-wine-operate">
+ <title>Does Having &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 &windows; partition or
+ drive is mounted to the &os; system and accessible to the
+ user, configuring some of these overrides will use native
+ &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 &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 under way 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 &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 &os;
+ 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">&os;
+ 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
+ available on &os;.</para>
+ </listitem>
+
+ <listitem>
+ <para>Finally, Codeweavers (a developer of a commercial
+ version of WINE) is an active upstream contributor.
+ Oftentimes 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>
+ </chapter>
diff --git a/share/images/books/handbook/wine/homura-install-1.jpg b/share/images/books/handbook/wine/homura-install-1.jpg
new file mode 100644
index 0000000000..b1bbb1912c
Binary files /dev/null and b/share/images/books/handbook/wine/homura-install-1.jpg differ
diff --git a/share/images/books/handbook/wine/homura-install-10.png.jpg b/share/images/books/handbook/wine/homura-install-10.png.jpg
new file mode 100644
index 0000000000..0ce1a86765
Binary files /dev/null and b/share/images/books/handbook/wine/homura-install-10.png.jpg differ
diff --git a/share/images/books/handbook/wine/homura-install-2.jpg b/share/images/books/handbook/wine/homura-install-2.jpg
new file mode 100644
index 0000000000..5bd881d763
Binary files /dev/null and b/share/images/books/handbook/wine/homura-install-2.jpg differ
diff --git a/share/images/books/handbook/wine/homura-install-3.jpg b/share/images/books/handbook/wine/homura-install-3.jpg
new file mode 100644
index 0000000000..db9549dd67
Binary files /dev/null and b/share/images/books/handbook/wine/homura-install-3.jpg differ
diff --git a/share/images/books/handbook/wine/homura-install-4.jpg b/share/images/books/handbook/wine/homura-install-4.jpg
new file mode 100644
index 0000000000..da8625e781
Binary files /dev/null and b/share/images/books/handbook/wine/homura-install-4.jpg differ
diff --git a/share/images/books/handbook/wine/homura-install-5.jpg b/share/images/books/handbook/wine/homura-install-5.jpg
new file mode 100644
index 0000000000..a2fc4cf3c7
Binary files /dev/null and b/share/images/books/handbook/wine/homura-install-5.jpg differ
diff --git a/share/images/books/handbook/wine/homura-install-6.jpg b/share/images/books/handbook/wine/homura-install-6.jpg
new file mode 100644
index 0000000000..2c36f824f9
Binary files /dev/null and b/share/images/books/handbook/wine/homura-install-6.jpg differ
diff --git a/share/images/books/handbook/wine/homura-install-7.jpg b/share/images/books/handbook/wine/homura-install-7.jpg
new file mode 100644
index 0000000000..19e766f34d
Binary files /dev/null and b/share/images/books/handbook/wine/homura-install-7.jpg differ
diff --git a/share/images/books/handbook/wine/homura-install-8.jpg b/share/images/books/handbook/wine/homura-install-8.jpg
new file mode 100644
index 0000000000..60eb7ccb90
Binary files /dev/null and b/share/images/books/handbook/wine/homura-install-8.jpg differ
diff --git a/share/images/books/handbook/wine/homura-install-9.png.jpg b/share/images/books/handbook/wine/homura-install-9.png.jpg
new file mode 100644
index 0000000000..249cdb65cf
Binary files /dev/null and b/share/images/books/handbook/wine/homura-install-9.png.jpg differ
diff --git a/share/images/books/handbook/wine/homura-launch-1.jpg b/share/images/books/handbook/wine/homura-launch-1.jpg
new file mode 100644
index 0000000000..1f0d599e88
Binary files /dev/null and b/share/images/books/handbook/wine/homura-launch-1.jpg differ
diff --git a/share/images/books/handbook/wine/homura-run-2.jpg b/share/images/books/handbook/wine/homura-run-2.jpg
new file mode 100644
index 0000000000..9db9614225
Binary files /dev/null and b/share/images/books/handbook/wine/homura-run-2.jpg differ
diff --git a/share/images/books/handbook/wine/homura-run-3.jpg b/share/images/books/handbook/wine/homura-run-3.jpg
new file mode 100644
index 0000000000..f63b4267b0
Binary files /dev/null and b/share/images/books/handbook/wine/homura-run-3.jpg differ
diff --git a/share/images/books/handbook/wine/homura-run-4.png.jpg b/share/images/books/handbook/wine/homura-run-4.png.jpg
new file mode 100644
index 0000000000..4eaca2960d
Binary files /dev/null and b/share/images/books/handbook/wine/homura-run-4.png.jpg differ
diff --git a/share/images/books/handbook/wine/homura-uninstall-1.jpg b/share/images/books/handbook/wine/homura-uninstall-1.jpg
new file mode 100644
index 0000000000..8d4ada30d6
Binary files /dev/null and b/share/images/books/handbook/wine/homura-uninstall-1.jpg differ
diff --git a/share/images/books/handbook/wine/wine-config-1.png b/share/images/books/handbook/wine/wine-config-1.png
new file mode 100644
index 0000000000..55611a9608
Binary files /dev/null and b/share/images/books/handbook/wine/wine-config-1.png differ
diff --git a/share/images/books/handbook/wine/wine-config-2.png b/share/images/books/handbook/wine/wine-config-2.png
new file mode 100644
index 0000000000..8b6ef10967
Binary files /dev/null and b/share/images/books/handbook/wine/wine-config-2.png differ
diff --git a/share/images/books/handbook/wine/wine-config-3.png b/share/images/books/handbook/wine/wine-config-3.png
new file mode 100644
index 0000000000..7e6fd50669
Binary files /dev/null and b/share/images/books/handbook/wine/wine-config-3.png differ
diff --git a/share/images/books/handbook/wine/wine-config-4.png b/share/images/books/handbook/wine/wine-config-4.png
new file mode 100644
index 0000000000..636c827ffe
Binary files /dev/null and b/share/images/books/handbook/wine/wine-config-4.png differ
diff --git a/share/images/books/handbook/wine/wine-config-5.png b/share/images/books/handbook/wine/wine-config-5.png
new file mode 100644
index 0000000000..d1cb04c963
Binary files /dev/null and b/share/images/books/handbook/wine/wine-config-5.png differ
diff --git a/share/images/books/handbook/wine/wine-config-6.png b/share/images/books/handbook/wine/wine-config-6.png
new file mode 100644
index 0000000000..3c4542bb96
Binary files /dev/null and b/share/images/books/handbook/wine/wine-config-6.png differ
diff --git a/share/images/books/handbook/wine/wine-config-7.png b/share/images/books/handbook/wine/wine-config-7.png
new file mode 100644
index 0000000000..80397f1c0e
Binary files /dev/null and b/share/images/books/handbook/wine/wine-config-7.png differ
diff --git a/share/images/books/handbook/wine/wine-run-np++-1.png b/share/images/books/handbook/wine/wine-run-np++-1.png
new file mode 100644
index 0000000000..3a83675b54
Binary files /dev/null and b/share/images/books/handbook/wine/wine-run-np++-1.png differ
diff --git a/share/images/books/handbook/wine/wine-run-np++-1.scr b/share/images/books/handbook/wine/wine-run-np++-1.scr
new file mode 100644
index 0000000000..3a83675b54
Binary files /dev/null and b/share/images/books/handbook/wine/wine-run-np++-1.scr differ
diff --git a/share/images/books/handbook/wine/winetricks-app-install-1.png b/share/images/books/handbook/wine/winetricks-app-install-1.png
new file mode 100644
index 0000000000..2b0f0500bd
Binary files /dev/null and b/share/images/books/handbook/wine/winetricks-app-install-1.png differ
diff --git a/share/images/books/handbook/wine/winetricks-app-install-2.png b/share/images/books/handbook/wine/winetricks-app-install-2.png
new file mode 100644
index 0000000000..e552ae88a8
Binary files /dev/null and b/share/images/books/handbook/wine/winetricks-app-install-2.png differ
diff --git a/share/images/books/handbook/wine/winetricks-install-1.png b/share/images/books/handbook/wine/winetricks-install-1.png
new file mode 100644
index 0000000000..0b1b5cb130
Binary files /dev/null and b/share/images/books/handbook/wine/winetricks-install-1.png differ
diff --git a/share/images/books/handbook/wine/winetricks-menu-1.jpg b/share/images/books/handbook/wine/winetricks-menu-1.jpg
new file mode 100644
index 0000000000..3b4359e7f8
Binary files /dev/null and b/share/images/books/handbook/wine/winetricks-menu-1.jpg differ
diff --git a/share/images/books/handbook/wine/winetricks-run-1.png b/share/images/books/handbook/wine/winetricks-run-1.png
new file mode 100644
index 0000000000..1fd5acc22a
Binary files /dev/null and b/share/images/books/handbook/wine/winetricks-run-1.png differ
diff --git a/share/images/books/handbook/wine/winetricks-run-2.png b/share/images/books/handbook/wine/winetricks-run-2.png
new file mode 100644
index 0000000000..ae35b5db80
Binary files /dev/null and b/share/images/books/handbook/wine/winetricks-run-2.png differ
diff --git a/share/images/books/handbook/wine/winetricks-uninstall-1.jpg b/share/images/books/handbook/wine/winetricks-uninstall-1.jpg
new file mode 100644
index 0000000000..5df6f43ffc
Binary files /dev/null and b/share/images/books/handbook/wine/winetricks-uninstall-1.jpg differ
diff --git a/share/images/books/handbook/wine/winetricks-uninstall-2.jpg b/share/images/books/handbook/wine/winetricks-uninstall-2.jpg
new file mode 100644
index 0000000000..b3d98d256b
Binary files /dev/null and b/share/images/books/handbook/wine/winetricks-uninstall-2.jpg differ
diff --git a/share/images/books/handbook/wine/winetricks-uninstall-3.jpg b/share/images/books/handbook/wine/winetricks-uninstall-3.jpg
new file mode 100644
index 0000000000..a4c8c96677
Binary files /dev/null and b/share/images/books/handbook/wine/winetricks-uninstall-3.jpg differ