<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

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

  <sect1>
    <title>Synopsis</title>

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

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

    <itemizedlist>
      <listitem>
	<para>How to install third-party binary software packages.</para>
      </listitem>
      <listitem>
	<para>How to build third-party software from the ports
	collection.</para>
      </listitem>
      <listitem>
	<para>How to remove previously installed packages or ports.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1>
    <title>Overview of Software Installation</title>

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

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

      <step>
	<para>Unpack the software from its distribution format (typically a
	  tarball compressed with either &man.compress.1; or &man.gzip.1;).</para>
      </step>

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

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

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

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

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

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

    <para>Installing a new application can be carried out with a single
      command.</para>

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

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

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

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

    <para>Given that the two technologies are quite similar, you might be
      wondering why FreeBSD bothers with both.  Packages and ports both have
      their own strengths, and which one you use will depend on your own
      preference.</para>

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

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

      <listitem>
	<para>Packages do not require you to understand the process
	  involved in compiling software on FreeBSD.</para>
      </listitem>
    </itemizedlist>

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

      <listitem>
	<para>Some applications have compile time options relating to what they
	  can and cannot do.  For example, <application>Apache</application>
	  can be configured with a wide variety of different built-in options.
	  By building from the port you do not have to accept the default
	  options, and can set them yourself.</para>

	<para>In some cases, multiple packages will exist for the same
	  application to specify certain settings.  For example,
	  <application>Ghostscript</application> is available as a
	  <filename>ghostscript</filename> package and a
	  <filename>ghostscript-nox11</filename> package, depending on whether
	  or not you have installed an X11 server.  This sort of rough
	  tweaking is possible with packages, but rapidly becomes impossible
	  if an application has more than one or two different compile time
	  options.</para>
      </listitem>

      <listitem>
	<para>The licensing conditions of some software distributions forbid
	  binary distribution.  They must be distributed as source
	  code.</para>
      </listitem>

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

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

      <listitem>
	<para>Some people like having code around, so they can read it if they
	  get bored, hack it, borrow from it (license permitting, of course),
	  and so on.</para>
      </listitem>
    </itemizedlist>

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

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

  <sect1>
    <title>Finding Your Application</title>

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

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

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

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

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

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

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

  <sect1 id="packages-using">
    <sect1info>    
      <authorgroup>
        <author>
          <firstname>Chern</firstname>
	  <surname>Lee</surname>
	  <contrib>Contributed by </contrib>
        </author>
      </authorgroup>
    <!-- 30 Mar 2001 -->
    </sect1info>

    <title>Using the Packages System</title>

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

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

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

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

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

      <para>The example above would download the correct package and add it without
        any further user intervention.</para>

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

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

    </sect2>

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

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

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

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

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

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

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

 	  <tbody>
  	    <row>
	    <entry>=</entry> <entry>The version of the
	    installed package matches that of the one found in the
	    local ports tree.</entry>
  	    </row>
 
        <row><entry>&lt;</entry>
	<entry>The installed version is older then the one available
	in the ports tree.</entry>
	</row>

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

        <row><entry>?</entry><entry>The installed package cannot be
        found in the ports index.</entry></row>

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

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

    <sect2>
      <title>Miscellaneous</title>
      <para>All package information is stored within the 
        <filename>/var/db/pkg</filename> directory.  The installed
	file list and descriptions of each package can be found within 
        files in this directory.
      </para>
    </sect2>
  </sect1>
  
  <sect1 id="ports-using">
    <title>Using the Ports Collection</title>

    <para>The following sections provide basic instructions on using the
      ports collection to install or remove programs from your
      system.</para>

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

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

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

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

	<para>This method involves using
	  <application>sysinstall</application> again to manually
	  install the ports collection.</para>

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

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

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

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

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

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

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

	<step>
	  <para>Follow the menus to exit <application>sysinstall</application>.</para>
	</step>
      </procedure>

      <para>The alternative method to obtain and keep your ports
	collection up to date is by using
	<application>CVSup</application>.  Look at the ports
	<application>CVSup</application> file,
	<filename>/usr/share/examples/cvsup/ports-supfile</filename>.
	See <link linkend="cvsup">Using CVSup</link> (<xref
	  linkend="cvsup">) for more information on using
	<application>CVSup</application> and the mentioned file.</para>

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

	<para>This is a quick method to getting the ports collection
	  using <application>CVSup</application>.  If you want to keep
	  your ports tree up to date, or learn more about
	  <application>CVSup</application>, read the previously
	  mentioned sections.</para>

	<step>
	  <para>Install the <filename role="package">net/cvsup</filename> port.  See <link
	      linkend="cvsup-install">CVSup Installation</link> (<xref
	      linkend="cvsup-install">) for more details.</para>
	</step>

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

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

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

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

	  <screen>&prompt.root; cvsup -g -L 2 <replaceable>/root/ports-supfile</replaceable></screen>
	</step>

	<step>
	  <para>Running this consequent times at later dates will
	    download all the recent changes to your ports
	    collection.</para>
	</step>
      </procedure>
    </sect2>

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

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

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

	<listitem>
	  <para>A <filename>distinfo</filename> file.  This file contains
	    information about the files that must be downloaded to build the
	    port, and checksums, to ensure that those files have not been
	    corrupted during the download.</para>
	</listitem>
	
	<listitem>
	  <para>A <filename>files</filename> directory.  This directory
	    contains patches to make the program compile and install on
	    your FreeBSD system.  Patches are basically small files that
	    specify changes to particular files.  They are in plain text
	    format, and basically say <quote>Remove line 10</quote> or
	    <quote>Change line 26 to this ...</quote>.  Patches are also
	    known as <quote>diffs</quote> because they are generated by the
	    <application>diff</application> program.</para>

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

	<listitem>
	  <para>A <filename>pkg-comment</filename> file.  This is a one-line
	    description of the program.</para>
	</listitem>

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

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

      <para>Now that you have enough background information to know what
        the ports collection is used for, you are ready to install your
	first port.  There are two ways this can be done, and each is
	explained below.</para>

      <para>Before we get into that however, you will need to choose a
        port to install.  There are a few ways to do this, with the
	easiest method being the <ulink
	url="../../../../ports/index.html">ports listing on the FreeBSD
	web site</ulink>.  You can browse through the ports listed there
	or use the search function on the site.  Each port also includes
	a description so you can read a bit about each port before
	deciding to install it.</para>

      <para>Another method is to use the <command>whereis</command>
        command.  Simply type <command>whereis <replaceable>file</replaceable></command>,
	where <replaceable>file</replaceable> is the program you want to
	install.  If it is found on
        your system, you will be told where it is, like so:</para>

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

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

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

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

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

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

      <para>In both of these cases, the search string is case-insensitive.
       Searching for <quote>LSOF</quote> will yield the same results as 
       searching for <quote>lsof</quote>.</para>

      <note>
        <para>You must be the <username>root</username> user to install
          ports.</para>
      </note>

      <para>Now that you have found a port you would like to install,
        you are ready to do the actual installation.  The port
        includes instructions on how to build source code, but no
        actual source code.  You can get the source code from a CDROM
        or from the Internet.  Source code is distributed in whatever
        manner the software author desires.  Frequently this is a
        tarred and gzipped file, but it might be compressed with some
        other tool or even uncompressed.  The program source code,
        whatever form it comes in, is called a
        <quote>distfile</quote>.  You can get the distfile from a
        CDROM or from the Internet.</para>

      <sect3 id="ports-cd">
        <title>Installing Ports from a CDROM</title>

        <indexterm>
          <primary>ports</primary>
          <secondary>installing from CDROM</secondary>
        </indexterm>
        <para>The FreeBSD Project's official CDROM images no longer
	  include distfiles.  They take up a lot of room that is
	  better used by precompiled packages.  CDROM products such as
	  the FreeBSD PowerPak do include distfiles, and you can
	  order these sets from a vendor such as the <ulink
	  url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>.
	  This section assumes you have such a FreeBSD CDROM
	  set.</para>

        <para>Place your FreeBSD CDROM in the drive.  Mount it on
	  <filename>/cdrom</filename>.  (If you use a different mount
	  point, the install will not work.)  To begin, change to the
	  directory for the port you want to install:</para>

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

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

        <screen>&prompt.root; <userinput>make</userinput>
