diff --git a/en_US.ISO8859-1/books/handbook/Makefile b/en_US.ISO8859-1/books/handbook/Makefile --- a/en_US.ISO8859-1/books/handbook/Makefile +++ b/en_US.ISO8859-1/books/handbook/Makefile @@ -151,6 +151,42 @@ 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+= 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 --- a/en_US.ISO8859-1/books/handbook/book.xml +++ b/en_US.ISO8859-1/books/handbook/book.xml @@ -4,7 +4,6 @@ @@ -224,6 +223,7 @@ &chap.kernelconfig; &chap.printing; &chap.linuxemu; + &chap.wine; diff --git a/en_US.ISO8859-1/books/handbook/chapters.ent b/en_US.ISO8859-1/books/handbook/chapters.ent --- 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$ --> @@ -26,6 +25,7 @@ + diff --git a/en_US.ISO8859-1/books/handbook/preface/preface.xml b/en_US.ISO8859-1/books/handbook/preface/preface.xml --- 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: + + has been added with information + about how to run &windows; applications on &os;. + + has been added with information about the powerful &dtrace; performance analysis tool. diff --git a/en_US.ISO8859-1/books/handbook/wine/Makefile b/en_US.ISO8859-1/books/handbook/wine/Makefile new file mode 100644 --- /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 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/wine/chapter.xml @@ -0,0 +1,1838 @@ + + + + + WINE + + + + + Aaron + Peters + + Contributed by + + + + + + Benedict + Reuschling + + DocBook markup edits by + + + + + + Synopsis + + WINE, + 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. + + 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 + emulates a &windows; environment, in that + it provides many of the resources &windows; applications are + expecting. + + 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 + emulators/qemu 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 + guest) requires resources from the real + machine (the host), and holds on to those + resources for as long as it is running. + + 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. + + 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. + + This chapter will describe: + + + + How to install WINE on a &os; system. + + + + How WINE operates, and how it is different from other + alternatives like virtualizaton. + + + + How to fine-tune WINE to the specific needs of some + applications. + + + + How to install GUI helpers for WINE. + + + + Common tips and solutions for on &os;. + + + + Considerations for WINE on &os; in terms of the + multi-user environment. + + + + Before reading this chapter, it will be useful to: + + + + Understand the basics of &unix; + and &os;. + + + + Know how to install + &os;. + + + + Know how to set up a + network connection. + + + + Know how to install additional + third-party software. + + + + + + WINE Overview & Concepts + + 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. + + + What is WINE? + + As mentioned in the Synopsis 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. + + When WINE runs a &windows; executable, two things + occur: + + + + 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;. + + + + 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. + + + + + + WINE and the &os; System + + Installing WINE on a &os; system will entail a few + different components: + + + + &os; applications for tasks such as running the + &windows; executables, configuring the WINE sub-system, or + compiling programs with WINE support. + + + + A large number of libraries that implement the core + functions of &windows; (for example + /lib/wine/api-ms-core-memory-l1-1-1.dll.so, + which is part of the aforementioned memory + interface). + + + + A number of &windows; executables, which are (or + mimic) common utilities (such as + /lib/wine/notepad.exe.so, which + provides the standard &windows; text editor). + + + + Additional &windows; assets, in particular fonts (like + the Tahoma font, which is stored in + share/wine/fonts/tahoma.ttf in + the install root). + + + + + + Graphical Versus Text Mode/Terminal Programs in + WINE + + As an operating system where terminal utilities are + first-class citizens, 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. + + However, there are three methods available to run these + so-called Console User Interface (CUI) programs: + + + + The Bare Streams approach will + display the output directly to standard output. + + + + The wineconsole utility can be + used with either the user or + curses backed to utilize some of the + enhancements the WINE system provides for CUI + applications. + + + + These approaches are described in greater detail on the + WINE + Wiki. + + + + WINE Derivative Projects + + WINE itself is a mature open source project, so it is + little surprise it is used as the foundation of more complex + solutions. + + + Commercial WINE Implementations + + 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: + + + + Codeweavers CrossOver + + + + This solution provides a simplified + one-click installation of WINE, which + contains additional enhancements and optimizations (although + the company contributes many of these back upstream to the + WINE project). One area of focus for Codeweavers is to make + the most popular applications install and run + smoothly. + + 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 dedicated + forum) are still present, they also have seen no + activity for some time. + + + + Steam Proton + + + + 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. + + While Steam does not offer a native &os; client,there + are several options for using the &linux; client using + &os;'s Linux Compatibility Layer. + + + + WINE Companion Programs + + 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. + + These solutions are covered in greater detail in the + later section on GUI frontends, and + include the following: + + + + winetricks + + + + Homura + + + + + + + Alternatives to WINE + + For &os; users, some alternatives to using WINE are as + follows: + + + + 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. + + + + 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 Virtualization for + more detail. + + + + 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 + xrdp that connect to the + standard &windows; Remote Desktop Protocol, other open + source standards such as vnc + can also be used (provided a compatible server is present + on the other side). + + + + + + + Installing WINE on &os; + + WINE can be installed via the pkg tool, or by compiling the + port(s). + + + WINE Prerequistes + + Before installing WINE itself, it is useful to have the + following pre-requisites installed. + + + + A GUI + + + + 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. + + + + wine-gecko + + + + 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. + + Install this package with the following: + + &prompt.root; pkg install wine-gecko + + Alternately, compile the port with the following: + + &prompt.root; cd /usr/ports/emulator/wine-gecko +&prompt.root; make install + + + + wine-mono + + + + 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. + + To install the package: + + &prompt.root; pkg install wine-mono + + To compile from the ports collection: + + &prompt.root; cd /usr/ports/emulator/wine-mono +&prompt.root; make install + + + + Installing WINE via &os; Package Repositories + + With the pre-requisites in place, install WINE via package + with the following command: + + &prompt.root; pkg install wine + + Alternately compile the WINE sub-system from source with + the following: + + &prompt.root; cd /usr/ports/emulator/wine +&prompt.root; make install + + + + Concerns of 32- Versus 64-Bit in WINE + Installations + + 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. + + 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: + + + + 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. + + + + 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. + + + + However, given a 64-bit version of &os; and need to run + 32-bit &windows; + applications, installing a different port is required to + enable 32-bit compatibility. To install the pre-compiled + package, use the following: + + &prompt.root; pkg install i386-wine + + Or compile the port with the following: + + &prompt.root; cd /usr/ports/emulator/i386-wine +&prompt.root; make install + + + + + Running a First WINE Program on &os; + + 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. + + So-called "portable" versions of applications + are good choices for this test, as are programs that run with + only a single executable file. + + + Running a Program from the Command Line + + 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) and + issue the following: + + &prompt.user; wine program.exe + + For applications that take command-line arguments, add + them after the executable as usual: + + &prompt.user; wine program2.exe -file file.txt + + Alternately, supply the full path to the executable to + use it in a script, for example: + + &prompt.user; wine /home/user/bin/program.exe + + + + Running a Program from a GUI + + 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). + + 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 + Wine Windows Program + Loader, as shown in the below + screenshot: + + + + + + + + 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. + + In the event WINE is not 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. + + + + + Configuring WINE Installation + + With an understanding of what WINE is and how it works at + a high level, the next step to effectively using it on + &os; is becoming familiar with its configuration. The + following sections will describe the key concept of the + WINE prefix, and illustrate how it is + used to control the behavior of applications run through + WINE. + + + WINE Prefixes + + A WINE prefix is a directory, + usually located beneath the default location of + $HOME/.wine though it can be located + elsewhere. The prefix is a set of configurations and + support files used by the wine to + configure and run the &windows; environment a given + application needs. By default, a brand new WINE + installation will create the following structure when + first launched by a user: + + + + .update-timestamp: contains the + last modified date of + file /usr/share/wine/wine.inf. It + is used by WINE to determine if a prefix is out of date, + and automatically update it if needed. + + + + dosdevices/: contains + information on mappings of &windows; resources to + resources on the host &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: + + + + c:@: A link to + drive_c described below. + + + + z:@: A link to the root + directory of the system. + + + + + + drive_c/: emulates the main + (i.e., C:) drive of a + &windows; system. It contains a directory structure + and associated files mirroring that of standard + &windows; systems. A fresh WINE prefix will contain + &windows; 10 directories such as + Users and + Windows that holds the OS itself. + Furthermore, applications installed within a prefix will + be located in either Program Files + or Program Files (x86), depending + on their architecture. + + + + system.reg: This Registry file + contains information on the &windows; installation, + which in the case of WINE is the environment in + drive_c. + + + + user.reg: This Registry file + contains the current user's personal configurations, + made either by varous software or through the use of the + Registry Editor. + + + + userdef.reg: This Registry file + is a default set of configurations for newly-created + users. + + + + + + Creating and Using WINE Prefixes + + While WINE will create a default prefix in the user's + $HOME/.wine/, it is possible to + set up multiple prefixes. There are a few reasons to do + this: + + + + The most common reason is to emulate different + versions of &windows;, according to the compatibility + needs of the software in question. + + + + In addition, it is common to encounter software that + does not work correctly in the default environment, and + requires special configuration. it is useful to isolate + these in their own, custom prefixes, so the changes do + not impact other applications. + + + + Similarly, copying the default or "main" + prefix into a separate "testing" one in order + to evaluate an application's compatibility can reduce + the chance of corruption. + + + + Creating a prefix from the terminal requires the + following command: + + &prompt.user; WINEPREFIX="/home/username/.wine-new" winecfg + + This will run the winecfg + program, which can be used to configure wine prefixes (more + on this in a later section). But by providing a directory + path value for the WINEPREFIX environment + variable, a new prefix is created at that location if one + does not already exist. + + Supplying the same variable to the + wine program will similarly cause + the selected program to be run with the specified + prefix: + + &prompt.user; WINEPREFIX="/home/username/.wine-new" wine program.exe + + + + Configuring WINE Prefixes with + <application>winecfg</application> + + As described above WINE includes a tool called + winecfg to configure prefixes + from within a GUI. It contains a variety of functions, + which are detailed in the sections below. When + winecfg is run from within a + prefix, or provided the location of a prefix within the + WINEPREFIX variable, it enables the + configuration of the selected prefix as described in the + below sections. + + Selections made on the Applications + tab will affect the scope of changes made in the + Libraries and + Graphics tabs, which will be limited to + the application selected. See the section on Using + Winecfg in the WINE Wiki for more details. + + + Applications + + + + + + + + The Applications contains + controls enabling the association of programs with a + particular version of &windows;. On first start-up the + Application settings section will + contain a single entry: Default + Settings. This corresponds to all the + default configurations of the prefix, which (as the + disabled Remove application button + implies) cannot be deleted. + + But additional applications can be added with the + following process: + + + + Click the Add application + button. + + + + Use the provided dialog to select the desired + program's executable. + + + + Select the version of &windows; to be used + with the selected program. + + + + + + Libraries + + + + + + + + WINE provides a set of open source library files + as part of its distribution that provide the same + functions as their &windows; counterparts. However, + as noted earlier in this chapter, the WINE project is + always trying to keep pace with new updates to these + libraries. As a result, the versions that ship with + WINE may be missing functionality that the latest + &windows; programs are expecting. + + However, winecfg + makes it possible specify overrides for the built-in + libraries, particularly there is a version of + &windows; available on the same machine as the host + &os; installation. For each library to be + overridden, do the following: + + + + Open the New override for + library drop-down and select the + library to be replaced. + + + + Click the Add + button. + + + + The new override will appear in the + Existing overrides list, + notice the native, + builtin designation in + parentheses. + + + + Click to select the library. + + + + Click the Edit + button. + + + + Use the provided dialog to select a + corresponding library to be used in place + of the built-in one. + + + + Be sure to select a file that is truly the + corresponding version of the built-in one, otherwise + there may be unexpected behavior. + + + + Graphics + + + + + + + + The Graphics tab provides + some options to make the windows of programs run + via WINE operate smoothly with &os; + + + + Automatic mouse capture when windows are + full-screen. + + + + Allowing the &os; window manager to + decorate the windows, such as their title + bars, for programs running via WINE. + + + + Allowing the window manager to control + windows for programs running via WINE, such as + running resizing functions on them. + + + + Create an emulated virtual desktop, within + which all WINE programs will run. If this + item is selected, the size of the virtual + desktop can be specified using the + Desktop size input + boxes. + + + + Setting the screen resolution for programs + running via WINE. + + + + + + Desktop Integration + + + + + + + + This tab allows configuration of the following + items: + + + + The theme and related visual settings to + be used for programs running via WINE. + + + + Whether the WINE sub-system should manage + MIME types (used to determine which + application opens a particular file type) + internally. + + + + Mappings of directories in the host &os; + system to useful folders within the &windows; + environment. To change an existing + association, select the desired item and click + Browse, then use the + provided dialog to select a directory. + + + + + + Drives + + + + + + + + The Drives tab allows + linking of directories in the host &os; system to + drive letters in the &windows; environment. The + default values in this tab should look familiar, + as they're displaying the contents of + dosdevices/ in the current + WINE prefix. Changes made via this dialog will + reflect in dosdevices, and + properly-formatted links created in that directory + will display in this tab. + + To create a new entry, such as for a CD-ROM + (mounted at /mnt/cdrom), take + the following steps: + + + + Click the Add + button. + + + + In the provided dialog, choose a free + drive letter. + + + + Click OK. + + + + Fill in the Path + input box by either typing the path to the + resource, or click + Browse and use the + provided dialog to select it. + + + + By default WINE will autodetect the type of + resource linked, but this can be manually + overridden. See the + section in the WINE Wiki for more + detail on advanced options. + + + + Audio + + + + + + + + This tab contains some configurable options + for routing sound from &windows; programs to the + native &os; sound system, including: + + + + Driver selection + + + + Default device selection + + + + Sound test + + + + + + About + + + + + + + + The final tab contains information on the WINE + project, including a link to the website. It also + allows entry of (entirely optional) user + information, although this is not sent anywhere as + it is in other operating systems. + + + + + + WINE Management GUIs + + While the base install of WINE comes with a GUI + configuration tool in + winecfg, it is main purpose + is just that: strictly configuring an existing WINE + prefix. There are, however, more advanced + applications that will assist in the initial + installation of applications as well as optimizing + their WINE environments. The below sections include a + selection of the most popular. + + + Winetricks + + winetricks is a + cross-platform, general purpose helper program for + WINE. It is not developed by the WINE project + proper, but rather maintained on Github + by a group of contributors. It contains some + automated "recipes" for getting common + applications to work on WINE, both by optimizing the + settings as well as acquiring some DLL libraries + automatically. + + + Installing + <application>winetricks</application> + + To install + winetricks on a + &os; using binary packages, use the following + commands (note + winetricks requires + either the i386-wine or i386-wine-devel package, + and is therefore not installed automatically with + other dependencies): + + &prompt.root; pkg install i386-wine winetricks + + To compile it from source, issue the following + in the terminal: + + &prompt.root; cd /usr/ports/emulators/i386-wine +&prompt.root; make install +&prompt.root; cd /usr/ports/emulators/winetricks +&prompt.root; make install + + If a manual installation is required, refer to + the Github + account for instructions. + + + + Using + <application>winetricks</application> + + Run winetricks with + the following command: + + &prompt.user; winetricks + + Note: this should be in a 32-bit prefix + to run winetricks. + Launching winetricks + displays a window with a number of choices, as + follows: + + + + + + + + Selecting either Install an + application, Install a + benchmark, or Install a + game shows a list with supported + options, such as the one below for + applications: + + + + + + + + Selecting one or more items and clicking + OK will start their + installation process(es). Initially, some + messages that appear to be errors may show up, but + they're actually informational alerts as + winetricks configures + the WINE environment to get around known issues + for the application: + + + + + + + + Once these are circumvented, the actual + installer for the application will be run: + + + + + + + + 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): + + + + + + + + In order to remove the application, run + winetricks again, and + select Run an + uninstaller. + + + + + + + + A &windows;-style dialog will appear with a + list of installed programs and components. Select + the application to be removed, then click the + Modify/Remove button. + + + + + + + + This will run the applications built-in + installer, which should also have the option to + uninstall. + + + + + + + + + + + Homura + + Homura is an application similar to + winetricks, although it + was inspired by the Lutris + gaming system for Linux. But while it is focused on + games, there are also non-gaming applications + available for install through Homura. + + + Installing Homura + + To install Homura's binary package, issue the + following command: + + &prompt.root; pkg install homura + + Homura is available in the FreeBSD Ports + system. However, than the + emulators section of Ports or + binary packages, look for it in the + games section. + + &prompt.root; cd /usr/ports/games/homura +&prompt.root; make install + + + Using Homura + + Homura's usage is quite similar to that of + winetricks. When using it for + the first time, launch it from the command line (or a + desktop environment runner applet) with: + + &prompt.user; Homura + + This should result in a friendly welcome message. Click + OK to continue. + + + + + + + + The program will also offer to place a link in the + application menu of compatible environments: + + + + + + + + Depending on the setup of the &os; machine, Homura may + display a message urging the install of native graphics + drivers. + + + + + + + + The application's window should then appear, which + amounts to a "main menu" with all its options. + Many of the items are the same as + winetricks, although Homura + offers some additional, helpful options such as opening its + data folder (Open Homura Folder) or + running a specified program (Run a executable in + prefix). + + + + + + + + To select one of Homura's supported applications to + install, select Installation, and click + OK. This will display a list of + applications Homura can install automatically. Select + one, and click OK to start the + process. + + + + + + + + As a first step Homura will download the selected + program. A notification may appear in supported desktop + environments. + + + + + + + + The program will also create a new prefix for the + application. A standard WINE dialog with this message + will display. + + + + + + + + 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. + + + + + + + + Downloaded packages are automatically opened and run + as required. + + + + + + + + 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 Launcher, and + click OK. + + + + + + + + This will display a list of installed + applications. + + + + + + + + To run the new program, select it from the list, and + click OK. To uninstall the + application, select Uninstallation + from the main screen, which will display a similar list. + Select the program to be removed, and click + OK. + + + + + + + + + + + Running Multiple Management GUIs + + it is worth noting that the above solutions are not + mutually exclusive. it is perfectly acceptable, even + advantageous, to have both installed at the same time, as + they support a different set of programs. + + However, it is wise to ensure that they do not access + any of the same WINE prefixes. Each of these solutions + applies workarounds and makes changes to the registries + based on known workarounds to existing WINE issues in order + to make a given application run smoothly. Allowing both + winetricks 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. + + + + + WINE in Multi-User &os; Installations + + + Issues with Using a Common WINE Prefix + + Like most &unix;-like operating systems, &os; is + designed for multiple users to be logged in and working at + the same time. On the other hand, &windows; is multi-user + in the sense that there can be multiple user accounts set up + on one system. But the expectation is that only one will be + using the physical machine (a desktop or laptop PC) at any + given moment. + + More recent consumer versions of &windows; have taken + some steps to improve the OS in multi-user scenarios. But + it is still largely structured around a single-user + experience. Furthermore, the measures the WINE project has + taken to create acompatible environment means, unlike &os; + applications (including WINE itself), it will resemble this + single-user environment. + + So it follows that each user will have to maintain their + own set of configurations, which is potentially good. Yet + it is advantageous to install applications, particularly + large ones like office suites or games, only once. Two + examples of reasons to do this are maintenance (software + updates need only be applied once) and efficiency in storage + (no duplicated files). + + There are two strategies to minimze the impact of + multiple WINE users in the system. + + + + Installing Applications to a Common Drive + + 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. + + The steps to make install applications in this way are + as follows: + + + + First, set up a shared location on the system where + the files will be stored, such as + /mnt/windows-drive_d/. Creating new + directories is described in man page for the + mkdir command. + + + + Next, set permissions for this new directory to allow + only desired users to access it. One approach to this is + to create a new group such as "windows," add the + desired users to that group (see the sub-section on groups + in the Handbook's Users and Basic Account Management + section), and set to the permissions on the directory to + 770 (the section on Permissions in the + &os; Basics chapter of the Handbook illustrates this + process). + + + + Finally, add the location as a drive to the user's + prefix using the winecfg + as described in the above section on WINE Configuration + in this chapter. + + + + Once complete, applications can be installed to this + location, and subsequently run using the assigned drive + letter (or the standard &unix;-style directory path). + However, as noted above, only one user should be running + these applications (which may be accessing files within + their installation directory) at the same time. Some + applications may also exhibit unexpected behavior when run + by a user who is not the owner, despite being a member of + the group that should have full + "read/write/execute" permissions for the + entire directory. + + + + Using a Common Installation of WINE + + 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 + su 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. + + Create a new user with the following command (as root), + which will step through the required details: + + &prompt.root; adduser + + Enter the username (e.g., + windows) and Full name + ("Microsoft Windows"). Then accept the defaults + for the remainder of the questions. Next, install the + sudo utlity using binary packages + with the following: + + &prompt.root; pkg install sudo + + Once installed, edit /etc/sudoers + as follows: + + # 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 + + The result of these changes is the users named in the + User_Alias section are permitted to run + the programs listed in the + CmndAlias section + using the resources listed in the + Defaults section (the current display) as + if they were the user listed in the final line of the file. + In other words, users designates as + WINDOWS_USERS can run the + wine and + winecfg applications as user + windows. As a bonus, the configuration + here means they will not be required to enter the password for + the windows user. + + Next provide access to the display back to the + windows user, as whom the WINE programs + will be running: + + &prompt.user; xhost +local:windows + + This should be added to the list of commands run either at + login or when the default graphical environment starts. Once + all the above are complete, a user configured as one of the + WINDOW_USERS in + sudoers can run programs using the + shared prefix with the following command: + + it is worth noting that multiple users accessing this + shared environment at the same time is still risky. However, + consider also that the shared environment can itself contain + multiple prefixes. In this way an administrator can create a + tested and verified set of programs, each with its own prefix. + At the same time, one user can play a game while another works + with office programs without the need for redundant software + installations. + + + + + WINE on &os; FAQ + + The following section describes some frequently asked + questions, tips/tricks, or common issues in running WINE on + &os;, along with their respective answers. + + + Basic Installation and Usage + + + How to Install 32-bit and 64-bit WINE on the Same + System? + + As described earlier in this section, the + wine and + i386-wine packages conflict with + one another, and therefore cannot be installed on the same + system in the normal way. However, multiple installs can be + achieved using mechanisms like chroots/jails, or by building + WINE from source (note this does not + mean building the port). + + + + Can DOS Programs Be Run on WINE? + + They can, as "Console User Interface" + applications as mentioned eariler in this section. However, + there is an arguably better method for running DOS software: + DOSBox. On the other hand, + there's little reason not to at least try it. Simply create + a new prefix, install the software, and if it does not work + delete the prefix. + + + + Should the "wine-devel" Package/Port be + Installed to Use the Development Version of WINE Instead of + Stable? + + Yes, installing this version will install the + "development" version of WINE. As with the 32- + and 64-bit versions, they cannot be installed together with + the stable versions unless additional measures are + taken. + + Note that WINE also has a "Staging" version, + which contains the most recent updates. This was at one + time available as a &os; port; however, it has since been + removed. It can be compiled directly from source + however. + + + + + Install Optimization + + + How Should &windows; Hardware (e.g., Graphics) Drivers + be Handled? + + Operating system drivers transfer commands between + applications and hardware. WINE emulates a &windows; + environment, including the drivers, which in turn use + &os;'s native drivers for this transfer. it is not advisable + to install &windows; drivers, as the WINE system is designed + to use the host systems drivers. If, for example, + a graphics card that benefits from dedicated drivers, + install them using the standard &os; methods, not &windows; + installers. + + + + Is There a way to Make &windows; Fonts Look + Better? + + A user on the &os; forums suggests this configuration to + fix out-of-the-box look of WINE fonts, which can be slightly + pixelated. + + According to a + post in the FreeBSD Forums, adding the following to + .config/fontconfig/fonts.conf + will add anti-aliasing and make text more readable. + + <?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> + + + + Does Having &windows; Installed Elsewhere on a System + Help WINE Operate? + + It may, depending on the application being run. As + mentioned in the section describing + winecfg, some built-in WINE DLLs + and other libraries can be overridden by providing a path to + an alternate version. Provided the &windows; partition or + drive is mounted to the &os; system and accessible to the + user, configuring some of these overrides will use native + &windows; libraries and may decrease the chance of + unexpected behavior. + + + + + Application-Specific + + + Where is the Best Place to see if Application X Works on + WINE? + + The first stop in determining compatibiliy should be the + WINE + AppDB. 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. + + + + Is There Anything That Will Help Games Run + Better? + + Perhaps. Many &windows; games rely on DirectX, a + proprietary Microsoft graphics layer. However there are + projects in the open source community attempting to implement + support for this technology. + + The dxvk 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, some + &os; users report compiling and using dxvk. + + In addition, work is under way on a + wine-proton port. + This will bring the work of Valve, developer of the Steam + gaming platform, to &os;. Proton is a distribution of WINE + designed to allow many &windows; games to run on other + operating systems with minimal setup. + + + + Is There Anywhere FreeBSD WINE Users Gather to Exchange + Tips and Tricks? + + There are plenty of places FreeBSD users discuss issues + related to WINE that can be searched for solutions: + + + The &os; + forums, particularly the Installation and + Maintenance of Ports or Packages or + Emulation and virtualization + forums. + + + + &os; + IRC channels including #freebsd (for general + support), #freebsd-games, and others. + + + + The + BSD World Discord server's channels including + bsd-desktop, + bsd-gaming, + bsd-wine, and others. + + + + + + + Other OS Resources + + There are a number of resources focused on other + operating systems that may be useful for &os; users: + + + + The WINE + Wiki has a wealth of information on using WINE, + much of which is applicable across many of WINE's + supported operating systems. + + + + Similarly, the documentation available from other OS + projects can also be of good value. The + WINE page on the Arch Linux Wiki is a + particularly good example, although some of the + "Third-party applications" (i.e., + "companion applications") are obviously not + available on &os;. + + + + Finally, Codeweavers (a developer of a commercial + version of WINE) is an active upstream contributor. + Oftentimes answers to questions in their + support forum can be of aid in troubleshooting + problems with the open source version of WINE. + + + + + diff --git a/share/images/books/handbook/wine/homura-install-1.jpg b/share/images/books/handbook/wine/homura-install-1.jpg new file mode 100644 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 GIT binary patch literal 0 Hc$@