aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook/wine/chapter.xml
blob: 2178d7f8cb978fd94f6f0accfb0e822a27e904f1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
<?xml version="1.0" encoding="iso-8859-1"?>
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="wine">

<info>
  <title>WINE</title>

  <authorgroup>
    <author>
      <personname>
	<firstname>Aaron</firstname>
	<surname>Peters</surname>
      </personname>
      <contrib>Contributed by </contrib>
    </author>
  </authorgroup>
  <authorgroup>
    <author>
      <personname>
	<firstname>Benedict</firstname>
	<surname>Reuschling</surname>
      </personname>
      <contrib>DocBook markup edits by </contrib>
    </author>
  </authorgroup>
</info>

  <sect1 xml:id="wine-synopsis">
    <title>Synopsis</title>

    <para><link xlink:href="https://www.winehq.org/">WINE</link>,
      which stands for Wine Is Not an Emulator, is technically a
      software translation layer.  It enables to install and run some
      software written for &windows; on &os; (and other)
      systems.</para>

    <para>It operates by intercepting system calls, or requests from
      the software to the operating system, and translating them from
      &windows; calls to calls that &os; understands.  It will also
      translate any responses as needed into what the &windows;
      software is expecting.  So in some ways, it
      <emphasis>emulates</emphasis> a &windows; environment, in that
      it provides many of the resources &windows; applications are
      expecting.</para>

    <para>However, it is not an emulator in the traditional sense.
      Many of these solutions operate by constructing an entire other
      computer using software processes in place of hardware
      Virtualization (such as that provided by the
      <package>emulators/qemu</package> port) operates in this way.
      One of the benefits of this approach is the ability to install
      a full version of the OS in question to the emulator.  It means
      that the environment will not look any different to applications
      than a real machine, and chances are good that everything will
      work on it.  The downside to this approach is the fact that
      software acting as hardware is inherently slower than actual
      hardware.  The computer built in software (called the
      <emphasis>guest</emphasis>) requires resources from the real
      machine (the <emphasis>host</emphasis>), and holds on to those
      resources for as long as it is running.</para>

    <para>The WINE Project, on the other hand, is much lighter on
      system's resources.  It will translate system calls on the fly,
      so while it is difficult to be as fast as a real &windows;
      computer, it can come very close.  On the other hand, WINE is
      trying to keep up with a moving target in terms of all the
      different system calls and other functionality it needs to
      support.  As a result there may be applications that do not work
      as expected on WINE, will not work at all, or will not even
      install to begin with.</para>

    <para>At the end of the day, WINE provides another option to try
      to get a particular &windows; software program running on &os;.
      It can always serve as the first option which, if successful,
      offers a good experience without unnecessarily depleting the
      host &os; system's resources.</para>

    <para>This chapter will describe:</para>

    <itemizedlist>
      <listitem>
	<para>How to install WINE on a &os; system.</para>
      </listitem>

      <listitem>
	<para>How WINE operates, and how it is different from other
	  alternatives like virtualizaton.</para>
      </listitem>

      <listitem>
	<para>How to fine-tune WINE to the specific needs of some
	  applications.</para>
      </listitem>

      <listitem>
	<para>How to install GUI helpers for WINE.</para>
      </listitem>

      <listitem>
	<para>Common tips and solutions for on &os;.</para>
      </listitem>

      <listitem>
	<para>Considerations for WINE on &os; in terms of the
	  multi-user environment.</para>
      </listitem>
    </itemizedlist>

    <para>Before reading this chapter, it will be useful to:</para>

    <itemizedlist>
      <listitem>
	<para>Understand the <link linkend="basics">basics of &unix;
	  and &os;</link>.</para>
      </listitem>

      <listitem>
	<para>Know how to <link linkend="bsdinstall">install
	  &os;</link>.</para>
      </listitem>

      <listitem>
	<para>Know how to <link linkend="advanced-networking">set up a
	  network connection</link>.</para>
      </listitem>

      <listitem>
	<para>Know how to <link linkend="ports">install additional
	  third-party software</link>.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="wine-overview-concepts">
    <title>WINE Overview &amp; Concepts</title>

    <para>WINE is a complex system, so before running it on a &os;
      system it is worth gaining an understanding of what it is and
      how it works.</para>

    <sect2 xml:id="what-is-wine">
      <title>What is WINE?</title>

      <para>As mentioned in the <link
	  linkend="wine-synopsis">Synopsis</link> for this chapter,
	WINE is a compatibility layer that allows &windows;
	applications to run on other operating systems.  In theory, it
	means these programs should run on systems like &os;,
	macOS, and Android.</para>

      <para>When WINE runs a &windows; executable, two things
	occur:</para>

      <itemizedlist>
	<listitem>
	  <para>Firstly, WINE implements an environment that mimics
	    that of various versions of &windows;.  For example, if an
	    application requests access to a resource such as RAM,
	    WINE has a memory interface that looks and acts (as far as
	    the application is concerned) like &windows;.</para>
	</listitem>

	<listitem>
	  <para>Then, once that application makes use of that
	    interface, WINE takes the incoming request for space in
	    memory and translates it to something compatible with the
	    host system.  In the same way when the application
	    retrieves that data, WINE facilitates fetching it from the
	    host system and passing it back to the &windows;
	    application.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 xml:id="wine-and-the-os-system">
      <title>WINE and the &os; System</title>

      <para>Installing WINE on a &os; system will entail a few
	different components:</para>

      <itemizedlist>
	<listitem>
	  <para>&os; applications for tasks such as running the
	    &windows; executables, configuring the WINE sub-system, or
	    compiling programs with WINE support.</para>
	</listitem>

	<listitem>
	  <para>A large number of libraries that implement the core
	    functions of &windows; (for example
	    <filename>/lib/wine/api-ms-core-memory-l1-1-1.dll.so</filename>,
	    which is part of the aforementioned memory
	    interface).</para>
	</listitem>

	<listitem>
	  <para>A number of &windows; executables, which are (or
	    mimic) common utilities (such as
	    <filename>/lib/wine/notepad.exe.so</filename>, which
	    provides the standard &windows; text editor).</para>
	</listitem>

	<listitem>
	  <para>Additional &windows; assets, in particular fonts (like
	    the Tahoma font, which is stored in
	    <filename>share/wine/fonts/tahoma.ttf</filename> in
	    the install root).</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2
      xml:id="graphical-versus-text-modeterminal-programs-in-wine">
    <title>Graphical Versus Text Mode/Terminal Programs in
      WINE</title>

    <para>As an operating system where terminal utilities are
      <quote>first-class citizens,</quote> it is natural to assume
	that WINE will contain extensive support for text-mode
	program.  However, the majority of applications for &windows;,
	especially the most popular ones, are designed with a
	graphical user interface (GUI) in mind.  Therefore, WINE's
	utilities are designed by default to launch graphical
	programs.</para>

      <para>However, there are three methods available to run these
	so-called Console User Interface (CUI) programs:</para>

      <itemizedlist>
	<listitem>
	  <para>The <emphasis>Bare Streams</emphasis> approach will
	    display the output directly to standard output.</para>
	</listitem>

	<listitem>
	  <para>The <emphasis>wineconsole</emphasis> utility can be
	    used with either the <emphasis>user</emphasis> or
	    <emphasis>curses</emphasis> backed to utilize some of the
	    enhancements the WINE system provides for CUI
	    applications.</para>
	</listitem>
      </itemizedlist>

      <para>These approaches are described in greater detail on the
	<link
	xlink:href="https://wiki.winehq.org/Wine_User%27s_Guide#Text_mode_programs_.28CUI:_Console_User_Interface.29">WINE
	  Wiki</link>.</para>
    </sect2>

    <sect2 xml:id="wine-derivative-projects">
      <title>WINE Derivative Projects</title>

      <para>WINE itself is a mature open source project, so it is
	little surprise it is used as the foundation of more complex
	solutions.</para>

      <sect3 xml:id="commercial-wine-implementations">
	<title>Commercial WINE Implementations</title>

	<para>A number of companies have taken WINE and made it a core
	  of their own, proprietary products (WINE's LGPL license
	  permits this).  Two of the most famous of these are as
	  follows:</para>

	<itemizedlist>
	  <listitem>
	    <para>Codeweavers CrossOver</para>
	  </listitem>
	</itemizedlist>

	<para>This solution provides a simplified
	  <quote>one-click</quote> installation of WINE, which
	  contains additional enhancements and optimizations (although
	  the company contributes many of these back upstream to the
	  WINE project).  One area of focus for Codeweavers is to make
	  the most popular applications install and run
	  smoothly.</para>

	<para>While the company once produced a native FreeBSD version
	  of their <application>CrossOver</application> solution, it
	  appears to have long been abandoned.  While some resources
	  (such as a <link
	    xlink:href="https://www.codeweavers.com/compatibility/crossover/forum/freebsd">dedicated
	    forum</link>) are still present, they also have seen no
	  activity for some time.</para>

	<itemizedlist>
	  <listitem>
	    <para>Steam Proton</para>
	  </listitem>
	</itemizedlist>

	<para>Gaming company Steam also uses WINE to enable &windows;
	  games to install and run on other systems.  it is primary
	  target is Linux-based systems, though some support exists
	  for macOS as well.</para>

	<para>While Steam does not offer a native &os; client,there
	  are several options for using the &linux; client using
	  &os;'s Linux Compatibility Layer.</para>
      </sect3>

      <sect3 xml:id="wine-companion-programs">
	<title>WINE Companion Programs</title>

	<para>In addition to proprietary offerings, other projects
	  have released applications designed to work in tandem with
	  the standard, open source version of WINE.  The goals for
	  these can range from making installation easier to offering
	  easy ways to get popular software installed.</para>

	<para>These solutions are covered in greater detail in the
	  later section on <link
	    linkend="wine-management-guis">GUI frontends</link>, and
	  include the following:</para>

	<itemizedlist>
	  <listitem>
	    <para>winetricks</para>
	  </listitem>

	  <listitem>
	    <para>Homura</para>
	  </listitem>
	</itemizedlist>
      </sect3>
    </sect2>

    <sect2 xml:id="alternatives-to-wine">
      <title>Alternatives to WINE</title>

      <para>For &os; users, some alternatives to using WINE are as
	follows:</para>

      <itemizedlist>
	<listitem>
	  <para>Dual-Booting: A straightforward option is to run
	    desired &windows; applications natively on that OS.  This
	    of course means existing &os; in order to boot &windows;,
	    so this method is not feasible if access to programs in
	    both systems is required simultaneously.</para>
	</listitem>

	<listitem>
	  <para>Virtual Machines: Virtual Machines (VMs), as mentioned
	    earlier in this chapter, are software processes that
	    emulate full sets of hardware, on which additional
	    operating systems (including &windows;) can be installed
	    and run.  Modern tools make VMs easy to create and manage,
	    but this method comes at a cost.  A good portion of the
	    host systems resources must be allocated to each VM, and
	    those resources cannot be reclaimed by the host as long as
	    the VM is running.  A few examples of VM managers include
	    the open source solutions qemu, bhyve, and VirtualBox.
	    See the chapter on <link
	      linkend="virtualization">Virtualization</link> for
	    more detail.</para>
	</listitem>

	<listitem>
	  <para>Remote Access: Like many other &unix;-like systems,
	    &os; can run a variety of applications enabling users to
	    remotely access &windows; computers and use their programs
	    or data.  In addtion to clients such as
	    <application>xrdp</application> that connect to the
	    standard &windows; Remote Desktop Protocol, other open
	    source standards such as <application>vnc</application>
	    can also be used (provided a compatible server is present
	    on the other side).</para>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 xml:id="installing-wine-on-freebsd">
    <title>Installing WINE on &os;</title>

    <para>WINE can be installed via the pkg tool, or by compiling the
      port(s).</para>

    <sect2 xml:id="wine-prerequistes">
      <title>WINE Prerequistes</title>

      <para>Before installing WINE itself, it is useful to have the
	following pre-requisites installed.</para>

      <itemizedlist>
	<listitem>
	  <para>A GUI</para>
	</listitem>
      </itemizedlist>

      <para>Most &windows; programs are expecting to have a graphical
	user interface available.  If WINE is installed without one
	present, its dependencies will include the Wayland compositor,
	and so a GUI will be installed along with WINE.  But it is
	useful to have the GUI of choice installed, configured,
	and working correctly before installing WINE.</para>

      <itemizedlist>
	<listitem>
	  <para>wine-gecko</para>
	</listitem>
      </itemizedlist>

      <para>The &windows; operating system has for some time had a
	default web browser pre-installed: Internet Explorer.  As a
	result, some applications work under the assumption that there
	will always be something capable of displaying web pages.  In
	order to provide this functionality, the WINE layer includes a
	web browser component using the Mozilla project's Gecko
	engine.  When WINE is first launched it will offer to download
	and install this, and there are reasons users might want it do
	so (these will be covered in a later chapter).  But they can
	also install it prior to installing WINE, or alongside the
	install of WINE proper.</para>

      <para>Install this package with the following:</para>

      <screen>&prompt.root; <userinput>pkg install wine-gecko</userinput></screen>

      <para>Alternately, compile the port with the following:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/emulator/wine-gecko</userinput>