&gt;&gt; lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
&gt;&gt; Attempting to fetch from file:/cdrom/ports/distfiles/.
===&gt;  Extracting for lsof-4.57
...
[extraction output snipped]
...
&gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
===&gt;  Patching for lsof-4.57
===&gt;  Applying FreeBSD patches for lsof-4.57
===&gt;  Configuring for lsof-4.57
...
[configure output snipped]
...
===&gt;  Building for lsof-4.57
...
[compilation output snipped]
...
&prompt.root;</screen>

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

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

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

        <note>
          <para>You can save an extra step by just running <command>make
            install</command> instead of <command>make</command> and
	    <command>make install</command> as two separate steps.</para>
	</note>

        <note>
          <para>Please be aware that the licenses of a few ports do not
            allow for inclusion on the CDROM.  This could be because a
            registration form needs
	    to be filled out before downloading, redistribution is not
	    allowed, and so on.  If you wish to install a port not
	    included on the CDROM, you will need to be online in order to
	    do so (see the <link linkend="ports-inet">next
	    section</link>).</para>
	</note>
      </sect3>

      <sect3 id="ports-inet">
      <title>Installing Ports from the Internet</title>

        <para>As with the last section, this section makes an assumption
          that you have a working Internet connection.  If you do not,
	  you will need to perform the <link linkend="ports-cd">CDROM
	  installation</link>.</para>

        <para>Installing a port from the Internet is done exactly the same
	  way as it would be if you were installing from a CDROM.  The
	  only difference between the two is that the port distfile
	  is downloaded from the Internet instead of pulled from the
	  CDROM.</para>

        <para>The steps involved are identical:</para>

        <screen>&prompt.root; <userinput>make install</userinput>
