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