aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook/ports/chapter.xml
blob: 52007d7538d75ebe5f2db2677c2e5a1d931aa571 (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
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="ports">

  <title>Installing Applications: Packages and Ports</title>

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

    <indexterm><primary>ports</primary></indexterm>
    <indexterm><primary>packages</primary></indexterm>
    <para>&os; is bundled with a rich collection of system tools as
      part of the base system.  In addition,  &os; provides two
      complementary technologies for installing third-party software:
      the &os; Ports Collection, for installing from source, and
      packages, for installing from pre-built binaries.  Either
      method may be used to install software from local media or
      from the network.</para>

    <para>After reading this chapter, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>The difference between binary packages and ports.</para>
      </listitem>

      <listitem>
	<para>How to find third-party software that has been ported
	  to &os;.</para>
      </listitem>

      <listitem>
	<para>How to manage binary packages using
	  <application>pkg</application>.</para>
      </listitem>

      <listitem>
	<para>How to build third-party software from source using the
	  Ports Collection.</para>
      </listitem>

      <listitem>
	<para>How to find the files installed with the application
	  for post-installation configuration.</para>
      </listitem>

      <listitem>
	<para>What to do if a software installation fails.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="ports-overview">
    <title>Overview of Software Installation</title>

    <para>The typical steps for installing third-party software on a
      &unix; system include:</para>

    <procedure>
      <step>
	<para>Find and download the software, which might be
	  distributed in source code format or as a binary.</para>
      </step>

      <step>
	<para>Unpack the software from its distribution format.  This
	  is typically a tarball compressed with a program such as
	  &man.compress.1;, &man.gzip.1;, &man.bzip2.1; or &man.xz.1;.</para>
      </step>

      <step>
	<para>Locate the documentation in
	  <filename>INSTALL</filename>, <filename>README</filename>
	  or some file in a <filename>doc/</filename> subdirectory and
	  read up on how to install the software.</para>
      </step>

      <step>
	<para>If the software was distributed in source format,
	  compile it.  This may involve editing a
	  <filename>Makefile</filename> or running a
	  <command>configure</command> script.</para>
      </step>

      <step>
	<para>Test and install the software.</para>
      </step>
    </procedure>

    <para>A &os; <emphasis>port</emphasis> is a collection of files
      designed to automate
      the process of compiling an application from source code.  The
      files that comprise a port contain all the necessary information
      to automatically download, extract, patch, compile, and install
      the application.</para>

    <para>If the software has not already been adapted and tested
      on &os;, the source code might need editing in
      order for it to install and run properly.</para>

    <para>However, over
      <link xlink:href="&url.base;/ports/index.html">&os.numports;</link>
      third-party applications have already been
      ported to &os;.  When feasible, these applications are made
      available for download as pre-compiled <emphasis>packages</emphasis>.</para>

    <para>Packages
      can be manipulated with the &os; package management
      commands.</para>

    <para>Both packages and ports understand dependencies.  If a
      package or port is used to install an application and a
      dependent library is not already installed, the library will
      automatically be installed first.</para>

    <para>A &os; package contains pre-compiled copies of all the
      commands for an application, as well as any configuration files
      and documentation.  A package can be manipulated with the
      &man.pkg.8; commands, such as
      <command>pkg install</command>.</para>

    <para>While the two technologies are similar, packages and
      ports each have their own strengths.  Select the technology that
      meets your requirements for installing a particular
      application.</para>

    <itemizedlist>
      <title>Package Benefits</title>

      <listitem>
	<para>A compressed package tarball is typically smaller than
	  the compressed tarball containing the source code for the
	  application.</para>
      </listitem>

      <listitem>
	<para>Packages do not require compilation time.  For large
	  applications, such as <application>Mozilla</application>,
	  <application>KDE</application>, or
	  <application>GNOME</application>, this can be important
	  on a slow system.</para>
      </listitem>

      <listitem>
	<para>Packages do not require any understanding of the process
	  involved in compiling software on &os;.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <title>Port Benefits</title>

      <listitem>
	<para>Packages are normally compiled with conservative
	  options because they have to run on the maximum number of
	  systems.  By compiling from the port, one can change the
	  compilation options.</para>
      </listitem>

      <listitem>
	<para>Some applications have compile-time options relating to
	  which features are installed.  For example,
	  <application>Apache</application> can be configured with a
	  wide variety of different built-in options.</para>

	<para>In some cases, multiple packages will exist for the same
	  application to specify certain settings.  For example,
	  <application>Ghostscript</application> is available as a
	  <filename>ghostscript</filename> package and a
	  <filename>ghostscript-nox11</filename> package, depending on
	  whether or not <application>Xorg</application> is installed.
	  Creating multiple packages rapidly becomes impossible if an
	  application has more than one or two different compile-time
	  options.</para>
      </listitem>

      <listitem>
	<para>The licensing conditions of some software forbid binary
	  distribution.  Such software must be distributed as source
	  code which must be compiled by the end-user.</para>
      </listitem>

      <listitem>
	<para>Some people do not trust binary distributions or prefer
	  to read through source code in order to look for potential
	  problems.</para>
      </listitem>

      <listitem>
	<para>Source code is needed in
	  order to apply custom patches.</para>
      </listitem>
    </itemizedlist>

    <para>To keep track of updated ports, subscribe to the
      &a.ports; and the &a.ports-bugs;.</para>

    <warning>
      <para>Before installing any application, check <link
	  xlink:href="https://vuxml.freebsd.org/"></link>
	for security issues related to the application or type
	<command>pkg audit -F</command> to check all installed
	applications for known vulnerabilities.</para>
    </warning>

    <para>The remainder of this chapter explains how to use packages
      and ports to install and manage third-party software on
      &os;.</para>
  </sect1>

  <sect1 xml:id="ports-finding-applications">
    <title>Finding Software</title>

    <para>&os;'s list of available applications is growing all the
      time.  There are a number of ways to find software to
      install:</para>

    <itemizedlist>
      <listitem>
	<para>The &os; web site maintains an up-to-date searchable
	  list of all the available applications, at <link
	    xlink:href="&url.base;/ports/index.html">https://www.FreeBSD.org/ports/</link>.
	  The ports can be searched by application name or by
	  software category.</para>
      </listitem>

      <listitem>
	<indexterm><primary>FreshPorts</primary></indexterm>

	<para>Dan Langille maintains <link
	    xlink:href="http://www.FreshPorts.org/">FreshPorts.org</link>
	  which provides a comprehensive search utility and also
	  tracks changes to the applications in the Ports Collection.
	  Registered users can create a customized watch list in order
	  to receive an automated email when their watched ports are
	  updated.</para>
      </listitem>

      <listitem>
	<indexterm><primary>SourceForge</primary></indexterm>

	<para>If finding a particular application becomes challenging,
	  try searching a site like <link
	    xlink:href="http://www.sourceforge.net/">SourceForge.net</link>
	  or <link
	    xlink:href="http://www.github.com/">GitHub.com</link> then
	  check back at the <link
	    xlink:href="&url.base;/ports/index.html">&os; site</link>
	  to see if the application has been ported.</para>
      </listitem>

      <listitem>
	<indexterm>
	  <primary>pkg</primary>
	  <secondary>search</secondary>
	</indexterm>

	<para xml:id="pkg-search">To search the binary package
	  repository for an application:</para>

	<screen>&prompt.root; <userinput>pkg search <replaceable>subversion</replaceable></userinput>
git-subversion-<replaceable>1.9.2</replaceable>
java-subversion-<replaceable>1.8.8_2</replaceable>
p5-subversion-<replaceable>1.8.8_2</replaceable>
py27-hgsubversion-<replaceable>1.6</replaceable>
py27-subversion-<replaceable>1.8.8_2</replaceable>
ruby-subversion-<replaceable>1.8.8_2</replaceable>
subversion-<replaceable>1.8.8_2</replaceable>
subversion-book-<replaceable>4515</replaceable>
subversion-static-<replaceable>1.8.8_2</replaceable>
subversion16-<replaceable>1.6.23_4</replaceable>
subversion17-<replaceable>1.7.16_2</replaceable></screen>

	<para>Package names include the version number and, in the case of
	  ports based on python, the version number of the version of
	  python the package was built with.  Some ports also have
	  multiple versions available.  In the case of
	  <application>Subversion</application>, there are different
	  versions available, as well as different compile options.
	  In this case, the statically linked version of
	  <application>Subversion</application>.  When indicating
	  which package to install, it is best to specify the
	  application by the port origin, which is the path in the
	  ports tree.  Repeat the <command>pkg search</command> with
	  <option>-o</option> to list the origin of each
	  package:</para>

	<screen>&prompt.root; <userinput>pkg search -o <replaceable>subversion</replaceable></userinput>
devel/git-subversion
java/java-subversion
devel/p5-subversion
devel/py-hgsubversion
devel/py-subversion
devel/ruby-subversion
devel/subversion16
devel/subversion17
devel/subversion
devel/subversion-book
devel/subversion-static</screen>

	<para>Searching by shell globs, regular expressions, exact
	  match, by description, or any other field in the repository
	  database is also supported by <command>pkg search</command>.
	  After installing <package>ports-mgmt/pkg</package> or
	  <package>ports-mgmt/pkg-devel</package>, see
	  &man.pkg-search.8; for more details.</para>
      </listitem>

      <listitem>
	<para>If the Ports Collection is already installed, there are
	  several methods to query the local version of the ports
	  tree.  To find out which category a port is in, type
	  <command>whereis <replaceable>file</replaceable></command>,
	  where <replaceable>file</replaceable> is the program to be
	  installed:</para>

	<screen>&prompt.root; <userinput>whereis lsof</userinput>
lsof: /usr/ports/sysutils/lsof</screen>

	<para>Alternately, an &man.echo.1; statement can be
	  used:</para>

	<screen>&prompt.root; <userinput>echo /usr/ports/*/*lsof*</userinput>
/usr/ports/sysutils/lsof</screen>

	<para>Note that this will also return any matched files
	  downloaded into the
	  <filename>/usr/ports/distfiles</filename> directory.</para>
      </listitem>

      <listitem>
	<para>Another way to find software is by using the Ports
	  Collection's built-in search mechanism.  To use the search
	  feature, <application>cd</application> to
	  <filename>/usr/ports</filename> then run <command>make
	    search name=program-name</command> where
	  <replaceable>program-name</replaceable> is the name of the
	  software.  For example, to search for
	  <command>lsof</command>:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make search name=lsof</userinput>
Port:   lsof-4.88.d,8
Path:   /usr/ports/sysutils/lsof
Info:   Lists information about open files (similar to fstat(1))
Maint:  ler@lerctr.org
Index:  sysutils
B-deps:
R-deps: </screen>

	<tip>
	  <para>The built-in search mechanism uses a file
	    of index information.  If a message indicates that the
	    <filename>INDEX</filename> is required, run
	    <command>make fetchindex</command> to download the current
	    index file.  With the <filename>INDEX</filename> present,
	    <command>make search</command> will be able to perform the
	    requested search.</para>
	</tip>

	<para>The <quote>Path:</quote> line indicates where to find
	  the port.</para>

	<para>To receive less information, use the
	  <command>quicksearch</command> feature:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make quicksearch name=lsof</userinput>
Port:   lsof-4.88.d,8
Path:   /usr/ports/sysutils/lsof
Info:   Lists information about open files (similar to fstat(1))</screen>

	<para>For more in-depth searching, use
	  <command>make search
	  key=<replaceable>string</replaceable></command> or
	  <command>make quicksearch
	  key=<replaceable>string</replaceable></command>, where
	  <replaceable>string</replaceable> is some text to search
	  for.  The text can be in comments, descriptions, or
	  dependencies in order to find ports which relate to a
	  particular subject when the name of the program is
	  unknown.</para>

	<para>When using <buildtarget>search</buildtarget> or
	  <buildtarget>quicksearch</buildtarget>, the search string
	  is case-insensitive.  Searching for <quote>LSOF</quote> will
	  yield the same results as searching for
	  <quote>lsof</quote>.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="pkgng-intro">
    <title>Using <application>pkg</application> for Binary Package
      Management</title>

    <para><application>pkg</application> is the next generation
      replacement for the traditional &os; package management tools,
      offering many features that make dealing with binary packages
      faster and easier.</para>

    <para>For sites wishing to only use prebuilt binary packages
      from the &os; mirrors, managing packages with
      <application>pkg</application> can be sufficient.</para>

    <para>However, for those sites building from source or using
      their own repositories, a separate
      <link linkend="ports-upgrading-tools">port management tool</link>
      will be needed.</para>

    <para>Since <application>pkg</application> only works with
      binary packages, it
      is not a replacement for such tools.  Those tools can be
      used to install software from both binary packages
      and the Ports Collection, while
      <application>pkg</application> installs only binary
      packages.</para>

    <sect2 xml:id="pkgng-initial-setup">
      <title>Getting Started with
	<application>pkg</application></title>

      <para>&os; includes a bootstrap utility which can be used to
	download and install <application>pkg</application>
	and its manual pages.  This utility is designed to work
	with versions of &os; starting with
	10.<replaceable>X</replaceable>.</para>

      <note>
	<para>Not all &os; versions and architectures
	  support this bootstrap process.  The current list is at
	  <link xlink:href="https://pkg.freebsd.org/"></link>.
	  For other cases,
	  <application>pkg</application> must instead be installed
	  from the Ports Collection or as a binary package.</para>

      </note>

      <para>To bootstrap the system, run:</para>

      <screen>&prompt.root; <userinput>/usr/sbin/pkg</userinput></screen>

      <para>You must have a working Internet connection for the
	bootstrap process to succeed.</para>

      <para>Otherwise, to install the port, run:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/pkg</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

      <para>When upgrading an existing system that originally used the
	older pkg_* tools, the database must be converted to the
	new format, so that the new tools are aware of the already
	installed packages.  Once <application>pkg</application> has
	been installed, the
	package database must be converted from the traditional format
	to the new format by running this command:</para>

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

      <note><para>This step is not required for new installations that
	do not yet have any third-party software
	installed.</para></note>

      <important>
	<para>This step is not reversible.  Once the package database
	  has been converted to the <application>pkg</application>
	  format, the traditional <literal>pkg_*</literal> tools
	  should no longer be used.</para>
      </important>

      <note>
	<para>The package database conversion may emit errors as the
	  contents are converted to the new version.  Generally, these
	  errors can be safely ignored.  However, a list of
	  software that was not successfully converted
	  is shown after <command>pkg2ng</command> finishes.
	  These applications must be manually reinstalled.</para>
      </note>

      <para>To ensure that the Ports Collection registers
	new software with <application>pkg</application> instead of
	the traditional packages database, &os; versions earlier than
	10.<replaceable>X</replaceable> require this line in
	<filename>/etc/make.conf</filename>:</para>

      <programlisting>WITH_PKGNG=	yes</programlisting>

      <para>By default, <application>pkg</application> uses the
	binary packages from the &os;
	package mirrors (the <emphasis>repository</emphasis>).
	For information about building a custom
	package repository, see
	<xref linkend="ports-poudriere"/>.</para>

      <para>Additional <application>pkg</application> configuration
	options are described in &man.pkg.conf.5;.</para>

      <para>Usage information for <application>pkg</application> is
	available in the &man.pkg.8; manual page or by running
	<command>pkg</command> without additional arguments.</para>

      <para>Each <application>pkg</application> command argument is
	documented in a command-specific manual page.  To read the
	manual page for <command>pkg install</command>, for example,
	run either of these commands:</para>

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

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

      <para>The rest of this section demonstrates common binary
	package management tasks which can be performed using
	<application>pkg</application>.  Each demonstrated command
	provides many switches to customize its use.  Refer to a
	command's help or man page for details and more
	examples.</para>
    </sect2>

    <sect2 xml:id="pkgng-pkg-info">
      <title>Obtaining Information About Installed Packages</title>

      <para>Information about the packages installed on a system
	can be viewed by running <command>pkg info</command> which,
	when run without any switches, will list the package version
	for either all installed packages or the specified
	package.</para>

      <para>For example, to see which version of
	<application>pkg</application> is installed, run:</para>

      <screen>&prompt.root; <userinput>pkg info pkg</userinput>
pkg-1.1.4_1</screen>
    </sect2>

    <sect2 xml:id="pkgng-installing-deinstalling">
      <title>Installing and Removing Packages</title>

      <para>To install a binary package use the following command,
	where <replaceable>packagename</replaceable> is the name of
	the package to install:</para>

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

      <para>This command uses repository data to determine which
	version of the software to install and if it has any
	uninstalled dependencies.  For example, to install
	<application>curl</application>:</para>

      <screen>&prompt.root; <userinput>pkg install curl</userinput>
Updating repository catalogue
/usr/local/tmp/All/curl-7.31.0_1.txz          100% of 1181 kB 1380 kBps 00m01s

/usr/local/tmp/All/ca_root_nss-3.15.1_1.txz   100% of  288 kB 1700 kBps 00m00s

Updating repository catalogue
The following 2 packages will be installed:

        Installing ca_root_nss: 3.15.1_1
        Installing curl: 7.31.0_1

The installation will require 3 MB more space

0 B to be downloaded

Proceed with installing packages [y/N]: <userinput>y</userinput>
Checking integrity... done
[1/2] Installing ca_root_nss-3.15.1_1... done
[2/2] Installing curl-7.31.0_1... done
Cleaning up cache files...Done</screen>

	<para>The new package and any additional packages that were
	  installed as dependencies can be seen in the installed
	  packages list:</para>

	<screen>&prompt.root; <userinput>pkg info</userinput>
ca_root_nss-3.15.1_1	The root certificate bundle from the Mozilla Project
curl-7.31.0_1	Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
pkg-1.1.4_6	New generation package manager</screen>

	<para>Packages that are no longer needed can be removed with
	  <command>pkg delete</command>.  For example:</para>

	<screen>&prompt.root; <userinput>pkg delete curl</userinput>
The following packages will be deleted:

	curl-7.31.0_1

The deletion will free 3 MB

Proceed with deleting packages [y/N]: <userinput>y</userinput>
[1/1] Deleting curl-7.31.0_1... done</screen>
    </sect2>

    <sect2 xml:id="pkgng-upgrading">
      <title>Upgrading Installed Packages</title>

      <para>Installed packages can be upgraded to their latest
	versions by running:</para>

      <screen>&prompt.root; <userinput>pkg upgrade</userinput></screen>

      <para>This command will compare the installed versions with
	those available in the repository catalogue and upgrade them
	from the repository.</para>
    </sect2>

    <sect2 xml:id="pkgng-auditing">
      <title>Auditing Installed Packages</title>

      <para>Software vulnerabilities are regularly discovered
	in third-party applications.  To address this,
	<application>pkg</application> includes a built-in auditing
	mechanism.  To determine if there are any known
	vulnerabilities for the software installed on the system,
	run:</para>

	<screen>&prompt.root; <userinput>pkg audit -F</userinput></screen>
    </sect2>

    <sect2 xml:id="pkgng-autoremove">
      <title>Automatically Removing Leaf Dependencies</title>

      <para>Removing a package may leave behind dependencies which
	are no longer required.  Unneeded packages that were installed
	as dependencies can be automatically detected and removed
	using:</para>

      <screen>&prompt.root; <userinput>pkg autoremove</userinput>
Packages to be autoremoved:
	ca_root_nss-3.15.1_1

The autoremoval will free 723 kB

Proceed with autoremoval of packages [y/N]: <userinput>y</userinput>
Deinstalling ca_root_nss-3.15.1_1... done</screen>
    </sect2>

    <sect2 xml:id="pkgng-backup">
      <title>Restoring the Package Database</title>

      <para>Unlike the traditional package management system,
	<application>pkg</application> includes its own package
	database backup mechanism.  This functionality is enabled by
	default.</para>

      <tip>
	<para>To disable the periodic script from backing up the
	  package database, set
	  <literal>daily_backup_pkgdb_enable="NO"</literal> in
	  &man.periodic.conf.5;.</para>
      </tip>

      <para>To restore the contents of a previous package database
	backup, run the following command replacing
	<replaceable>/path/to/pkg.sql</replaceable> with the location
	of the backup:</para>

      <screen>&prompt.root; <userinput>pkg backup -r <replaceable>/path/to/pkg.sql</replaceable></userinput></screen>

      <note>
	<para>If restoring a backup taken by the periodic script,
	  it must be decompressed prior to being restored.</para>
      </note>

      <para>To run a manual backup of the
	<application>pkg</application> database, run the following
	command, replacing <replaceable>/path/to/pkg.sql</replaceable>
	with a suitable file name and location:</para>

      <screen>&prompt.root; <userinput>pkg backup -d <replaceable>/path/to/pkg.sql</replaceable></userinput></screen>
    </sect2>

    <sect2 xml:id="pkgng-clean">
      <title>Removing Stale Packages</title>

      <para>By default, <application>pkg</application> stores
	binary packages in a cache directory defined by
	<envar>PKG_CACHEDIR</envar> in &man.pkg.conf.5;.  Only copies
	of the latest installed packages are kept.  Older versions of
	<application>pkg</application> kept all previous packages.  To
	remove these outdated binary packages, run:</para>

      <screen>&prompt.root; <userinput>pkg clean</userinput></screen>

      <para>The entire cache may be cleared by running:</para>

      <screen>&prompt.root; <userinput>pkg clean -a</userinput></screen>
    </sect2>

    <sect2 xml:id="pkgng-set">
      <title>Modifying Package Metadata</title>

      <para>Software within the &os;&nbsp;Ports Collection can
	undergo major version number changes.  To address this,
	<application>pkg</application> has a built-in command to
	update package origins.  This can be useful, for example, if
	<package>lang/php5</package> is renamed to
	<package>lang/php53</package> so that
	<package>lang/php5</package> can now
	represent version <literal>5.4</literal>.</para>

      <para>To change the package origin for the above example,
	run:</para>

      <screen>&prompt.root; <userinput>pkg set -o lang/php5:lang/php53</userinput></screen>

      <para>As another example, to update
	<package>lang/ruby18</package> to
	<package>lang/ruby19</package>, run:</para>

      <screen>&prompt.root; <userinput>pkg set -o lang/ruby18:lang/ruby19</userinput></screen>

      <para>As a final example, to change the origin of the
	<filename>libglut</filename> shared libraries from
	<package>graphics/libglut</package> to
	<package>graphics/freeglut</package>, run:</para>

      <screen>&prompt.root; <userinput>pkg set -o graphics/libglut:graphics/freeglut</userinput></screen>

      <note>
	<para>When changing package origins, it is important to
	  reinstall packages that are dependent on the package with
	  the modified origin.  To force a reinstallation of dependent
	  packages, run:</para>

	<screen>&prompt.root; <userinput>pkg install -Rf <replaceable>graphics/freeglut</replaceable></userinput></screen>
      </note>
    </sect2>
  </sect1>

  <sect1 xml:id="ports-using">
    <title>Using the Ports Collection</title>

    <para>The Ports Collection is a set of
      <filename>Makefiles</filename>, patches, and description files.
      Each set of these files is used to compile and install an individual
      application on &os;, and is called a <emphasis>port</emphasis>.</para>

    <para>By default, the Ports Collection itself is stored as a subdirectory
      of <filename>/usr/ports</filename>.</para>

    <para>Before an
      application can be compiled using a port, the Ports Collection
      must first be installed.  If it was not installed during the
      installation of &os;, use one of the following methods to
      install it:</para>

    <procedure xml:id="ports-using-portsnap-method">
      <title>Portsnap Method</title>

      <para>The base system of &os; includes
	<application>Portsnap</application>.  This is a fast and
	user-friendly tool for retrieving the Ports Collection and
	is the recommended choice for most users.  This utility
	connects to a &os; site, verifies the secure key, and
	downloads a new copy of the Ports Collection.  The key is used
	to verify the integrity of all downloaded files.</para>

      <step>
	<para>To download a compressed snapshot of the Ports
	  Collection into
	  <filename>/var/db/portsnap</filename>:</para>

	<screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
      </step>

      <step>
	<para>When running <application>Portsnap</application> for the
	  first time, extract the snapshot into
	  <filename>/usr/ports</filename>:</para>

	<screen>&prompt.root; <userinput>portsnap extract</userinput></screen>
      </step>

      <step>
	<para>After the first use of
	  <application>Portsnap</application> has been completed as
	  shown above, <filename>/usr/ports</filename> can be updated
	  as needed by running:</para>

	<screen>&prompt.root; <userinput>portsnap fetch</userinput>
&prompt.root; <userinput>portsnap update</userinput></screen>

	<para>When using <literal>fetch</literal>, the
	  <literal>extract</literal> or the <literal>update</literal>
	  operation may be run consecutively, like so:</para>

	<screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
      </step>
    </procedure>

    <procedure xml:id="ports-using-subversion-method">
      <title>Subversion Method</title>

      <para>If more control over the ports tree is needed or if local
	changes need to be maintained,
	<application>Subversion</application> can be used to obtain
	the Ports Collection.  Refer to <link
	  xlink:href="&url.articles.committers-guide;/subversion-primer.html">the
	  Subversion Primer</link> for a detailed description of
	<application>Subversion</application>.</para>

      <step>
	<para><application>Subversion</application> must be installed
	  before it can be used to check out the ports tree.  If a
	  copy of the ports tree is already present, install
	  <application>Subversion</application> like this:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/devel/subversion</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

	<para>If the ports tree is not available, or
	  <application>pkg</application> is being used to manage
	  packages, <application>Subversion</application> can be
	  installed as a package:</para>

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

      </step>

      <step>
	<para>Check out a copy of the ports tree:</para>

	<screen>&prompt.root; <userinput>svn checkout https://svn.FreeBSD.org/ports/head /usr/ports</userinput></screen>
      </step>

      <step>
	<para>As needed, update <filename>/usr/ports</filename> after
	  the initial <application>Subversion</application>
	  checkout:</para>

	<screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen>
      </step>
    </procedure>

    <para>The Ports Collection contains directories
      for software categories.  Inside each category are
      subdirectories for individual applications.  Each application
      subdirectory contains a set of files that
      tells &os; how to compile and install that program,
      called a <emphasis>ports skeleton</emphasis>.  Each port
      skeleton includes these files and directories:</para>

    <itemizedlist>
      <listitem>
	<para><filename>Makefile</filename>: contains statements that
	  specify how the application should be compiled and where
	  its components should be installed.</para>
      </listitem>

      <listitem>
	<para><filename>distinfo</filename>: contains the names and
	  checksums of the files that must be downloaded to build the
	  port.</para>
      </listitem>

      <listitem>
	<para><filename>files/</filename>: this directory contains
	  any patches needed for the program to compile and install
	  on &os;.  This directory may also contain other files used
	  to build the port.</para>
      </listitem>

      <listitem>
	<para><filename>pkg-descr</filename>: provides a more detailed
	  description of the program.</para>
      </listitem>

      <listitem>
	<para><filename>pkg-plist</filename>:  a list of all the
	  files that will be installed by the port.  It also tells
	  the ports system which files to remove upon
	  deinstallation.</para>
      </listitem>
    </itemizedlist>

    <para>Some ports include <filename>pkg-message</filename> or
      other files to handle special situations.  For more details
      on these files, and on ports in general, refer to the <link
	xlink:href="&url.books.porters-handbook;/index.html">&os;
	Porter's Handbook</link>.</para>

    <para>The port does not include the actual source code, also
      known as a <filename>distfile</filename>.  The extract portion
      of building a port will automatically save the downloaded
      source to <filename>/usr/ports/distfiles</filename>.</para>

    <sect2 xml:id="ports-skeleton">
      <title>Installing Ports</title>

      <indexterm>
	<primary>ports</primary>
	<secondary>installing</secondary>
      </indexterm>

      <para>This section provides basic instructions on using the
	Ports Collection to install or remove software.  The detailed
	description of available <command>make</command> targets and
	environment variables is available in &man.ports.7;.</para>

      <warning>
	<para>Before compiling any port, be sure to update the Ports
	  Collection as described in the previous section.  Since
	  the installation of any third-party software can introduce
	  security vulnerabilities, it is recommended to first check
	  <link xlink:href="https://vuxml.freebsd.org/"></link>
	  for known security issues related to the port.  Alternately,
	  run <command>pkg audit -F</command> before installing a new
	  port.  This command can be configured to automatically
	  perform a security audit and an update of the vulnerability
	  database during the daily security system check.  For more
	  information, refer to &man.pkg-audit.8; and
	  &man.periodic.8;.</para>
      </warning>

      <para>Using the Ports Collection assumes a working Internet
	connection.  It also requires superuser privilege.</para>

      <para>To compile and install the port, change to the directory
	of the port to be installed, then type <command>make
	  install</command> at the prompt.  Messages will indicate
	the progress:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
&prompt.root; <userinput>make install</userinput>
&gt;&gt; lsof_4.88D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
&gt;&gt; Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
===&gt;  Extracting for lsof-4.88
...
[extraction output snipped]
...
&gt;&gt; Checksum OK for lsof_4.88D.freebsd.tar.gz.
===&gt;  Patching for lsof-4.88.d,8
===&gt;  Applying FreeBSD patches for lsof-4.88.d,8
===&gt;  Configuring for lsof-4.88.d,8
...
[configure output snipped]
...
===&gt;  Building for lsof-4.88.d,8
...
[compilation output snipped]
...

===&gt;  Installing for lsof-4.88.d,8
...
[installation output snipped]
...
===&gt;   Generating temporary packing list
===&gt;   Compressing manual pages for lsof-4.88.d,8
===&gt;   Registering installation for lsof-4.88.d,8
===&gt;  SECURITY NOTE:
      This port has installed the following binaries which execute with
      increased privileges.
/usr/local/sbin/lsof
&prompt.root;</screen>

      <para>Since <command>lsof</command> is a program that runs
	with increased privileges, a security warning is displayed
	as it is installed.  Once the installation is complete, the
	prompt will be returned.</para>

      <para>Some shells keep a cache of the commands that are
	available in the directories listed in the
	<envar>PATH</envar> environment variable, to speed up lookup
	operations for the executable file of these commands.  Users
	of the <command>tcsh</command> shell should type
	<command>rehash</command> so that a newly installed command
	can be used without specifying its full path.  Use
	<command>hash -r</command> instead for the
	<command>sh</command> shell.  Refer to the documentation
	for the shell for more information.</para>

      <para>During installation, a working subdirectory is created
	which contains all the temporary files used during
	compilation.  Removing this directory saves disk space and
	minimizes the chance of problems later when upgrading to the
	newer version of the port:</para>

      <screen>&prompt.root; <userinput>make clean</userinput>
===&gt;  Cleaning for lsof-88.d,8
&prompt.root;</screen>

      <note>
	<para>To save this extra step, instead use <command>make
	    install clean</command> when compiling the port.</para>
      </note>

      <sect3>
	<title>Customizing Ports Installation</title>

	<para>Some ports provide build options which can be used to
	  enable or disable application components, provide security
	  options, or allow for other customizations.  Examples
	  include <package>www/firefox</package>,
	  <package>security/gpgme</package>, and
	  <package>mail/sylpheed-claws</package>.
	  If the port depends upon other ports which have configurable
	  options, it may pause several times for user interaction
	  as the default behavior is to prompt the user to select
	  options from a menu.  To avoid this and do all of the configuration
	  in one batch, run <command>make config-recursive</command>
	  within the port skeleton.  Then, run <command>make
	    install [clean]</command> to compile and install the
	  port.</para>

	<tip>
	  <para>When using
	    <buildtarget>config-recursive</buildtarget>, the list of
	    ports to configure are gathered by the
	    <buildtarget>all-depends-list</buildtarget> target.  It is
	    recommended to run <command>make
	      config-recursive</command> until all dependent ports
	    options have been defined, and ports options screens no
	    longer appear, to be certain that all dependency options
	    have been configured.</para>
	</tip>

	<para>There are several ways to revisit a port's build options
	  menu in order to add, remove, or change these options after
	  a port has been built.  One method is to
	  <command>cd</command> into the directory containing the
	  port and type <command>make config</command>.  Another
	  option is to use <command>make showconfig</command>.
	  Another option is to execute <command>make
	    rmconfig</command> which will remove all selected options
	  and allow you to start over.  All of these options, and
	  others, are explained in great detail in
	  &man.ports.7;.</para>

	<para>The ports system uses &man.fetch.1; to download the
	  source files, which supports various environment variables.
	  The <envar>FTP_PASSIVE_MODE</envar>,
	  <envar>FTP_PROXY</envar>, and <envar>FTP_PASSWORD</envar>
	  variables may need to be set if the &os; system is behind
	  a firewall or FTP/HTTP proxy.  See &man.fetch.3; for the
	  complete list of supported variables.</para>

	<para>For users who cannot be connected to the Internet all
	  the time, <command>make fetch</command> can be run within
	  <filename>/usr/ports</filename>, to fetch all distfiles, or
	  within a category, such as
	  <filename>/usr/ports/net</filename>, or within the specific
	  port skeleton.  Note that if a port has any dependencies,
	  running this command in a category or ports skeleton will
	  <emphasis>not</emphasis> fetch the distfiles of ports from
	  another category.  Instead, use <command>make
	    fetch-recursive</command> to also fetch the distfiles for
	  all the dependencies of a port.</para>

	<para>In rare cases, such as when an organization has a local
	  distfiles repository, the <varname>MASTER_SITES</varname>
	  variable can be used to override the download locations
	  specified in the <filename>Makefile</filename>.  When using,
	  specify the alternate location:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
<replaceable>ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/</replaceable> fetch</userinput></screen>

	<para>The <varname>WRKDIRPREFIX</varname> and
	  <varname>PREFIX</varname> variables can override the default
	  working and target directories.  For example:</para>

	<screen>&prompt.root; <userinput>make WRKDIRPREFIX=/usr/home/example/ports install</userinput></screen>

	<para>will compile the port in
	  <filename>/usr/home/example/ports</filename> and install
	  everything under <filename>/usr/local</filename>.</para>

	<screen>&prompt.root; <userinput>make PREFIX=/usr/home/example/local install</userinput></screen>

	<para>will compile the port in <filename>/usr/ports</filename>
	  and install it in
	  <filename>/usr/home/example/local</filename>.  And:</para>

	<screen>&prompt.root; <userinput>make WRKDIRPREFIX=../ports PREFIX=../local install</userinput></screen>

	<para>will combine the two.</para>

	<para>These can also be set as environmental variables.  Refer
	  to the manual page for your shell for instructions on how to
	  set an environmental variable.</para>
      </sect3>
    </sect2>

    <sect2 xml:id="ports-removing">
      <title>Removing Installed Ports</title>

      <indexterm>
	<primary>ports</primary>
	<secondary>removing</secondary>
      </indexterm>

      <para>Installed ports can be uninstalled using <command>pkg
	  delete</command>.  Examples for using this command can be
	found in the &man.pkg-delete.8; manual page.</para>

      <para>Alternately, <command>make deinstall</command> can be
	run in the port's directory:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
<userinput>make deinstall</userinput>
===&gt;  Deinstalling for sysutils/lsof
===&gt;   Deinstalling
Deinstallation has been requested for the following 1 packages:

	lsof-4.88.d,8

The deinstallation will free 229 kB
[1/1] Deleting lsof-4.88.d,8... done</screen>

      <para>It is recommended to read the messages as the port is
	uninstalled.  If the port has any applications that depend
	upon it, this information will be displayed but the
	uninstallation will proceed.  In such cases, it may be better
	to reinstall the application in order to prevent broken
	dependencies.</para>
    </sect2>

    <sect2 xml:id="ports-upgrading">
      <title>Upgrading Ports</title>

      <indexterm>
	<primary>ports</primary>
	<secondary>upgrading</secondary>
      </indexterm>

      <para>Over time, newer versions of software become available
	in the Ports Collection.  This section describes how to
	determine which software can be upgraded and how to perform
	the upgrade.</para>

      <para>To determine if newer versions of installed ports are
	available, ensure that the latest version of the ports tree is
	installed, using the updating command described in either
	<xref linkend="ports-using-portsnap-method"/> or
	<xref linkend="ports-using-subversion-method"/>.  On &os; 10
	and later, or if the system has been converted to
	<application>pkg</application>, the following command will
	list the installed ports which are out of date:</para>

      <screen>&prompt.root; <userinput>pkg version -l "&lt;"</userinput></screen>

      <para>For &os; 9.<replaceable>X</replaceable> and lower, the
	following command will list the installed ports that are out
	of date:</para>

      <screen>&prompt.root; <userinput>pkg_version -l "&lt;"</userinput></screen>

      <important>
	<para>Before
	  attempting an upgrade, read
	  <filename>/usr/ports/UPDATING</filename> from the top of
	  the file to the date closest to the last time ports were
	  upgraded or the system was installed.  This file describes
	  various issues and additional steps users may encounter and
	  need to perform when updating a port, including such things
	  as file format changes, changes in locations of
	  configuration files, or any incompatibilities with previous
	  versions.  Make note of any instructions which match any of
	  the ports that need upgrading and follow these instructions
	  when performing the upgrade.</para>
      </important>

      <sect3 xml:id="ports-upgrading-tools">
	<title>Tools To Upgrade And Manage Ports</title>

	<indexterm>
	  <primary>ports</primary>
	  <secondary>upgrading-tools</secondary>
	</indexterm>

	<para>The Ports Collection contains several utilities to perform
	  the actual upgrade.  Each has its strengths and weaknesses.</para>

	<para>Historically, most installations used either
	  <application>Portmaster</application> or
	  <application>Portupgrade</application>.
	  <application>Synth</application> is a newer
	  alternative.</para>

	<note>
	  <para>The choice of which tool is best for a particular system
	    is up to the system administrator.  It is recommended practice
	    to back up your data before using any of these tools.</para>
	</note>

      </sect3>

      <sect3 xml:id="portmaster">
	<title>Upgrading Ports Using
	  <application>Portmaster</application></title>

	<indexterm>
	  <primary>portmaster</primary>
	</indexterm>

	<para><package>ports-mgmt/portmaster</package> is a very
	  small utility for upgrading installed ports.
	  It is designed to use the tools installed with the &os;
	  base system
	  without depending on other ports or databases.
	  To install this utility
	  as a port:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portmaster</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

	<para><application>Portmaster</application> defines four
	  categories of ports:</para>

	<itemizedlist>
	  <listitem>
	    <para>Root port: has no dependencies and is not a
	      dependency of any other ports.</para>
	  </listitem>

	  <listitem>
	    <para>Trunk port: has no dependencies, but other ports
	      depend upon it.</para>
	  </listitem>

	  <listitem>
	    <para>Branch port: has dependencies and other ports
	      depend upon it.</para>
	  </listitem>

	  <listitem>
	    <para>Leaf port: has dependencies but no other ports
	      depend upon it.</para>
	  </listitem>
	</itemizedlist>

	<para>To list these categories and search for updates:</para>

	<screen>&prompt.root; <userinput>portmaster -L</userinput>
===&gt;&gt;&gt; Root ports (No dependencies, not depended on)
===&gt;&gt;&gt; ispell-3.2.06_18
===&gt;&gt;&gt; screen-4.0.3
        ===&gt;&gt;&gt; New version available: screen-4.0.3_1
===&gt;&gt;&gt; tcpflow-0.21_1
===&gt;&gt;&gt; 7 root ports
...
===&gt;&gt;&gt; Branch ports (Have dependencies, are depended on)
===&gt;&gt;&gt; apache22-2.2.3
        ===&gt;&gt;&gt; New version available: apache22-2.2.8
...
===&gt;&gt;&gt; Leaf ports (Have dependencies, not depended on)
===&gt;&gt;&gt; automake-1.9.6_2
===&gt;&gt;&gt; bash-3.1.17
        ===&gt;&gt;&gt; New version available: bash-3.2.33
...
===&gt;&gt;&gt; 32 leaf ports

===&gt;&gt;&gt; 137 total installed ports
        ===&gt;&gt;&gt; 83 have new versions available</screen>

	<para>This command is used to upgrade all outdated
	  ports:</para>

	<screen>&prompt.root; <userinput>portmaster -a</userinput></screen>

	<note>
	  <para>By default, <application>Portmaster</application>
	    makes a backup package before deleting the existing port.
	    If the installation of the new version is successful,
	    <application>Portmaster</application> deletes the
	    backup.  Using <option>-b</option> instructs
	    <application>Portmaster</application> not to automatically
	    delete the backup.  Adding <option>-i</option> starts
	    <application>Portmaster</application> in interactive mode,
	    prompting for confirmation before upgrading each port.
	    Many other options are available.  Read through the
	    manual page for &man.portmaster.8; for details regarding
	    their usage.</para>
	</note>

	<para>If errors are encountered during the upgrade process,
	  add <option>-f</option> to upgrade and rebuild all
	  ports:</para>

	<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>

	<para><application>Portmaster</application> can also be used
	  to install new ports on the system, upgrading all
	  dependencies before building and installing the new
	  port.  To use this function, specify the location of the
	  port in the Ports Collection:</para>

	<screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen>

	<para>More information about <package>ports-mgmt/portmaster</package>
	  may be found in its <filename>pkg-descr</filename>.</para>
      </sect3>

      <sect3 xml:id="portupgrade">
	<title>Upgrading Ports Using Portupgrade</title>

	<indexterm>
	  <primary>portupgrade</primary>
	</indexterm>

	<para><package>ports-mgmt/portupgrade</package> is 
	  another utility that can be used to upgrade ports.  It
	  installs a suite of applications
	  which can be used to manage ports.  However, it is dependent
	  upon Ruby.  To install the port:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portupgrade</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

	<para>Before performing an upgrade using this utility, it is
	  recommended to scan the list of installed ports using
	  <command>pkgdb -F</command> and to fix all the
	  inconsistencies it reports.</para>

	<para>To upgrade all the outdated ports installed on the
	  system, use <command>portupgrade -a</command>.  Alternately,
	  include <option>-i</option> to be asked for confirmation
	  of every individual upgrade:</para>

	<screen>&prompt.root; <userinput>portupgrade -ai</userinput></screen>

	<para>To upgrade only a specified application instead of all
	  available ports, use <command>portupgrade
	    <replaceable>pkgname</replaceable></command>.  It is very
	  important to include <option>-R</option> to first upgrade
	  all the ports required by the given application:</para>

	<screen>&prompt.root; <userinput>portupgrade -R firefox</userinput></screen>

	<para>If
	  <option>-P</option> is included,
	  <application>Portupgrade</application> searches for
	  available packages in the local directories listed in
	  <envar>PKG_PATH</envar>.  If none are available locally, it
	  then fetches packages from a remote site.  If packages can
	  not be found locally or fetched remotely,
	  <application>Portupgrade</application> will use ports.  To
	  avoid using ports entirely, specify <option>-PP</option>.
	  This last set of options tells
	  <application>Portupgrade</application> to abort if no
	  packages are available:</para>

	<screen>&prompt.root; <userinput>portupgrade -PP gnome3</userinput></screen>

	<para>To just fetch the port distfiles, or packages, if
	  <option>-P</option> is specified, without building or
	  installing anything, use <option>-F</option>.  For further
	  information on all of the available switches, refer to the
	  manual page for <command>portupgrade</command>.</para>

	<para>More information about <package>ports-mgmt/portupgrade</package>
	  may be found in its <filename>pkg-descr</filename>.</para>
      </sect3>

    </sect2>

    <sect2 xml:id="ports-disk-space">
      <title>Ports and Disk Space</title>

      <indexterm>
	<primary>ports</primary>
	<secondary>disk-space</secondary>
      </indexterm>

      <para>Using the Ports Collection will use up disk space over
	time.  After building and installing a port, running
	<command>make clean</command> within the ports skeleton will
	clean up the temporary <filename>work</filename> directory.
	If <application>Portmaster</application> is used to install a
	port, it will automatically remove this directory unless
	<option>-K</option> is specified.  If
	<application>Portupgrade</application> is installed, this
	command will remove all <filename>work</filename> directories
	found within the local copy of the Ports Collection:</para>

      <screen>&prompt.root; <userinput>portsclean -C</userinput></screen>

      <para>In addition, outdated source distribution files
	accumulate in <filename>/usr/ports/distfiles</filename> over
	time.  To use <application>Portupgrade</application> to
	delete all the distfiles that are no longer
	referenced by any ports:</para>

      <screen>&prompt.root; <userinput>portsclean -D</userinput></screen>

      <para><application>Portupgrade</application> can remove
	all distfiles not referenced by any port currently installed
	on the system:</para>

      <screen>&prompt.root; <userinput>portsclean -DD</userinput></screen>

      <para>If <application>Portmaster</application> is installed,
	use:</para>

      <screen>&prompt.root; <userinput>portmaster --clean-distfiles</userinput></screen>

      <para>By default, this command is interactive and prompts
	the user to confirm if a distfile should be deleted.</para>

      <para>In addition to these commands,
	<package>ports-mgmt/pkg_cutleaves</package>
	automates the task of removing installed ports that are no
	longer needed.</para>
    </sect2>
  </sect1>

  <sect1 xml:id="ports-poudriere">
    <title>Building Packages with
      <application>Poudriere</application></title>

    <para><application>Poudriere</application> is a
      <acronym>BSD</acronym>-licensed utility for creating and testing
      &os; packages.  It uses &os; jails to set up isolated
      compilation environments.  These jails can be used to build
      packages for versions of &os; that are different from the system
      on which it is installed, and also to build packages for i386 if
      the host is an &arch.amd64; system.  Once the packages are
      built, they are in a layout identical to the official mirrors.
      These packages are usable by &man.pkg.8; and other package
      management tools.</para>

    <para><application>Poudriere</application> is installed using
      the <package role="port">ports-mgmt/poudriere</package> package
      or port.  The installation includes a sample configuration
      file <filename>/usr/local/etc/poudriere.conf.sample</filename>.
      Copy this file to
      <filename>/usr/local/etc/poudriere.conf</filename>.  Edit the
      copied file to suit the local configuration.</para>

    <para>While <acronym>ZFS</acronym> is not required on the system
      running <application>poudriere</application>, it is beneficial.
      When <acronym>ZFS</acronym> is used,
      <varname>ZPOOL</varname> must be specified in
      <filename>/usr/local/etc/poudriere.conf</filename> and
      <varname>FREEBSD_HOST</varname> should be set to a nearby
      mirror.  Defining <varname>CCACHE_DIR</varname> enables the use
      of <package role="port">devel/ccache</package> to cache
      compilation and reduce build times for frequently-compiled code.
      It may be convenient to put
      <application>poudriere</application> datasets in an isolated
      tree mounted at <filename
	>/poudriere</filename>.  Defaults for the
      other configuration values are adequate.</para>

    <para>The number of processor cores detected is used to define how
      many builds will run in parallel.  Supply enough virtual
      memory, either with <acronym>RAM</acronym> or swap space.  If
      virtual memory runs out, the compilation jails will stop and be torn
      down, resulting in weird error messages.</para>

    <sect2 xml:id="poudriere-initialization">
      <title>Initialize Jails and Port Trees</title>

      <para>After configuration, initialize
	<application>poudriere</application> so that it installs a
	jail with the required &os; tree and a ports tree.  Specify a
	name for the jail using <option>-j</option> and the &os;
	version with <option>-v</option>.  On systems running
	&os;/&arch.amd64;, the architecture can be set with
	<option>-a</option> to either <literal>i386</literal> or
	<literal>amd64</literal>.  The default is the
	architecture shown by <command>uname</command>.</para>

      <screen>&prompt.root; <userinput>poudriere jail -c -j <replaceable>10amd64</replaceable> -v <replaceable>10.0-RELEASE</replaceable></userinput>
====&gt;&gt; Creating 10amd64 fs... done
====&gt;&gt; Fetching base.txz for FreeBSD 10.0-RELEASE amd64
/poudriere/jails/10amd64/fromftp/base.txz      100% of   59 MB 1470 kBps 00m42s
====&gt;&gt; Extracting base.txz... done
====&gt;&gt; Fetching src.txz for FreeBSD 10.0-RELEASE amd64
/poudriere/jails/10amd64/fromftp/src.txz       100% of  107 MB 1476 kBps 01m14s
====&gt;&gt; Extracting src.txz... done
====&gt;&gt; Fetching games.txz for FreeBSD 10.0-RELEASE amd64
/poudriere/jails/10amd64/fromftp/games.txz     100% of  865 kB  734 kBps 00m01s
====&gt;&gt; Extracting games.txz... done
====&gt;&gt; Fetching lib32.txz for FreeBSD 10.0-RELEASE amd64
/poudriere/jails/10amd64/fromftp/lib32.txz     100% of   14 MB 1316 kBps 00m12s
====&gt;&gt; Extracting lib32.txz... done
====&gt;&gt; Cleaning up... done
====&gt;&gt; Jail 10amd64 10.0-RELEASE amd64 is ready to be used</screen>

      <screen>&prompt.root; <userinput>poudriere ports -c -p <replaceable>local</replaceable></userinput>
====&gt;&gt; Creating local fs... done
====&gt;&gt; Extracting portstree "local"...
Looking up portsnap.FreeBSD.org mirrors... 7 mirrors found.
Fetching public key from ec2-eu-west-1.portsnap.freebsd.org... done.
Fetching snapshot tag from ec2-eu-west-1.portsnap.freebsd.org... done.
Fetching snapshot metadata... done.
Fetching snapshot generated at Tue Feb 11 01:07:15 CET 2014:
94a3431f0ce567f6452ffde4fd3d7d3c6e1da143efec76100% of   69 MB 1246 kBps 00m57s
Extracting snapshot... done.
Verifying snapshot integrity... done.
Fetching snapshot tag from ec2-eu-west-1.portsnap.freebsd.org... done.
Fetching snapshot metadata... done.
Updating from Tue Feb 11 01:07:15 CET 2014 to Tue Feb 11 16:05:20 CET 2014.
Fetching 4 metadata patches... done.
Applying metadata patches... done.
Fetching 0 metadata files... done.
Fetching 48 patches.
(48/48) 100.00%  done.
done.
Applying patches...
done.
Fetching 1 new ports or files... done.
/poudriere/ports/tester/CHANGES
/poudriere/ports/tester/COPYRIGHT

[...]

Building new INDEX files... done.</screen>

      <para>On a single computer, <application>poudriere</application>
	can build ports with multiple configurations, in multiple
	jails, and from different port trees.  Custom configurations
	for these combinations are called <emphasis>sets</emphasis>.
	See the CUSTOMIZATION section of &man.poudriere.8; for details
	after <package>ports-mgmt/poudriere</package> or
	<package>ports-mgmt/poudriere-devel</package> is
	installed.</para>

      <para>The basic configuration shown here puts a single jail-,
	port-, and set-specific <filename>make.conf</filename> in
	<filename
	  >/usr/local/etc/poudriere.d</filename>.
	The filename in this example is created by combining the jail
	name, port name, and set name:
	<filename><replaceable>10amd64-local-workstation</replaceable>-make.conf</filename>.
	The system <filename>make.conf</filename> and this new file
	are combined at build time to create the
	<filename>make.conf</filename> used by the build jail.</para>

      <para>Packages to be built are entered in
	<filename><replaceable>10amd64-local-workstation</replaceable>-pkglist</filename>:</para>

      <programlisting>editors/emacs
devel/git
ports-mgmt/pkg
...</programlisting>

      <para>Options and dependencies for the specified ports are
	configured:</para>

      <screen>&prompt.root; <userinput>poudriere options -j <replaceable>10amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>10amd64-local-workstation-pkglist</replaceable></userinput></screen>

      <para>Finally, packages are built and a package
	repository is created:</para>

      <screen>&prompt.root; <userinput>poudriere bulk -j <replaceable>10amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>10amd64-local-workstation-pkglist</replaceable></userinput></screen>

      <para>While running, pressing <keycombo
	  action="simul"><keycap>Ctrl</keycap><keycap>t</keycap></keycombo>
	displays the current state of the build.
	<application>Poudriere</application> also builds files in
	<filename>/poudriere/logs/bulk/<replaceable>jailname</replaceable></filename>
	that can be used with a web server to display build
	information.</para>

      <para>After completion, the new packages are now available for
	installation from the <application>poudriere</application>
	repository.</para>

      <para>For more information on using
	<application>poudriere</application>, see &man.poudriere.8;
	and the main web site, <link
	  xlink:href="https://github.com/freebsd/poudriere/wiki"></link>.</para>
    </sect2>
    <sect2>
      <title>Configuring pkg Clients to Use a Poudriere
	Repository</title>

      <para>While it is possible to use both a custom repository along
	side of the official repository, sometimes it is useful to
	disable the official repository.  This is done by creating a
	configuration file that overrides and disables the official
	configuration file.  Create
	<filename>/usr/local/etc/pkg/repos/FreeBSD.conf</filename>
	that contains the following:</para>

      <programlisting>FreeBSD: {
	enabled: no
}</programlisting>

      <para>Usually it is easiest to serve a poudriere repository to
	the client machines via HTTP.  Set up a webserver to serve up
	the package directory, for instance:
	<filename>/usr/local/poudriere/data/packages/<replaceable>10amd64</replaceable></filename>,
	where <filename><replaceable>10amd64</replaceable></filename>
	is the name of the build.</para>

      <para>If the URL to the package repository is:
	<literal>http://pkg.example.com/10amd64</literal>, then the
	repository configuration file in
	<filename>/usr/local/etc/pkg/repos/custom.conf</filename>
	would look like:</para>

      <programlisting>custom: {
	url: "<replaceable>http://pkg.example.com/10amd64</replaceable>",
	enabled: yes,
}</programlisting>
    </sect2>
  </sect1>

  <sect1 xml:id="ports-nextsteps">
    <title>Post-Installation Considerations</title>

    <para>Regardless of whether the software was installed from a
      binary package or port, most third-party applications require
      some level of configuration after installation.  The following
      commands and locations can be used to help determine what was
      installed with the application.</para>

    <itemizedlist>
      <listitem>
	<para>Most applications install at least one default
	  configuration file in <filename>/usr/local/etc</filename>.
	  In cases where an application has a large number of
	  configuration files, a subdirectory will be created to hold
	  them.  Often, sample configuration files are installed which
	  end with a suffix such as <filename>.sample</filename>.  The
	  configuration files should be reviewed and possibly
	  edited to meet the system's needs.  To edit a sample file,
	  first copy it without the <filename>.sample</filename>
	  extension.</para>
      </listitem>

      <listitem>
	<para>Applications which provide documentation will install
	  it into <filename>/usr/local/share/doc</filename> and many
	  applications also install manual pages.  This documentation
	  should be consulted before continuing.</para>
      </listitem>

      <listitem>
	<para>Some applications run services which must be added
	  to <filename>/etc/rc.conf</filename> before starting the
	  application.  These applications usually install a startup
	  script in <filename>/usr/local/etc/rc.d</filename>.  See
	  <link linkend="configtuning-starting-services">Starting
	    Services</link> for more information.</para>

	<note>
	  <para>By design, applications do not run their startup
	    script upon installation, nor do they run their stop
	    script upon deinstallation or upgrade.  This decision
	    is left to the individual system administrator.</para>
	</note>

      </listitem>

      <listitem>
	<para>Users of &man.csh.1; should run
	  <command>rehash</command> to rebuild the known binary list
	  in the shells <envar>PATH</envar>.</para>
      </listitem>

      <listitem>
	<para>Use <command>pkg info</command> to determine which
	  files, man pages, and binaries were installed with the
	  application.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="ports-broken">
    <title>Dealing with Broken Ports</title>

    <para>When a port does not build or
      install, try the following:</para>

    <orderedlist>
      <listitem>
	<para>Search to see if there is a fix pending for the port in
	  the <link xlink:href="&url.base;/support.html">Problem
	    Report database</link>.  If so, implementing the proposed
	  fix may fix the issue.</para>
      </listitem>

      <listitem>
	<para>Ask the maintainer of the port for help.  Type
	  <command>make maintainer</command>
	  in the ports skeleton or read the port's
	  <filename>Makefile</filename> to find the maintainer's
	  email address.  Remember to include the
	  <literal>&dollar;FreeBSD:</literal> line from the port's
	  <filename>Makefile</filename> and the output leading up to
	  the error in the email to the maintainer.</para>

	<note>
	  <para>Some ports are not maintained by an individual but
	    instead by a group maintainer represented by a <link
	      xlink:href="&url.articles.mailing-list-faq;/article.html">mailing
	      list</link>.  Many, but not all, of these addresses look
	    like <email
	      role="nolink">freebsd-<replaceable>listname</replaceable>@FreeBSD.org</email>.
	    Please take this into account when sending an email.</para>

	  <para>In particular, ports maintained by
	    <email role="nolink">ports@FreeBSD.org</email> are not
	    maintained by a specific individual.  Instead, any fixes
	    and support come from the general community who subscribe
	    to that mailing list.  More volunteers are always
	    needed!</para>
	</note>

	<para>If there is no response to the email, use
	  Bugzilla to submit a bug report using the
	  instructions in <link
	    xlink:href="&url.articles.problem-reports;/article.html">Writing
	    &os; Problem Reports</link>.</para>
      </listitem>

      <listitem>
	<para>Fix it!  The <link
	    xlink:href="&url.books.porters-handbook;/index.html">Porter's
	    Handbook</link> includes detailed information on the
	  ports infrastructure so that you can fix the occasional
	  broken port or even submit your own!</para>
      </listitem>

      <listitem>
	<para>Install the package instead of the port using the
	  instructions in <xref linkend="pkgng-intro"/>.</para>
      </listitem>
    </orderedlist>
  </sect1>
</chapter>