&gt;&gt; lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
&gt;&gt; Attempting to fetch from ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/.
Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
439860 bytes transferred in 18.0 seconds (23.90 kBps)
===&gt;  Extracting for lsof-4.57
...
[extraction output snipped]
...
&gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
===&gt;  Patching for lsof-4.57
===&gt;  Applying FreeBSD patches for lsof-4.57
===&gt;  Configuring for lsof-4.57
...
[configure output snipped]
...
===&gt;  Building for lsof-4.57
...
[compilation snipped]
...
===&gt;  Installing for lsof-4.57
...
[install routines snipped]
...
===&gt;   Generating temporary packing list
===&gt;   Compressing manual pages for lsof-4.57
===&gt;   Registering installation for lsof-4.57
===&gt;  SECURITY NOTE: 
      This port has installed the following binaries which execute with
      increased privileges.
&prompt.root;</screen>

        <para>As you can see, the only difference is the line that tells
	  you where the system is fetching the port from.</para>

        <para>That about does it for installing ports onto your
	  system.  In the next section you will learn how to remove a
	  port from your system.</para>
      </sect3>
    </sect2>

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

      <indexterm>
        <primary>ports</primary>
        <secondary>removing</secondary>
      </indexterm>
      <para>Now that you know how to install ports, you are probably
        wondering how to remove them, just in case you install one and
	later on you decide that you installed the wrong port.  
        We will remove our previous example (which was 
	<command>lsof</command> for
        those of you not paying attention).  As with installing ports,
	the first thing you must do is change to the port directory,
	<filename>/usr/ports/sysutils/lsof</filename>.  After you change
	directories, you are ready to uninstall <command>lsof</command>.
	This is done with
	the <command>make deinstall</command> command:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
