diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
index 9fa0995c28..a5d0479b5a 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
@@ -1,1138 +1,1254 @@
<!--
The FreeBSD Documentation Project
- $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml,v 1.114 2001/04/12 07:36:08 nik Exp $
+ $FreeBSD: doc/en_US.ISO8859-1/books/handbook/ports/chapter.sgml,v 1.115 2001/04/17 01:37:32 dd Exp $
-->
<chapter id="ports">
<title>Installing Applications: Packages and Ports</title>
<sect1>
<title>Synopsis</title>
<para>There is only so much you can do with FreeBSD. If you are an
operating systems developer then the base system likely contains
everything you need. If that is not what you are planning to do with
FreeBSD then you will probably want to install additional
software—perhaps a web server, or a mail reader, or a graphical
environment such as KDE or GNOME.</para>
<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 4,000 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 <literal>pkg_*</literal> 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 alllow 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 the <literal>pkg_*</literal>
commands.</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 any of the process
involved in compiling software on FreeBSD.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Ports benefits</title>
<listitem>
<para>Packages are normally compiled with conservative options,
because they have to run on the maximum number of systems. By
installing from the port, you can tweak the compilation options to
(for example) generate code that is specific to a 686 processor.</para>
</listitem>
<listitem>
<para>Some packages have compile time options relating to what they
can and can't do. For example, <application>Apache</application>
can be configured with a wide variety of different builtin 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
+ <emphasis>freebsd-ports</emphasis>.</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.
Currently there are over 4,000 applications available as packages or
ports. 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="http://www.FreeBSD.org/ports/">http://www.FreeBSD.org/ports/</ulink>.
The name space is divided in to 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>
<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 e-mail when they are updated.</para>
</listitem>
<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>)
or AppWatch
(<ulink url="http://www.appwatch.com/">http://www.appwatch.com/</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>
- <title>* Using the Packages System</title>
+ <sect1 id="packages-using">
+ <title>Using the Packages System</title>
+ <para><emphasis>Contributed by &a.chern;, April 30, 2001.</emphasis>
+ </para>
<sect2>
<title>Installing a Package</title>
- <para>After you have decided which application you want to install you
- need to download the package file and install it.</para>
-
- <para>There are several ways you can do this.</para>
+ <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 and installing in multiple steps</title>
-
- <para></para>
+ <title>Downloading a package and then installing it locally</title>
+
+ <screen>&prompt.root; <userinput>ftp <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.
+ftp> <userinput>cd /pub/FreeBSD/ports/packages/irc</userinput>
+250 CWD command successful.
+ftp> <userinput>get xchat-1.7.1.tgz</userinput>
+local: xchat-1.7.1.tgz remote: xchat-1.7.1.tgz
+150 Opening BINARY mode data connection for 'xchat-1.7.1.tgz' (471488 bytes).
+100% |**************************************************| 460 KB 00:00 ETA
+226 Transfer complete.
+471488 bytes received in 5.37 seconds (85.70 KB/s)
+ftp> <userinput>exit</userinput>
+&prompt.root; <userinput>pkg_add <replaceable>xchat-1.7.1.tgz</replaceable></userinput>
+&prompt.root;
+ </screen>
</example>
+
+ <para>If you don't have a source of local packages (such as a
+ FreeBSD CD-ROM set) then it will probably be easier to use the
+ -r 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>
+
+ <screen>&prompt.root; <userinput>pkg_add -r <replaceable>xchat-1.7.1</replaceable></userinput>
+ </screen>
+
+ <para>This 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/ports/packages">ftp://ftp.freebsd.org/ports/packages</ulink>,
+ or on the FreeBSD CD-ROM 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 homologous
+ 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>
-
- <para></para>
+ <screen>&prompt.root <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput>
+&prompt.root
+ </screen>
+ <para>&man.pkg.delete.1; is the utility for removing
+ previously installed software package distributions.
+ </para>
</sect2>
<sect2>
- <title>Updating a Package</title>
+ <title>Managing packages</title>
+
+ <para>&man.pkg.info.1; a utility that lists and describes
+ the various packages installed.
+ </para>
- <para></para>
+ <screen>&prompt.root <userinput>pkg_info</userinput>
+cvsup-bin-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; 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>
+ <screen>&prompt.root <userinput>pkg_version</userinput>
+cvsup-bin =
+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>
+ <tgroup cols="2">
+ <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><</entry>
+ <entry>The installed version is older then the one available
+ in the ports tree.</entry>
+ </row>
+
+ <row><entry>></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></title>
-
- <para></para>
+ <title>Miscellaneous</title>
+ <para>&man.pkg.add.1; &man.pkg.delete.1; &man.pkg.info.1;
+ &man.pkg.version.1; &man.pkg.create.1;
+ </para>
+ <para>All package information is stored within the
+ <filename>/var/db/pkg</filename> directory. The listing
+ of contents 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-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>distinfo</filename> file. This file contains
information about the files that must be downloaded to build the
port, and checksums, to ensure that that files have not been
corrupted during the download.</para>
</listitem>
<listitem>
<para>A <filename>files</filename> directory. This directory
contains patches to make the program compile and install on
your FreeBSD system. Patches are basically small files that
specify changes to particular files. They are in plain text
format, and basically say <quote>Remove line 10</quote> or
<quote>Change line 26 to this ...</quote>. Patches are also
known as <quote>diffs</quote> because they are generated by the
<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>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 <program you want to
install></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>
>> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system.
>> Attempting to fetch from file:/cdrom/ports/distfiles/.
===> Extracting for xchat-1.3.8
>> Checksum OK for xchat-1.3.8.tar.bz2.
===> xchat-1.3.8 depends on executable: bzip2 - found
===> xchat-1.3.8 depends on executable: gmake - found
===> xchat-1.3.8 depends on shared library: gtk12.2 - found
===> xchat-1.3.8 depends on shared library: Imlib.5 - found
===> xchat-1.3.8 depends on shared library: X11.6 - found
===> Patching for xchat-1.3.8
===> Applying FreeBSD patches for xchat-1.3.8
===> Configuring for xchat-1.3.8
...
[configure output snipped]
...
===> 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>
===> Installing for xchat-1.3.8
===> xchat-1.3.8 depends on shared library: gtk12.2 - found
===> xchat-1.3.8 depends on shared library: Imlib.5 - found
===> xchat-1.3.8 depends on shared library: X11.6 - found
...
[install routines snipped]
...
===> Generating temporary packing list
===> Installing xchat docs in /usr/X11R6/share/doc/xchat
===> 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>
>> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system.
>> 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)
===> Extracting for xchat-1.3.8
>> Checksum OK for xchat-1.3.8.tar.bz2.
===> xchat-1.3.8 depends on executable: bzip2 - found
===> xchat-1.3.8 depends on executable: gmake - found
===> xchat-1.3.8 depends on shared library: gtk12.2 - found
===> xchat-1.3.8 depends on shared library: Imlib.5 - found
===> xchat-1.3.8 depends on shared library: X11.6 - found
===> Patching for xchat-1.3.8
===> Applying FreeBSD patches for xchat-1.3.8
===> Configuring for xchat-1.3.8
...
[configure output snipped]
...
===> Building for xchat-1.3.8
...
[compilation snipped]
...
===> Installing for xchat-1.3.8
===> xchat-1.3.8 depends on shared library: gtk12.2 - found
===> xchat-1.3.8 depends on shared library: Imlib.5 - found
===> xchat-1.3.8 depends on shared library: X11.6 - found
...
[install routines snipped]
...
===> Generating temporary packing list
===> Installing xchat docs in /usr/X11R6/share/doc/xchat
===> 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>
===> 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 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>
>> cku190.tar.gz doesn't seem to exist on this system.
>> 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—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>Some ports that use &man.imake.1; (a part of the X Windows
System) don't 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 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—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 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> — 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—<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—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:
-->