path: root/en_US.ISO8859-1/books/handbook/ports/chapter.sgml

<!--
     The FreeBSD Documentation Project

     $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml,v 1.110 2000/06/09 18:08:44 nik Exp $
-->

<chapter id="ports">
  <title>Installing Applications: The Ports collection</title>

  <para><emphasis>Rewritten by &a.jim;, 22 November 1999.  Original work
    by various people.</emphasis></para>

  <sect1>
    <title>Synopsis</title>

    <para>The FreeBSD Ports collection allows you to compile and install a
      very wide range of applications with a minimum amount of
      effort.</para>

    <para>In general, it is a group of <link
      linkend="ports-skeleton">skeletons</link>
      which contain a minimal set of items needed to make an application
      compile and install cleanly on FreeBSD.</para>

    <para>Even with all the hype about open standards, getting a program
      to compile on various UNIX platforms can be a tricky task.
      Occasionally, you might be lucky enough to find that the program you
      want compiles cleanly on  your system, install everything into all
      the right directories, and run flawlessly
      <quote>out-of-the-box</quote>, but this behavior is somewhat rare.
      Most of the time, you find yourself needing to make modifications in
      order to get the program to work.  This is where the FreeBSD Ports
      collection comes to the rescue.</para>

    <para>The general idea behind the Ports collection is to eliminate all
      of the messy steps involved with making things work properly so that
      the installation is simple and very painless.  With the Ports
      collection, all of the hard work has already been done for you, and
      you are able to install any of the Ports collection ports by simply
      typing <command>make install</command>.</para>
  </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-skeleton">
      <title>Installing Ports</title>

      <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 are needed for a program to compile and
	install cleanly on FreeBSD.  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>files</filename> directory.  The
	    <filename>files</filename> directory contains a file named
	    <filename>md5</filename>.  This file is named after the MD5
	    algorithm used to determine ports checksums.  A checksum is a
	    number generated by adding up all the data in the file you
	    want to check.  If any characters change, the checksum will
	    differ from the original and an error message will be
	    displayed so you are able to investigate the changes.</para>

	  <para>The <filename>files</filename> directory can also contain
	    other files that are required by the port but do not belong
	    elsewhere in the directory structure.</para>
	</listitem>

	<listitem>
	  <para>A <filename>patches</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>
	</listitem>

	<listitem>
	  <para>A <filename>pkg</filename> directory.  This directory
	    normally contains three files.  Occasionally, there will be
	    more than three, but it depends on the port.  Most only
	    require three.  The files are:</para>

	  <itemizedlist>
	    <listitem>
	      <para><filename>COMMENT</filename>.  This is a one-line
	        description of the program.</para>
	    </listitem>

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

	    <listitem>
	      <para><filename>PLIST</filename>.  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>
	</listitem>
      </itemizedlist>

      <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="http://www.freebsd.org/ports/">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.  To use <command>whereis</command>, simply type
	<quote><command>whereis &lt;program you want to
	install&gt;</command></quote> at the prompt, and if it is found on
        your system, you will be told where it is, like so:</para>

      <screen>&prompt.root; <userinput>whereis xchat</userinput>
xchat: /usr/ports/irc/xchat
&prompt.root;</screen>

      <para>This tells us that xchat (an irc client) can be found in the
        <filename>/usr/ports/irc/xchat</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 key=program-name</command>
	where <quote>program-name</quote> is the name of the program you
	want to find.  For example, if you were looking for xchat:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make search key=xchat</userinput>
Port:   xchat-1.3.8
Path:   /usr/ports/irc/xchat
Info:   An X11 IRC client using the GTK+ toolkit, and optionally, GNOME
Maint:  jim@FreeBSD.org
Index:  irc
B-deps: XFree86-3.3.5 bzip2-0.9.5d gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gmake-3.77 gtk-1.2.6
		imlib-1.9.8 jpeg-6b png-1.0.3 tiff-3.5.1