&prompt.root; <userinput>make deinstall</userinput>
===&gt;  Deinstalling for lsof-4.57</screen>

      <para>That was easy enough.  You have removed
	<command>lsof</command>
        from your system.  If you would like to reinstall it, you can do
	so by running <command>make reinstall</command> from the
        <filename>/usr/ports/sysutils/lsof</filename> directory.</para>

      <para>The <command>make deinstall</command> and <command>make
        reinstall</command> sequence does not work once you have run
        <command>make clean</command>.  If you want to deinstall a
        port after cleaning, use <command>pkg_delete</command> as
        discussed in the <link linkend="packages-using">Packages
        section of the Handbook</link>.</para>
    </sect2>
  </sect1>

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

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

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

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

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

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

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

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

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

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

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

	<screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen>
	
	<para>will often include a <literal>WWW:</literal> line with the URL
	  of the application's web site.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="ports-trouble">
    <title>Troubleshooting</title>

    <para>The following sections cover some of the more frequently asked
      questions about the ports collection and some basic troubleshooting
      techniques, and what do to if a <link
      linkend="ports-broken">port is broken.</link></para>

    <sect2 id="ports-questions">
      <title>Some Questions and Answers</title>

      <qandaset>
        <qandaentry>
	  <question>
	  <para>I thought this was going to be a discussion about
	    modems??!</para>
	  </question>

	  <answer>
	  <para>Ah, you must be thinking of the serial ports on the back
	    of your computer.  We are using <quote>port</quote> here to
	    mean the result of <quote>porting</quote> a program from one
	    version of Unix to another.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para id="ports-patch">What is a patch?</para>
	  </question>

	  <answer>
	  <para>A patch is a small file that specifies how to go from
	    one version of a file to another.  It contains plain text,
	    and basically says things like <quote>delete line 23</quote>,
	    <quote>add these two lines after line 468</quote>, or
	    <quote>change line 197 to this</quote>.  They are also known
	    as diffs because they are generated by the
	    <application>diff</application> program.</para>
	  </answer>
	</qandaentry>

  <indexterm><primary>tarball</primary></indexterm>
	<qandaentry>
	  <question>
	  <para id="ports-tarball">What is all this about
	    tarballs?</para>
	  </question>

	  <answer>
	  <para>It is a file ending in <filename>.tar</filename>, or
	    with variations such as <filename>.tar.gz</filename>,
	    <filename>.tar.Z</filename>, <filename>.tar.bz2</filename>,
	    and even <filename>.tgz</filename>.</para>

	  <para>Basically, it is a directory tree that has been archived
	    into a single file (<filename>.tar</filename>) and
	    optionally compressed (<filename>.gz</filename>).  This
	    technique was originally used for <emphasis>T</emphasis>ape
	    <emphasis>AR</emphasis>chives (hence the name
	    <command>tar</command>), but it is a widely used way of
	    distributing program source code around the Internet.</para>

	  <para>You can see what files are in them, or even extract
            them yourself by using the standard Unix
	    <command>tar</command> program, which comes with the base
	    FreeBSD system, like this:</para>

	  <screen>&prompt.user; <userinput>tar tvzf foobar.tar.gz</userinput>
&prompt.user; <userinput>tar xzvf foobar.tar.gz</userinput>
&prompt.user; <userinput>tar tvf foobar.tar</userinput>
&prompt.user; <userinput>tar xvf foobar.tar</userinput></screen>
	  </answer>
	</qandaentry>

  <indexterm><primary>checksum</primary></indexterm>
	<qandaentry>
	  <question>
	  <para id="ports-checksum">And a checksum?</para>
	  </question>

	  <answer>
	  <para>It is a number generated by adding up all the data in
	    the file you want to check.  If any of the characters
	    change, the checksum will no longer be equal to the total,
	    so a simple comparison will allow you to spot the
	    difference.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I did what you said for compiling ports from a CDROM and
	    it worked great until I tried to install the kermit
	    port.</para>

	  <screen>&prompt.root; <userinput>make install</userinput>
