5a646bd197a2014faa617452fc7e52e1b279c7a0
[dragonfly.git] / en / books / handbook / ports / chapter.sgml
1 <!--
2      The FreeBSD Documentation Project
3
4      $FreeBSD: doc/en_US.ISO8859-1/books/handbook/ports/chapter.sgml,v 1.218 2004/05/06 11:37:25 den Exp $
5      $DragonFly: doc/en/books/handbook/ports/Attic/chapter.sgml,v 1.1 2004/06/25 15:24:35 justin Exp $
6 -->
7
8 <chapter id="ports">
9   <title>Installing Applications: Packages and Ports</title>
10
11   <sect1 id="ports-synopsis">
12     <title>Synopsis</title>
13
14     <indexterm><primary>ports</primary></indexterm>
15     <indexterm><primary>packages</primary></indexterm>
16     <para>FreeBSD is bundled with a rich collection of system tools as
17       part of the base system.  However, there is only so much one can
18       do before needing to install an additional third-party
19       application to get real work done.  FreeBSD provides two
20       complementary technologies for installing third party software
21       on your system: the FreeBSD Ports Collection, and binary
22       software packages.  Either system may be used to install the
23       newest version of your favorite applications from local media or
24       straight off the network.</para>
25
26     <para>After reading this chapter, you will know:</para>
27
28     <itemizedlist>
29       <listitem>
30         <para>How to install third-party binary software packages.</para>
31       </listitem>
32       <listitem>
33         <para>How to build third-party software from the ports
34         collection.</para>
35       </listitem>
36       <listitem>
37         <para>How to remove previously installed packages or ports.</para>
38       </listitem>
39       <listitem>
40         <para>How to override the default values that the ports
41           collection uses.</para>
42       </listitem>
43       <listitem>
44         <para>How to upgrade your ports.</para>
45       </listitem>
46     </itemizedlist>
47   </sect1>
48
49   <sect1 id="ports-overview">
50     <title>Overview of Software Installation</title>
51
52     <para>If you have used a &unix; system before you will know that the typical
53       procedure for installing third party software goes something like
54       this:</para>
55
56     <procedure>
57       <step>
58         <para>Download the software, which might be distributed in source code
59           format, or as a binary.</para>
60       </step>
61
62       <step>
63         <para>Unpack the software from its distribution format (typically a
64           tarball compressed with &man.compress.1;, &man.gzip.1;, or &man.bzip2.1;).</para>
65       </step>
66
67       <step>
68         <para>Locate the documentation (perhaps an <filename>INSTALL</filename> or <filename>README</filename>
69           file, or some files in a <filename>doc/</filename> subdirectory) and
70           read up on how to install the software.</para>
71       </step>
72
73       <step>
74         <para>If the software was distributed in source format, compile it.
75           This may involve editing a <filename>Makefile</filename>, or
76           running a <command>configure</command> script, and other work.</para>
77       </step>
78
79       <step>
80         <para>Test and install the software.</para>
81       </step>
82     </procedure>
83
84     <para>And that is only if everything goes well.  If you are installing a
85       software package that was not deliberately ported to FreeBSD you may
86       even have to go in and edit the code to make it work properly.</para>
87
88     <para>Should you want to, you can continue to install software the
89       <quote>traditional</quote> way with FreeBSD.  However, FreeBSD
90       provides two technologies which can save you a lot of effort:
91       packages and ports.  At the time of writing, over &os.numports;
92       third party applications have been made available in this
93       way.</para>
94
95     <para>For any given application, the FreeBSD package for that
96       application is a single file which you must download.  The
97       package contains pre-compiled copies of all the commands for the
98       application, as well as any configuration files or
99       documentation.  A downloaded package file can be manipulated
100       with FreeBSD package management commands, such as
101       &man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so
102       on.  Installing a new application can be carried out with a single
103       command.</para>
104
105     <para>A FreeBSD port for an application is a collection of files
106       designed to automate the process of compiling an application
107       from source code.</para>
108
109     <para>Remember that there are a number of steps you would normally
110       carry out if you compiled a program yourself (downloading,
111       unpacking, patching, compiling, installing).  The files that
112       make up a port contain all the necessary information to allow
113       the system to do this for you.  You run a handful of simple
114       commands and the source code for the application is
115       automatically downloaded, extracted, patched, compiled, and
116       installed for you.</para>
117
118     <para>In fact, the ports system can also be used to generate packages
119       which can later be manipulated with <command>pkg_add</command>
120       and the other package management commands that will be introduced
121       shortly.</para>
122
123     <para>Both packages and ports understand
124       <emphasis>dependencies</emphasis>.  Suppose you want to install
125       an application that depends on a specific library being
126       installed.  Both the application and the library have been made
127       available as FreeBSD ports and packages.  If you use the
128       <command>pkg_add</command> command or the ports system to add
129       the application, both will notice that the library has not been
130       installed, and automatically install the library first.</para>
131
132     <para>Given that the two technologies are quite similar, you might
133       be wondering why FreeBSD bothers with both.  Packages and ports
134       both have their own strengths, and which one you use will depend
135       on your own preference.</para>
136
137     <itemizedlist>
138       <title>Package Benefits</title>
139       
140       <listitem>
141         <para>A compressed package tarball is typically smaller than
142           the compressed tarball containing the source code for the
143           application.</para>
144       </listitem>
145
146       <listitem>
147         <para>Packages do not require any additional compilation.  For
148           large applications, such as
149           <application>Mozilla</application>,
150           <application>KDE</application>, or
151           <application>GNOME</application> this can be important,
152           particularly if you are on a slow system.</para>
153       </listitem>
154
155       <listitem>
156         <para>Packages do not require any understanding of the process
157           involved in compiling software on FreeBSD.</para>
158       </listitem>
159     </itemizedlist>
160
161     <itemizedlist>
162       <title>Ports Benefits</title>
163       
164       <listitem>
165         <para>Packages are normally compiled with conservative options,
166           because they have to run on the maximum number of systems.  By
167           installing from the port, you can tweak the compilation options to
168           (for example) generate code that is specific to a Pentium
169           IV or Athlon processor.</para>
170       </listitem>
171
172       <listitem>
173         <para>Some applications have compile time options relating to
174           what they can and cannot do.  For example,
175           <application>Apache</application> can be configured with a
176           wide variety of different built-in options.  By building
177           from the port you do not have to accept the default options,
178           and can set them yourself.</para>
179
180         <para>In some cases, multiple packages will exist for the same
181           application to specify certain settings.  For example,
182           <application>Ghostscript</application> is available as a
183           <filename>ghostscript</filename> package and a
184           <filename>ghostscript-nox11</filename> package, depending on
185           whether or not you have installed an X11 server.  This sort
186           of rough tweaking is possible with packages, but rapidly
187           becomes impossible if an application has more than one or
188           two different compile time options.</para>
189       </listitem>
190
191       <listitem>
192         <para>The licensing conditions of some software distributions forbid
193           binary distribution.  They must be distributed as source
194           code.</para>
195       </listitem>
196
197       <listitem>
198         <para>Some people do not trust binary distributions.  At least
199           with source code, you can (in theory) read through it and
200           look for potential problems yourself.</para>
201       </listitem>
202
203       <listitem>
204         <para>If you have local patches, you will need the source in order to
205           apply them.</para>
206       </listitem>
207
208       <listitem>
209         <para>Some people like having code around, so they can read it
210           if they get bored, hack it, borrow from it (license
211           permitting, of course), and so on.</para>
212       </listitem>
213     </itemizedlist>
214
215     <para>To keep track of updated ports, subscribe to the
216       &a.ports; and the &a.ports-bugs;.</para>
217
218     <warning>
219       <para>Before installing any application, you should check <ulink
220         url="http://vuxml.freebsd.org/"></ulink> for security issues
221         related to your application.</para>
222
223       <para>You can also install <filename
224         role="package">security/portaudit</filename> which will
225         automatically check all installed applications for known
226         vulnerabilities, a check will be also performed before any port
227         build.  Meanwhile, you can use the command <command>portaudit
228         -F -a</command> after you have installed some
229         packages.</para>
230     </warning>
231
232     <para>The remainder of this chapter will explain how to use
233       packages and ports to install and manage third party software on
234       FreeBSD.</para>
235   </sect1>
236
237   <sect1 id="ports-finding-applications">
238     <title>Finding Your Application</title>
239
240     <para>Before you can install any applications you need to know what you
241       want, and what the application is called.</para>
242
243     <para>FreeBSD's list of available applications is growing all the
244       time.  Fortunately, there are a number of ways to find what you
245       want:</para>
246
247     <itemizedlist>
248       <listitem>
249         <para>The FreeBSD web site maintains an up-to-date searchable
250           list of all the available applications, at <ulink
251           url="&url.main;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>.
252           The ports are divided into categories, and you may either
253           search for an application by name (if you know it), or see
254           all the applications available in a category.</para>
255       </listitem>
256
257       <indexterm><primary>FreshPorts</primary></indexterm>
258
259       <listitem>
260         <para>Dan Langille maintains FreshPorts, at <ulink
261           url="http://www.FreshPorts.org/"></ulink>.  FreshPorts
262           tracks changes to the applications in the ports tree as they
263           happen, allows you to <quote>watch</quote> one or more
264           ports, and can send you email when they are updated.</para>
265       </listitem>
266
267       <indexterm><primary>FreshMeat</primary></indexterm>
268
269       <listitem>
270         <para>If you do not know the name of the application you want,
271           try using a site like FreshMeat (<ulink
272           url="http://www.freshmeat.net/"></ulink>) to find an
273           application, then check back at the FreeBSD site to see if
274           the application has been ported yet.</para>
275       </listitem>
276     </itemizedlist>
277   </sect1>
278
279   <sect1 id="packages-using">
280     <sect1info>    
281       <authorgroup>
282         <author>
283           <firstname>Chern</firstname>
284           <surname>Lee</surname>
285           <contrib>Contributed by </contrib>
286         </author>
287       </authorgroup>
288     <!-- 30 Mar 2001 -->
289     </sect1info>
290
291     <title>Using the Packages System</title>
292
293     <sect2>
294       <title>Installing a Package</title>
295       <indexterm>
296         <primary>packages</primary>
297         <secondary>installing</secondary>
298       </indexterm>
299     
300       <indexterm>
301         <primary><command>pkg_add</command></primary>
302       </indexterm>
303       <para>You can use the &man.pkg.add.1; utility to install a
304         FreeBSD software package from a local file or from a server on
305         the network.</para>
306
307       <example>
308         <title>Downloading a Package Manually and Installing It Locally</title>
309
310         <screen>&prompt.root; <userinput>ftp -a <replaceable>ftp2.FreeBSD.org</replaceable></userinput>
311 Connected to ftp2.FreeBSD.org.
312 220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready.
313 331 Guest login ok, send your email address as password.
314 230-
315 230-     This machine is in Vienna, VA, USA, hosted by Verio.
316 230-         Questions? E-mail freebsd@vienna.verio.net.
317 230-
318 230-
319 230 Guest login ok, access restrictions apply.
320 Remote system type is UNIX.
321 Using binary mode to transfer files.
322 <prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/packages/sysutils/</userinput>
323 250 CWD command successful.
324 <prompt>ftp></prompt> <userinput>get lsof-4.56.4.tgz</userinput>
325 local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
326 200 PORT command successful.
327 150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
328 100% |**************************************************| 92375       00:00 ETA
329 226 Transfer complete.
330 92375 bytes received in 5.60 seconds (16.11 KB/s)
331 <prompt>ftp></prompt> <userinput>exit</userinput>
332 &prompt.root; <userinput>pkg_add <replaceable>lsof-4.56.4.tgz</replaceable></userinput></screen>
333       </example>
334
335       <para>If you do not have a source of local packages (such as a
336         FreeBSD CD-ROM set) then it will probably be easier to use the
337         <option>-r</option> option to &man.pkg.add.1;.  This will
338         cause the utility to automatically determine the correct
339         object format and release and then fetch and install the
340         package from an FTP site.
341       </para>
342
343       <indexterm>
344         <primary><command>pkg_add</command></primary></indexterm>
345       <screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen>
346
347       <para>The example above would download the correct package and
348         add it without any further user intervention.
349         If you want to specify an alternative &os; Packages Mirror,
350         instead of the main distribution site, you have to set
351         <envar>PACKAGESITE</envar> accordingly, to
352         override the default settings.  &man.pkg.add.1;
353         uses &man.fetch.3; to download the files, which honors various
354         environment variables, including
355         <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and
356         <envar>FTP_PASSWORD</envar>.  You may need to set one or more
357         of these if you are behind a firewall, or need to use an
358         FTP/HTTP proxy.  See &man.fetch.3; for the complete list.
359         Note that in the example above
360         <literal>lsof</literal> is used instead of
361         <literal>lsof-4.56.4</literal>.  When the remote fetching
362         feature is used, the version number of the package must be
363         removed.  &man.pkg.add.1; will automatically fetch the latest
364         version of the application.</para>
365
366       <para>Package files are distributed in <filename>.tgz</filename>
367           and <filename>.tbz</filename> formats.  You can find them at <ulink
368           url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>,
369           or on the FreeBSD CD-ROM distribution.  Every CD on the
370           FreeBSD 4-CD set (and the PowerPak, etc.) contains packages
371           in the <filename>/packages</filename> directory.  The layout
372           of the packages is similar to that of the
373           <filename>/usr/ports</filename> tree.  Each category has its
374           own directory, and every package can be found within the
375           <filename>All</filename> directory.
376       </para>
377
378       <para>The directory structure of the package system matches the
379         ports layout; they work with each other to form the entire
380         package/port system.
381       </para>
382
383     </sect2>
384
385     <sect2>
386       <title>Managing Packages</title>
387
388       <indexterm>
389         <primary>packages</primary>
390         <secondary>managing</secondary>
391       </indexterm>
392       <para>&man.pkg.info.1; is a utility that lists and describes 
393         the various packages installed.
394       </para>
395
396       <indexterm>
397         <primary><command>pkg_info</command></primary>
398       </indexterm>
399       <screen>&prompt.root; <userinput>pkg_info</userinput>
400 cvsup-16.1          A general network file distribution system optimized for CV
401 docbook-1.2         Meta-port for the different versions of the DocBook DTD
402 ...</screen>
403       <para>&man.pkg.version.1; is a utility that summarizes the
404         versions of all installed packages.  It compares the package 
405         version to the current version found in the ports tree.
406       </para> 
407       <indexterm>
408         <primary><command>pkg_version</command></primary>
409       </indexterm>
410         <screen>&prompt.root; <userinput>pkg_version</userinput>
411 cvsup                       =
412 docbook                     =
413 ...</screen>
414
415       <para>The symbols in the second column indicate the relative age
416         of the installed version and the version available in the
417         local ports tree.</para>
418
419       <informaltable frame="none">
420         <tgroup cols="2">
421           <thead>
422             <row>
423               <entry>Symbol</entry>
424               <entry>Meaning</entry>
425             </row>
426           </thead>
427
428           <tbody>
429             <row>
430             <entry>=</entry> <entry>The version of the
431             installed package matches the one found in the
432             local ports tree.</entry>
433             </row>
434  
435         <row><entry>&lt;</entry>
436         <entry>The installed version is older than the one available
437         in the ports tree.</entry>
438         </row>
439
440         <row><entry>&gt;</entry><entry>The installed version is newer
441           than the one found in the local ports tree. (The local ports
442           tree is probably out of date.)</entry></row>
443
444         <row><entry>?</entry><entry>The installed package cannot be
445           found in the ports index.  (This can happen, for instance, if an
446           installed port is removed from the ports collection or
447           renamed.)</entry></row>
448
449         <row><entry>*</entry><entry>There are multiple versions of the
450         package.</entry></row>
451
452         </tbody>
453         </tgroup>
454     </informaltable>
455     </sect2>
456
457     <sect2>
458       <title>Deleting a Package</title>
459       <indexterm>
460         <primary><command>pkg_delete</command></primary>
461       </indexterm>
462       <indexterm>
463         <primary>packages</primary>
464         <secondary>deleting</secondary>
465       </indexterm>
466       <para>To remove a previously installed software package, use the
467         &man.pkg.delete.1; utility.
468       </para>
469
470       <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>
471     </sect2>
472
473     <sect2>
474       <title>Miscellaneous</title>
475       <para>All package information is stored within the 
476         <filename>/var/db/pkg</filename> directory.  The installed
477         file list and descriptions of each package can be found within 
478         files in this directory.
479       </para>
480     </sect2>
481   </sect1>
482   
483   <sect1 id="ports-using">
484     <title>Using the Ports Collection</title>
485
486     <para>The following sections provide basic instructions on using the
487       ports collection to install or remove programs from your
488       system.</para>
489
490     <sect2 id="ports-tree">
491       <title>Obtaining the Ports Collection</title>
492
493       <para>Before you can install ports, you must first obtain the
494         ports collection&mdash;which is essentially a set of
495         <filename>Makefiles</filename>, patches, and description files
496         placed in <filename>/usr/ports</filename>.
497       </para>
498
499       <para>When installing your FreeBSD system,
500         <application>sysinstall</application> asked if you would like
501         to install the ports collection.  If you chose no, you can
502         follow these instructions to obtain the ports
503         collection:</para>
504
505       <procedure>
506         <title>Sysinstall Method</title>
507
508         <para>This method involves using
509           <application>sysinstall</application> again to manually
510           install the ports collection.</para>
511
512         <step>
513           <para>As <username>root</username>, run <command>/stand/sysinstall</command> as
514             shown below:</para>
515
516           <screen>&prompt.root; <userinput>/stand/sysinstall</userinput></screen>
517         </step>
518
519         <step>
520           <para>Scroll down and select <guimenuitem>Configure</guimenuitem>,
521             press <keycap>Enter</keycap>.</para>
522         </step>
523
524         <step>
525           <para>Scroll down and select
526             <guimenuitem>Distributions</guimenuitem>, press <keycap>Enter</keycap>.</para>
527         </step>
528
529         <step>
530           <para>Scroll down to <guimenuitem>ports</guimenuitem>, press
531             <keycap>Space</keycap>.</para>
532         </step>
533
534         <step>
535           <para>Scroll up to <guimenuitem>Exit</guimenuitem>, press
536             <keycap>Enter</keycap>.</para>
537         </step>
538
539         <step>
540           <para>Select your desired installation media, such as CDROM,
541             FTP, and so on.</para>
542         </step>
543
544         <step>
545           <para>Scroll up to <guimenuitem>Exit</guimenuitem> and press
546             <keycap>Enter</keycap>.</para>
547         </step>
548
549         <step>
550           <para>Press <keycap>X</keycap> to exit
551             <application>sysinstall</application>.</para>
552         </step>
553       </procedure>
554
555       <para>The alternative method to obtain and keep your ports
556         collection up to date is by using
557         <application>CVSup</application>.  Look at the ports
558         <application>CVSup</application> file,
559         <filename>/usr/share/examples/cvsup/ports-supfile</filename>.
560         See <link linkend="cvsup">Using CVSup</link> (<xref
561           linkend="cvsup">) for more information on using
562         <application>CVSup</application> and this file.</para>
563
564       <procedure>
565         <title>CVSup Method</title>
566
567         <para>This is a quick method for getting the ports collection
568           using <application>CVSup</application>.  If you want to keep
569           your ports tree up to date, or learn more about
570           <application>CVSup</application>, read the previously
571           mentioned sections.</para>
572
573         <step>
574           <para>Install the <filename
575               role="package">net/cvsup</filename> port.  See <link
576               linkend="cvsup-install">CVSup Installation</link> (<xref
577               linkend="cvsup-install">) for more details.</para>
578         </step>
579
580         <step>
581           <para>As <username>root</username>, copy
582             <filename>/usr/share/examples/cvsup/ports-supfile</filename>
583             to a new location, such as <filename>/root</filename> or your
584               home directory.</para>
585         </step>
586
587         <step>
588           <para>Edit <filename>ports-supfile</filename>.</para>
589         </step>
590
591         <step>
592           <para>Change <replaceable>CHANGE_THIS.FreeBSD.org</replaceable> to a
593             <application>CVSup</application> server near you.  See <link
594               linkend="cvsup-mirrors">CVSup Mirrors</link> (<xref
595               linkend="cvsup-mirrors">) for a complete listing of mirror
596             sites.</para>
597         </step>
598
599         <step>
600           <para>Run <command>cvsup</command>:</para>
601
602           <screen>&prompt.root; <userinput>cvsup -g -L 2 <replaceable>/root/ports-supfile</replaceable></userinput></screen>
603         </step>
604
605         <step>
606           <para>Running this command later will download and apply all
607             the recent changes to your ports collection, except
608             actually rebuilding the ports for your own system.</para>
609         </step>
610       </procedure>
611     </sect2>
612
613     <sect2 id="ports-skeleton">
614       <title>Installing Ports</title>
615
616       <indexterm>
617         <primary>ports</primary>
618         <secondary>installing</secondary>
619       </indexterm>
620       <para>The first thing that should be explained when it comes to
621         the ports collection is what is actually meant by a
622         <quote>skeleton</quote>.  In a nutshell, a port skeleton is a
623         minimal set of files that tell your FreeBSD system how to
624         cleanly compile and install a program.  Each port skeleton
625         includes:</para>
626
627       <itemizedlist>
628         <listitem>
629           <para>A <filename>Makefile</filename>.  The
630             <filename>Makefile</filename> contains various statements
631             that specify how the application should be compiled and
632             where it should be installed on your system.</para>
633         </listitem>
634
635         <listitem>
636           <para>A <filename>distinfo</filename> file.  This file
637             contains information about the files that must be
638             downloaded to build the port and their checksums, to
639             verify that files have not been corrupted during the
640             download using &man.md5.1;.</para>
641         </listitem>
642         
643         <listitem>
644           <para>A <filename>files</filename> directory.  This
645             directory contains patches to make the program compile and
646             install on your FreeBSD system.  Patches are basically
647             small files that specify changes to particular files.
648             They are in plain text format, and basically say
649             <quote>Remove line 10</quote> or <quote>Change line 26 to
650             this ...</quote>.  Patches are also known as
651             <quote>diffs</quote> because they are generated by the
652             &man.diff.1; program.</para>
653
654           <para>This directory may also contain other files used to build
655             the port.</para>
656         </listitem>
657
658         <listitem>
659           <para>A <filename>pkg-descr</filename> file.  This is a more
660             detailed, often multiple-line, description of the program.</para>
661         </listitem>
662         
663         <listitem>
664           <para>A <filename>pkg-plist</filename> file.  This is a list of all
665             the files that will be installed by the port.  It also tells the
666             ports system what files to remove upon deinstallation.</para>
667         </listitem>
668       </itemizedlist>
669
670       <para>Some ports have other files, such as
671         <filename>pkg-message</filename>.  The ports system uses these
672         files to handle special situations.  If you want more details
673         on these files, and on ports in general, check out the <ulink
674         url="../porters-handbook/index.html">FreeBSD Porter's
675         Handbook</ulink>.</para>
676
677       <para>Now that you have enough background information to know
678         what the ports collection is used for, you are ready to
679         install your first port.  There are two ways this can be done,
680         and each is explained below.</para>
681
682       <para>Before we get into that, however, you will need to choose a
683         port to install.  There are a few ways to do this, with the
684         easiest method being the <ulink
685         url="&url.main;/ports/index.html">ports listing on the FreeBSD
686         web site</ulink>.  You can browse through the ports listed there
687         or use the search function on the site.  Each port also includes
688         a description so you can read a bit about each port before
689         deciding to install it.</para>
690
691       <para>Another method is to use the &man.whereis.1; command.
692         Simply type <command>whereis
693         <replaceable>file</replaceable></command>, where
694         <replaceable>file</replaceable> is the program you want to
695         install.  If it is found on your system, you will be told
696         where it is, as follows:</para>
697
698       <screen>&prompt.root; <userinput>whereis lsof</userinput>
699 lsof: /usr/ports/sysutils/lsof</screen>
700
701       <para>This tells us that <command>lsof</command> (a system
702         utility) can be found in the
703         <filename>/usr/ports/sysutils/lsof</filename>
704         directory.</para>
705
706       <para>Yet another way to find a particular port is by using the
707         ports collection's built-in search mechanism.  To use the
708         search feature, you will need to be in the
709         <filename>/usr/ports</filename> directory.  Once in that
710         directory, run <command>make search
711         name=<replaceable>program-name</replaceable></command> where
712         <replaceable>program-name</replaceable> is the name of the
713         program you want to find.  For example, if you were looking
714         for <command>lsof</command>:</para>
715
716       <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
717 &prompt.root; <userinput>make search name=lsof</userinput>
718 Port:   lsof-4.56.4
719 Path:   /usr/ports/sysutils/lsof
720 Info:   Lists information about open files (similar to fstat(1))
721 Maint:  obrien@FreeBSD.org
722 Index:  sysutils
723 B-deps: 
724 R-deps: </screen>
725
726       <para>The part of the output you want to pay particular
727         attention to is the <quote>Path:</quote> line, since that
728         tells you where to find the port.  The other information
729         provided is not needed in order to install the port, so it
730         will not be covered here.</para>
731
732       <para>For more in-depth searching you can also use <command>make
733        search key=<replaceable>string</replaceable></command> where
734        <replaceable>string</replaceable> is some text to search for.
735        This searches port names, comments, descriptions and
736        dependencies and can be used to find ports which relate to a
737        particular subject if you don't know the name of the program
738        you are looking for.</para>
739
740       <para>In both of these cases, the search string is case-insensitive.
741        Searching for <quote>LSOF</quote> will yield the same results as 
742        searching for <quote>lsof</quote>.</para>
743
744       <note>
745         <para>You must be logged in as <username>root</username> to install
746           ports.</para>
747       </note>
748
749       <para>Now that you have found a port you would like to install,
750         you are ready to do the actual installation.  The port
751         includes instructions on how to build source code, but does not include the
752         actual source code.  You can get the source code from a CD-ROM
753         or from the Internet.  Source code is distributed in whatever
754         manner the software author desires.  Frequently this is a
755         tarred and gzipped file, but it might be compressed with some
756         other tool or even uncompressed.  The program source code,
757         whatever form it comes in, is called a
758         <quote>distfile</quote>.  You can get the distfile from a
759         CD-ROM or from the Internet.</para>
760
761       <warning>
762         <para>Before installing any port, you should be sure to have
763           an up-to-date ports collection and you should check <ulink
764           url="http://vuxml.freebsd.org/"></ulink> for security issues
765           related to your port.</para>
766
767         <para>A security vulnerabilities check can be automatically
768           done by <application>portaudit</application> before any new
769           application installation.  This tool can be found in the
770           ports collection (<filename
771           role="package">security/portaudit</filename>).  Consider
772           running <command>portaudit -F</command> before installing a
773           new port, to fetch the current vulnerabilities database.  A
774           security audit and an update of the database will be
775           performed during the daily security system check.  For more
776           informations read the &man.portaudit.1; and &man.periodic.8;
777           manual pages.</para>
778       </warning>
779
780       <sect3 id="ports-cd">
781         <title>Installing Ports from a CD-ROM</title>
782
783         <indexterm>
784           <primary>ports</primary>
785           <secondary>installing from CD-ROM</secondary>
786         </indexterm>
787         <para>The FreeBSD Project's official CD-ROM images no longer
788           include distfiles.  They take up a lot of room that is
789           better used for precompiled packages.  CD-ROM products such as
790           the FreeBSD PowerPak do include distfiles, and you can
791           order these sets from a vendor such as the <ulink
792           url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>.
793           This section assumes you have such a FreeBSD CD-ROM
794           set.</para>
795
796         <para>Place your FreeBSD CD-ROM in the drive.  Mount it on
797           <filename>/cdrom</filename>.  (If you use a different mount
798           point, the install will not work.)  To begin, change to the
799           directory for the port you want to install:</para>
800
801         <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput></screen>
802
803         <para>Once inside the <filename>lsof</filename> directory,
804           you will see the port
805           skeleton.  The next step is to compile, or <quote>build</quote>, the
806           port.  This is done by simply typing <command>make</command> at
807           the prompt.  Once you have done so, you should see something
808           like this:</para>
809
810         <screen>&prompt.root; <userinput>make</userinput>
811 &gt;&gt; lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
812 &gt;&gt; Attempting to fetch from file:/cdrom/ports/distfiles/.
813 ===&gt;  Extracting for lsof-4.57
814 ...
815 [extraction output snipped]
816 ...
817 &gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
818 ===&gt;  Patching for lsof-4.57
819 ===&gt;  Applying FreeBSD patches for lsof-4.57
820 ===&gt;  Configuring for lsof-4.57
821 ...
822 [configure output snipped]
823 ...
824 ===&gt;  Building for lsof-4.57
825 ...
826 [compilation output snipped]
827 ...
828 &prompt.root;</screen>
829
830         <para>Notice that once the compile is complete you are
831           returned to your prompt.  The next step is to install the
832           port.  In order to install it, you simply need to tack one word
833           onto the <command>make</command> command, and that word is
834           <command>install</command>:</para>
835
836         <screen>&prompt.root; <userinput>make install</userinput>
837 ===&gt;  Installing for lsof-4.57
838 ...
839 [installation output snipped]
840 ...
841 ===&gt;   Generating temporary packing list
842 ===&gt;   Compressing manual pages for lsof-4.57
843 ===&gt;   Registering installation for lsof-4.57
844 ===&gt;  SECURITY NOTE: 
845       This port has installed the following binaries which execute with
846       increased privileges.
847 &prompt.root;</screen>
848
849         <para>Once you are returned to your prompt, you should be able to
850           run the application you just installed.  Since 
851           <command>lsof</command> is a
852           program that runs with increased privileges, a security
853           warning is shown.  During the building and installation of
854           ports, you should take heed of any other warnings that
855           may appear.</para>
856
857         <note>
858           <para>You can save an extra step by just running <command>make
859             install</command> instead of <command>make</command> and
860             <command>make install</command> as two separate steps.</para>
861         </note>
862
863         <note>
864           <para>Some shells keep a cache of the commands that are
865             available in the directories listed in the
866             <envar>PATH</envar> environment variable, to speed up
867             lookup operations for the executable file of these
868             commands.  If you are using one of these shells, you might
869             have to use the <command>rehash</command> command after
870             installing a port, before the newly installed commands can
871             be used.  This is true for both shells that are part of
872             the base-system (such as <command>tcsh</command>) and
873             shells that are available as ports (for instance,
874             <filename role="package">shells/zsh</filename>).</para>
875         </note>
876
877         <note>
878           <para>Please be aware that the licenses of a few ports do
879             not allow for inclusion on the CD-ROM.  This could be
880             because a registration form needs to be filled out before
881             downloading or redistribution is not allowed, or for
882             another reason.  If you wish to install a port not
883             included on the CD-ROM, you will need to be online in
884             order to do so (see the <link linkend="ports-inet">next
885             section</link>).</para>
886         </note>
887       </sect3>
888
889       <sect3 id="ports-inet">
890       <title>Installing Ports from the Internet</title>
891
892         <para>As with the last section, this section makes an
893           assumption that you have a working Internet connection.  If
894           you do not, you will need to perform the <link
895           linkend="ports-cd">CD-ROM installation</link>, or put a copy
896           of the distfile into
897           <filename>/usr/ports/distfiles</filename> manually.</para>
898
899         <para>Installing a port from the Internet is done exactly the
900           same way as it would be if you were installing from a
901           CD-ROM.  The only difference between the two is that the
902           distfile is downloaded from the Internet instead of read
903           from the CD-ROM.</para>
904
905         <para>The steps involved are identical:</para>
906
907         <screen>&prompt.root; <userinput>make install</userinput>
908 &gt;&gt; lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
909 &gt;&gt; Attempting to fetch from ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/.
910 Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
911 439860 bytes transferred in 18.0 seconds (23.90 kBps)
912 ===&gt;  Extracting for lsof-4.57
913 ...
914 [extraction output snipped]
915 ...
916 &gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
917 ===&gt;  Patching for lsof-4.57
918 ===&gt;  Applying FreeBSD patches for lsof-4.57
919 ===&gt;  Configuring for lsof-4.57
920 ...
921 [configure output snipped]
922 ...
923 ===&gt;  Building for lsof-4.57
924 ...
925 [compilation output snipped]
926 ...
927 ===&gt;  Installing for lsof-4.57
928 ...
929 [installation output snipped]
930 ...
931 ===&gt;   Generating temporary packing list
932 ===&gt;   Compressing manual pages for lsof-4.57
933 ===&gt;   Registering installation for lsof-4.57
934 ===&gt;  SECURITY NOTE: 
935       This port has installed the following binaries which execute with
936       increased privileges.
937 &prompt.root;</screen>
938
939         <para>As you can see, the only difference is the line that tells
940           you where the system is fetching the port distfile from.</para>
941
942         <para>The ports system uses &man.fetch.1; to download the
943           files, which honors various environment variables, including
944           <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>,
945           and <envar>FTP_PASSWORD</envar>.  You may need to set one or
946           more of these if you are behind a firewall, or need to use
947           an FTP/HTTP proxy.  See &man.fetch.3; for the complete
948           list.</para>
949
950         <para>For users which cannot be connected all the time, the
951           <command>make <maketarget>fetch</maketarget></command> option is
952           provided.  Just run this command at the top level directory
953           (<filename>/usr/ports</filename>) and the required files
954           will be downloaded for you.  This command will also work in
955           the lower level categories, for example:
956           <filename>/usr/ports/net</filename>.
957           Note that if a port depends on libraries or other ports this will
958           <emphasis>not</emphasis> fetch the distfiles of those ports too.
959           Replace <maketarget>fetch</maketarget> with
960           <maketarget>fetch-recursive</maketarget>
961           if you want to fetch all the dependencies of a port too.</para>
962
963         <note><para>You can build all the ports in a category or as a
964           whole by running <command>make</command> in the top level
965           directory, just like the aforementioned <command>make
966           <makevar>fetch</makevar></command> method.  This is
967           dangerous, however, as some ports cannot co-exist.  In other
968           cases, some ports can install two different files with the
969           same filename.</para></note>
970
971         <para>In some rare cases, users may need to acquire the
972           tarballs from a site other than the
973           <makevar>MASTER_SITES</makevar> (the location where files
974           are downloaded from).  You can override the
975           <makevar>MASTER_SITES</makevar> option with the following
976           command:</para>
977
978         <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
979 &prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
980 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen>
981
982         <para>In this example we change the
983           <makevar>MASTER_SITES</makevar> option to <hostid
984           role="fqdn">ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</hostid>.</para>
985
986         <note><para>Some ports allow (or even require) you to provide build options
987           which can enable/disable parts of the application which are
988           unneeded, certain security options, and other
989           customizations.  A few which come to mind are <filename
990           role="package">www/mozilla</filename>, <filename
991           role="package">security/gpgme</filename>, and <filename
992           role="package">mail/sylpheed-claws</filename>.  A message
993           will be displayed when options such as these are
994           available.</para></note>
995       </sect3>
996
997       <sect3>
998         <title>Overriding the Default Ports Directories</title>
999
1000         <para>Sometimes it is useful (or mandatory) to use a different
1001           distfiles and ports directory.  The
1002           <makevar>PORTSDIR</makevar> and <makevar>PREFIX</makevar>
1003           variables can override the default directories.  For
1004           example:</para>
1005
1006         <screen>&prompt.root; <userinput>make PORTSDIR=/usr/home/example/ports install</userinput></screen>
1007
1008         <para>will compile the port in
1009             <filename>/usr/home/example/ports</filename> and install
1010             everything under <filename>/usr/local</filename>.</para>
1011
1012         <screen>&prompt.root; <userinput>make PREFIX=/usr/home/example/local install</userinput></screen>
1013
1014         <para>will compile it in <filename>/usr/ports</filename> and
1015           install it in
1016           <filename>/usr/home/example/local</filename>.</para>
1017
1018         <para>And of course,</para>
1019
1020         <screen>&prompt.root; <userinput>make PORTSDIR=../ports PREFIX=../local install</userinput></screen>
1021
1022         <para>will combine the two (it is too long to completely write
1023           on this page, but it should give you the general
1024           idea).</para>
1025
1026         <para>Alternatively, these variables can also be set as part
1027           of your environment.  Read the manual page for your shell
1028           for instructions on doing so.</para>
1029       </sect3>
1030
1031       <sect3>
1032         <title>Dealing with <command>imake</command></title>
1033
1034         <para>Some ports that use <command>imake</command> (a part of
1035           the X Window System) do not work well with
1036           <makevar>PREFIX</makevar>, and will insist on installing
1037           under <filename>/usr/X11R6</filename>.  Similarly, some Perl
1038           ports ignore <makevar>PREFIX</makevar> and install in the
1039           Perl tree.  Making these ports respect
1040           <makevar>PREFIX</makevar> is a difficult or impossible
1041           job.</para>
1042
1043       </sect3>
1044     </sect2>
1045
1046     <sect2 id="ports-removing">
1047       <title>Removing Installed Ports</title>
1048
1049       <indexterm>
1050         <primary>ports</primary>
1051         <secondary>removing</secondary>
1052       </indexterm>
1053       <para>Now that you know how to install ports, you are probably
1054         wondering how to remove them, just in case you install one and
1055         later on decide that you installed the wrong port.  
1056         We will remove our previous example (which was 
1057         <command>lsof</command> for
1058         those of you not paying attention).  As with installing ports,
1059         the first thing you must do is change to the port directory,
1060         <filename>/usr/ports/sysutils/lsof</filename>.  After you change
1061         directories, you are ready to uninstall <command>lsof</command>.
1062         This is done with
1063         the <command>make deinstall</command> command:</para>
1064
1065       <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
1066 &prompt.root; <userinput>make deinstall</userinput>
1067 ===&gt;  Deinstalling for lsof-4.57</screen>
1068
1069       <para>That was easy enough.  You have removed
1070         <command>lsof</command>
1071         from your system.  If you would like to reinstall it, you can do
1072         so by running <command>make reinstall</command> from the
1073         <filename>/usr/ports/sysutils/lsof</filename> directory.</para>
1074
1075       <para>The <command>make deinstall</command> and <command>make
1076         reinstall</command> sequence does not work once you have run
1077         <command>make clean</command>.  If you want to deinstall a
1078         port after cleaning, use &man.pkg.delete.1; as
1079         discussed in the <link linkend="packages-using">Packages
1080         section of the Handbook</link>.</para>
1081     </sect2>
1082
1083     <sect2 id="ports-disk-space">
1084       <title>Ports and Disk Space</title>
1085
1086       <indexterm>
1087         <primary>ports</primary>
1088         <secondary>disk-space</secondary>
1089       </indexterm>
1090       <para>Using the ports collection can defiantly eat up your disk
1091         space.  For this reason you should always remember to clean up
1092         the work directories using the <command>make
1093         <makevar>clean</makevar></command> option.  This will remove
1094         the <filename>work</filename> directory after a port has been
1095         built, and installed.  You can also remove the tar files from
1096         the <filename>distfiles</filename> directory, and remove the
1097         installed ports when their use has delimited.</para>
1098
1099       <para>Some users choose to limit the port categories by placing an entry
1100         in the <filename>refuse</filename> file.  This way when they run the
1101         <application>CVSup</application> application, it will not download the
1102         files in that category.</para>
1103     </sect2>
1104
1105     <sect2 id="ports-upgrading">
1106       <title>Upgrading Ports</title>
1107
1108       <indexterm>
1109         <primary>portupgrade</primary>
1110       </indexterm>
1111       <indexterm>
1112         <primary>ports</primary>
1113         <secondary>upgrading</secondary>
1114       </indexterm>
1115       <note>
1116         <para>Once you updated your ports collection, before
1117           attempting a port upgrade, you should check the
1118           <filename>/usr/ports/UPDATING</filename> file.  This file
1119           describes various issues and additional steps users may
1120           encounter and need to perform when updating a port.</para>
1121       </note>
1122
1123       <para>Keeping your ports up to date can be a tedious job.  For
1124         instance, to upgrade a port you would go to the ports
1125         directory, build the port, deinstall the old port, install the
1126         new port, and then clean up after the build.  Imagine doing
1127         that for five ports, tedious right?  This was a large problem
1128         for system administrators to deal with, and now we have
1129         utilities which do this for us.  For instance the <filename
1130         role="package">sysutils/portupgrade</filename> utility will do
1131         everything for you!  Just install it like you would any other
1132         port, using the <command>make <makevar>install
1133         clean</makevar></command> command.</para>
1134
1135       <para>Now create a database with the <command>pkgdb -F</command>
1136         command.  This will read the list of installed ports and
1137         create a database file in the <filename>/var/db/pkg</filename>
1138         directory.  Now when you run <command>portupgrade
1139         -a</command>, it will read this and the ports
1140         <filename>INDEX</filename> file.  Finally,
1141         <application>portupgrade</application> will begin to download, build,
1142         backup, install, and clean the ports which have been updated.
1143         <application>portupgrade</application> comes with a lot of options
1144         for different use cases, the most important ones will be presented
1145         below.</para>
1146
1147       <para>If you want to upgrade only a certain application, not the
1148         complete database, use <command>portupgrade
1149         <replaceable>pkgname</replaceable></command>, 
1150         include the flags <option>-r</option> if
1151         <application>portupgrade</application> should act on all
1152         those packages depending on the given package as well, and
1153         <option>-R</option> to act on all packages required by
1154         the given packages.
1155         To use packages instead of ports for installation, provide
1156         <option>-P</option> and to just fetch distfiles without
1157         building or installing anything, use <option>-F</option>.
1158         For further information see &man.portupgrade.1;.</para>
1159
1160       <note>
1161         <para>It is important to regularly update the package database using
1162           <command>pkgdb -F</command> to fix inconsistencies, especially when 
1163           <application>portupgrade</application> asks you to.  Do not abort
1164           <application>portupgrade</application> while it is updating the
1165           package database, this will leave you an inconsistent
1166           database.</para>
1167       </note>
1168
1169       <para>Other utilities exist which will do this, check out the
1170         <filename>ports/sysutils</filename> directory and see what you
1171         come up with.</para>
1172     </sect2>
1173   </sect1>
1174
1175   <sect1 id="ports-nextsteps">
1176     <title>Post-installation Activities</title>
1177
1178     <para>After installing a new application you will normally want to
1179       read any documentation it may have included, edit any
1180       configuration files that are required, ensure that the
1181       application starts at boot time (if it is a daemon), and so
1182       on.</para>
1183
1184     <para>The exact steps you need to take to configure each
1185       application will obviously be different.  However, if you have
1186       just installed a new application and are wondering <quote>What
1187       now?</quote> these tips might help:</para>
1188
1189     <itemizedlist>
1190       <listitem>
1191         <para>Use &man.pkg.info.1; to find out which files were installed,
1192           and where.  For example, if you have just
1193           installed FooPackage version 1.0.0, then this command</para>
1194
1195         <screen>&prompt.root; <userinput>pkg_info -L foopackage-1.0.0 | less</userinput></screen>
1196
1197         <para>will show all the files installed by the package.  Pay
1198           special attention to files in <filename>man/</filename>
1199           directories, which will be manual pages,
1200           <filename>etc/</filename> directories, which will be
1201           configuration files, and <filename>doc/</filename>, which
1202           will be more comprehensive documentation.</para>
1203
1204         <para>If you are not sure which version of the application was
1205           just installed, a command like this</para>
1206
1207         <screen>&prompt.root; <userinput>pkg_info | grep -i <replaceable>foopackage</replaceable></userinput></screen>
1208
1209         <para>will find all the installed packages that have
1210           <replaceable>foopackage</replaceable> in the package name.
1211           Replace <replaceable>foopackage</replaceable> in your
1212           command line as necessary.</para>
1213       </listitem>
1214
1215       <listitem>
1216         <para>Once you have identified where the application's manual
1217           pages have been installed, review them using &man.man.1;.
1218           Similarly, look over the sample configuration files, and any
1219           additional documentation that may have been provided.</para>
1220       </listitem>
1221
1222       <listitem>
1223         <para>If the application has a web site, check it for
1224           additional documentation, frequently asked questions, and so
1225           forth.  If you are not sure of the web site address it may
1226           be listed in the output from</para>
1227
1228         <screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen>
1229         
1230         <para>A <literal>WWW:</literal> line, if present, should provide a URL
1231           for the application's web site.</para>
1232       </listitem>
1233
1234       <listitem>
1235         <para>Ports that should start at boot (such as Internet
1236           servers) will usually install a sample script in
1237           <filename>/usr/local/etc/rc.d</filename>.  You should
1238           review this script for correctness and edit or rename it if
1239           needed.  See <link
1240           linkend="configtuning-starting-services">Starting
1241           Services</link> for more information.</para>
1242       </listitem>
1243     </itemizedlist>
1244   </sect1>
1245
1246   <sect1 id="ports-broken">
1247     <title>Dealing with Broken Ports</title>
1248
1249       <para>If you come across a port that does not work for you,
1250         there are a few things you can do, including:</para>
1251
1252       <orderedlist>
1253         <listitem>
1254           <para>Fix it!  The <ulink
1255             url="../porters-handbook/index.html">Porter's
1256             Handbook</ulink> includes detailed information on the
1257             <quote>Ports</quote> infrastructure so that you can fix the occasional
1258             broken port or even submit your own!</para>
1259         </listitem>
1260
1261         <listitem>
1262           <para>Gripe&mdash;<emphasis>by email only</emphasis>!  Send
1263             email to the maintainer of the port first.  Type
1264             <command>make maintainer</command> or read the
1265             <filename>Makefile</filename> to find the maintainer's
1266             email address.  Remember to include the name and version
1267             of the port (send the <literal>&dollar;FreeBSD:</literal>
1268             line from the <filename>Makefile</filename>) and the
1269             output leading up to the error when you email the
1270             maintainer.  If you do not get a response from the
1271             maintainer, you can use &man.send-pr.1; to submit a bug
1272             report.</para>
1273         </listitem>
1274
1275         <listitem>
1276           <para>Grab the package from an FTP site near you.  The
1277             <quote>master</quote> package collection is on <hostid
1278             role="fqdn">ftp.FreeBSD.org</hostid> in the <ulink
1279             url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">packages
1280             directory</ulink>, but be sure to check your local mirror
1281             <emphasis>first</emphasis>!  These are more likely to work
1282             than trying to compile from source and are a lot faster as
1283             well.  Use the &man.pkg.add.1; program to install the
1284             package on your system.</para>
1285         </listitem>
1286       </orderedlist>
1287   </sect1>
1288
1289 </chapter>
1290
1291 <!--
1292      Local Variables:
1293      mode: sgml
1294      sgml-declaration: "../chapter.decl"
1295      sgml-indent-data: t
1296      sgml-omittag: nil
1297      sgml-always-quote-attributes: t
1298      sgml-parent-document: ("../book.sgml" "part" "chapter")
1299      End:
1300 -->