&prompt.root; <userinput>make install</userinput></screen>

      <itemizedlist>
	<listitem>
	  <para>wine-mono</para>
	</listitem>
      </itemizedlist>

      <para>This port installs the MONO framework, an open source
	implementation of Microsoft's .NET.  Including this with the
	WINE installation will make it that much more likely that any
	applications written in .NET will install and run on the
	system.</para>

      <para>To install the package:</para>

      <screen>&prompt.root; <userinput>pkg install wine-mono</userinput></screen>

      <para>To compile from the ports collection:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/emulator/wine-mono</userinput>
&prompt.root; <userinput>make install</userinput></screen>
    </sect2>

    <sect2 xml:id="installing-wine">
      <title>Installing WINE via &os; Package Repositories</title>

      <para>With the pre-requisites in place, install WINE via package
	with the following command:</para>

      <screen>&prompt.root; <userinput>pkg install wine</userinput></screen>

      <para>Alternately compile the WINE sub-system from source with
	the following:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/emulator/wine</userinput>
&prompt.root; <userinput>make install</userinput></screen>
    </sect2>

    <sect2 xml:id="thirtytwo-vs-sixtyfour-bit-wine">
      <title>Concerns of 32- Versus 64-Bit in WINE
	Installations</title>

      <para>Like most software, &windows; applications made the
	upgrade from the older 32-bit architecture to 64 bits.  And
	most recent software is written for 64-bit operating systems,
	although modern OSes can sometimes continue to run older
	32-bit programs as well.  &os; is no different, having had
	support for 64-bit since the 5.x series.</para>

      <para>However, using old software no longer supported by default
	is a common use for emulators, and users commonly turn to WINE
	to play games and use other programs that do not run properly
	on modern hardware.  Fortunately, &os; can support all three
	scenarios:</para>

      <itemizedlist>
	<listitem>
	  <para>On modern, 64-bit machine and want to run 64-bit
	    &windows; software, simply install the ports mentioned in
	    the above sections.  The ports system will automatically
	    install the 64-bit version.</para>
	</listitem>

	<listitem>
	  <para>Alternately, users might have an older 32-bit machine
	    that they do not want to run with its original, now
	    non-supported software.  They can install the 32-bit
	    (i386) version of &os;, then install the ports in the
	    above sections.  Again, on a 32-bit machine the ports
	    system will install the corresponding 32-bit version of
	    WINE by default.</para>
	</listitem>
      </itemizedlist>

      <para>However, given a 64-bit version of &os; and need to run
	<emphasis role="strong">32-bit</emphasis> &windows;
	applications, installing a different port is required to
	enable 32-bit compatibility.  To install the pre-compiled
	package, use the following:</para>

      <screen>&prompt.root; <userinput>pkg install i386-wine</userinput></screen>

      <para>Or compile the port with the following:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/emulator/i386-wine</userinput>
