Page MenuHomeFreeBSD
Files F164722924

D27484.id80353.diff
No OneTemporary
Actions

D27484.id80353.diff
View Options

Index: en_US.ISO8859-1/books/handbook/wine/Makefile
===================================================================
--- en_US.ISO8859-1/books/handbook/wine/Makefile
+++ en_US.ISO8859-1/books/handbook/wine/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD: head/en_US.ISO8859-1/books/handbook/virtualization/Makefile 39631 2012-10-01 09:53:01Z gabor $
+#
+
+CHAPTERS= wine/chapter.xml
+
+VPATH= ..
+
+MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= ${.CURDIR}/../../../..
+
+.include "../Makefile"
Index: en_US.ISO8859-1/books/handbook/wine/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/handbook/wine/chapter.xml
+++ en_US.ISO8859-1/books/handbook/wine/chapter.xml
@@ -0,0 +1,1773 @@
+<?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 &quot;portable&quot; 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 &amp; 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
+ &quot;first-class citizens,&quot; 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
+ &quot;one-click&quot; 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 &amp;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. &quot;C:&quot;) 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 &quot;main&quot; prefix
+ into a separate &quot;testing&quot; 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=&quot;/home/username/.wine-new&quot; 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=&quot;/home/username/.wine-new&quot; 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, &lt;application&gt;winecfg&lt;/application&gt; 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
+ &quot;recipes&quot; 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 &quot;main menu&quot; 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 &quot;Console User Interface&quot; 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 &quot;wine-devel&quot; package/port be
+ installed to use the development version of WINE instead of
+ stable?</title>
+
+ <para>Yes, installing this version will install the
+ &quot;development&quot; 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 &quot;Staging&quot; 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 &quot;Third-party
+ applications&quot; (i.e. &quot;companion applications&quot;)
+ 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 &amp;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, &amp;os; is
+ designed for multiple users to be logged in and working at the
+ same time. On the other hand, &amp;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 &quot;windows,&quot; 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
+ &quot;770&quot; (the section on Permissions in the &amp;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&lt;/application&gt; 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 &amp;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
+ &quot;read/write/execute&quot; 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&lt;/application&gt;
+ 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. &quot;windows&quot;) and Full name
+ (&quot;Microsoft Windows&quot;). Then accept the defaults for
+ the remainder of the questions. Next, install the
+ <application>sudo&lt;/application&gt; 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
+ &quot;WINDOW_USERS&quot; 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>

File Metadata

Mime Type
text/plain
Expires
Tue, Aug 4, 8:47 AM (18 h, 32 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
35957750
Default Alt Text
D27484.id80353.diff (73 KB)

Event Timeline