aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
blob: 44cccea95195aa80ced1bf2b6873520d5029afca (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
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="ports">
  <title>Installing Applications: Packages and Ports</title>

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

    <indexterm><primary>ports</primary></indexterm>
    <indexterm><primary>packages</primary></indexterm>
    <para>FreeBSD is bundled with a rich collection of system tools as
      part of the base system.  However, there is only so much one can
      do before needing to install an additional third-party
      application to get real work done.  FreeBSD provides two
      complementary technologies for installing third-party software
      on your system: the FreeBSD Ports Collection (for installing from
      source), and packages (for installing from pre-built binaries).
      Either method may be used to install the
      newest version of your favorite applications from local media or
      straight off the network.</para>

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

    <itemizedlist>
      <listitem>
	<para>How to install third-party binary software packages.</para>
      </listitem>
      <listitem>
	<para>How to build third-party software from source by using the ports
	collection.</para>
      </listitem>
      <listitem>
	<para>How to remove previously installed packages or ports.</para>
      </listitem>
      <listitem>
	<para>How to override the default values that the ports
	  collection uses.</para>
      </listitem>
      <listitem>
	<para>How to find the appropriate software package.</para>
      </listitem>
      <listitem>
	<para>How to upgrade your applications.</para>
      </listitem>
    </itemizedlist>
  </sect1>

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

    <para>If you have used a &unix; system before you will know that
      the typical procedure for installing third-party software goes
      something like this:</para>

    <procedure>
      <step>
	<para>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
	  (typically a tarball compressed with &man.compress.1;,
	  &man.gzip.1;, or &man.bzip2.1;).</para>
      </step>

      <step>
	<para>Locate the documentation (perhaps an
	  <filename>INSTALL</filename> or <filename>README</filename>
	  file, or some files 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, and other work.</para>
      </step>

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

    <para>And that is only if everything goes well.  If you are
      installing a software package that was not deliberately ported
      to FreeBSD you may even have to go in and edit the code to make
      it work properly.</para>

    <para>Should you want to, you can continue to install software the
      <quote>traditional</quote> way with FreeBSD.  However, FreeBSD
      provides two technologies which can save you a lot of effort:
      packages and ports.  At the time of writing, over &os.numports;
      third-party applications have been made available in this
      way.</para>

    <para>For any given application, the FreeBSD package for that
      application is a single file which you must download.  The
      package contains pre-compiled copies of all the commands for the
      application, as well as any configuration files or
      documentation.  A downloaded package file can be manipulated
      with FreeBSD package management commands, such as
      &man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so
      on.  Installing a new application can be carried out with a
      single command.</para>

    <para>A FreeBSD port for an application is a collection of files
      designed to automate the process of compiling an application
      from source code.</para>

    <para>Remember that there are a number of steps you would normally
      carry out if you compiled a program yourself (downloading,
      unpacking, patching, compiling, installing).  The files that
      make up a port contain all the necessary information to allow
      the system to do this for you.  You run a handful of simple
      commands and the source code for the application is
      automatically downloaded, extracted, patched, compiled, and
      installed for you.</para>

    <para>In fact, the ports system can also be used to generate packages
      which can later be manipulated with <command>pkg_add</command>
      and the other package management commands that will be introduced
      shortly.</para>

    <para>Both packages and ports understand
      <emphasis>dependencies</emphasis>.  Suppose you want to install
      an application that depends on a specific library being
      installed.  Both the application and the library have been made
      available as FreeBSD ports and packages.  If you use the
      <command>pkg_add</command> command or the ports system to add
      the application, both will notice that the library has not been
      installed, and automatically install the library first.</para>

    <para>Given that the two technologies are quite similar, you might
      be wondering why FreeBSD bothers with both.  Packages and ports
      both have their own strengths, and which one you use will depend
      on your own preference.</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 any additional compilation.  For
	  large applications, such as
	  <application>Mozilla</application>,
	  <application>KDE</application>, or
	  <application>GNOME</application> this can be important,
	  particularly if you are on a slow system.</para>
      </listitem>

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

    <itemizedlist>
      <title>Ports Benefits</title>

      <listitem>
	<para>Packages are normally compiled with conservative options,
	  because they have to run on the maximum number of systems.  By
	  installing from the port, you can tweak the compilation options to
	  (for example) generate code that is specific to a Pentium
	  4 or Athlon processor.</para>
      </listitem>

      <listitem>
	<para>Some applications have compile-time options relating to
	  what they can and cannot do.  For example,
	  <application>Apache</application> can be configured with a
	  wide variety of different built-in options.  By building
	  from the port you do not have to accept the default options,
	  and can set them yourself.</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 you have installed an X11 server.  This sort
	  of rough tweaking is possible with packages, but 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 distributions forbid
	  binary distribution.  They must be distributed as source
	  code.</para>
      </listitem>

      <listitem>
	<para>Some people do not trust binary distributions.  At least
	  with source code, you can (in theory) read through it and
	  look for potential problems yourself.</para>
      </listitem>

      <listitem>
	<para>If you have local patches, you will need the source in order to
	  apply them.</para>
      </listitem>

      <listitem>
	<para>Some people like having code around, so they can read it
	  if they get bored, hack it, borrow from it (license
	  permitting, of course), and so on.</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, you should check <ulink
	url="http://vuxml.freebsd.org/"></ulink> for security issues
	related to your application.</para>

      <para>You can also install <filename
	role="package">ports-mgmt/portaudit</filename> which will
	automatically check all installed applications for known
	vulnerabilities; a check will be also performed before any port
	build.  Meanwhile, you can use the command <command>portaudit
	-F -a</command> after you have installed some
	packages.</para>
    </warning>

    <para>The remainder of this chapter will explain how to use
      packages and ports to install and manage third-party software on
      FreeBSD.</para>
  </sect1>

  <sect1 id="ports-finding-applications">
    <title>Finding Your Application</title>

    <para>Before you can install any applications you need to know what you
      want, and what the application is called.</para>

    <para>FreeBSD's list of available applications is growing all the
      time.  Fortunately, there are a number of ways to find what you
      want:</para>

    <itemizedlist>
      <listitem>
	<para>The FreeBSD web site maintains an up-to-date searchable
	  list of all the available applications, at <ulink
	  url="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>.
	  The ports are divided into categories, and you may either
	  search for an application by name (if you know it), or see
	  all the applications available in a category.</para>
      </listitem>

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

      <listitem>
	<para>Dan Langille maintains FreshPorts, at <ulink
	  url="http://www.FreshPorts.org/"></ulink>.  FreshPorts
	  tracks changes to the applications in the ports tree as they
	  happen, allows you to <quote>watch</quote> one or more
	  ports, and can send you email when they are updated.</para>
      </listitem>

      <indexterm><primary>FreshMeat</primary></indexterm>

      <listitem>
	<para>If you do not know the name of the application you want,
	  try using a site like FreshMeat (<ulink
	  url="http://www.freshmeat.net/"></ulink>) to find an
	  application, then check back at the FreeBSD site to see if
	  the application has been ported yet.</para>
      </listitem>

      <listitem>
	<para>If you know the exact name of the port, but just need to
        find out which category it is in, you can use the
        &man.whereis.1; command.
	Simply type <command>whereis
        <replaceable>file</replaceable></command>, where
        <replaceable>file</replaceable> is the program you want to
        install.  If it is found on your system, you will be told
        where it is, as follows:</para>

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

      <para>This tells us that <command>lsof</command> (a system
	utility) can be found in the
	<filename>/usr/ports/sysutils/lsof</filename>
	directory.</para></listitem>

      <listitem>
	<para>Additionally, you can use a simple &man.echo.1; statement
	  to find where a port exists in the ports tree.  For
	  example:</para>

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

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

      <listitem>
	<para>Yet another way to find a particular port is by using the
        Ports Collection's built-in search mechanism.  To use the
        search feature, you will need to be in the
        <filename>/usr/ports</filename> directory.  Once in that
        directory, run <command>make <maketarget>search</maketarget>
        name=<replaceable>program-name</replaceable></command> where
        <replaceable>program-name</replaceable> is the name of the
        program you want to find.  For example, if you were looking
        for <command>lsof</command>:</para>

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

      <para>The part of the output you want to pay particular
        attention to is the <quote>Path:</quote> line, since that
        tells you where to find the port.  The other information
        provided is not needed in order to install the port, so it
        will not be covered here.</para>

      <para>For more in-depth searching you can also use <command>make
       <maketarget>search</maketarget> key=<replaceable>string</replaceable></command>
       where <replaceable>string</replaceable> is some text to search for.
       This searches port names, comments, descriptions and
       dependencies and can be used to find ports which relate to a
       particular subject if you do not know the name of the program
       you are looking for.</para>

      <para>In both of these cases, 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 id="packages-using">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Chern</firstname>
	  <surname>Lee</surname>
	  <contrib>Contributed by </contrib>
        </author>
      </authorgroup>
    <!-- 30 Mar 2001 -->
    </sect1info>

    <title>Using the Packages System</title>

    <para>There are several different tools used to manage packages on
      FreeBSD:</para>

    <itemizedlist>
      <listitem><para>The <command>sysinstall</command> utility can be invoked on a
        running system to install, delete, and list available and
        installed packages. For more information, see <xref
        linkend="packages">.</para></listitem>
      <listitem><para>The package management command line tools, which are
        the subject of the rest of this section.</para></listitem>
    </itemizedlist>

    <sect2>
      <title>Installing a Package</title>
      <indexterm>
        <primary>packages</primary>
        <secondary>installing</secondary>
      </indexterm>

      <indexterm>
        <primary><command>pkg_add</command></primary>
      </indexterm>
      <para>You can use the &man.pkg.add.1; utility to install a
	FreeBSD software package from a local file or from a server on
	the network.</para>

      <example>
        <title>Downloading a Package Manually and Installing It Locally</title>

        <screen>&prompt.root; <userinput>ftp -a <replaceable>ftp2.FreeBSD.org</replaceable></userinput>
Connected to ftp2.FreeBSD.org.
220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready.
331 Guest login ok, send your email address as password.
230-
230-     This machine is in Vienna, VA, USA, hosted by Verio.
230-         Questions? E-mail freebsd@vienna.verio.net.
230-
230-
230 Guest login ok, access restrictions apply.
Remote system type is UNIX.
Using binary mode to transfer files.
<prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/packages/sysutils/</userinput>
250 CWD command successful.
<prompt>ftp></prompt> <userinput>get lsof-4.56.4.tgz</userinput>
local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
200 PORT command successful.
150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
100% |**************************************************| 92375       00:00 ETA
226 Transfer complete.
92375 bytes received in 5.60 seconds (16.11 KB/s)
<prompt>ftp></prompt> <userinput>exit</userinput>
&prompt.root; <userinput>pkg_add <replaceable>lsof-4.56.4.tgz</replaceable></userinput></screen>
      </example>

      <para>If you do not have a source of local packages (such as a
        FreeBSD CD-ROM set) then it will probably be easier to use the
        <option>-r</option> option to &man.pkg.add.1;.  This will
        cause the utility to automatically determine the correct
        object format and release and then fetch and install the
        package from an FTP site.
      </para>

      <indexterm>
        <primary><command>pkg_add</command></primary></indexterm>
      <screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen>

      <para>The example above would download the correct package and
	add it without any further user intervention.
	If you want to specify an alternative &os; Packages Mirror,
	instead of the main distribution site, you have to set the
	<envar>PACKAGESITE</envar> environment variable accordingly, to
	override the default settings.  &man.pkg.add.1;
	uses &man.fetch.3; to download the files, which honors various
	environment variables, including
	<envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and
	<envar>FTP_PASSWORD</envar>.  You may need to set one or more
	of these if you are behind a firewall, or need to use an
	FTP/HTTP proxy.  See &man.fetch.3; for the complete list.
	Note that in the example above
	<literal>lsof</literal> is used instead of
	<literal>lsof-4.56.4</literal>.  When the remote fetching
	feature is used, the version number of the package must be
	removed.  &man.pkg.add.1; will automatically fetch the latest
	version of the application.</para>

      <note>
	<para>&man.pkg.add.1; will download the latest version of
	  your application if you are using &os.current; or
	  &os.stable;.  If you run a -RELEASE version, it will grab
	  the version of the package that was built with your
	  release.  It is possible to change this behavior by
	  overriding <envar>PACKAGESITE</envar>.
	  For example, if you run a &os;&nbsp;8.1-RELEASE
	  system, by default &man.pkg.add.1; will try to fetch
	  packages from
	  <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8.1-release/Latest/</literal>.
	  If you want to force &man.pkg.add.1; to download
	  &os;&nbsp;8-STABLE packages, set <envar>PACKAGESITE</envar>
	  to
	  <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8-stable/Latest/</literal>.
	</para>
      </note>

      <para>Package files are distributed in <filename>.tgz</filename>
          and <filename>.tbz</filename> formats.  You can find them at <ulink
          url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>,
          or on the FreeBSD CD-ROM distribution.  Every CD on the
          FreeBSD 4-CD set (and the PowerPak, etc.) contains packages
          in the <filename>/packages</filename> directory.  The layout
          of the packages is similar to that of the
          <filename>/usr/ports</filename> tree.  Each category has its
          own directory, and every package can be found within the
          <filename>All</filename> directory.
      </para>

      <para>The directory structure of the package system matches the
        ports layout; they work with each other to form the entire
        package/port system.
      </para>

    </sect2>

    <sect2>
      <title>Managing Packages</title>

      <indexterm>
        <primary>packages</primary>
        <secondary>managing</secondary>
      </indexterm>
      <para>&man.pkg.info.1; is a utility that lists and describes
        the various packages installed.
      </para>

      <indexterm>
        <primary><command>pkg_info</command></primary>
      </indexterm>
      <screen>&prompt.root; <userinput>pkg_info</userinput>
cvsup-16.1          A general network file distribution system optimized for CV
docbook-1.2         Meta-port for the different versions of the DocBook DTD
...</screen>
      <para>&man.pkg.version.1; is a utility that summarizes the
        versions of all installed packages.  It compares the package
        version to the current version found in the ports tree.
      </para>
      <indexterm>
        <primary><command>pkg_version</command></primary>
      </indexterm>
        <screen>&prompt.root; <userinput>pkg_version</userinput>
cvsup                       =
docbook                     =
...</screen>

      <para>The symbols in the second column indicate the relative age
        of the installed version and the version available in the
        local ports tree.</para>

      <informaltable frame="none" pgwide="1">
        <tgroup cols="2">
	  <thead>
            <row>
              <entry>Symbol</entry>
              <entry>Meaning</entry>
            </row>
          </thead>

 	  <tbody>
  	    <row>
	    <entry>=</entry> <entry>The version of the
	    installed package matches the one found in the
	    local ports tree.</entry>
  	    </row>

        <row><entry>&lt;</entry>
	<entry>The installed version is older than the one available
	in the ports tree.</entry>
	</row>

        <row><entry>&gt;</entry><entry>The installed version is newer
          than the one found in the local ports tree. (The local ports
          tree is probably out of date.)</entry></row>

        <row><entry>?</entry><entry>The installed package cannot be
	  found in the ports index.  (This can happen, for instance, if an
	  installed port is removed from the Ports Collection or
	  renamed.)</entry></row>

        <row><entry>*</entry><entry>There are multiple versions of the
        package.</entry></row>

        <row><entry>!</entry><entry>The installed package exists in the
        index but for some reason, <command>pkg_version</command> was
        unable to compare the version number of the installed package
        with the corresponding entry in the index.</entry></row>

	</tbody>
	</tgroup>
    </informaltable>
    </sect2>

    <sect2>
      <title>Deleting a Package</title>
      <indexterm>
        <primary><command>pkg_delete</command></primary>
      </indexterm>
      <indexterm>
        <primary>packages</primary>
        <secondary>deleting</secondary>
      </indexterm>
      <para>To remove a previously installed software package, use the
	&man.pkg.delete.1; utility.
      </para>

      <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>

      <para>Note that &man.pkg.delete.1; requires the full package
	name and number; the above command would not work if
	<replaceable>xchat</replaceable> was given instead of
	<replaceable>xchat-1.7.1</replaceable>.  It is, however, easy
	to use &man.pkg.version.1; to find the version of the
	installed package.  You could instead simply use a wildcard:</para>

      <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat\*</replaceable></userinput></screen>

      <para>in this case, all packages whose names start with
	<literal>xchat</literal> will be deleted.</para>
    </sect2>

    <sect2>
      <title>Miscellaneous</title>
      <para>All package information is stored within the
        <filename>/var/db/pkg</filename> directory.  The installed
	file list and descriptions of each package can be found within
        files in this directory.
      </para>
    </sect2>
  </sect1>

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

    <para>The following sections provide basic instructions on using the
      Ports Collection to install or remove programs from your
      system.  The detailed description of available <command>make</command>
      targets and environment variables is available in &man.ports.7;.</para>

    <sect2 id="ports-tree">
      <title>Obtaining the Ports Collection</title>

      <para>Before you can install ports, you must first obtain the
	Ports Collection&mdash;which is essentially a set of
	<filename>Makefiles</filename>, patches, and description files
	placed in <filename>/usr/ports</filename>.
      </para>

      <para>When installing your FreeBSD system,
	<application>sysinstall</application> asked if you would like
	to install the Ports Collection.  If you chose no, you can
	follow these instructions to obtain the ports
	collection:</para>

      <procedure>
	<title>CVSup Method</title>

	<para>This is a quick method for getting and keeping your copy of the
	  Ports Collection up to date using <application>CVSup</application>
	  protocol.  If you want to learn more about
	  <application>CVSup</application>, see <link
	    linkend="cvsup">Using CVSup</link>.</para>

	<note>
	  <para>The implementation of <application>CVSup</application> protocol
	    included with the &os; system is called
	    <application>csup</application>.</para>
	</note>

	<para>Make sure <filename class="directory">/usr/ports</filename>
	  is empty before you run <application>csup</application> for
	  the first time!  If you already have the Ports Collection present,
	  obtained from another source, <application>csup</application>
	  will not prune removed patch files.</para>

	<step>
	  <para>Run <command>csup</command>:</para>

	  <screen>&prompt.root; <userinput>csup -L 2 -h <replaceable>cvsup.FreeBSD.org</replaceable> /usr/share/examples/cvsup/ports-supfile</userinput></screen>

	  <para>Change
	    <replaceable>cvsup.FreeBSD.org</replaceable> to a
	    <application>CVSup</application> server near you.  See
	    <link linkend="cvsup-mirrors">CVSup Mirrors</link> (<xref
	    linkend="cvsup-mirrors">) for a complete listing of mirror
	    sites.</para>

	  <note>
	    <para>One may want to use his own
	      <filename>ports-supfile</filename>, for example to avoid
	      the need of passing the <application>CVSup</application>
	      server on the command line.</para>

	    <procedure>
	      <step>
		<para>In this case, as <username>root</username>, copy
		  <filename>/usr/share/examples/cvsup/ports-supfile</filename>
		  to a new location, such as
		  <filename>/root</filename> or your home
		  directory.</para>
	      </step>

	      <step>
		<para>Edit <filename>ports-supfile</filename>.</para>
	      </step>

	      <step>
		<para>Change
		  <replaceable>CHANGE_THIS.FreeBSD.org</replaceable>
		  to a <application>CVSup</application> server near
		  you.  See <link linkend="cvsup-mirrors">CVSup
		  Mirrors</link> (<xref linkend="cvsup-mirrors">) for
		  a complete listing of mirror sites.</para>
	      </step>

	      <step>
		<para>And now to run <command>csup</command>, use the
		  following:</para>

		<screen>&prompt.root; <userinput>csup -L 2 <replaceable>/root/ports-supfile</replaceable></userinput></screen>
	      </step>
	    </procedure>
	  </note>
	</step>

	<step>
	  <para>Running the &man.csup.1; command later will download and apply
	    all the recent changes to your Ports Collection, except
	    actually rebuilding the ports for your own system.</para>
	</step>
      </procedure>

      <procedure>
	<title>Portsnap Method</title>

	<para><application>Portsnap</application> is an alternative system for
	  distributing the Ports Collection.
	  Please refer to <link linkend="updating-upgrading-portsnap">Using Portsnap</link>
	  for a detailed description of all <application>Portsnap</application>
	  features.</para>

	<step>
	  <para>Download a compressed snapshot of the Ports Collection into
	    <filename class="directory">/var/db/portsnap</filename>.  You can
	    disconnect from the Internet after this step, if you wish.</para>

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

	<step>
	  <para>If you are running <application>Portsnap</application> for the
	    first time, extract the snapshot into <filename
	    class="directory">/usr/ports</filename>:
	  </para>

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

	  <para>If you already have a populated <filename
	    class="directory">/usr/ports</filename> and you are just updating,
	    run the following command instead:</para>

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

      </procedure>

      <procedure>
	<title>Sysinstall Method</title>

	<para>This method involves using <application>sysinstall</application>
	  to install the Ports Collection from the installation media.  Note
	  that the old copy of Ports Collection from the date of the release
	  will be installed.  If you have Internet access, you should always
	  use one of the methods mentioned above.</para>

	<step>
	  <para>As <username>root</username>, run
	    <command>sysinstall</command> as shown below:</para>

	  <screen>&prompt.root; <userinput>sysinstall</userinput></screen>
	</step>

	<step>
	  <para>Scroll down and select <guimenuitem>Configure</guimenuitem>,
	    press <keycap>Enter</keycap>.</para>
	</step>

	<step>
	  <para>Scroll down and select
	    <guimenuitem>Distributions</guimenuitem>, press
	    <keycap>Enter</keycap>.</para>
	</step>

	<step>
	  <para>Scroll down to <guimenuitem>ports</guimenuitem>, press
	    <keycap>Space</keycap>.</para>
	</step>

	<step>
	  <para>Scroll up to <guimenuitem>Exit</guimenuitem>, press
	    <keycap>Enter</keycap>.</para>
	</step>

	<step>
	  <para>Select your desired installation media, such as CDROM,
	    FTP, and so on.</para>
	</step>

	<step>
	  <para>Scroll up to <guimenuitem>Exit</guimenuitem> and press
	    <keycap>Enter</keycap>.</para>
	</step>

	<step>
	  <para>Press <keycap>X</keycap> to exit
	    <application>sysinstall</application>.</para>
	</step>
      </procedure>
    </sect2>

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

      <indexterm>
        <primary>ports</primary>
        <secondary>installing</secondary>
      </indexterm>
      <para>The first thing that should be explained when it comes to
        the Ports Collection is what is actually meant by a
        <quote>skeleton</quote>.  In a nutshell, a port skeleton is a
        minimal set of files that tell your FreeBSD system how to
        cleanly compile and install a program.  Each port skeleton
        includes:</para>

      <itemizedlist>
	<listitem>
	  <para>A <filename>Makefile</filename>.  The
	    <filename>Makefile</filename> contains various statements
	    that specify how the application should be compiled and
	    where it should be installed on your system.</para>
	</listitem>

	<listitem>
	  <para>A <filename>distinfo</filename> file.  This file
	    contains information about the files that must be
	    downloaded to build the port, and their checksums
	    (using &man.sha256.1;), to
	    verify that files have not been corrupted during the
	    download.</para>
	</listitem>

	<listitem>
	  <para>A <filename>files</filename> directory.  This
	    directory contains patches to make the program compile and
	    install on your FreeBSD system.  Patches are basically
	    small files that specify changes to particular files.
	    They are in plain text format, and basically say
	    <quote>Remove line 10</quote> or <quote>Change line 26 to
	    this ...</quote>.  Patches are also known as
	    <quote>diffs</quote> because they are generated by the
	    &man.diff.1; program.</para>

	  <para>This directory may also contain other files used to build
	    the port.</para>
	</listitem>

	<listitem>
	  <para>A <filename>pkg-descr</filename> file.  This is a more
	    detailed, often multiple-line, description of the program.</para>
	</listitem>

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

      <para>Some ports have other files, such as
        <filename>pkg-message</filename>.  The ports system uses these
        files to handle special situations.  If you want more details
        on these files, and on ports in general, check out the <ulink
        url="&url.books.porters-handbook;/index.html">FreeBSD Porter's
        Handbook</ulink>.</para>

      <para>The port includes instructions on how to build source
        code, but does not include the actual source code.  You can
        get the source code from a CD-ROM or from the Internet.
        Source code is distributed in whatever manner the software
        author desires.  Frequently this is a tarred and gzipped file,
        but it might be compressed with some other tool or even
        uncompressed.  The program source code, whatever form it comes
        in, is called a <quote>distfile</quote>.  The two methods for
        installing a &os; port are described below.</para>

      <note>
        <para>You must be logged in as <username>root</username> to
          install ports.</para>
      </note>

      <warning>
	<para>Before installing any port, you should be sure to have
	  an up-to-date Ports Collection and you should check <ulink
	  url="http://vuxml.freebsd.org/"></ulink> for security issues
	  related to your port.</para>

	<para>A security vulnerabilities check can be automatically
	  done by <application>portaudit</application> before any new
	  application installation.  This tool can be found in the
	  Ports Collection (<filename
	  role="package">ports-mgmt/portaudit</filename>).  Consider
	  running <command>portaudit -F</command> before installing a
	  new port, to fetch the current vulnerabilities database.  A
	  security audit and an update of the database will be
	  performed during the daily security system check.  For more
	  information read the &man.portaudit.1; and &man.periodic.8;
	  manual pages.</para>
      </warning>

      <para>The Ports Collection makes an assumption that you have a working
	Internet connection.  If you do not, you will need to put a copy of the
	distfile into <filename>/usr/ports/distfiles</filename>
	manually.</para>

	<para>To begin, change to the directory for the port you want to
	  install:</para>

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

        <para>Once inside the <filename>lsof</filename> directory, you
	  will see the port skeleton.  The next step is to compile, or
	  <quote>build</quote>, the port.  This is done by simply
	  typing <command>make</command> at the prompt.  Once you have
	  done so, you should see something like this:</para>

        <screen>&prompt.root; <userinput>make</userinput>
&gt;&gt; lsof_4.57D.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.57
...
[extraction output snipped]
...
&gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
===&gt;  Patching for lsof-4.57
===&gt;  Applying FreeBSD patches for lsof-4.57
===&gt;  Configuring for lsof-4.57
...
[configure output snipped]
...
===&gt;  Building for lsof-4.57
...
[compilation output snipped]
...
&prompt.root;</screen>

        <para>Notice that once the compile is complete you are
	  returned to your prompt.  The next step is to install the
	  port.  In order to install it, you simply need to tack one word
	  onto the <command>make</command> command, and that word is
	  <maketarget>install</maketarget>:</para>

        <screen>&prompt.root; <userinput>make install</userinput>
===&gt;  Installing for lsof-4.57
...
[installation output snipped]
...
===&gt;   Generating temporary packing list
===&gt;   Compressing manual pages for lsof-4.57
===&gt;   Registering installation for lsof-4.57
===&gt;  SECURITY NOTE:
      This port has installed the following binaries which execute with
      increased privileges.
&prompt.root;</screen>

        <para>Once you are returned to your prompt, you should be able to
          run the application you just installed.  Since
	  <command>lsof</command> is a
	  program that runs with increased privileges, a security
	  warning is shown.  During the building and installation of
	  ports, you should take heed of any other warnings that
	  may appear.</para>

	<para>It is a good idea to delete the working subdirectory,
	  which contains all the temporary files used during compilation.
	  Not only does it consume valuable disk space, but it would also
	  cause problems later when upgrading to the newer version of the
	  port.</para>

	<screen>&prompt.root; <userinput>make clean</userinput>
===&gt;  Cleaning for lsof-4.57
&prompt.root;</screen>

        <note>
          <para>You can save two extra steps by just running <command>make
	    <maketarget>install clean</maketarget></command> instead of
	    <command>make</command>,
	    <command>make <maketarget>install</maketarget></command> and
	    <command>make <maketarget>clean</maketarget></command>
	    as three separate steps.</para>
	</note>

	<note>
	  <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.  If you are using one of these shells, you might
	    have to use the <command>rehash</command> command after
	    installing a port, before the newly installed commands can
	    be used.  This command will work for shells like
	    <command>tcsh</command>.  Use the <command>hash -r</command>
	    command for shells like <command>sh</command>.  Look at the
	    documentation for your shell for more information.</para>
	</note>

	<para>Some third-party DVD-ROM products such as the FreeBSD Toolkit
	  from the <ulink url="http://www.freebsdmall.com/">FreeBSD
	  Mall</ulink> contain distfiles.  They can be used with the Ports
	  Collection.  Mount the DVD-ROM on <filename>/cdrom</filename>.  If
	  you use a different mount point, set <makevar>CD_MOUNTPTS</makevar>
	  make variable.  The needed distfiles will be automatically used
	  if they are present on the disk.</para>

	<note>
	  <para>Please be aware that the licenses of a few ports do
	    not allow for inclusion on the CD-ROM.  This could be
	    because a registration form needs to be filled out before
	    downloading or redistribution is not allowed, or for
	    another reason.  If you wish to install a port not
	    included on the CD-ROM, you will need to be online in
	    order to do so.</para>
	</note>

	<para>The ports system uses &man.fetch.1; to download the
	  files, which honors various environment variables, including
	  <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>,
	  and <envar>FTP_PASSWORD</envar>.  You may need to set one or
	  more of these if you are behind a firewall, or need to use
	  an FTP/HTTP proxy.  See &man.fetch.3; for the complete
	  list.</para>

	<para>For users which cannot be connected all the time, the
	  <command>make <maketarget>fetch</maketarget></command> option is
	  provided.  Just run this command at the top level directory
	  (<filename>/usr/ports</filename>) and the required files
	  will be downloaded for you.  This command will also work in
	  the lower level categories, for example:
	  <filename>/usr/ports/net</filename>.
	  Note that if a port depends on libraries or other ports this will
	  <emphasis>not</emphasis> fetch the distfiles of those ports too.
	  Replace <maketarget>fetch</maketarget> with
	  <maketarget>fetch-recursive</maketarget>
	  if you want to fetch all the dependencies of a port too.</para>

	<note><para>You can build all the ports in a category or as a
	  whole by running <command>make</command> in the top level
	  directory, just like the aforementioned <command>make
	  <maketarget>fetch</maketarget></command> method.  This is
	  dangerous, however, as some ports cannot co-exist.  In other
	  cases, some ports can install two different files with the
	  same filename.</para></note>

	<para>In some rare cases, users may need to acquire the
	  tarballs from a site other than the
	  <makevar>MASTER_SITES</makevar> (the location where files
	  are downloaded from).  You can override the
	  <makevar>MASTER_SITES</makevar> option with the following
	  command:</para>

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

	<para>In this example we change the
	  <makevar>MASTER_SITES</makevar> option to <hostid
	  role="fqdn">ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</hostid>.</para>

	<note><para>Some ports allow (or even require) you to provide
	  build options which can enable/disable parts of the
	  application which are unneeded, certain security options,
	  and other customizations.  A few which come to mind are
	  <filename role="package">www/firefox</filename>, <filename
	  role="package">security/gpgme</filename>, and <filename
	  role="package">mail/sylpheed-claws</filename>.  A message
	  will be displayed when options such as these are
	  available.</para></note>

      <sect3>
        <title>Overriding the Default Ports Directories</title>

	<para>Sometimes it is useful (or mandatory) to use a different
	  working and target directory.  The
	  <makevar>WRKDIRPREFIX</makevar> and <makevar>PREFIX</makevar>
	  variables can override the default 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 it in <filename>/usr/ports</filename> and
	  install it in
	  <filename>/usr/home/example/local</filename>.</para>

	<para>And of course,</para>

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

	<para>will combine the two (it is too long to completely write
	  on this page, but it should give you the general
	  idea).</para>

	<para>Alternatively, these variables can also be set as part
	  of your environment.  Read the manual page for your shell
	  for instructions on doing so.</para>
      </sect3>

      <sect3>
	<title>Dealing with <command>imake</command></title>

	<para>Some ports that use <command>imake</command> (a part of
	  the X Window System) do not work well with
	  <makevar>PREFIX</makevar>, and will insist on installing
	  under <filename>/usr/X11R6</filename>.  Similarly, some Perl
	  ports ignore <makevar>PREFIX</makevar> and install in the
	  Perl tree.  Making these ports respect
	  <makevar>PREFIX</makevar> is a difficult or impossible
	  job.</para>

      </sect3>

      <sect3>
	<title>Reconfiguring Ports</title>

	<para>When building certain ports, you may be presented with a
	  ncurses-based menu from which you can select certain build options.
	  It is not uncommon for users to wish to revisit this menu to add,
	  remove, or change these options after a port has been built.  There
	  are many ways to do this.  One option is to go into the directory
	  containing the port and type <command>make
	  <maketarget>config</maketarget></command>, which will simply present
	  the menu again with the same options selected.  Another option is to
	  use <command>make <maketarget>showconfig</maketarget></command>,
	  which will show you all the configuration options for the port.  Yet
	  another option is to execute <command>make
	  <maketarget>rmconfig</maketarget></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 the manual page for
	  &man.ports.7;.</para>
      </sect3>
    </sect2>

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

      <indexterm>
        <primary>ports</primary>
        <secondary>removing</secondary>
      </indexterm>
      <para>Now that you know how to install ports, you are probably
        wondering how to remove them, just in case you install one and
	later on decide that you installed the wrong port.
        We will remove our previous example (which was
	<command>lsof</command> for
	those of you not paying attention).  Ports are being removed exactly
	the same as the packages (discussed in the <link
	linkend="packages-using">Packages section</link>), using the
	&man.pkg.delete.1; command:</para>

      <screen>&prompt.root; <userinput>pkg_delete lsof-4.57</userinput></screen>

    </sect2>

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

      <indexterm>
	<primary>ports</primary>
	<secondary>upgrading</secondary>
      </indexterm>
      <para>First, list outdated ports that have a newer version available in
	the Ports Collection with the &man.pkg.version.1; command:</para>

      <screen>&prompt.root; <userinput>pkg_version -v</userinput></screen>

      <sect3 id="ports-file-updating">
	<title><filename>/usr/ports/UPDATING</filename></title>

	<para>Once you have updated your Ports Collection, before
	  attempting a port upgrade, you should check
	  <filename>/usr/ports/UPDATING</filename>.  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 other such incompatibilities with
	  previous versions.</para>

	<para>If <filename>UPDATING</filename> contradicts something you
	  read here, <filename>UPDATING</filename> takes precedence.</para>
      </sect3>

      <sect3 id="portupgrade">
	<title>Upgrading Ports using Portupgrade</title>

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

      <para>The <application>portupgrade</application> utility is designed
	to easily upgrade installed ports.  It is available from the <filename
	role="package">ports-mgmt/portupgrade</filename> port.  Install it like
	any other port, using the <command>make <maketarget>install
	clean</maketarget></command> command:</para>

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

      <para>Scan the list of installed ports with the <command>pkgdb
	-F</command> command and fix all the inconsistencies it reports.  It is
	a good idea to do this regularly, before every upgrade.</para>

      <para>When you run <command>portupgrade -a</command>,
	<application>portupgrade</application> will begin to upgrade all the
	outdated ports installed on your system.  Use the <option>-i</option>
	flag if you want to be asked for confirmation of every individual
	upgrade.</para>

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

      <para>If you want to upgrade only a
	certain application, not all available ports, use <command>portupgrade
	<replaceable>pkgname</replaceable></command>.  Include the
	<option>-R</option> flag if <application>portupgrade</application>
	should first upgrade all the ports required by the given
	application.</para>

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

      <para>To use packages instead of ports for installation, provide
	<option>-P</option> flag.  With this option
	<application>portupgrade</application> searches
	the local directories listed in <envar>PKG_PATH</envar>, or
	fetches packages from remote site if it is not found locally.
	If packages can not be found locally or fetched remotely,
	<application>portupgrade</application> will use ports.
	To avoid using ports, specify <option>-PP</option>.</para>

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

      <para>To just fetch distfiles (or packages, if
	<option>-P</option> is specified) without building or
	installing anything, use <option>-F</option>.
	For further information see &man.portupgrade.1;.</para>
      </sect3>

      <sect3 id="portmanager">
	<title>Upgrading Ports using Portmanager</title>

	<indexterm>
	  <primary>portmanager</primary>
	</indexterm>

	<para><application>Portmanager</application> is another utility for
	  easy upgrading of installed ports.  It is available from the
	  <filename role="package">ports-mgmt/portmanager</filename>
	  port:</para>

	<screen>&prompt.root; <userinput>cd <filename class="directory">/usr/ports/ports-mgmt/portmanager</filename></userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

	<para>All the installed ports can be upgraded using this simple
	  command:</para>

	<screen>&prompt.root; <userinput>portmanager -u</userinput></screen>

	<para>You can add the <option>-ui</option> flag to get asked for
	  confirmation of every step <application>Portmanager</application>
	  will perform.  <application>Portmanager</application> can also be
	  used to install new ports on the system.  Unlike the usual
	  <command>make <maketarget>install clean</maketarget></command>
	  command, it will upgrade all the dependencies prior to building and
	  installing the selected port.</para>

	<screen>&prompt.root; <userinput>portmanager <replaceable>x11/gnome2</replaceable></userinput></screen>

	<para>If there are any problems regarding the dependencies for the
	  selected port, you can use <application>Portmanager</application> to
	  rebuild all of them in the correct order.  Once finished, the
	  problematic port will be rebuilt too.</para>

	<screen>&prompt.root; <userinput>portmanager <replaceable>graphics/gimp</replaceable> -f</userinput></screen>

	<para>For further information see &man.portmanager.1;.</para>
      </sect3>

      <sect3 id="portmaster">
	<title>Upgrading Ports using Portmaster</title>

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

	<para><application>Portmaster</application> is another utility for
	  upgrading installed ports.  <application>Portmaster</application>
	  was designed make use of the tools found in the <quote>base</quote>
	  system (it does not depend upon other ports) and uses the
	  information in <filename class="directory">/var/db/pkg/</filename>
	  to determine which ports to upgrade.  It is available from the
	  <filename role="package">ports-mgmt/portmaster</filename>
	  port:</para>

	<screen>&prompt.root; <userinput>cd <filename class="directory">/usr/ports/ports-mgmt/portmaster</filename></userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

	<para><application>Portmaster</application> groups ports into four
	  categories:</para>

	<itemizedlist>
	  <listitem>
	    <para>Root ports (no dependencies, not depended on)</para>
	    </listitem>
	  <listitem>
	    <para>Trunk ports (no dependencies, are depended on)</para>
	    </listitem>
	  <listitem>
	    <para>Branch ports (have dependencies, are depended on)</para>
	    </listitem>
	  <listitem>
	    <para>Leaf ports (have dependencies, not depended on)</para>
	    </listitem>
	</itemizedlist>

	<para>You can list all the installed ports and search
	  for updates using the <option>-L</option> option:</para>

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

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

	<para>All the installed ports can be upgraded using this simple
	  command:</para>

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

	<note><para>By default, <application>Portmaster</application>
	  will make a backup package before deleting the existing port.  If
	  the installation of the new version is successful,
	  <application>Portmaster</application> will delete the backup.
	  Using the <option>-b</option> will instruct
	  <application>Portmaster</application> not to automatically delete
	  the backup.  Adding the <option>-i</option> option will start
	  <application>Portmaster</application> in interactive mode, prompting
	  you before upgrading each port.</para></note>

	<para>If you encounter errors during the upgrade process, you can use
	  the <option>-f</option> option to upgrade/rebuild all ports:</para>

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

	<para>You can also use <application>Portmaster</application> to
	  install new ports on the system, upgrading all dependencies
	  before building and installing the new port:</para>

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

	<para>Please see &man.portmaster.8; for more information.</para>
      </sect3>
    </sect2>

    <sect2 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 software from the
	ports, you should always remember to clean up
	the temporary <filename class="directory">work</filename> directories
	using the <command>make	<maketarget>clean</maketarget></command>
	command.  You can sweep the whole Ports Collection with the following
	command:</para>

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

      <para>You will accumulate a lot of old source distribution files in the
	<filename class="directory">distfiles</filename> directory over time.
	You can remove them by hand, or you can use the following command to
	delete all the distfiles that are no longer referenced by any
	ports:</para>

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

      <para>Or to remove all distfiles not referenced by any port
	currently installed on your system:</para>

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

      <note>
	<para>The <command>portsclean</command> utility is part of the
	  <application>portupgrade</application> suite.</para>
      </note>

      <para>Do not forget to remove the installed ports once you no longer need
	them.  A nice tool to help automate this task is available from the
	<filename role="package">ports-mgmt/pkg_cutleaves</filename>
	port.</para>
    </sect2>

  </sect1>

  <sect1 id="ports-nextsteps">
    <title>Post-installation Activities</title>

    <para>After installing a new application you will normally want to
      read any documentation it may have included, edit any
      configuration files that are required, ensure that the
      application starts at boot time (if it is a daemon), and so
      on.</para>

    <para>The exact steps you need to take to configure each
      application will obviously be different.  However, if you have
      just installed a new application and are wondering <quote>What
      now?</quote> these tips might help:</para>

    <itemizedlist>
      <listitem>
	<para>Use &man.pkg.info.1; to find out which files were installed,
	  and where.  For example, if you have just
	  installed FooPackage version 1.0.0, then this command</para>

	<screen>&prompt.root; <userinput>pkg_info -L foopackage-1.0.0 | less</userinput></screen>

	<para>will show all the files installed by the package.  Pay
	  special attention to files in <filename>man/</filename>
	  directories, which will be manual pages,
	  <filename>etc/</filename> directories, which will be
	  configuration files, and <filename>doc/</filename>, which
	  will be more comprehensive documentation.</para>

	<para>If you are not sure which version of the application was
	  just installed, a command like this</para>

	<screen>&prompt.root; <userinput>pkg_info | grep -i <replaceable>foopackage</replaceable></userinput></screen>

	<para>will find all the installed packages that have
	  <replaceable>foopackage</replaceable> in the package name.
	  Replace <replaceable>foopackage</replaceable> in your
	  command line as necessary.</para>
      </listitem>

      <listitem>
	<para>Once you have identified where the application's manual
	  pages have been installed, review them using &man.man.1;.
	  Similarly, look over the sample configuration files, and any
	  additional documentation that may have been provided.</para>
      </listitem>

      <listitem>
	<para>If the application has a web site, check it for
	  additional documentation, frequently asked questions, and so
	  forth.  If you are not sure of the web site address it may
	  be listed in the output from</para>

	<screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen>

	<para>A <literal>WWW:</literal> line, if present, should provide a URL
	  for the application's web site.</para>
      </listitem>

      <listitem>
	<para>Ports that should start at boot (such as Internet
	  servers) will usually install a sample script in
	  <filename>/usr/local/etc/rc.d</filename>.  You should
	  review this script for correctness and edit or rename it if
	  needed.  See <link
	  linkend="configtuning-starting-services">Starting
	  Services</link> for more information.</para>
      </listitem>
    </itemizedlist>
  </sect1>

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

      <para>If you come across a port that does not work for you,
        there are a few things you can do, including:</para>

      <orderedlist>
	<listitem>
	  <para>Find out if there is a fix pending for the port in
	    the <ulink url="&url.base;/support.html#gnats">Problem Report
	    database</ulink>.  If so, you may be able to use the
	    proposed fix.</para>
	</listitem>

	<listitem>
	  <para>Ask the maintainer of the port for help.  Type
	    <command>make <maketarget>maintainer</maketarget></command> or read
	    the <filename>Makefile</filename> to find the maintainer's
	    email address.  Remember to include the name and version
	    of the port (send the <literal>&dollar;FreeBSD:</literal>
	    line from the <filename>Makefile</filename>) and the
	    output leading up to the error when you email the
	    maintainer.</para>

	  <note>
	    <para>Some ports are not maintained by an individual but
	      instead by a <ulink
	      url="&url.articles.mailing-list-faq;/article.html">mailing
	      list</ulink>.  Many, but not all, of these addresses look like
	      <email role="nolink">freebsd-listname@FreeBSD.org</email>.
	      Please take this into account when phrasing your
	      questions.</para>

	    <para>In particular, ports shown as maintained by
	      <email role="nolink">ports@FreeBSD.org</email> are
	      actually not maintained by anyone.  Fixes and support, if
	      any, come from the general community who subscribe to that
	      mailing list.  More volunteers are always needed!</para>
	  </note>

	  <para>If you do not get a response,
	    you can use &man.send-pr.1; to submit a bug
	    report (see <ulink
	    url="&url.articles.problem-reports;/article.html">Writing
	    FreeBSD Problem Reports</ulink>).</para>
	</listitem>

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

	<listitem>
	  <para>Grab the package from an FTP site near you.  The
	    <quote>master</quote> package collection is on <hostid
	    role="fqdn">ftp.FreeBSD.org</hostid> in the <ulink
	    url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">packages
	    directory</ulink>, but be sure to check your closer <link
	    linkend="mirrors-ftp">mirror sites</link>
	    <emphasis>first</emphasis>!  These are more likely to work
	    than trying to compile from source and are a lot faster as
	    well.  Use the &man.pkg.add.1; program to install the
	    package on your system.</para>
	</listitem>
      </orderedlist>
  </sect1>

</chapter>

<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->