&prompt.root; <userinput>make install</userinput></screen>
      </sect2>
    </sect1>

    <sect1 xml:id="running-first-wine-program">
      <title>Running a First WINE Program on &os;</title>

      <para>Now that WINE is installed, the next step is to try it out
	by running a simple program.  An easy way to do this is to
	download a self-contained application, i.e., one can
	simply unpack and run without any complex installation
	process.</para>

      <para>So-called &quot;portable&quot; versions of applications
	are good choices for this test, as are programs that run with
	only a single executable file.</para>

      <sect2 xml:id="running-a-program-from-the-command-line">
	<title>Running a Program from the Command Line</title>

	<para>There are two different methods to launch a Windows
	  program from the terminal.  The first, and most
	  straightforward is to navigate to the directory containing
	  the program's executable (<filename>.EXE</filename>) and
	  issue the following:</para>

	<screen>&prompt.user; <userinput>wine program.exe</userinput></screen>

	<para>For applications that take command-line arguments, add
	  them after the executable as usual:</para>

	<screen>&prompt.user; <userinput>wine <replaceable>program2.exe</replaceable> -file <filename><replaceable>file.txt</replaceable></filename></userinput></screen>

	<para>Alternately, supply the full path to the executable to
	  use it in a script, for example:</para>

	<screen>&prompt.user; <userinput>wine /home/<replaceable>user</replaceable>/bin/program.exe</userinput></screen>
      </sect2>

      <sect2 xml:id="running-a-program-from-a-gui">
	<title>Running a Program from a GUI</title>

	<para>After installation graphical shells should be updated
	  with new associations for Windows executable
	  (<filename>.EXE</filename>) files.  It will now be possible
	  to browse the system using a file manager, and launch the
	  Windows application in the same way as other files and
	  programs (either a single- or double-click, depending on the
	  desktop's settings).</para>

	<para>On most desktops, check to make sure this association is
	  correct by right-clicking on the file, and looking for an
	  entry in the context menu to open the file.  One of the
	  options (hopefully the default one) will be with the
	  <emphasis role="strong">Wine Windows Program
	    Loader</emphasis>, as shown in the below
	  screenshot:</para>

	<mediaobject>
	  <imageobject>
	    <imagedata fileref="wine/wine-run-np++-1"/>
	  </imageobject>
	</mediaobject>

	<para>In the event the program does not run as expected, try
	  launching it from the command line and review any messages
	  displayed in the terminal to troubleshoot.</para>

	<para>In the event WINE is not the default application for
	  <filename>.EXE</filename> files after install, check the
	  MIME associate for this extension in the current desktop
	  environment, graphical shell, or file manager.</para>
      </sect2>
    </sect1>

    <sect1 xml:id="configuring-wine-installation">
      <title>Configuring WINE Installation</title>

      <para>With an understanding of what WINE is and how it works at
	a high level, the next step to effectively using it on
	&os; is becoming familiar with its configuration.  The
	following sections will describe the key concept of the
	<emphasis>WINE prefix</emphasis>, and illustrate how it is
	used to control the behavior of applications run through
	WINE.</para>

      <sect2 xml:id="wine-prefixes">
	<title>WINE Prefixes</title>

	<para>A WINE <emphasis>prefix</emphasis> is a directory,
	  usually located beneath the default location of
	  <filename>$HOME/.wine</filename> though it can be located
	  elsewhere.  The prefix is a set of configurations and
	  support files used by the <application>wine</application> to
	  configure and run the &windows; environment a given
	  application needs.  By default, a brand new WINE
	  installation will create the following structure when
	  first launched by a user:</para>

	<itemizedlist spacing="compact">
	  <listitem>
	    <para><filename>.update-timestamp</filename>: contains the
	      last modified date of
	      <filename>file /usr/share/wine/wine.inf</filename>.  It
	      is used by WINE to determine if a prefix is out of date,
	      and automatically update it if needed.</para>
	  </listitem>

	  <listitem>
	    <para><filename>dosdevices/</filename>: contains
	      information on mappings of &windows; resources to
	      resources on the host &os; system.  For example, after a
	      new WINE installation, this should contain at least two
	      entries which enable access to the &os; filesystem using
	      &windows;-style drive letters:</para>

	    <itemizedlist>
	      <listitem>
		<para><filename>c:@</filename>: A link to
		  <filename>drive_c</filename> described below.</para>
	      </listitem>

	      <listitem>
		<para><filename>z:@</filename>: A link to the root
		  directory of the system.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para><filename>drive_c/</filename>: emulates the main
	      (i.e., <filename>C:</filename>) drive of a
	      &windows; system.  It contains a directory structure
	      and associated files mirroring that of standard
	      &windows; systems.  A fresh WINE prefix will contain
	      &windows;&nbsp;10 directories such as
	      <emphasis>Users</emphasis> and
	      <emphasis>Windows</emphasis> that holds the OS itself.
	      Furthermore, applications installed within a prefix will
	      be located in either <emphasis>Program Files</emphasis>
	      or <emphasis>Program Files (x86)</emphasis>, depending
	      on their architecture.</para>
	  </listitem>

	  <listitem>
	    <para><filename>system.reg</filename>: This Registry file
	      contains information on the &windows; installation,
	      which in the case of WINE is the environment in
	      <filename>drive_c</filename>.</para>
	  </listitem>

	  <listitem>
	    <para><filename>user.reg</filename>: This Registry file
	      contains the current user's personal configurations,
	      made either by varous software or through the use of the
	      Registry Editor.</para>
	  </listitem>

	  <listitem>
	    <para><filename>userdef.reg</filename>: This Registry file
	      is a default set of configurations for newly-created
	      users.</para>
	  </listitem>
	</itemizedlist>
      </sect2>

      <sect2 xml:id="creating-and-using-wine-prefixes">
	<title>Creating and Using WINE Prefixes</title>

	<para>While WINE will create a default prefix in the user's
	  <filename>$HOME/.wine/</filename>, it is possible to
	  set up multiple prefixes.  There are a few reasons to do
	  this:</para>

	<itemizedlist>
	  <listitem>
	    <para>The most common reason is to emulate different
	      versions of &windows;, according to the compatibility
	      needs of the software in question.</para>
	  </listitem>

	  <listitem>
	    <para>In addition, it is common to encounter software that
	      does not work correctly in the default environment, and
	      requires special configuration.  it is useful to isolate
	      these in their own, custom prefixes, so the changes do
	      not impact other applications.</para>
	  </listitem>

	  <listitem>
	    <para>Similarly, copying the default or &quot;main&quot;
	      prefix into a separate &quot;testing&quot; one in order
	      to evaluate an application's compatibility can reduce
	      the chance of corruption.</para>
	  </listitem>
	</itemizedlist>

	<para>Creating a prefix from the terminal requires the
	  following command:</para>

	<screen>&prompt.user; <userinput>WINEPREFIX="/home/<replaceable>username</replaceable>/.wine-new" winecfg</userinput></screen>

	<para>This will run the <application>winecfg</application>
	  program, which can be used to configure wine prefixes (more
	  on this in a later section).  But by providing a directory
	  path value for the <varname>WINEPREFIX</varname> environment
	  variable, a new prefix is created at that location if one
	  does not already exist.</para>

	<para>Supplying the same variable to the
	  <application>wine</application> program will similarly cause
	  the selected program to be run with the specified
	  prefix:</para>

	<screen>&prompt.user; <userinput>WINEPREFIX="/home/<replaceable>username</replaceable>/.wine-new" wine program.exe</userinput></screen>
      </sect2>

      <sect2 xml:id="configuring-wine-prefixes-with-winecfg">
	<title>Configuring WINE Prefixes with
	  <application>winecfg</application></title>

	<para>As described above WINE includes a tool called
	  <application>winecfg</application> to configure prefixes
	  from within a GUI.  It contains a variety of functions,
	  which are detailed in the sections below.  When
	  <application>winecfg</application> is run from within a
	  prefix, or provided the location of a prefix within the
	  <varname>WINEPREFIX</varname> variable, it enables the
	  configuration of the selected prefix as described in the
	  below sections.</para>

	<para>Selections made on the <emphasis>Applications</emphasis>
	  tab will affect the scope of changes made in the
	  <emphasis>Libraries</emphasis> and
	  <emphasis>Graphics</emphasis> tabs, which will be limited to
	  the application selected.  See the section on <link
	    xlink:href="https://wiki.winehq.org/Wine_User%27s_Guide#Using_Winecfg">Using
	      Winecfg</link> in the WINE Wiki for more details.</para>

	  <sect3 xml:id="applications">
	    <title>Applications</title>

	    <para><inlinemediaobject>
		<imageobject>
		  <imagedata fileref="wine/wine-config-1" />
		</imageobject>
	      </inlinemediaobject></para>

	    <para>The <emphasis>Applications</emphasis> contains
	      controls enabling the association of programs with a
	      particular version of &windows;.  On first start-up the
	      <emphasis>Application settings</emphasis> section will
	      contain a single entry: <emphasis>Default
		Settings</emphasis>.  This corresponds to all the
	      default configurations of the prefix, which (as the
	      disabled <emphasis>Remove application</emphasis> button
	      implies) cannot be deleted.</para>

	    <para>But additional applications can be added with the
	      following process:</para>

	    <orderedlist spacing="compact">
	      <listitem>
		<para>Click the <emphasis>Add application</emphasis>
		    button.</para>
		</listitem>

		<listitem>
		  <para>Use the provided dialog to select the desired
		    program's executable.</para>
		</listitem>

		<listitem>
		  <para>Select the version of &windows; to be used
		    with the selected program.</para>
		</listitem>
	      </orderedlist>
	    </sect3>

	    <sect3 xml:id="libraries">
	      <title>Libraries</title>

	      <para><inlinemediaobject>
		  <imageobject>
		    <imagedata fileref="wine/wine-config-2" />
		  </imageobject>
		</inlinemediaobject></para>

	      <para>WINE provides a set of open source library files
		as part of its distribution that provide the same
		functions as their &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.</para>

	      <para>However, <application>winecfg</application>
		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:</para>

	      <orderedlist spacing="compact">
		<listitem>
		  <para>Open the <emphasis>New override for
		      library</emphasis> drop-down and select the
		    library to be replaced.</para>
		</listitem>

		<listitem>
		  <para>Click the <emphasis>Add</emphasis>
		      button.</para>
		</listitem>

		<listitem>
		  <para>The new override will appear in the
		    <emphasis>Existing overrides</emphasis> list,
		    notice the <emphasis>native,
		      builtin</emphasis> designation in
		    parentheses.</para>
		</listitem>

		<listitem>
		  <para>Click to select the library.</para>
		</listitem>

		<listitem>
		  <para>Click the <emphasis>Edit</emphasis>
		    button.</para>
		  </listitem>

		  <listitem>
		    <para>Use the provided dialog to select a
		      corresponding library to be used in place
		      of the built-in one.</para>
		  </listitem>
		</orderedlist>

		<para>Be sure to select a file that is truly the
		  corresponding version of the built-in one, otherwise
		  there may be unexpected behavior.</para>
	      </sect3>

	      <sect3 xml:id="graphics">
		<title>Graphics</title>

		<para><inlinemediaobject>
		    <imageobject>
		      <imagedata fileref="wine/wine-config-3" />
		    </imageobject>
		  </inlinemediaobject></para>

		  <para>The <emphasis>Graphics</emphasis> tab provides
		    some options to make the windows of programs run
		    via WINE operate smoothly with &os;</para>

		  <itemizedlist>
		    <listitem>
		      <para>Automatic mouse capture when windows are
			full-screen.</para>
		    </listitem>

		    <listitem>
		      <para>Allowing the &os; window manager to
			decorate the windows, such as their title
			bars, for programs running via WINE.</para>
		    </listitem>

		    <listitem>
		      <para>Allowing the window manager to control
			windows for programs running via WINE, such as
			running resizing functions on them.</para>
		    </listitem>

		    <listitem>
		      <para>Create an emulated virtual desktop, within
			which all WINE programs will run.  If this
			item is selected, the size of the virtual
			desktop can be specified using the
			<emphasis>Desktop size</emphasis> input
			boxes.</para>
		    </listitem>

		    <listitem>
		      <para>Setting the screen resolution for programs
			running via WINE.</para>
		    </listitem>
		  </itemizedlist>
		</sect3>

		<sect3 xml:id="desktop-integration">
		  <title>Desktop Integration</title>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata fileref="wine/wine-config-4" />
		      </imageobject>
		  </inlinemediaobject></para>

		  <para>This tab allows configuration of the following
		    items:</para>

		  <itemizedlist>
		    <listitem>
		      <para>The theme and related visual settings to
			be used for programs running via WINE.</para>
		    </listitem>

		    <listitem>
		      <para>Whether the WINE sub-system should manage
			MIME types (used to determine which
			application opens a particular file type)
			internally.</para>
		    </listitem>

		    <listitem>
		      <para>Mappings of directories in the host &os;
			system to useful folders within the &windows;
			environment.  To change an existing
			association, select the desired item and click
			<emphasis>Browse</emphasis>, then use the
			provided dialog to select a directory.</para>
		    </listitem>
		  </itemizedlist>
		</sect3>

		<sect3 xml:id="drives">
		  <title>Drives</title>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata fileref="wine/wine-config-5" />
		      </imageobject>
		  </inlinemediaobject></para>

		  <para>The <emphasis>Drives</emphasis> 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
		    <filename>dosdevices/</filename> in the current
		    WINE prefix.  Changes made via this dialog will
		    reflect in <filename>dosdevices</filename>, and
		    properly-formatted links created in that directory
		    will display in this tab.</para>

		  <para>To create a new entry, such as for a CD-ROM
		    (mounted at <filename>/mnt/cdrom</filename>), take
		    the following steps:</para>

		  <orderedlist>
		    <listitem>
		      <para>Click the <emphasis>Add </emphasis>
			button.</para>
		    </listitem>

		    <listitem>
		      <para>In the provided dialog, choose a free
			drive letter.</para>
		    </listitem>

		    <listitem>
		      <para>Click <emphasis>OK</emphasis>.</para>
		    </listitem>

		    <listitem>
		      <para>Fill in the <emphasis>Path</emphasis>
			input box by either typing the path to the
			resource, or click
			<emphasis>Browse </emphasis> and use the
			provided dialog to select it.</para>
		    </listitem>
		  </orderedlist>

		  <para>By default WINE will autodetect the type of
		    resource linked, but this can be manually
		    overridden.  See <link
		      xlink:href="https://wiki.winehq.org/Wine_User%27s_Guide#Drive_Settings">the
			section in the WINE Wiki</link> for more
		    detail on advanced options.</para>
		</sect3>

		<sect3 xml:id="audio">
		  <title>Audio</title>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata fileref="wine/wine-config-6" />
		      </imageobject>
		  </inlinemediaobject></para>

		  <para>This tab contains some configurable options
		    for routing sound from &windows; programs to the
		    native &os; sound system, including:</para>

		  <itemizedlist>
		    <listitem>
		      <para>Driver selection</para>
		    </listitem>

		    <listitem>
		      <para>Default device selection</para>
		    </listitem>

		    <listitem>
		      <para>Sound test</para>
		    </listitem>
		  </itemizedlist>
		</sect3>

		<sect3 xml:id="about">
		  <title>About</title>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata fileref="wine/wine-config-7" />
		      </imageobject>
		  </inlinemediaobject></para>

		  <para>The final tab contains information on the WINE
		    project, including a link to the website.  It also
		    allows entry of (entirely optional) user
		    information, although this is not sent anywhere as
		    it is in other operating systems.</para>
		</sect3>
	      </sect2>
	    </sect1>

	    <sect1 xml:id="wine-management-guis">
	      <title>WINE Management GUIs</title>

	      <para>While the base install of WINE comes with a GUI
		configuration tool in
		<application>winecfg</application>, it 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.</para>

	      <sect2 xml:id="winetricks">
		<title>Winetricks</title>

		<para><application>winetricks</application> is a
		  cross-platform, general purpose helper program for
		  WINE.  It is not developed by the WINE project
		  proper, but rather maintained on <link
		    xlink:href="https://github.com/Winetricks/winetricks">Github</link>
		  by a group of contributors.  It contains some
		  automated &quot;recipes&quot; for getting common
		  applications to work on WINE, both by optimizing the
		  settings as well as acquiring some DLL libraries
		  automatically.</para>

		<sect3 xml:id="installing-winetricks">
		  <title>Installing
		    <application>winetricks</application></title>

		  <para>To install
		    <application>winetricks</application> on a
		    &os; using binary packages, use the following
		    commands (note
		    <application>winetricks</application> requires
		    either the i386-wine or i386-wine-devel package,
		    and is therefore not installed automatically with
		    other dependencies):</para>

		  <screen>&prompt.root; <userinput>pkg install i386-wine winetricks</userinput></screen>

		  <para>To compile it from source, issue the following
		    in the terminal:</para>

		  <screen>&prompt.root; <userinput>cd /usr/ports/emulators/i386-wine
&prompt.root; make install
&prompt.root; cd /usr/ports/emulators/winetricks
&prompt.root; make install</userinput></screen>

		  <para>If a manual installation is required, refer to
		    the <link
		      xlink:href="https://github.com/Winetricks/winetricks">Github</link>
		    account for instructions.</para>
		</sect3>

		<sect3 xml:id="using-winetricks">
		  <title>Using
		    <application>winetricks</application></title>

		  <para>Run <application>winetricks</application> with
		    the following command:</para>

		  <screen>&prompt.user; <userinput>winetricks</userinput></screen>

		  <para>Note: this should be in a 32-bit prefix
		    to run <application>winetricks</application>.
		    Launching <application>winetricks</application>
		    displays a window with a number of choices, as
		    follows:</para>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata fileref="wine/winetricks-run-1" />
		      </imageobject>
		    </inlinemediaobject></para>

		  <para>Selecting either <emphasis>Install an
		    application</emphasis>, <emphasis>Install a
		      benchmark</emphasis>, or <emphasis>Install a
		      game</emphasis> shows a list with supported
		    options, such as the one below for
		    applications:</para>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata fileref="wine/winetricks-run-2" />
		      </imageobject>
		    </inlinemediaobject></para>

		  <para>Selecting one or more items and clicking
		    <emphasis>OK</emphasis> will start their
		    installation process(es).  Initially, some
		    messages that appear to be errors may show up, but
		    they're actually informational alerts as
		    <application>winetricks</application> configures
		    the WINE environment to get around known issues
		    for the application:</para>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata
			  fileref="wine/winetricks-app-install-1" />
		      </imageobject>
		    </inlinemediaobject></para>

		  <para>Once these are circumvented, the actual
		    installer for the application will be run:</para>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata
			  fileref="wine/winetricks-app-install-2" />
		      </imageobject>
		    </inlinemediaobject></para>

		  <para>Once the installation completes, the new
		    Windows application should be available from the
		    desktop environment's standard menu (shown in the
		    screenshot below for the LXQT desktop
		    environment):</para>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata fileref="wine/winetricks-menu-1" />
		      </imageobject>
		  </inlinemediaobject></para>

		  <para>In order to remove the application, run
		  <application>winetricks</application> again, and
		    select <emphasis>Run an
		      uninstaller</emphasis>.</para>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata
			  fileref="wine/winetricks-uninstall-1" />
		      </imageobject>
		  </inlinemediaobject></para>

		  <para>A &windows;-style dialog will appear with a
		    list of installed programs and components.  Select
		    the application to be removed, then click the
		    <emphasis>Modify/Remove</emphasis> button.</para>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata
			  fileref="wine/winetricks-uninstall-2" />
		      </imageobject>
		    </inlinemediaobject></para>

		  <para>This will run the applications built-in
		    installer, which should also have the option to
		    uninstall.</para>

		  <para><inlinemediaobject>
		      <imageobject>
			<imagedata
			  fileref="wine/winetricks-uninstall-3" />
		      </imageobject>
		    </inlinemediaobject></para>
		</sect3>
	      </sect2>

	      <sect2 xml:id="homura">
		<title>Homura</title>

		<para>Homura is an application similar to
		  <application>winetricks</application>, although it
		  was inspired by the <link
		    xlink:href="https://lutris.net/">Lutris</link>
		  gaming system for Linux.  But while it is focused on
		  games, there are also non-gaming applications
		  available for install through Homura.</para>

		<sect3 xml:id="installing-homura">
		  <title>Installing Homura</title>

		  <para>To install Homura's binary package, issue the
		    following command:</para>

		  <screen>&prompt.root; <userinput>pkg install homura</userinput></screen>

		  <para>Homura is available in the FreeBSD Ports
		    system.  However, than the
		    <emphasis>emulators</emphasis> section of Ports or
		    binary packages, look for it in the
		    <emphasis>games</emphasis> section.</para>

		  <screen>&prompt.root; <userinput>cd /usr/ports/games/homura
