git: 1980db649f - Add new WINE handbook chapter written as part of Google Season of Docs 2020.
Benedict Reuschling
bcr at FreeBSD.org
Fri Dec 25 16:51:13 UTC 2020
The branch main has been updated by bcr:
URL: https://cgit.FreeBSD.org/doc/commit/?id=1980db649f63ddbc4e6749fc47e47efd63c1f66f
commit 1980db649f63ddbc4e6749fc47e47efd63c1f66f
Author: Benedict Reuschling <bcr at FreeBSD.org>
AuthorDate: 2020-12-25 16:48:11 +0000
Commit: Benedict Reuschling <bcr at FreeBSD.org>
CommitDate: 2020-12-25 16:48:11 +0000
Add new WINE handbook chapter written as part of Google Season of Docs 2020.
Thanks to Aaron Peters for researching and writing this chapter from
scratch. He also provided most of the images, together with Alexander
Leidinger (netchild@). Alexander was also kind enough to be the official
mentor for the WINE side of the content, while I focused on the
documentation side. His insights into WINE from a users perspective
helped make this chapter better by adding information about Homura.
A big thank you to Google Season of Docs 2020 for enabling us to have
Aaron as technical writer working on this project.
I've re-ordered the finalized submission so that the FAQ is the last
part of this chapter. I also moved the "WINE Overview & concepts"
section after the Synopsis for a more logical flow of information.
Additionally, a lot of DocBook editing was done to bring it to the
current form. The remaining checks by textproc/igor revolve around
indentation errors. But one can't fix all of them without violating
others.
Please enjoy running WINE and games on FreeBSD with the help of this
chapter.
Todo:
- Some references to other parts of the chapter or to others in the
handbook need to be replaced by actual links.
- Some of the images could be resized a bit more. I only did it on
those that would create a horizontal scroll bar. Reizing them to 50%
made them small enough to fit the other images while retaining
legible text.
A note on the images: I realize they are mixed JPEG and PNGs in the
same chapter. However, many of the images in the handbook do not
have a uniform image type either (compare IMAGES_EN+= entries in
Makefile). This may be a future project to unify these without
compromising image quality.
Contributed by: Aaron Peters (acpkendo gmail.com)
Reviewed by: netchild, bcr
Sponsored by: Google Season of Docs 2020
Differential Revision: https://reviews.freebsd.org/D27484
Differential Revision: https://reviews.freebsd.org/D27455
Differential Revision: https://reviews.freebsd.org/D27444
Differential Revision: https://reviews.freebsd.org/D27232
Differential Revision: https://reviews.freebsd.org/D27146
Differential Revision: https://reviews.freebsd.org/D26983
Differential Revision: https://reviews.freebsd.org/D26914
Differential Revision: https://reviews.freebsd.org/D26788
---
en_US.ISO8859-1/books/handbook/Makefile | 37 +
en_US.ISO8859-1/books/handbook/book.xml | 2 +-
en_US.ISO8859-1/books/handbook/chapters.ent | 2 +-
en_US.ISO8859-1/books/handbook/preface/preface.xml | 5 +
en_US.ISO8859-1/books/handbook/wine/Makefile | 14 +
en_US.ISO8859-1/books/handbook/wine/chapter.xml | 1838 ++++++++++++++++++++
.../books/handbook/wine/homura-install-1.jpg | Bin 0 -> 136796 bytes
.../books/handbook/wine/homura-install-10.png.jpg | Bin 0 -> 136799 bytes
.../books/handbook/wine/homura-install-2.jpg | Bin 0 -> 27597 bytes
.../books/handbook/wine/homura-install-3.jpg | Bin 0 -> 39100 bytes
.../books/handbook/wine/homura-install-4.jpg | Bin 0 -> 25301 bytes
.../books/handbook/wine/homura-install-5.jpg | Bin 0 -> 63194 bytes
.../books/handbook/wine/homura-install-6.jpg | Bin 0 -> 115843 bytes
.../books/handbook/wine/homura-install-7.jpg | Bin 0 -> 90915 bytes
.../books/handbook/wine/homura-install-8.jpg | Bin 0 -> 66729 bytes
.../books/handbook/wine/homura-install-9.png.jpg | Bin 0 -> 19225 bytes
.../images/books/handbook/wine/homura-launch-1.jpg | Bin 0 -> 56970 bytes
share/images/books/handbook/wine/homura-run-2.jpg | Bin 0 -> 48752 bytes
share/images/books/handbook/wine/homura-run-3.jpg | Bin 0 -> 82508 bytes
.../books/handbook/wine/homura-run-4.png.jpg | Bin 0 -> 90585 bytes
.../books/handbook/wine/homura-uninstall-1.jpg | Bin 0 -> 78638 bytes
share/images/books/handbook/wine/wine-config-1.png | Bin 0 -> 11154 bytes
share/images/books/handbook/wine/wine-config-2.png | Bin 0 -> 10516 bytes
share/images/books/handbook/wine/wine-config-3.png | Bin 0 -> 10128 bytes
share/images/books/handbook/wine/wine-config-4.png | Bin 0 -> 12296 bytes
share/images/books/handbook/wine/wine-config-5.png | Bin 0 -> 9631 bytes
share/images/books/handbook/wine/wine-config-6.png | Bin 0 -> 10604 bytes
share/images/books/handbook/wine/wine-config-7.png | Bin 0 -> 27059 bytes
.../images/books/handbook/wine/wine-run-np++-1.png | Bin 0 -> 120438 bytes
.../images/books/handbook/wine/wine-run-np++-1.scr | Bin 0 -> 120438 bytes
.../handbook/wine/winetricks-app-install-1.png | Bin 0 -> 41859 bytes
.../handbook/wine/winetricks-app-install-2.png | Bin 0 -> 20223 bytes
.../books/handbook/wine/winetricks-install-1.png | Bin 0 -> 207578 bytes
.../books/handbook/wine/winetricks-menu-1.jpg | Bin 0 -> 36456 bytes
.../books/handbook/wine/winetricks-run-1.png | Bin 0 -> 36023 bytes
.../books/handbook/wine/winetricks-run-2.png | Bin 0 -> 131302 bytes
.../books/handbook/wine/winetricks-uninstall-1.jpg | Bin 0 -> 85586 bytes
.../books/handbook/wine/winetricks-uninstall-2.jpg | Bin 0 -> 88678 bytes
.../books/handbook/wine/winetricks-uninstall-3.jpg | Bin 0 -> 52834 bytes
39 files changed, 1896 insertions(+), 2 deletions(-)
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>
*** 1218 LINES SKIPPED ***
More information about the dev-commits-doc-all
mailing list