&gt;&gt; cku190.tar.gz doesn't seem to exist on this system.
&gt;&gt; Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.</screen>

	  <para>Why can it not be found?  Have I got a dud CDROM?</para>
	  </question>

	  <answer>
	  <para>As explained in the <link
	    linkend="ports-cd">compiling ports from CDROM</link>
	    section, some ports cannot be put on the CDROM set
	    due to licensing restrictions.  Kermit is an example of
	    that.  The licensing terms for kermit do not allow us to put
	    the tarball for it on the CDROM, so you will have to fetch
	    it by hand&mdash;sorry!</para>

	  <para>The reason why you got all those error messages was
	    because you were not connected to the Internet at the time.
	    Once you have downloaded it from any of the <makevar>MASTER_SITES</makevar>
	    (listed in the <filename>Makefile</filename>), you can restart the install
	    process.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I did that, but when I tried to put it into
	    <filename>/usr/ports/distfiles</filename> I got some error
	    about not having permission.</para>
	  </question>

	  <answer>
	  <para>The ports mechanism will download distribution
	    tarballs into <filename>/usr/ports/distfiles</filename>,
	    but many system administrators will symlink this directory
	    to a remote file server or local read-only CDROM media.
	    If this is the case, then you should specify a different
	    directory to be used for storing distfiles with the
	    following command:</para>

	  <screen>&prompt.root; <userinput>make DISTDIR=<replaceable>/local/dir/with/write/permission</replaceable> install</userinput></screen>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>Does the ports scheme only work if you have everything
	    in <filename>/usr/ports</filename>?  My system administrator
	    says I must put everything under
	    <filename>/u/people/guests/wurzburger</filename>, but it
	    does not seem to work.</para>
	  </question>

	  <answer>
	  <para>You can use the <makevar>PORTSDIR</makevar> and
	    <makevar>PREFIX</makevar> variables to tell the ports
	    mechanism to use different directories.  For
	    instance,</para>

	  <screen>&prompt.root; <userinput>make PORTSDIR=/u/people/guests/wurzburger/ports install</userinput></screen>

	  <para>will compile the port in
	    <filename>/u/people/guests/wurzburger/ports</filename> and
	    install everything under
	    <filename>/usr/local</filename>.</para>

	  <screen>&prompt.root; <userinput>make PREFIX=/u/people/guests/wurzburger/local install</userinput></screen>

	  <para>will compile it in <filename>/usr/ports</filename> and
	    install it in
	    <filename>/u/people/guests/wurzburger/local</filename>.</para>

	  <para>And of course,</para>

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

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

	  <indexterm><primary>imake</primary></indexterm>

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

	  <para>If you do not fancy typing all that in every time you
	    install a port, it is a good idea to put these variables
	    into your environment.  Read the manual page for your shell for
	    instructions on doing so.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I do not have a FreeBSD CDROM, but I would like to have
	    all the tarballs handy on my system so I do not have to wait
	    for a download every time I install a port.  Is there any
	    way to get them all at once?</para>
	  </question>

	  <answer>
	  <para>To get every single tarball for the ports collection,
	    do:</para>

	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make fetch</userinput></screen>

	  <para>For all the tarballs for a single ports directory,
	    do:</para>

	  <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