&prompt.root; make install</userinput></screen></sect3>

      <sect3 xml:id="using-homura">
	<title>Using Homura</title>

	<para>Homura's usage is quite similar to that of
	  <application>winetricks</application>.  When using it for
	  the first time, launch it from the command line (or a
	  desktop environment runner applet) with:</para>

	<screen>&prompt.user; <userinput>Homura</userinput></screen>

	<para>This should result in a friendly welcome message.  Click
	  <emphasis>OK</emphasis> to continue.</para>

	<para><inlinemediaobject>
	    <imageobject>
	      <imagedata
		fileref="wine/homura-launch-1" />
	    </imageobject>
	  </inlinemediaobject></para>

	<para>The program will also offer to place a link in the
	  application menu of compatible environments:</para>

	<para><inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="wine/homura-run-2" />
	    </imageobject>
	  </inlinemediaobject></para>

	<para>Depending on the setup of the &os; machine, Homura may
	  display a message urging the install of native graphics
	  drivers.</para>

	<para><inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="wine/homura-run-3" />
	    </imageobject>
	  </inlinemediaobject></para>

	<para>The application's window should then appear, which
	  amounts to a &quot;main menu&quot; with all its options.
	  Many of the items are the same as
	  <application>winetricks</application>, although Homura
	  offers some additional, helpful options such as opening its
	  data folder (<emphasis>Open Homura Folder</emphasis>) or
	  running a specified program (<emphasis>Run a executable in
	  prefix</emphasis>).</para>

	<para><inlinemediaobject>
	  <imageobject>
	    <imagedata
	      fileref="wine/homura-install-1" />
	  </imageobject>
	</inlinemediaobject></para>

	<para>To select one of Homura's supported applications to
	  install, select <emphasis>Installation</emphasis>, and click
	  <emphasis>OK</emphasis>.  This will display a list of
	  applications Homura can install automatically.  Select
	  one, and click <emphasis>OK</emphasis> to start the
	  process.</para>

	<para><inlinemediaobject>
	    <imageobject>
	      <imagedata
		fileref="wine/homura-install-2" />
	    </imageobject>
	  </inlinemediaobject></para>

	  <para>As a first step Homura will download the selected
	    program.  A notification may appear in supported desktop
	    environments.</para>

	  <para><inlinemediaobject>
	      <imageobject>
		<imagedata
		  fileref="wine/homura-install-3" />
	      </imageobject>
	  </inlinemediaobject></para>

	  <para>The program will also create a new prefix for the
	    application.  A standard WINE dialog with this message
	    will display.</para>

	  <para><inlinemediaobject>
	      <imageobject>
		<imagedata
		  fileref="wine/homura-install-4" />
	      </imageobject>
	    </inlinemediaobject></para>

	  <para>Next, Homura will install any prerequisites for the
	    selected program.  This may involve downloading and
	    extracting a fair number of files, the details of which
	    will show in dialogs.</para>

	  <para><inlinemediaobject>
	      <imageobject>
		<imagedata
		  fileref="wine/homura-install-5" />
	      </imageobject>
	    </inlinemediaobject></para>

	  <para>Downloaded packages are automatically opened and run
	    as required.</para>

	  <para><inlinemediaobject>
	      <imageobject>
		<imagedata
		  fileref="wine/homura-install-6" />
	      </imageobject>
	  </inlinemediaobject></para>

	  <para>The installation may end with a simple desktop
	    notification or message in the terminal, depending on how
	    Homura was launched.  But in either case Homura should
	    return to the main screen.  To confirm the installation
	    was successful, select <emphasis>Launcher</emphasis>, and
	    click <emphasis>OK</emphasis>.</para>

	  <para><inlinemediaobject>
	      <imageobject>
		<imagedata
		  fileref="wine/homura-install-7" />
	      </imageobject>
	    </inlinemediaobject></para>

	  <para>This will display a list of installed
	    applications.</para>

	  <para><inlinemediaobject>
	      <imageobject>
		<imagedata
		  fileref="wine/homura-install-8" />
	      </imageobject>
	  </inlinemediaobject></para>

	  <para>To run the new program, select it from the list, and
	    click <emphasis>OK</emphasis>.  To uninstall the
	    application, select <emphasis>Uninstallation</emphasis>
	    from the main screen, which will display a similar list.
	    Select the program to be removed, and click
	    <emphasis>OK</emphasis>.</para>

	  <para><inlinemediaobject>
	      <imageobject>
		<imagedata
		  fileref="wine/homura-uninstall-1" />
	      </imageobject>
	    </inlinemediaobject></para>
	</sect3>
      </sect2>

      <sect2 xml:id="running-multiple-management-guis">
	<title>Running Multiple Management GUIs</title>

	<para>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.</para>

	<para>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
	<application>winetricks</application> and Homura to access the
	  same prefix could lead to some of these being overwritten,
	  with the result being some or all applications do not work
	  as expected.</para>
      </sect2>
    </sect1>

    <sect1 xml:id="wine-in-multi-user-os-installations">
      <title>WINE in Multi-User &os; Installations</title>

      <sect2 xml:id="issues-with-using-a-common-wine-prefix">
	<title>Issues with Using a Common WINE Prefix</title>

	<para>Like most &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.</para>

	<para>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.</para>

	<para>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).</para>

	<para>There are two strategies to minimze the impact of
	  multiple WINE users in the system.</para>
      </sect2>

      <sect2
	xml:id="installing-applications-to-a-common-drivesettings">
	<title>Installing Applications to a Common Drive</title>

	<para>As shown in the section on WINE Configuration, WINE
	  provides the ability to attach additional drives to a
	  given prefix.  In this way, applications can be installed to
	  a common location, while each user will still have an prefix
	  where individual settings may be kept (depending on the
	  program).  This is a good setup if there are relatively few
	  applications to be shared between users, and they are
	  programs that require few custom tweaks changes to the
	  prefix in order to function.</para>

	<para>The steps to make install applications in this way are
	  as follows:</para>

	<orderedlist>
	  <listitem>
	    <para>First, set up a shared location on the system where
	      the files will be stored, such as
	    <filename>/mnt/windows-drive_d/</filename>.  Creating new
	      directories is described in man page for the
	    <application>mkdir</application> command.</para>
	</listitem>

	<listitem>
	  <para>Next, set permissions for this new directory to allow
	    only desired users to access it.  One approach to this is
	    to create a new group such as &quot;windows,&quot; add the
	    desired users to that group (see the sub-section on groups
	    in the Handbook's Users and Basic Account Management
	    section), and set to the permissions on the directory to
	  <literal>770</literal> (the section on Permissions in the
	    &os; Basics chapter of the Handbook illustrates this
	    process).</para>
	</listitem>

	<listitem>
	  <para>Finally, add the location as a drive to the user's
	    prefix using the <application>winecfg</application>
	      as described in the above section on WINE Configuration
	      in this chapter.</para>
	  </listitem>
	</orderedlist>

	<para>Once complete, applications can be installed to this
	  location, and subsequently run using the assigned drive
	  letter (or the standard &unix;-style directory path).
	  However, as noted above, only one user should be running
	  these applications (which may be accessing files within
	  their installation directory) at the same time.  Some
	  applications may also exhibit unexpected behavior when run
	  by a user who is not the owner, despite being a member of
	  the group that should have full
	  &quot;read/write/execute&quot; permissions for the
	  entire directory.</para>
      </sect2>

      <sect2 xml:id="using-a-common-installation-of-wine">
	<title>Using a Common Installation of WINE</title>

	<para>If, on the other hand, there are many applications to be
	  shared, or they require specific tuning in order to work
	  correctly, a different approach may be required.  In this
	  method, a completely separate user is created specifically
	  for the purposes of storing the WINE prefix and all its
	  installed applications.  Individual users are then granted
	  permission to run programs as this user using the
	  <application>su</application> command.  The result is
	  that these users can launch a WINE application as they
	  normally would, only it will act as though launched by the
	  newly-created user, and therefore use the
	  centrally-maintained prefix containing both settings and
	  programs.  To accomplish this, take the following
	  steps.</para>

	<para>Create a new user with the following command (as root),
	  which will step through the required details:</para>

	<screen>&prompt.root; <userinput>adduser</userinput></screen>

	<para>Enter the username (e.g.,
	  <replaceable>windows</replaceable>) and Full name
	  (&quot;Microsoft Windows&quot;).  Then accept the defaults
	  for the remainder of the questions.  Next, install the
	  <application>sudo</application> utlity using binary packages
	  with the following:</para>

	<screen>&prompt.root; <userinput>pkg install sudo</userinput></screen>

	<para>Once installed, edit <filename>/etc/sudoers</filename>
	    as follows:</para>

	<programlisting># User alias specification

