Index: documentation/content/en/books/handbook/wine/_index.adoc =================================================================== --- documentation/content/en/books/handbook/wine/_index.adoc +++ documentation/content/en/books/handbook/wine/_index.adoc @@ -1,17 +1,17 @@ --- -title: Chapter 11. WINE +title: Chapter 11. Wine part: Part II. Common Tasks prev: books/handbook/linuxemu next: books/handbook/partiii -description: This chapter will describe how to install WINE on a FreeBSD system and how to configure WINE -tags: ["WINE", "emulation", "guide", "tutorial"] +description: This chapter will describe how to install Wine on a FreeBSD system and how to configure Wine +tags: ["Wine", "emulation", "guide", "tutorial"] showBookMenu: true weight: 14 path: "/books/handbook/" --- [[wine]] -= WINE += Wine :doctype: book :toc: macro :toclevels: 1 @@ -51,7 +51,7 @@ [[wine-synopsis]] == Synopsis -https://www.winehq.org/[WINE], which stands for Wine Is Not an Emulator, is technically a software translation layer. +https://www.winehq.org/[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(R) on FreeBSD (and other) systems. It operates by intercepting system calls, or requests from the software to the operating system, and translating them from Windows(R) calls to calls that FreeBSD understands. @@ -65,22 +65,22 @@ 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. +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(R) 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. +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(R) software program running on FreeBSD. +At the end of the day, Wine provides another option to try to get a particular Windows(R) software program running on FreeBSD. It can always serve as the first option which, if successful, offers a good experience without unnecessarily depleting the host FreeBSD system's resources. This chapter will describe: -* How to install WINE on a FreeBSD 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. +* How to install Wine on a FreeBSD 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 FreeBSD. -* Considerations for WINE on FreeBSD in terms of the multi-user environment. +* Considerations for Wine on FreeBSD in terms of the multi-user environment. Before reading this chapter, it will be useful to: @@ -90,59 +90,59 @@ * Know how to crossref:ports[ports,install additional third-party software]. [[wine-overview-concepts]] -== WINE Overview & Concepts +== Wine Overview & Concepts -WINE is a complex system, so before running it on a FreeBSD system it is worth gaining an understanding of what it is and how it works. +Wine is a complex system, so before running it on a FreeBSD system it is worth gaining an understanding of what it is and how it works. [[what-is-wine]] -=== What is WINE? +=== What is Wine? -As mentioned in the <> for this chapter, WINE is a compatibility layer that allows Windows(R) applications to run on other operating systems. +As mentioned in the <> for this chapter, Wine is a compatibility layer that allows Windows(R) applications to run on other operating systems. In theory, it means these programs should run on systems like FreeBSD, macOS, and Android. -When WINE runs a Windows(R) executable, two things occur: +When Wine runs a Windows(R) executable, two things occur: -* Firstly, WINE implements an environment that mimics that of various versions of Windows(R). 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(R). -* 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(R) application. +* Firstly, Wine implements an environment that mimics that of various versions of Windows(R). 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(R). +* 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(R) application. [[wine-and-the-os-system]] -=== WINE and the FreeBSD System +=== Wine and the FreeBSD System -Installing WINE on a FreeBSD system will entail a few different components: +Installing Wine on a FreeBSD system will entail a few different components: -* FreeBSD applications for tasks such as running the Windows(R) executables, configuring the WINE sub-system, or compiling programs with WINE support. +* FreeBSD applications for tasks such as running the Windows(R) executables, configuring the Wine sub-system, or compiling programs with Wine support. * A large number of libraries that implement the core functions of Windows(R) (for example [.filename]#/lib/wine/api-ms-core-memory-l1-1-1.dll.so#, which is part of the aforementioned memory interface). * A number of Windows(R) executables, which are (or mimic) common utilities (such as [.filename]#/lib/wine/notepad.exe.so#, which provides the standard Windows(R) text editor). * Additional Windows(R) assets, in particular fonts (like the Tahoma font, which is stored in [.filename]#share/wine/fonts/tahoma.ttf# in the install root). [[graphical-versus-text-modeterminal-programs-in-wine]] -=== Graphical Versus Text Mode/Terminal Programs in WINE +=== 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. +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(R), 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. +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. +* 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 https://wiki.winehq.org/Wine_User%27s_Guide#Text_mode_programs_.28CUI:_Console_User_Interface.29[WINE Wiki]. +These approaches are described in greater detail on the https://wiki.winehq.org/Wine_User%27s_Guide#Text_mode_programs_.28CUI:_Console_User_Interface.29[Wine Wiki]. [[wine-derivative-projects]] -=== WINE Derivative Projects +=== 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. +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]] -==== Commercial WINE Implementations +==== 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). +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). +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. @@ -150,54 +150,54 @@ * Steam Proton -Gaming company Steam also uses WINE to enable Windows(R) games to install and run on other systems. +Gaming company Steam also uses Wine to enable Windows(R) 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 FreeBSD client,there are several options for using the Linux(R) client using FreeBSD's Linux Compatibility Layer. [[wine-companion-programs]] -==== WINE Companion Programs +==== 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. +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 <>, and include the following: * winetricks -* Homura +* Suyimazu [[alternatives-to-wine]] -=== Alternatives to WINE +=== Alternatives to Wine -For FreeBSD users, some alternatives to using WINE are as follows: +For FreeBSD users, some alternatives to using Wine are as follows: * Dual-Booting: A straightforward option is to run desired Windows(R) applications natively on that OS. This of course means existing FreeBSD in order to boot Windows(R), 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(R)) 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 <> for more detail. * Remote Access: Like many other UNIX(R)-like systems, FreeBSD can run a variety of applications enabling users to remotely access Windows(R) computers and use their programs or data. In addtion to clients such as xrdp that connect to the standard Windows(R) 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-freebsd]] -== Installing WINE on FreeBSD +== Installing Wine on FreeBSD -WINE can be installed via the pkg tool, or by compiling the port(s). +Wine can be installed via the pkg tool, or by compiling the port(s). [[wine-prerequistes]] -=== WINE Prerequistes +=== Wine Prerequistes -Before installing WINE itself, it is useful to have the following pre-requisites installed. +Before installing Wine itself, it is useful to have the following pre-requisites installed. * A GUI Most Windows(R) 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. +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(R) 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. +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: @@ -217,7 +217,7 @@ * 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. +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: @@ -235,16 +235,23 @@ .... [[installing-wine]] -=== Installing WINE via FreeBSD Package Repositories +=== Installing Wine via FreeBSD Package Repositories -With the pre-requisites in place, install WINE via package with the following command: +With the pre-requisites in place, install Wine via package with the following command: [source,shell] .... # pkg install wine .... -Alternately compile the WINE sub-system from source with the following: +In order for Wine to run 32-bit capable programs, the 32-bit libraries must also be installed. + +[source,shell] +.... +/usr/local/share/wine/pkg32.sh install wine mesa-dri +.... + +Alternately compile the Wine sub-system from source with the following: [source,shell] .... @@ -252,23 +259,19 @@ # make install .... -[[thirtytwo-vs-sixtyfour-bit-wine]] -=== Concerns of 32- Versus 64-Bit in WINE Installations - -Like most software, Windows(R) 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. -FreeBSD is no different, having had support for 64-bit since the 5.x series. +In order for Wine to run 32-bit capable programs, the 32-bit libraries must also be build. -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, FreeBSD can support all three scenarios: +The easiest way is to build the packages in https://docs.freebsd.org/en/books/porters-handbook/testing/#testing-poudriere[Poudriere] with an i386 jail and then install them with: -* On modern, 64-bit machine and want to run 64-bit Windows(R) 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 FreeBSD, then install the ports in the above sections. +[source,shell] +.... +/usr/local/share/wine/pkg32.sh /dir/to/package.txz +.... [[running-first-wine-program]] -== Running a First WINE Program on FreeBSD +== Running a First Wine Program on FreeBSD -Now that WINE is installed, the next step is to try it out by running a simple program. +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. @@ -311,36 +314,36 @@ 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 [.filename]#.EXE# files after install, check the MIME associate for this extension in the current desktop environment, graphical shell, or file manager. +In the event Wine is not the default application for [.filename]#.EXE# files after install, check the MIME associate for this extension in the current desktop environment, graphical shell, or file manager. [[configuring-wine-installation]] -== Configuring WINE Installation +== 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 FreeBSD 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. +With an understanding of what Wine is and how it works at a high level, the next step to effectively using it on FreeBSD 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]] -=== WINE Prefixes +=== Wine Prefixes -A WINE _prefix_ is a directory, usually located beneath the default location of [.filename]#$HOME/.wine# though it can be located elsewhere. +A Wine _prefix_ is a directory, usually located beneath the default location of [.filename]#$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(R) environment a given application needs. -By default, a brand new WINE installation will create the following structure when first launched by a user: +By default, a brand new Wine installation will create the following structure when first launched by a user: -* [.filename]#.update-timestamp#: contains the last modified date of [.filename]#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. -* [.filename]#dosdevices/#: contains information on mappings of Windows(R) resources to resources on the host FreeBSD system. For example, after a new WINE installation, this should contain at least two entries which enable access to the FreeBSD filesystem using Windows(R)-style drive letters: +* [.filename]#.update-timestamp#: contains the last modified date of [.filename]#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. +* [.filename]#dosdevices/#: contains information on mappings of Windows(R) resources to resources on the host FreeBSD system. For example, after a new Wine installation, this should contain at least two entries which enable access to the FreeBSD filesystem using Windows(R)-style drive letters: ** [.filename]#c:@#: A link to [.filename]#drive_c# described below. ** [.filename]#z:@#: A link to the root directory of the system. -* [.filename]#drive_c/#: emulates the main (i.e., [.filename]#C:#) drive of a Windows(R) system. It contains a directory structure and associated files mirroring that of standard Windows(R) systems. A fresh WINE prefix will contain Windows(R) 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. -* [.filename]#system.reg#: This Registry file contains information on the Windows(R) installation, which in the case of WINE is the environment in [.filename]#drive_c#. +* [.filename]#drive_c/#: emulates the main (i.e., [.filename]#C:#) drive of a Windows(R) system. It contains a directory structure and associated files mirroring that of standard Windows(R) systems. A fresh Wine prefix will contain Windows(R) 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. +* [.filename]#system.reg#: This Registry file contains information on the Windows(R) installation, which in the case of Wine is the environment in [.filename]#drive_c#. * [.filename]#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. * [.filename]#userdef.reg#: This Registry file is a default set of configurations for newly-created users. [[creating-and-using-wine-prefixes]] -=== Creating and Using WINE Prefixes +=== Creating and Using Wine Prefixes -While WINE will create a default prefix in the user's [.filename]#$HOME/.wine/#, it is possible to set up multiple prefixes. +While Wine will create a default prefix in the user's [.filename]#$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(R), according to the compatibility needs of the software in question. @@ -365,14 +368,14 @@ .... [[configuring-wine-prefixes-with-winecfg]] -=== Configuring WINE Prefixes with winecfg +=== Configuring Wine Prefixes with winecfg -As described above WINE includes a tool called winecfg to configure prefixes from within a GUI. +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 https://wiki.winehq.org/Wine_User%27s_Guide#Using_Winecfg[Using Winecfg] in the WINE Wiki for more details. +See the section on https://wiki.winehq.org/Wine_User%27s_Guide#Using_Winecfg[Using Winecfg] in the Wine Wiki for more details. [[applications]] ==== Applications @@ -394,9 +397,9 @@ image::wine-config-2.png[] -WINE provides a set of open source library files as part of its distribution that provide the same functions as their Windows(R) 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(R) programs are expecting. +Wine provides a set of open source library files as part of its distribution that provide the same functions as their Windows(R) 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(R) programs are expecting. However, winecfg makes it possible specify overrides for the built-in libraries, particularly there is a version of Windows(R) available on the same machine as the host FreeBSD installation. For each library to be overridden, do the following: @@ -414,13 +417,13 @@ image::wine-config-3.png[] -The _Graphics_ tab provides some options to make the windows of programs run via WINE operate smoothly with FreeBSD +The _Graphics_ tab provides some options to make the windows of programs run via Wine operate smoothly with FreeBSD * Automatic mouse capture when windows are full-screen. -* Allowing the FreeBSD 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. +* Allowing the FreeBSD 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]] ==== Desktop Integration @@ -429,8 +432,8 @@ 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. +* 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 FreeBSD system to useful folders within the Windows(R) environment. To change an existing association, select the desired item and click _Browse_, then use the provided dialog to select a directory. [[drives]] @@ -439,7 +442,7 @@ image::wine-config-5.png[] The _Drives_ tab allows linking of directories in the host FreeBSD system to drive letters in the Windows(R) environment. -The default values in this tab should look familiar, as they're displaying the contents of [.filename]#dosdevices/# in the current WINE prefix. +The default values in this tab should look familiar, as they're displaying the contents of [.filename]#dosdevices/# in the current Wine prefix. Changes made via this dialog will reflect in [.filename]#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 [.filename]#/mnt/cdrom#), take the following steps: @@ -449,7 +452,7 @@ . 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. +By default Wine will autodetect the type of resource linked, but this can be manually overridden. See https://wiki.winehq.org/Wine_User%27s_Guide#Drive_Settings[the section in the WINE Wiki] for more detail on advanced options. [[audio]] @@ -468,39 +471,37 @@ image::wine-config-7.png[] -The final tab contains information on the WINE project, including a link to the website. +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]] -== WINE Management GUIs +== 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. +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 -winetricks is a cross-platform, general purpose helper program for WINE. -It is not developed by the WINE project proper, but rather maintained on https://github.com/Winetricks/winetricks[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. +winetricks is a cross-platform, general purpose helper program for Wine. +It is not developed by the Wine project proper, but rather maintained on https://github.com/Winetricks/winetricks[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-winetricks]] ==== Installing winetricks -To install winetricks on a FreeBSD 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): +To install winetricks on a FreeBSD using binary packages, use the following commands: [source,shell] .... -# pkg install i386-wine winetricks +# pkg install winetricks .... To compile it from source, issue the following in the terminal: [source,shell] .... -# cd /usr/ports/emulators/i386-wine -# make install # cd /usr/ports/emulators/winetricks # make install .... @@ -527,7 +528,7 @@ image::winetricks-run-2.png[] 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: +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: image::winetricks-app-install-1.png[] @@ -552,116 +553,92 @@ image::winetricks-uninstall-3.png[] -[[homura]] -=== Homura +[[suyimazu]] +=== Suyimazu -Homura is an application similar to winetricks, although it was inspired by the https://lutris.net/[Lutris] gaming system for Linux. -But while it is focused on games, there are also non-gaming applications available for install through Homura. +Suyimazu is an application similar to winetricks, although it was inspired by the https://lutris.net/[Lutris] gaming system for Linux. +But while it is focused on games, there are also non-gaming applications available for install through Suyimazu. -[[installing-homura]] -==== Installing Homura +[[installing-suyimazu]] +==== Installing Suyimazu -To install Homura's binary package, issue the following command: +To install Suyimazu's binary package, issue the following command: [source,shell] .... -# pkg install homura +# pkg install suyimazu .... -Homura is available in the FreeBSD Ports system. +Suyimazu is available in the FreeBSD Ports system. However, than the _emulators_ section of Ports or binary packages, look for it in the _games_ section. [source,shell] .... -# cd /usr/ports/games/homura +# cd /usr/ports/games/suyimazu # make install .... -[[using-homura]] -==== Using Homura +[[using-suyimazu]] +==== Using Suyimazu -Homura's usage is quite similar to that of winetricks. +Suyimazu'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: [source,shell] .... -% Homura +% Suyimazu .... This should result in a friendly welcome message. Click _OK_ to continue. -image::homura-launch-1.png[] +image::suyimazu-launch-1.png[] The program will also offer to place a link in the application menu of compatible environments: -image::homura-run-2.png[] +image::suyimazu-run-2.png[] -Depending on the setup of the FreeBSD machine, Homura may display a message urging the install of native graphics drivers. +Depending on the setup of the FreeBSD machine, Suyimazu may display a message urging the install of native graphics drivers. -image::homura-run-3.png[] +image::suyimazu-run-3.png[] 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_). +Many of the items are the same as winetricks, although Suyimazu offers some additional, helpful options such as opening its data folder (_Open Suyimazu Folder_) or running a specified program (_Run a executable in prefix_). -image::homura-install-1.png[] +image::suyimazu-install-1.png[] -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. +To select one of Suyimazu's supported applications to install, select _Installation_, and click _OK_. +This will display a list of applications Suyimazu can install automatically. Select one, and click _OK_ to start the process. -image::homura-install-2.png[] - -As a first step Homura will download the selected program. -A notification may appear in supported desktop environments. +image::suyimazu-install-2.png[] -image::homura-install-3.png[] - -The program will also create a new prefix for the application. -A standard WINE dialog with this message will display. - -image::homura-install-4.png[] - -Next, Homura will install any prerequisites for the selected program. +Next, Suyimazu 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. -image::homura-install-5.png[] - -Downloaded packages are automatically opened and run as required. - -image::homura-install-6.png[] +image::suyimazu-install-3.png[] -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. +The installation may end with a simple desktop notification or message in the terminal, depending on how Suyimazu was launched. +But in either case Suyimazu should return to the main screen. To confirm the installation was successful, select _Launcher_, and click _OK_. -image::homura-install-7.png[] +image::suyimazu-install-4.png[] This will display a list of installed applications. -image::homura-install-8.png[] +image::suyimazu-install-5.png[] 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_. -image::homura-uninstall-1.png[] - -[[running-multiple-management-guis]] -=== 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. +image::suyimazu-uninstall-1.png[] [[wine-in-multi-user-os-installations]] -== WINE in Multi-User FreeBSD Installations +== Wine in Multi-User FreeBSD Installations [[issues-with-using-a-common-wine-prefix]] -=== Issues with Using a Common WINE Prefix +=== Issues with Using a Common Wine Prefix Like most UNIX(R)-like operating systems, FreeBSD is designed for multiple users to be logged in and working at the same time. On the other hand, Windows(R) is multi-user in the sense that there can be multiple user accounts set up on one system. @@ -669,18 +646,18 @@ More recent consumer versions of Windows(R) 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 FreeBSD applications (including WINE itself), it will resemble this single-user environment. +Furthermore, the measures the Wine project has taken to create a compatible environment means, unlike FreeBSD 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 minimize the impact of multiple WINE users in the system. +There are two strategies to minimize the impact of multiple Wine users in the system. [[installing-applications-to-a-common-drivesettings]] === 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. +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. @@ -688,19 +665,19 @@ . First, set up a shared location on the system where the files will be stored, such as [.filename]#/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 FreeBSD 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. +. 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(R)-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]] -=== Using a Common Installation of WINE +=== 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. +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. +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: @@ -755,7 +732,7 @@ 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: +Next provide access to the display back to the _windows_ user, as whom the Wine programs will be running: [source,shell] .... @@ -771,21 +748,15 @@ 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]] -== WINE on FreeBSD FAQ +== Wine on FreeBSD FAQ -The following section describes some frequently asked questions, tips/tricks, or common issues in running WINE on FreeBSD, along with their respective answers. +The following section describes some frequently asked questions, tips/tricks, or common issues in running Wine on FreeBSD, along with their respective answers. [[basic-installation-and-usage]] === Basic Installation and Usage -[[how-to-install-32-bit-and-64-bit-wine-on-the-same-system]] -==== 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]] -==== Can DOS Programs Be Run on WINE? +==== Can DOS Programs Be Run on Wine? They can, as "Console User Interface" applications as mentioned earlier in this section. However, there is an arguably better method for running DOS software: DOSBox. @@ -793,14 +764,12 @@ Simply create a new prefix, install the software, and if it does not work delete the prefix. [[should-the-wine-devel-packageport-be-installed-to-use-the-development-version-of-wine-instead-of-stable]] -==== Should the "wine-devel" Package/Port be Installed to Use the Development Version of WINE Instead of Stable? +==== 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. +Yes, installing this version will install the "development" version of Wine. -Note that WINE also has a "Staging" version, which contains the most recent updates. -This was at one time available as a FreeBSD port; however, it has since been removed. -It can be compiled directly from source however. +Note that Wine also has a "Staging" version, which contains the most recent updates. +This was at one time available as a FreeBSD port; however, it has since been removed and brought back as an build option in wine-devel. [[install-optimization]] === Install Optimization @@ -809,14 +778,14 @@ ==== How Should Windows(R) Hardware (e.g., Graphics) Drivers be Handled? Operating system drivers transfer commands between applications and hardware. -WINE emulates a Windows(R) environment, including the drivers, which in turn use FreeBSD's native drivers for this transfer. -it is not advisable to install Windows(R) drivers, as the WINE system is designed to use the host systems drivers. +Wine emulates a Windows(R) environment, including the drivers, which in turn use FreeBSD's native drivers for this transfer. +it is not advisable to install Windows(R) 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 FreeBSD methods, not Windows(R) installers. [[is-there-a-way-to-make-windows-fonts-look-better]] ==== Is There a way to Make Windows(R) Fonts Look Better? -A user on the FreeBSD forums suggests this configuration to fix out-of-the-box look of WINE fonts, which can be slightly pixelated. +A user on the FreeBSD forums suggests this configuration to fix out-of-the-box look of Wine fonts, which can be slightly pixelated. According to https://forums.freebsd.org/threads/make-wine-ui-fonts-look-good.68273/[a post in the FreeBSD Forums], adding the following to [.filename]#.config/fontconfig/fonts.conf# will add anti-aliasing and make text more readable. @@ -839,19 +808,19 @@ [[does-having-windows-installed-elsewhere-on-a-system-help-wine-operate]] -==== Does Having Windows(R) Installed Elsewhere on a System Help WINE Operate? +==== Does Having Windows(R) 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. +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(R) partition or drive is mounted to the FreeBSD system and accessible to the user, configuring some of these overrides will use native Windows(R) libraries and may decrease the chance of unexpected behavior. [[application-specific]] === Application-Specific [[where-is-the-best-place-to-see-if-application-x-works-on-wine]] -==== Where is the Best Place to see if Application X Works on WINE? +==== Where is the Best Place to see if Application X Works on Wine? -The first stop in determining compatibility should be the https://appdb.winehq.org/[WINE AppDB]. +The first stop in determining compatibility should be the https://appdb.winehq.org/[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]] @@ -862,18 +831,19 @@ 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 FreeBSD-compatible Vulkan graphics sub-system, is one such. -Although its primary target is WINE on Linux, https://forums.freebsd.org/threads/what-about-gaming-on-freebsd.723/page-9[some FreeBSD users report] compiling and using dxvk. +Although its primary target is Wine on Linux, https://forums.freebsd.org/threads/what-about-gaming-on-freebsd.723/page-9[some FreeBSD users report] compiling and using dxvk. In addition, work is under way on a https://www.freshports.org/emulators/wine-proton/[wine-proton port]. This will bring the work of Valve, developer of the Steam gaming platform, to FreeBSD. -Proton is a distribution of WINE designed to allow many Windows(R) games to run on other operating systems with minimal setup. +Proton is a distribution of Wine designed to allow many Windows(R) games to run on other operating systems with minimal setup. [[is-there-anywhere-freebsd-wine-users-gather-to-exchange-tips-and-tricks]] -==== Is There Anywhere FreeBSD WINE Users Gather to Exchange Tips and Tricks? +==== 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: +There are plenty of places FreeBSD users discuss issues related to Wine that can be searched for solutions: * https://forums.freebsd.org/[The FreeBSD forums], particularly the _Installation and Maintenance of Ports or Packages_ or _Emulation and virtualization_ forums. +* https://discord.com/invite/n2wshsy[FreeBSD Discord server] * https://wiki.freebsd.org/IRC/Channels[FreeBSD IRC channels] including #freebsd (for general support), #freebsd-games, and others. * https://discord.gg/2CCuhCt[The BSD World Discord server's] channels including _bsd-desktop_, _bsd-gaming_, _bsd-wine_, and others. @@ -882,6 +852,6 @@ There are a number of resources focused on other operating systems that may be useful for FreeBSD users: -* https://wiki.winehq.org/[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. https://wiki.archlinux.org/index.php/wine[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 FreeBSD. -* Finally, Codeweavers (a developer of a commercial version of WINE) is an active upstream contributor. Oftentimes answers to questions in https://www.codeweavers.com/support/forums[their support forum] can be of aid in troubleshooting problems with the open source version of WINE. +* https://wiki.winehq.org/[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. https://wiki.archlinux.org/index.php/wine[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 FreeBSD. +* Finally, Codeweavers (a developer of a commercial version of Wine) is an active upstream contributor. Oftentimes answers to questions in https://www.codeweavers.com/support/forums[their support forum] can be of aid in troubleshooting problems with the open source version of Wine.