R-deps: XFree86-3.3.5 gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gtk-1.2.6 imlib-1.9.8 jpeg-6b
		png-1.0.3 tiff-3.5.1</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>

      <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.</para>

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

        <para>As you may have guessed from the title, everything
	  described in this section assumes you have a FreeBSD CDROM set.
	  If you do not, you can order one from the <ulink
	  url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>.</para>

        <para>Assuming that your FreeBSD CDROM is in the drive and is
	  mounted on <filename>/cdrom</filename> (and the mount point
	  <emphasis>must</emphasis> be <filename>/cdrom</filename>),
	  you are ready to install the port.  To begin, change directories
	  to the directory where the port you want to install lives:</para>

        <screen>&prompt.root; <userinput>cd /usr/ports/irc/xchat</userinput></screen>

        <para>Once inside the xchat 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; xchat-1.3.8.tar.bz2 doesn't seem to exist on this system.
&gt;&gt; Attempting to fetch from file:/cdrom/ports/distfiles/.
===&gt;  Extracting for xchat-1.3.8
&gt;&gt; Checksum OK for xchat-1.3.8.tar.bz2.
===&gt;   xchat-1.3.8 depends on executable: bzip2 - found
===&gt;   xchat-1.3.8 depends on executable: gmake - found
===&gt;   xchat-1.3.8 depends on shared library: gtk12.2 - found
===&gt;   xchat-1.3.8 depends on shared library: Imlib.5 - found
===&gt;   xchat-1.3.8 depends on shared library: X11.6 - found
===&gt;  Patching for xchat-1.3.8
===&gt;  Applying FreeBSD patches for xchat-1.3.8
===&gt;  Configuring for xchat-1.3.8
...
[configure output snipped]
...
===&gt;  Building for xchat-1.3.8
...
[compilation 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 xchat-1.3.8
===&gt;   xchat-1.3.8 depends on shared library: gtk12.2 - found
===&gt;   xchat-1.3.8 depends on shared library: Imlib.5 - found
===&gt;   xchat-1.3.8 depends on shared library: X11.6 - found
...
[install routines snipped]
...
===&gt;   Generating temporary packing list
===&gt;   Installing xchat docs in /usr/X11R6/share/doc/xchat
===&gt;   Registering installation for xchat-1.3.8
&prompt.root;</screen>

        <para>Once you are returned to your prompt, you should be able to
          run the application you just installed.</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 for various
	    reasons, including things such as as registration form needs
	    to be filled out before downloading, if 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 do 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 program's source
	  code 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; xchat-1.3.8.tar.bz2 doesn't seem to exist on this system.
&gt;&gt; Attempting to fetch from http://xchat.org/files/v1.3/.
Receiving xchat-1.3.8.tar.bz2 (305543 bytes): 100%
305543 bytes transferred in 2.9 seconds  (102.81 Kbytes/s)
===&gt;  Extracting for xchat-1.3.8
&gt;&gt; Checksum OK for xchat-1.3.8.tar.bz2.
===&gt;   xchat-1.3.8 depends on executable: bzip2 - found
===&gt;   xchat-1.3.8 depends on executable: gmake - found
===&gt;   xchat-1.3.8 depends on shared library: gtk12.2 - found
===&gt;   xchat-1.3.8 depends on shared library: Imlib.5 - found
===&gt;   xchat-1.3.8 depends on shared library: X11.6 - found
===&gt;  Patching for xchat-1.3.8
===&gt;  Applying FreeBSD patches for xchat-1.3.8
===&gt;  Configuring for xchat-1.3.8
...
[configure output snipped]
...
===&gt;  Building for xchat-1.3.8
...
[compilation snipped]
...
===&gt;  Installing for xchat-1.3.8
===&gt;   xchat-1.3.8 depends on shared library: gtk12.2 - found
===&gt;   xchat-1.3.8 depends on shared library: Imlib.5 - found
===&gt;   xchat-1.3.8 depends on shared library: X11.6 - found
...
[install routines snipped]
...
===&gt;   Generating temporary packing list
===&gt;   Installing xchat docs in /usr/X11R6/share/doc/xchat
===&gt;   Registering installation for xchat-1.3.8
&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 section you will learn how to remove a port from your
          system.</para>
      </sect3>
    </sect2>

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

      <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.  The next
	few paragraphs will cover just that.</para>

      <para>Now we will remove our previous example (which was xchat for
        those of you not paying attention).  As with installing ports,
	the first thing you must do is change to the port directory,
	which if you remember was
	<filename>/usr/ports/irc/xchat</filename>.  After you change
	directories, you are ready to uninstall xchat.  This is done with
	the <command>make deinstall</command> command (makes sense
	right?):</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/irc/xchat</userinput>
&prompt.root; <userinput>make deinstall</userinput>
===&gt;  Deinstalling for xchat-1.3.8
&prompt.root;</screen>

      <para>That was easy enough.  You have now managed to remove xchat
        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/irc/xchat</filename> directory.</para>
    </sect2>
  </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>I thought you were supposed to use packages to install
	    extra programs?</para>
	  </question>

	  <answer>
	  <para>Yes, that is usually the quickest and easiest way of
	    doing it.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>So why bother with ports then?</para>
	  </question>

	  <answer>
	  <para>Several reasons:</para>

	  <orderedlist>
	    <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>You might have opinions on how a program should be
	        compiled that differ from the person who did the
		package&mdash;some people have strong views on what
		optimization settings should be used, whether to build
		debug versions and then strip them or not, and so on.</para>
	    </listitem>

	      <listitem>
		<para>Packages are normally built with quite conservative
		  settings.  If a port has a compilation option to use code
		  for a specific processor, or a particular add-on board you
		  can enable this yourself in the port, without the people
		  making the package having to produce many, many different
		  packaged versions.</para>

		<para>The most obvious exception to this rule is paper sizes.
		  If a package can be provided with default support for
		  different paper sizes we will often provide multiple
		  packages, one per paper size.</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>

	    <listitem>
	      <para>If you ain't got the source, it ain't software!
		<!-- smiley -->;-)</para>
	    </listitem>
	  </orderedlist>
	  </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>

	<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 tar 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>

	<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 was 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 MASTER_SITES
	    (listed in the Makefile), 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 looks for the tarball in
	    <filename>/usr/ports/distfiles</filename>, but you will not
	    be able to copy anything there because it is symlinked to
	    the CDROM, which is read-only.  You can tell it to look
	    somewhere else by doing:</para>

	  <screen>&prompt.root; <userinput>make DISTDIR=<replaceable>/where/you/put/it</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>

	  <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 man 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, I think you have
	    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 MASTER_SITES?</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 control-C 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>Yep, <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 do:</para>

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

	  <para>Alternatively, you can do:</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 -a | grep grizzle</userinput>
Information for grizzle-6.5:
grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
arcade game.</screen>
	  </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 best 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>
	  </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 -DIS_INTERACTIVE 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 your
	    <ulink url="file://localhost/usr/ports/Mk/">makefiles
	    directory.</ulink></para>

	  <para>(Readers with an aversion to intricate shell-scripts are
	    advised not to follow this link...)</para>
	  </answer>
	</qandaentry>
      </qandaset>
    </sect2>

    <sect2 id="ports-broken">
      <title>Help!  This port is broken!</title>

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

      <orderedlist>
        <listitem>
	  <para>Fix it!  The <link linkend="porting"><quote>how to make a
	    port</quote></link> section should help you do this.</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>$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>Forget about it.  This is the easiest route&mdash;very
	  few ports can be classified as <quote>essential</quote>.  There's
	  also a good chance any problems will be fixed in the next
	  version when the port is updated.</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>

  <sect1 id="porting">
    <title>Advanced Topics</title>

    <para>The documentation that was here has been moved to its own <ulink
	url="../porters-handbook/index.html">Porter's Handbook</ulink> for ease of
      reference.  Please go there if you wish to create and submit your own
      ports.</para>
  </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:
-->