# define which users can run the wine/windows programs
User_Alias WINDOWS_USERS = user1,user2

# define which users can administrate (become root)
User_Alias ADMIN = user1

# Cmnd alias specification

# define which commands the WINDOWS_USERS may run
Cmnd_Alias WINDOWS = /usr/bin/wine,/usr/bin/winecfg

# Defaults
Defaults:WINDOWS_USERS env_reset
Defaults:WINDOWS_USERS env_keep += DISPLAY
Defaults:WINDOWS_USERS env_keep += XAUTHORITY
Defaults    !lecture,tty_tickets,!fqdn

# User privilege specification
root    ALL=(ALL) ALL

# Members of the admin user_alias, defined above, may gain root privileges
ADMIN ALL=(ALL) ALL

# The WINDOWS_USERS may run WINDOWS programs as user windows without a password
WINDOWS_USERS ALL = (windows) NOPASSWD: WINDOWS</programlisting>

      <para>The result of these changes is the users named in the
	<emphasis>User_Alias</emphasis> section are permitted to run
	the programs listed in the
	<emphasis>Cmnd<subscript>Alias</subscript></emphasis> section
	using the resources listed in the
	<emphasis>Defaults</emphasis> section (the current display) as
	if they were the user listed in the final line of the file.
	In other words, users designates as
	<emphasis>WINDOWS_USERS</emphasis> can run the
	<application>wine</application> and
	<application>winecfg</application> applications as user
	<emphasis>windows</emphasis>.  As a bonus, the configuration
	here means they will not be required to enter the password for
	the <emphasis>windows</emphasis> user.</para>

      <para>Next provide access to the display back to the
	<emphasis>windows</emphasis> user, as whom the WINE programs
	will be running:</para>

      <screen>&prompt.user; <userinput>xhost +local:windows</userinput></screen>

      <para>This should be added to the list of commands run either at
	login or when the default graphical environment starts.  Once
	all the above are complete, a user configured as one of the
	<literal>WINDOW_USERS</literal> in
	<filename>sudoers</filename> can run programs using the
	shared prefix with the following command:</para>

      <para>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.</para>
    </sect2>
  </sect1>

  <sect1 xml:id="wine-on-os-faq">
    <title>WINE on &os; FAQ</title>

    <para>The following section describes some frequently asked
      questions, tips/tricks, or common issues in running WINE on
      &os;, along with their respective answers.</para>

    <sect2 xml:id="basic-installation-and-usage">
      <title>Basic Installation and Usage</title>

      <sect3
	xml:id="how-to-install-32-bit-and-64-bit-wine-on-the-same-system">
	<title>How to Install 32-bit and 64-bit WINE on the Same
	  System?</title>

      <para>As described earlier in this section, the
	<application>wine</application> and
	<application>i386-wine</application> packages conflict with
	one another, and therefore 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 <emphasis>not</emphasis>
	mean building the port).</para>
    </sect3>

    <sect3 xml:id="can-dos-programs-be-run-on-wine">
      <title>Can DOS Programs Be Run on WINE?</title>

      <para>They can, as &quot;Console User Interface&quot;
	applications as mentioned eariler in this section.  However,
	there is an arguably better method for running DOS software:
      <application>DOSBox</application>.  On the other hand,
	there's little reason not to at least try it.  Simply create
	a new prefix, install the software, and if it does not work
	delete the prefix.</para>
    </sect3>

    <sect3
	xml:id="should-the-wine-devel-packageport-be-installed-to-use-the-development-version-of-wine-instead-of-stable">
      <title>Should the &quot;wine-devel&quot; Package/Port be
	Installed to Use the Development Version of WINE Instead of
	Stable?</title>

      <para>Yes, installing this version will install the
	&quot;development&quot; version of WINE.  As with the 32-
	and 64-bit versions, they cannot be installed together with
	the stable versions unless additional measures are
	taken.</para>

      <para>Note that WINE also has a &quot;Staging&quot; version,
	which contains the most recent updates.  This was at one
	time available as a &os; port; however, it has since been
	removed.  It can be compiled directly from source
	however.</para>
    </sect3>
  </sect2>

  <sect2 xml:id="install-optimization">
    <title>Install Optimization</title>

    <sect3
	xml:id="how-should-windows-hardware-graphics-drivers-be-handled">
      <title>How Should &windows; Hardware (e.g., Graphics) Drivers
	be Handled?</title>

      <para>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.</para>
    </sect3>

    <sect3 xml:id="is-there-a-way-to-make-windows-fonts-look-better">
      <title>Is There a way to Make &windows; Fonts Look
	Better?</title>

      <para>A user on the &os; forums suggests this configuration to
	fix out-of-the-box look of WINE fonts, which can be slightly
	pixelated.</para>

      <para>According to <link
	xlink:href="https://forums.freebsd.org/threads/make-wine-ui-fonts-look-good.68273/">a
	post in the FreeBSD Forums</link>, adding the following to
	<filename>.config/fontconfig/fonts.conf</filename>
	  will add anti-aliasing and make text more readable.</para>

      <programlisting>&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE fontconfig SYSTEM "fonts.dtd&gt;"