&prompt.root; <userinput>make fetch</userinput></screen>

	  <para>and for just one port&mdash;well, you have probably
	    guessed already.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I know it is probably faster to fetch the tarballs from
	    one of the FreeBSD mirror sites close by.  Is there any way
	    to tell the port to fetch them from servers other than the
	    ones listed in the <makevar>MASTER_SITES</makevar>?</para>
	  </question>

	  <answer>
	  <para>Yes.  If you know, for example, that <hostid
	    role="fqdn">ftp.FreeBSD.org</hostid> is much closer to you
	    than the sites listed in <makevar>MASTER_SITES</makevar>,
	    do as follows:</para>

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

	<qandaentry>
	  <question>
	  <para>I want to know what files <command>make</command> is
	    going to need before it tries to pull them down.</para>
	  </question>

	  <answer>
	  <para><command>make fetch-list</command> will display a list
	    of the files needed for a port.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>Is there any way to stop the port from compiling?  I
	    want to do some hacking on the source before I install it,
	    but it is a bit tiresome to watch it and hit
	    <keycombo action="simul">
	      <keycap>Ctrl</keycap>
	      <keycap>C</keycap>
	    </keycombo>
	    every time.</para>
	  </question>

	  <answer>
            <para>Doing <command>make extract</command> will stop it
	      after it has fetched and extracted the source code.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I am trying to make my own port and I want to be able
	    to stop it compiling until I have had a chance to see if my
	    patches worked properly.  Is there something like
	    <command>make extract</command>, but for patches?</para>
	  </question>

	  <answer>
	  <para>Yes, <command>make patch</command> is what you want.
	    You will probably find the <makevar>PATCH_DEBUG</makevar>
	    option useful as well.  And by the way, thank you for your
	    efforts!</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I have heard that some compiler options can cause bugs.
	    Is this true?  How can I make sure that I compile ports
	    with the right settings?</para>
	  </question>

	  <answer>
	  <para>Yes, with version 2.6.3 of <command>gcc</command> (the
	    version shipped with FreeBSD 2.1.0 and 2.1.5), the
	    <option>-O2</option> option could result in buggy code
	    unless you used the <option>-fno-strength-reduce</option>
	    option as well.  (Most of the ports do not use
	    <option>-O2</option>).  You <emphasis>should</emphasis> be
	    able to specify the compiler options used by something
	    like:</para>

	  <screen>&prompt.root; <userinput>make CFLAGS='-O2 -fno-strength-reduce' install</userinput></screen>

	  <para>or by editing <filename>/etc/make.conf</filename>, but
	    unfortunately not all ports respect this.  The surest way
	    is to do <command>make configure</command>, then go into
	    the source directory and inspect the Makefiles by hand, but
	    this can get tedious if the source has lots of
	    sub-directories, each with their own Makefiles.</para>

	    <para>The default FreeBSD compiler options are quite conservative, 
	      so if you have not changed them you should not have any
	      problems.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>There are so many ports it is hard to find the one I
	    want.  Is there a list anywhere of what ports are
	    available?</para>
	  </question>

	  <answer>
	  <para>Look in the <filename>INDEX</filename> file in
	    <filename>/usr/ports</filename>.  If you would like to
	    search the ports collection for a keyword, you can do that
	    too.  For example, you can find ports relevant to the LISP
	    programming language using:</para>

	  <screen>&prompt.user; <userinput>cd /usr/ports</userinput>
&prompt.user; <userinput>make search key=lisp</userinput></screen>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I went to install the <literal>foo</literal> port but
	    the system suddenly stopped compiling it and starting
	    compiling the <literal>bar</literal> port.  What is going
	    on?</para>
	  </question>

	  <answer>
	  <para>The <literal>foo</literal> port needs something that is
	    supplied with <literal>bar</literal> &mdash; for instance,
	    if <literal>foo</literal> uses graphics,
	    <literal>bar</literal> might have a library with useful
	    graphics processing routines.  Or <literal>bar</literal>
	    might be a tool that is needed to compile the
	    <literal>foo</literal> port.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para id="ports-remove">  I installed the
	    <literal>grizzle</literal> program from the ports and
	    frankly it is a complete waste of disk space.  I want to
	    delete it but I do not know where it put all the files.
	    Any clues?</para>
	  </question>

	  <answer>
	  <para>No problem, just type:</para>

	  <screen>&prompt.root; <userinput>pkg_delete grizzle-6.5</userinput></screen>

	  <para>Alternatively, you can type:</para>

	  <screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/grizzle</replaceable></userinput>
&prompt.root; <userinput>make deinstall</userinput></screen>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>Hang on a minute, you have to know the version number
	    to use that command.  You do not seriously expect me to
	    remember that, do you?</para>
	  </question>

	  <answer>
	  <para>Not at all, you can find it out by doing:</para>

	  <screen>&prompt.root; <userinput>pkg_info -I 'grizzle*'</userinput>
