From owner-dev-commits-doc-all@freebsd.org Fri Dec 25 16:51:13 2020 Return-Path: Delivered-To: dev-commits-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 51B204C6465 for ; Fri, 25 Dec 2020 16:51:13 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4D2XyT1nPYz3QMt; Fri, 25 Dec 2020 16:51:13 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 2FF0325A6D; Fri, 25 Dec 2020 16:51:13 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 0BPGpD4m090870; Fri, 25 Dec 2020 16:51:13 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 0BPGpD8c090869; Fri, 25 Dec 2020 16:51:13 GMT (envelope-from git) Date: Fri, 25 Dec 2020 16:51:13 GMT Message-Id: <202012251651.0BPGpD8c090869@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Benedict Reuschling Subject: git: 1980db649f - Add new WINE handbook chapter written as part of Google Season of Docs 2020. MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: bcr X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 1980db649f63ddbc4e6749fc47e47efd63c1f66f Auto-Submitted: auto-generated X-BeenThere: dev-commits-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: "Commit messages for all branches of the doc repository." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 25 Dec 2020 16:51:13 -0000 The branch main has been updated by bcr: URL: https://cgit.FreeBSD.org/doc/commit/?id=1980db649f63ddbc4e6749fc47e47efd63c1f66f commit 1980db649f63ddbc4e6749fc47e47efd63c1f66f Author: Benedict Reuschling AuthorDate: 2020-12-25 16:48:11 +0000 Commit: Benedict Reuschling CommitDate: 2020-12-25 16:48:11 +0000 Add new WINE handbook chapter written as part of Google Season of Docs 2020. Thanks to Aaron Peters for researching and writing this chapter from scratch. He also provided most of the images, together with Alexander Leidinger (netchild@). Alexander was also kind enough to be the official mentor for the WINE side of the content, while I focused on the documentation side. His insights into WINE from a users perspective helped make this chapter better by adding information about Homura. A big thank you to Google Season of Docs 2020 for enabling us to have Aaron as technical writer working on this project. I've re-ordered the finalized submission so that the FAQ is the last part of this chapter. I also moved the "WINE Overview & concepts" section after the Synopsis for a more logical flow of information. Additionally, a lot of DocBook editing was done to bring it to the current form. The remaining checks by textproc/igor revolve around indentation errors. But one can't fix all of them without violating others. Please enjoy running WINE and games on FreeBSD with the help of this chapter. Todo: - Some references to other parts of the chapter or to others in the handbook need to be replaced by actual links. - Some of the images could be resized a bit more. I only did it on those that would create a horizontal scroll bar. Reizing them to 50% made them small enough to fit the other images while retaining legible text. A note on the images: I realize they are mixed JPEG and PNGs in the same chapter. However, many of the images in the handbook do not have a uniform image type either (compare IMAGES_EN+= entries in Makefile). This may be a future project to unify these without compromising image quality. Contributed by: Aaron Peters (acpkendo gmail.com) Reviewed by: netchild, bcr Sponsored by: Google Season of Docs 2020 Differential Revision: https://reviews.freebsd.org/D27484 Differential Revision: https://reviews.freebsd.org/D27455 Differential Revision: https://reviews.freebsd.org/D27444 Differential Revision: https://reviews.freebsd.org/D27232 Differential Revision: https://reviews.freebsd.org/D27146 Differential Revision: https://reviews.freebsd.org/D26983 Differential Revision: https://reviews.freebsd.org/D26914 Differential Revision: https://reviews.freebsd.org/D26788 --- en_US.ISO8859-1/books/handbook/Makefile | 37 + en_US.ISO8859-1/books/handbook/book.xml | 2 +- en_US.ISO8859-1/books/handbook/chapters.ent | 2 +- en_US.ISO8859-1/books/handbook/preface/preface.xml | 5 + en_US.ISO8859-1/books/handbook/wine/Makefile | 14 + en_US.ISO8859-1/books/handbook/wine/chapter.xml | 1838 ++++++++++++++++++++ .../books/handbook/wine/homura-install-1.jpg | Bin 0 -> 136796 bytes .../books/handbook/wine/homura-install-10.png.jpg | Bin 0 -> 136799 bytes .../books/handbook/wine/homura-install-2.jpg | Bin 0 -> 27597 bytes .../books/handbook/wine/homura-install-3.jpg | Bin 0 -> 39100 bytes .../books/handbook/wine/homura-install-4.jpg | Bin 0 -> 25301 bytes .../books/handbook/wine/homura-install-5.jpg | Bin 0 -> 63194 bytes .../books/handbook/wine/homura-install-6.jpg | Bin 0 -> 115843 bytes .../books/handbook/wine/homura-install-7.jpg | Bin 0 -> 90915 bytes .../books/handbook/wine/homura-install-8.jpg | Bin 0 -> 66729 bytes .../books/handbook/wine/homura-install-9.png.jpg | Bin 0 -> 19225 bytes .../images/books/handbook/wine/homura-launch-1.jpg | Bin 0 -> 56970 bytes share/images/books/handbook/wine/homura-run-2.jpg | Bin 0 -> 48752 bytes share/images/books/handbook/wine/homura-run-3.jpg | Bin 0 -> 82508 bytes .../books/handbook/wine/homura-run-4.png.jpg | Bin 0 -> 90585 bytes .../books/handbook/wine/homura-uninstall-1.jpg | Bin 0 -> 78638 bytes share/images/books/handbook/wine/wine-config-1.png | Bin 0 -> 11154 bytes share/images/books/handbook/wine/wine-config-2.png | Bin 0 -> 10516 bytes share/images/books/handbook/wine/wine-config-3.png | Bin 0 -> 10128 bytes share/images/books/handbook/wine/wine-config-4.png | Bin 0 -> 12296 bytes share/images/books/handbook/wine/wine-config-5.png | Bin 0 -> 9631 bytes share/images/books/handbook/wine/wine-config-6.png | Bin 0 -> 10604 bytes share/images/books/handbook/wine/wine-config-7.png | Bin 0 -> 27059 bytes .../images/books/handbook/wine/wine-run-np++-1.png | Bin 0 -> 120438 bytes .../images/books/handbook/wine/wine-run-np++-1.scr | Bin 0 -> 120438 bytes .../handbook/wine/winetricks-app-install-1.png | Bin 0 -> 41859 bytes .../handbook/wine/winetricks-app-install-2.png | Bin 0 -> 20223 bytes .../books/handbook/wine/winetricks-install-1.png | Bin 0 -> 207578 bytes .../books/handbook/wine/winetricks-menu-1.jpg | Bin 0 -> 36456 bytes .../books/handbook/wine/winetricks-run-1.png | Bin 0 -> 36023 bytes .../books/handbook/wine/winetricks-run-2.png | Bin 0 -> 131302 bytes .../books/handbook/wine/winetricks-uninstall-1.jpg | Bin 0 -> 85586 bytes .../books/handbook/wine/winetricks-uninstall-2.jpg | Bin 0 -> 88678 bytes .../books/handbook/wine/winetricks-uninstall-3.jpg | Bin 0 -> 52834 bytes 39 files changed, 1896 insertions(+), 2 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/Makefile b/en_US.ISO8859-1/books/handbook/Makefile index dc04a1b584..aed69a7d35 100644 --- a/en_US.ISO8859-1/books/handbook/Makefile +++ b/en_US.ISO8859-1/books/handbook/Makefile @@ -151,6 +151,42 @@ IMAGES_EN+= virtualization/vmware-freebsd09.png IMAGES_EN+= virtualization/vmware-freebsd10.png IMAGES_EN+= virtualization/vmware-freebsd11.png IMAGES_EN+= virtualization/vmware-freebsd12.png +IMAGES_EN+= wine/wine-run-np++-1.png +IMAGES_EN+= wine/wine-config-1.png +IMAGES_EN+= wine/wine-config-2.png +IMAGES_EN+= wine/wine-config-3.png +IMAGES_EN+= wine/wine-config-4.png +IMAGES_EN+= wine/wine-config-5.png +IMAGES_EN+= wine/wine-config-6.png +IMAGES_EN+= wine/wine-config-7.png +IMAGES_EN+= wine/winetricks-run-1.png +IMAGES_EN+= wine/winetricks-run-2.png +IMAGES_EN+= wine/winetricks-menu-1.jpg +IMAGES_EN+= wine/winetricks-uninstall-1.jpg +IMAGES_EN+= wine/winetricks-uninstall-2.jpg +IMAGES_EN+= wine/winetricks-uninstall-3.jpg +IMAGES_EN+= wine/homura-launch-1.jpg +IMAGES_EN+= wine/homura-run-2.jpg +IMAGES_EN+= wine/homura-run-3.jpg +IMAGES_EN+= wine/homura-install-1.jpg +IMAGES_EN+= wine/homura-install-2.jpg +IMAGES_EN+= wine/homura-install-3.jpg +IMAGES_EN+= wine/homura-install-4.jpg +IMAGES_EN+= wine/homura-install-5.jpg +IMAGES_EN+= wine/homura-install-6.jpg +IMAGES_EN+= wine/homura-install-7.jpg +IMAGES_EN+= wine/homura-install-8.jpg +IMAGES_EN+= wine/homura-uninstall-1.jpg +IMAGES_EN+= wine/homura-run-2.jpg +IMAGES_EN+= wine/homura-run-3.jpg +IMAGES_EN+= wine/winetricks-run-1.png +IMAGES_EN+= wine/winetricks-run-2.png +IMAGES_EN+= wine/winetricks-app-install-1.png +IMAGES_EN+= wine/winetricks-app-install-2.png +IMAGES_EN+= wine/winetricks-menu-1.jpg +IMAGES_EN+= wine/winetricks-uninstall-1.jpg +IMAGES_EN+= wine/winetricks-uninstall-2.jpg +IMAGES_EN+= wine/winetricks-uninstall-3.jpg # Images from the cross-document image library IMAGES_LIB= callouts/1.png @@ -212,6 +248,7 @@ SRCS+= security/chapter.xml SRCS+= serialcomms/chapter.xml SRCS+= usb-device-mode/chapter.xml SRCS+= virtualization/chapter.xml +SRCS+= wine/chapter.xml SRCS+= x11/chapter.xml # Entities diff --git a/en_US.ISO8859-1/books/handbook/book.xml b/en_US.ISO8859-1/books/handbook/book.xml index 95de7bab27..97ab915034 100644 --- a/en_US.ISO8859-1/books/handbook/book.xml +++ b/en_US.ISO8859-1/books/handbook/book.xml @@ -4,7 +4,6 @@ @@ -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 index 2c3402c0af..0a4704c1e9 100644 --- a/en_US.ISO8859-1/books/handbook/chapters.ent +++ b/en_US.ISO8859-1/books/handbook/chapters.ent @@ -7,7 +7,6 @@ Chapters should be listed in the order in which they are referenced. - $FreeBSD$ --> @@ -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 index 427056edf8..b407afb658 100644 --- a/en_US.ISO8859-1/books/handbook/preface/preface.xml +++ b/en_US.ISO8859-1/books/handbook/preface/preface.xml @@ -36,6 +36,11 @@ the two volume third edition was published in 2004: + + 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 index 0000000000..b0c6855e1e --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/wine/Makefile @@ -0,0 +1,14 @@ +# +# Build the Handbook with just the content from this chapter. +# +# + +CHAPTERS= wine/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/wine/chapter.xml b/en_US.ISO8859-1/books/handbook/wine/chapter.xml new file mode 100644 index 0000000000..e749793ed2 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/wine/chapter.xml @@ -0,0 +1,1838 @@ + + + + + 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 *** 1218 LINES SKIPPED ***