&lt;fontconfig&gt;

  &lt;!-- antialias all fonts --&gt;
  &lt;match target="font"&gt;
    &lt;edit name="antialias" mode="assign"&gt;&lt;bool&gt;true&lt;/bool&gt;&lt;/edit&gt;&gt;
    &lt;edit name="hinting" mode="assign"&gt;&lt;bool&gt;true&lt;/bool&gt;&lt;/edit&gt;&gt;
    &lt;edit name="hintstyle" mode="assign"&gt;&lt;const&gt;hintslight&lt;/const&gt;&lt;/edit&gt;&gt;
    &lt;edit name="rgba" mode="assign"&gt;&lt;const&gt;rgb&lt;/const&gt;&lt;/edit&gt;&gt;
  &lt;/match&gt;
&lt;/fontconfig&gt;</programlisting>
      </sect3>

      <sect3
	  xml:id="does-having-windows-installed-elsewhere-on-a-system-help-wine-operate">
	<title>Does Having &windows; Installed Elsewhere on a System
	  Help WINE Operate?</title>

	<para>It may, depending on the application being run.  As
	  mentioned in the section describing
	<application>winecfg</application>, some built-in WINE DLLs
	  and other libraries can be overridden by providing a path to
	  an alternate version.  Provided the &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.</para>
      </sect3>
    </sect2>

    <sect2 xml:id="application-specific">
      <title>Application-Specific</title>

      <sect3
	xml:id="where-is-the-best-place-to-see-if-application-x-works-on-wine">
      <title>Where is the Best Place to see if Application X Works on
	WINE?</title>

      <para>The first stop in determining compatibiliy should be the
	<link xlink:href="https://appdb.winehq.org/">WINE
	    AppDB</link>.  This is a compilation of reports of
	  programs working (or not) on all supported platforms,
	  although (as previously mentioned), solutions for one
	  platform are often applicable to others.</para>
      </sect3>

      <sect3
	xml:id="is-there-anything-that-will-help-games-run-better">
      <title>Is There Anything That Will Help Games Run
	Better?</title>

      <para>Perhaps.  Many &windows; games rely on DirectX, a
	proprietary Microsoft graphics layer.  However there are
	projects in the open source community attempting to implement
	support for this technology.</para>

      <para>The <emphasis>dxvk</emphasis> project, which is an attempt
	to implement DirectX using the &os;-compatible Vulkan graphics
	sub-system, is one such.  Although its primary target is WINE
	on Linux, <link
	  xlink:href="https://forums.freebsd.org/threads/what-about-gaming-on-freebsd.723/page-9">some
	  &os; users report</link> compiling and using dxvk.</para>

      <para>In addition, work is under way on a
      <application>wine-proton</application> <link
	  xlink:href="https://www.freshports.org/emulators/wine-proton/">port</link>.
	  This will bring the work of Valve, developer of the Steam
	  gaming platform, to &os;.  Proton is a distribution of WINE
	  designed to allow many &windows; games to run on other
	  operating systems with minimal setup.</para>
      </sect3>

      <sect3
	xml:id="is-there-anywhere-freebsd-wine-users-gather-to-exchange-tips-and-tricks">
      <title>Is There Anywhere FreeBSD WINE Users Gather to Exchange
	Tips and Tricks?</title>

      <para>There are plenty of places FreeBSD users discuss issues
	related to WINE that can be searched for solutions:</para>

      <itemizedlist>
	<listitem><para><link
	  xlink:href="https://forums.freebsd.org/">The &os;
	  forums</link>, particularly the <emphasis>Installation and
	    Maintenance of Ports or Packages</emphasis> or
	    <emphasis>Emulation and virtualization</emphasis>
	      forums.</para>
	  </listitem>

	  <listitem>
	    <para><link
	      xlink:href="https://wiki.freebsd.org/IRC/Channels">&os;
	      IRC channels</link> including #freebsd (for general
		support), #freebsd-games, and others.</para>
	    </listitem>

	    <listitem>
	      <para><link xlink:href="https://discord.gg/2CCuhCt">The
		BSD World Discord server's</link> channels including
		<emphasis>bsd-desktop</emphasis>,
		<emphasis>bsd-gaming</emphasis>,
		<emphasis>bsd-wine</emphasis>, and others.</para>
	    </listitem>
	  </itemizedlist>
	</sect3>
      </sect2>

      <sect2 xml:id="other-os-resources">
	<title>Other OS Resources</title>

	<para>There are a number of resources focused on other
	  operating systems that may be useful for &os; users:</para>

	<itemizedlist spacing="compact">
	  <listitem>
	    <para><link xlink:href="https://wiki.winehq.org/">The WINE
	      Wiki</link> has a wealth of information on using WINE,
	      much of which is applicable across many of WINE's
	      supported operating systems.</para>
	  </listitem>

	  <listitem>
	    <para>Similarly, the documentation available from other OS
	      projects can also be of good value.  <link
		xlink:href="https://wiki.archlinux.org/index.php/wine">The
		  WINE page</link> on the Arch Linux Wiki is a
	      particularly good example, although some of the
	      &quot;Third-party applications&quot; (i.e.,
	      &quot;companion applications&quot;) are obviously not
	      available on &os;.</para>
	  </listitem>

	  <listitem>
	    <para>Finally, Codeweavers (a developer of a commercial
	      version of WINE) is an active upstream contributor.
	      Oftentimes answers to questions in <link
		xlink:href="https://www.codeweavers.com/support/forums">their
		support forum</link> can be of aid in troubleshooting
	      problems with the open source version of WINE.</para>
	  </listitem>
	</itemizedlist>
      </sect2>
    </sect1>
  </chapter>