Information for grizzle-6.5:
grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
arcade game.</screen>

	  <para>The version number can also be found using the 
	    <command>pkg_info</command> or by typing:
	    <command>ls /var/db/pkg</command></para>

	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>Talking of disk space, the ports directory seems to be
	    taking up an awful lot of room.  Is it safe to go in there
	    and delete things?</para>
	  </question>

	  <answer>
	  <para>Yes, if you have installed the program and are fairly
	    certain you will not need the source again, there is no
	    point in keeping it hanging around.  The surest way to do
	    this is:</para>

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

	  <para>which will go through all the ports subdirectories and
	    delete everything except the skeletons for each
	    port.</para>

	  <tip><para>It is possible to achieve the same effect without
		recursively calling each <filename>Makefile</filename>.  For example, you
		can delete all of the <filename>work/</filename> subdirectories directly
		with the following command:
	    <screen>&prompt.root; <userinput>find /usr/ports -depth -name work -exec rm -rf {} \;</userinput></screen></para>
	    </tip>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I tried that and it still left all those tarballs or
	    whatever you called them in the
	    <filename>distfiles</filename> directory.  Can I delete
	    those as well?</para>
	  </question>

	  <answer>
	  <para>Yes, if you are sure you have finished with them,
	     those can go as well.  They can be removed manually, or by
	     using <command>make distclean</command>.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I like having lots and lots of programs to play with.
	    Is there any way of installing all the ports in one
	    go?</para>
	  </question>

	  <answer>
	  <para>Just do:</para>

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

	    <para>Be careful, as some ports may install files with the same
	      name.  If you install two graphics ports and they both install
	      <filename>/usr/local/bin/plot</filename> then you will obviously 
	      have problems.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>OK, I tried that, but I thought it would take a very
	    long time so I went to bed and left it to get on with it.
	    When I looked at the computer this morning, it had only
	    done three and a half ports.  Did something go
	    wrong?</para>
	  </question>

	  <answer>
	  <para>No, the problem is that some of the ports need to ask
	    you questions that we cannot answer for you (e.g., <quote>Do
	    you want to print on A4 or US letter sized paper?</quote>)
	    and they need to have someone on hand to answer
	    them.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I really do not want to spend all day staring at the
	    monitor.  Any better ideas?</para>
	  </question>

	  <answer>
	  <para>OK, do this before you go to bed/work/the local
	    park:</para>

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

	  <para>This will install every port that does
	    <emphasis>not</emphasis> require user input.  Then, when
	    you come back, do:</para>

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

	  <para>to finish the job.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>At work, we are using <literal>frobble</literal>, which
	    is in your ports collection, but we have altered it quite a
	    bit to get it to do what we need.  Is there any way of making
	    our own packages, so we can distribute it more easily around
	    our sites?</para>
	  </question>

	  <answer>
	  <para>No problem, assuming you know how to make patches for
	    your changes:</para>

	  <screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/frobble</replaceable></userinput>
&prompt.root; <userinput>make extract</userinput>
&prompt.root; <userinput>cd work/frobble-2.8</userinput>
[Apply your patches]
&prompt.root; <userinput>cd ../..</userinput>
&prompt.root; <userinput>make package</userinput></screen>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>This ports stuff is really clever.  I am desperate to
	    find out how you did it.  What is the secret?</para>
	  </question>

	  <answer>
	  <para>Nothing secret about it at all, just look at the
	    <filename>bsd.port.mk</filename> and
	    <filename>bsd.port.subdir.mk</filename> files in
	    <filename>/usr/ports/Mk/</filename>.</para>

	  <para>(Readers with an aversion to intricate shell-scripts are
	    advised not to look at the files in this directory.)</para>
	  </answer>
	</qandaentry>
      </qandaset>
    </sect2>

    <sect2 id="ports-broken">
      <title>Help!  This Port Is Broken!</title>

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

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

	<listitem>
	  <para>Gripe&mdash;<emphasis>by email only!</emphasis>  Send
	    email to the maintainer of the port first.  Type <command>make
	    maintainer</command> or read the <filename>Makefile</filename>
	    to find the maintainer's email address.  Remember to include
	    the name and version of the port (send the
	    <literal>&dollar;FreeBSD:</literal> line from the
	    <filename>Makefile</filename>) and the output leading up to the
	    error when you email the maintainer.  If you do not get a
	    response from the maintainer, you can use
	    <command>send-pr</command> to submit a bug report.</para>
	</listitem>

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

</chapter>

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