<?xml version="1.0" encoding="iso-8859-1"?>
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="ports">
<title>Installing Applications: Packages and Ports</title>
<sect1 id="ports-synopsis">
<title>Synopsis</title>
<indexterm><primary>ports</primary></indexterm>
<indexterm><primary>packages</primary></indexterm>
<para>&os; 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. &os; provides two
complementary technologies for installing third-party software:
the &os; Ports Collection (for installing from source), and
packages (for installing from pre-built binaries). Either
method may be used to install software from local media or
from the network.</para>
<para>After reading this chapter, you will know how to:</para>
<itemizedlist>
<listitem>
<para>Install third-party binary software packages.</para>
</listitem>
<listitem>
<para>Build third-party software from source by using the
Ports Collection.</para>
</listitem>
<listitem>
<para>Remove previously installed packages or ports.</para>
</listitem>
<listitem>
<para>Override the default values used by the Ports
Collection.</para>
</listitem>
<listitem>
<para>Find the appropriate software package.</para>
</listitem>
<listitem>
<para>Upgrade installed software.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="ports-overview">
<title>Overview of Software Installation</title>
<para>The typical steps for installing third-party software on a
&unix; system include:</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 &man.compress.1;,
&man.gzip.1;, or &man.bzip2.1;).</para>
</step>
<step>
<para>Locate the documentation in
<filename>INSTALL</filename>, <filename>README</filename>
or some file 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>If you are installing a software package that was not
deliberately ported to &os; you may even have to go in and edit
the code to make it work properly.</para>
<para>&os; provides two technologies which perform these steps for
you. At the time of writing, over &os.numports; third-party
applications are available.</para>
<para>A &os; package contains pre-compiled copies of all the
commands for an application, as well as any configuration files
and documentation. A package can be manipulated with &os;
package management commands, such as &man.pkg.add.1;,
&man.pkg.delete.1;, and &man.pkg.info.1;.</para>
<para>A &os; port is a collection of files designed to automate
the process of compiling an application from source code. The
files that comprise a port contain all the necessary information
to automatically download, extract, patch, compile, and install
the application.</para>
<para>The ports system can also be used to generate packages which
can be manipulated with the &os; package management
commands.</para>
<para>Both packages and ports understand
<emphasis>dependencies</emphasis>. If &man.pkg.add.1; or the
Ports Collection is used to install an application and a
dependent library is not already installed, the library will
automatically be installed first.</para>
<para>While the two technologies are quite similar, packages and
ports each have their own strengths. Select the technology that
meets your requirements for installing a particular
application.</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 compilation time. For large
applications, such as
<application>Mozilla</application>,
<application>KDE</application>, or
<application>GNOME</application> this can be important,
on a slow system.</para>
</listitem>
<listitem>
<para>Packages do not require any understanding of the process
involved in compiling software on &os;.</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 compiling from the port, one can change the
compilation options.</para>
</listitem>
<listitem>
<para>Some applications have compile-time options relating to
which features are installed. For example,
<application>Apache</application> can be configured with a
wide variety of different built-in options.</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 <application>Xorg</application> is installed.
Creating multiple packages 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 forbid binary
distribution. These must be distributed as source code
which must be compiled by the end-user.</para>
</listitem>
<listitem>
<para>Some people do not trust binary distributions or prefer
to read through source code in order to look for potential
problems.</para>
</listitem>
<listitem>
<para>If you have local patches, you will need the source in
order to apply them.</para>
</listitem>
</itemizedlist>
<para>To keep track of updated ports, subscribe to the
&a.ports; and the &a.ports-bugs;.</para>
<warning>
<para>Before installing any application, check <ulink
url="http://vuxml.freebsd.org/"></ulink> for security issues
related to the application or install <filename
role="package">ports-mgmt/portaudit</filename>. Once
installed, type <command>portaudit -F -a</command> to check
all installed applications for known vulnerabilities.</para>
</warning>
<para>The remainder of this chapter explains how to use packages
and ports to install and manage third-party software on
&os;.</para>
</sect1>
<sect1 id="ports-finding-applications">
<title>Finding Software</title>
<para>&os;'s list of available applications is growing all the
time. There are a number of ways to find software to
install:</para>
<itemizedlist>
<listitem>
<para>The &os; web site maintains an up-to-date searchable
list of all the available applications, at <ulink
url="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>.
The ports can be searched by application name or by
software category.</para>
</listitem>
<listitem>
<indexterm><primary>FreshPorts</primary></indexterm>
<para>Dan Langille maintains <ulink
url="http://www.FreshPorts.org/">FreshPorts</ulink> which
provides a comprehensive search utility and also tracks
changes to the applications in the Ports Collection.
Registered users can create a customized watch list in order
to receive an automated email when their watched ports are
updated.</para>
</listitem>
<listitem>
<indexterm><primary>Freecode</primary></indexterm>
<para>If you do not know the name of the application you want,
try using a site like Freecode (<ulink
url="http://www.freecode.com/"></ulink>) to find an
application, then check back at the &os; site to see if
the application has been ported yet.</para>
</listitem>
<listitem>
<para>To find out which category a port is in, type
<command>whereis <replaceable>file</replaceable></command>,
where <replaceable>file</replaceable> is the program to be
installed:</para>
<screen>&prompt.root; <userinput>whereis lsof</userinput>
lsof: /usr/ports/sysutils/lsof</screen>
<para>Alternately, an &man.echo.1; statement can be
used:</para>
<screen>&prompt.root; <userinput>echo /usr/ports/*/*lsof*</userinput>
/usr/ports/sysutils/lsof</screen>
<para>Note that this will return any matched files downloaded
into the <filename
class="directory">/usr/ports/distfiles</filename>
directory.</para>
</listitem>
<listitem>
<para>Another way to find software is by using the Ports
Collection's built-in search mechanism. To use
the search feature, <application>cd</application> to
<filename>/usr/ports</filename> then run <command>make
<maketarget>search</maketarget>
name=<replaceable>program-name</replaceable></command>
where <replaceable>program-name</replaceable> is the name of
the software. For example, to search 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>
<tip>
<para><command>make search</command> searches through a file
of index information. If a message indicates the
<filename>INDEX</filename> is required, run
<command>make fetchindex</command> to download the current
index file. With the <filename>INDEX</filename> present,
<command>make search</command> will be able to perform the
requested search.</para>
</tip>
<para>The <quote>Path:</quote> line indicates where to find
the port.</para>
<para>To receive less information, use the
<command>quicksearch</command> feature:</para>
<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make quicksearch name=lsof</userinput>
Port: lsof-4.87.a,7
Path: /usr/ports/sysutils/lsof
Info: Lists information about open files (similar to fstat(1))</screen>
<para>For more in-depth searching, use
<command>make <maketarget>search</maketarget>
key=<replaceable>string</replaceable></command> or
<command>make <maketarget>quicksearch</maketarget>
key=<replaceable>string</replaceable></command>, where
<replaceable>string</replaceable> is some text to search
for. The text can be in comments, descriptions, or dependencies
in order to find ports which relate to a particular subject
when the name of the program is unknown.</para>
<para>When using (<maketarget>search</maketarget> and
<maketarget>quicksearch</maketarget>), the search string
is case-insensitive. Searching for <quote>LSOF</quote> will
yield the same results as searching for
<quote>lsof</quote>.</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 Binary Packages</title>
<para>At the present time, &os; is transitioning toward a new
method of package management. Users of the latest releases
may wish to investigate the benefits of using
<link linkend="pkgng-intro">PKGng</link> to manage third
party software on &os;. For those not yet migrated to the
<application>pkgng</application> tool, the tools discussed
here may be used for managing the package database. For
simplicity, the <command>sysinstall</command> utility is
also available post-install for package management.</para>
<para>All package installation files are stored in the
package database directory,
<filename class="directory">/var/db/pkg</filename>.</para>
<sect2>
<title>Installing a Package</title>
<indexterm>
<primary>packages</primary>
<secondary>installing</secondary>
</indexterm>
<indexterm>
<primary><command>pkg_add</command></primary>
</indexterm>
<para>Use &man.pkg.add.1; to install a &os; binary package from
a local file or from a server on the network.</para>
<example>
<title>Downloading a Package Manually and 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
&os; CD-ROM set, include <option>-r</option> with
&man.pkg.add.1;. This automatically determines the correct
object format and release, and then fetches and installs the
package from an FTP site without any further user
intervention.</para>
<indexterm>
<primary><command>pkg_add</command></primary>
</indexterm>
<screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen>
<para>To specify an alternative &os; FTP mirror, specify the
mirror in the <envar>PACKAGESITE</envar> environment variable.
&man.pkg.add.1; uses &man.fetch.3; to download files, which
uses various environment variables, including
<envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and
<envar>FTP_PASSWORD</envar>. You may need to set one or more
of these if you are behind a firewall, or need to use an
FTP/HTTP proxy. See &man.fetch.3; for the complete list of variables.
Note that in the example above <literal>lsof</literal> is used
instead of <literal>lsof-4.56.4</literal>. When the remote
fetching feature is used, the version number of the package
must be removed.</para>
<note>
<para>&man.pkg.add.1; will automatically download the latest
version of the application if you are using &os.current; or
&os.stable;. If you run a -RELEASE version, it instead
installs the version of the package that was built with that
release. It is possible to change this behavior by
overriding <envar>PACKAGESITE</envar>. For example, on a
&os; 8.1-RELEASE system, by default &man.pkg.add.1;
will try to fetch packages from
<literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8.1-release/Latest/</literal>.
To force &man.pkg.add.1; to download &os; 8-STABLE
packages, set <envar>PACKAGESITE</envar> to
<literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8-stable/Latest/</literal>.</para>
</note>
<para>Package files are distributed in <filename>.tgz</filename>
and <filename>.tbz</filename> formats. Packages are
available from <ulink
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>,
or the <filename>/packages</filename> directory of the &os;
DVD distribution. The layout of the packages directory 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>
</sect2>
<sect2>
<title>Managing Packages</title>
<indexterm>
<primary>packages</primary>
<secondary>managing</secondary>
</indexterm>
<para>&man.pkg.info.1; can be used to list and describe
installed packages:</para>
<indexterm>
<primary><command>pkg_info</command></primary>
</indexterm>
<screen>&prompt.root; <userinput>pkg_info</userinput>
colordiff-1.0.13 A tool to colorize diff output
docbook-1.2 Meta-port for the different versions of the DocBook DTD
...</screen>
<para>&man.pkg.version.1; summarizes the versions of all
installed packages and 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>
colordiff =
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" pgwide="1">
<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 the
one in the local ports tree.</entry>
</row>
<row>
<entry><</entry>
<entry>The version of the installed package is older
than the one in the local ports tree.</entry>
</row>
<row>
<entry>></entry>
<entry>The version of the installed package is newer
than the one in the local ports tree, meaning
that the local ports tree is probably out of
date.</entry>
</row>
<row>
<entry>?</entry>
<entry>The installed package cannot be found in the
ports index. This can happen when an installed port
is removed from the Ports Collection or is
renamed.</entry>
</row>
<row>
<entry>*</entry>
<entry>There are multiple versions of the
package.</entry>
</row>
<row>
<entry>!</entry>
<entry>The installed package exists in the index but for
some reason, <command>pkg_version</command> was unable
to compare the version number of the installed package
with the corresponding entry in the index.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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
&man.pkg.delete.1;:</para>
<screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>
<para>Note that &man.pkg.delete.1; requires the full package
name and number; the above command would not work if
<replaceable>xchat</replaceable> was given instead of
<replaceable>xchat-1.7.1</replaceable>. Use
&man.pkg.version.1; to find the version of the
installed package, or use a wildcard:</para>
<screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat\*</replaceable></userinput></screen>
<para>in this case, all packages whose names start with
<literal>xchat</literal> will be deleted.</para>
</sect2>
</sect1>
<sect1 id="pkgng-intro">
<title>Using <application>pkgng</application> for Binary Package
Management</title>
<para><application>pkgng</application> is an improved replacement
for the traditional &os; package management tools, offering
many features that make dealing with binary packages faster and
easier. The first release of <application>pkgng</application>
was in August, 2012.</para>
<para><application>pkgng</application> is not a replacement for
port management tools like <filename
role="package">ports-mgmt/portmaster</filename> or <filename
role="package">ports-mgmt/portupgrade</filename>. While
<filename role="package">ports-mgmt/portmaster</filename> and
<filename role="package">ports-mgmt/portupgrade</filename> can
install third-party software from both binary packages and the
Ports Collection, <application>pkgng</application> installs
only binary packages.</para>
<sect2 id="pkgng-initial-setup">
<title>Getting Started with
<application>pkgng</application></title>
<para>&os; 9.1 and later includes a "bootstrap"
utility for <application>pkgng</application>. The bootstrap
utility will download and install
<application>pkgng</application>.</para>
<para>To bootstrap the system, run:</para>
<screen>&prompt.root; <userinput>/usr/sbin/pkg</userinput></screen>
<para>For earlier &os; versions,
<application>pkgng</application> must be installed from the
Ports Collection, or as a binary package.</para>
<para>To install the <application>pkgng</application> port,
run:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/pkg</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
<para>To install the binary package, run:</para>
<screen>&prompt.root; <userinput>pkg_add -r pkg</userinput></screen>
<para>Existing &os; installations require conversion of the
<application>pkg_install</application> package database to the
new format. To convert the package database, run:</para>
<screen>&prompt.root; <userinput>pkg2ng</userinput></screen>
<para>This step is not required for new installations that do
not have third-party software installed.</para>
<important>
<para>This step is not reversible. Once the package database
has been converted to the <application>pkgng</application>
format, the <application>pkg_install</application> tools
should not be used.</para>
</important>
<note>
<para>The package database conversion may emit errors as the
contents are converted to the new version. Generally, these
errors can be safely ignored, however a list of third-party
software that was not successfully converted will be listed
after <command>pkg2ng</command> has finished. These must be
fixed by hand.</para>
</note>
<para>To ensure the &os; Ports Collection registers new
software with <application>pkgng</application>, and not
<application>pkg_install</application>, &os; versions earlier
than 10.<replaceable>X</replaceable> require this line in
<filename>/etc/make.conf</filename>:</para>
<programlisting>WITH_PKGNG= yes</programlisting>
</sect2>
<sect2 id="pkgng-pkg-conf">
<title>Configuring the <application>pkgng</application>
Environment</title>
<para>The <application>pkgng</application> package management
system uses a package repository for most operations. The
default package repository location is defined in
<filename>/usr/local/etc/pkg.conf</filename> or the
<envar>PACKAGESITE</envar> environment variable, which
overrides the configuration file.</para>
<para>Additional <application>pkgng</application>
configuration options are described in
pkg.conf(5).</para>
</sect2>
<sect2 id="pkgng-basic-usage">
<title>Basic <application>pkgng</application> Operations</title>
<para>Usage information for <application>pkgng</application> is
available in the pkg(8) manual page, or by running
<command>pkg</command> without additional arguments.</para>
<para>Each <application>pkgng</application> command argument is
documented in a command-specific manual page. To read the
manual page for <command>pkg install</command>, for example,
run either:</para>
<screen>&prompt.root; <userinput>pkg help install</userinput></screen>
<screen>&prompt.root; <userinput>man pkg-install</userinput></screen>
<sect3 id="pkgng-pkg-info">
<title>Obtaining Information About Installed Packages with
<application>pkgng</application></title>
<para>Information about the packages installed on a system can
be viewed by running <command>pkg info</command>. Similar
to &man.pkg.info.1;, the package version and
description for all packages will be listed.</para>
<para>Information about a specific package is available by
running:</para>
<screen>&prompt.root; <userinput>pkg info <replaceable>packagename</replaceable></userinput></screen>
<para>For example, to see which version of
<application>pkgng</application> is installed on the system,
run:</para>
<screen>&prompt.root; <userinput>pkg info pkg</userinput>
pkg-1.0.2 New generation package manager</screen>
</sect3>
<sect3 id="pkgng-installing-deinstalling">
<title>Installing and Removing Packages with
<application>pkgng</application></title>
<para>In general, most &os; users will install binary packages
by running:</para>
<screen>&prompt.root; <userinput>pkg install <replaceable>packagename</replaceable></userinput></screen>
<para><command>pkg install</command> uses repository data, as
mentioned in <xref linkend="pkgng-pkg-conf"/>. Conversely,
pkg-add(8) does not use repository data, nor does it use the
defined <envar>PACKAGESITE</envar>, so dependencies may not
be properly tracked, and missing dependencies will not be
fetched from a remote source. This section covers usage of
<command>pkg install</command>. For information on usage of
<command>pkg add</command>, see pkg-add(8).</para>
<para>Additional binary packages can be installed with
<command>pkg install</command>. For example, to install
<application>curl</application>:</para>
<screen>&prompt.root; <userinput>pkg install curl</userinput>
Updating repository catalogue
Repository catalogue is up-to-date, no need to fetch fresh copy
The following packages will be installed:
Installing ca_root_nss: 3.13.5
Installing curl: 7.24.0
The installation will require 4 MB more space
1 MB to be downloaded
Proceed with installing packages [y/N]: <userinput>y</userinput>
ca_root_nss-3.13.5.txz 100% 255KB 255.1KB/s 255.1KB/s 00:00
curl-7.24.0.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
Checking integrity... done
Installing ca_root_nss-3.13.5... done
Installing curl-7.24.0... done</screen>
<para>The new package and any additional packages that were
installed as dependencies can be seen in the installed
packages list:</para>
<screen>&prompt.root; <userinput>pkg info</userinput>
ca_root_nss-3.13.5 The root certificate bundle from the Mozilla Project
curl-7.24.0 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
pkg-1.0.2 New generation package manager</screen>
<para>Packages that are no longer needed can be removed with
<command>pkg delete</command>. For example, if it turns out
that <application>curl</application> is not needed after
all:</para>
<screen>&prompt.root; <userinput>pkg delete curl</userinput>
The following packages will be deleted:
curl-7.24.0_1
The deletion will free 3 MB
Proceed with deleting packages [y/N]: <userinput>y</userinput>
Deleting curl-7.24.0_1... done</screen>
</sect3>
<sect3 id="pkgng-upgrading">
<title>Upgrading Installed Packages with
<application>pkgng</application></title>
<para>Packages that are outdated can be found with
<command>pkg version</command>. If a local ports tree
does not exist, pkg-version(8) will use the remote
repository catalogue, otherwise the local ports tree will
be used to identify package versions.</para>
<para>Packages can be upgraded to newer versions with
<application>pkgng</application>. Suppose a new version of
<application>curl</application> has been released. The
local package can be upgraded to the new version:</para>
<screen>&prompt.root; <userinput>pkg upgrade</userinput>
Updating repository catalogue
repo.txz 100% 297KB 296.5KB/s 296.5KB/s 00:00
The following packages will be upgraded:
Upgrading curl: 7.24.0 -> 7.24.0_1
1 MB to be downloaded
Proceed with upgrading packages [y/N]: <userinput>y</userinput>
curl-7.24.0_1.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
Checking integrity... done
Upgrading curl from 7.24.0 to 7.24.0_1... done</screen>
</sect3>
<sect3 id="pkgng-auditing">
<title>Auditing Installed Packages with
<application>pkgng</application></title>
<para>Occasionally, software vulnerabilities may be discovered
in software within the Ports Collection.
<application>pkgng</application> includes built-in auditing,
similar to the <filename
role="package">ports-mgmt/portaudit</filename> package.
To audit the software installed on the system, run:</para>
<screen>&prompt.root; <userinput>pkg audit -F</userinput></screen>
</sect3>
</sect2>
<sect2 id="pkgng-advanced-usage">
<title>Advanced <application>pkgng</application>
Operations</title>
<sect3 id="pkgng-autoremove">
<title>Automatically Removing Leaf Dependencies with
<application>pkgng</application></title>
<para>Removing a package may leave behind unnecessary
dependencies, like <filename
role="package">security/ca_root_nss</filename> in the
example above. Such packages are still installed, but
nothing depends on them any more. Unneeded packages that
were installed as dependencies can be automatically detected
and removed:</para>
<screen>&prompt.root; <userinput>pkg autoremove</userinput>
Packages to be autoremoved:
ca_root_nss-3.13.5
The autoremoval will free 723 kB
Proceed with autoremoval of packages [y/N]: <userinput>y</userinput>
Deinstalling ca_root_nss-3.13.5... done</screen>
</sect3>
<sect3 id="pkgng-backup">
<title>Backing Up the <application>pkgng</application> Package
Database</title>
<para>Unlike the traditional package management system,
<application>pkgng</application> includes its own package
database backup mechanism. To manually back up the package
database contents, run:</para>
<screen>&prompt.root; <userinput>pkg backup -d <replaceable>pkgng.db</replaceable></userinput></screen>
<note>
<para>Replace the file name
<replaceable>pkgng.db</replaceable> to a suitable file
name.</para>
</note>
<para>Additionally, <application>pkgng</application> includes
a &man.periodic.8; script to automatically back up the
package database daily if
<literal>daily_backup_pkgng_enable</literal> is set to
<literal>YES</literal> in &man.periodic.conf.5;.</para>
<tip>
<para>To prevent the <application>pkg_install</application>
periodic script from also backing up the package database,
set <literal>daily_backup_pkgdb_enable</literal> to
<literal>NO</literal> in &man.periodic.conf.5;.</para>
</tip>
<para>To restore the contents of a previous package database
backup, run:</para>
<screen>&prompt.root; <userinput>pkg backup -r <replaceable>/path/to/pkgng.db</replaceable></userinput></screen>
</sect3>
<sect3 id="pkgng-clean">
<title>Removing Stale <application>pkgng</application>
Packages</title>
<para>By default, <application>pkgng</application> stores
binary packages in a cache directory as defined by
<envar>PKG_CACHEDIR</envar> in pkg.conf(5). When
upgrading packages with <command>pkg upgrade</command>, old
versions of the upgraded packages are not automatically
removed.</para>
<para>To remove the outdated binary packages, run:</para>
<screen>&prompt.root; <userinput>pkg clean</userinput></screen>
</sect3>
<sect3 id="pkgng-set">
<title>Modifying <application>pkgng</application> Package
Metadata</title>
<para>Historically, software within the &os; Ports
Collection can undergo major version number changes. Unlike
<application>pkg_install</application>,
<application>pkgng</application> has a built-in command to
update package origins. For example, if <filename
role="package">lang/php5</filename> was originally at
version <literal>5.3</literal>, but has been renamed to
<filename role="package">lang/php53</filename> for the
inclusion of version <literal>5.4</literal>,
<application>pkg_install</application> would require the use
of additional software such as <filename
role="package">ports-mgmt/portmaster</filename> to update
the package database, reflecting from which port the
installation originated.</para>
<para>Unlike the <filename
role="package">ports-mgmt/portmaster</filename> and
<filename role="package">ports-mgmt/portupgrade</filename>
ports, the order in which the new and old versions are
listed differ. For <application>pkgng</application>, the
syntax is:</para>
<screen>&prompt.root; <userinput>pkg set -o <replaceable>category/oldport</replaceable>:<replaceable>category/newport</replaceable></userinput></screen>
<para>For example, to change the package origin for the above
example, run:</para>
<screen>&prompt.root; <userinput>pkg set -o lang/php5:lang/php53</userinput></screen>
<para>As another example, to update <filename
role="package">lang/ruby18</filename> to <filename
role="package">lang/ruby19</filename>, run:</para>
<screen>&prompt.root; <userinput>pkg set -o lang/ruby18:lang/ruby19</userinput></screen>
<para>As a final example, to change the origin of the
<filename>libglut</filename> shared libraries from <filename
role="package">graphics/libglut</filename> to <filename
role="package">graphics/freeglut</filename>, run:</para>
<screen>&prompt.root; <userinput>pkg set -o graphics/libglut:graphics/freeglut</userinput></screen>
<note>
<para>When changing package origins, in most cases it is
important to reinstall packages that are dependent on the
package that has had the origin changed. To force a
reinstallation of dependent packages, run:</para>
<screen>&prompt.root; <userinput>pkg install -Rf <replaceable>graphics/freeglut</replaceable></userinput></screen>
</note>
</sect3>
</sect2>
</sect1>
<sect1 id="ports-using">
<title>Using the Ports Collection</title>
<para>This section provides basic instructions on using the Ports
Collection to install or remove software. The detailed
description of available <command>make</command> targets and
environment variables is available in &man.ports.7;.</para>
<warning>
<para>As of mid 2012, the &os; Ports Project has migrated
revision control systems from CVS to Subversion. The
preferred method for obtaining and maintaining the ports tree
is <application>Portsnap</application>. Users requiring local
customization of ports (that is, maintaining additional local
patches) will probably prefer to use Subversion directly. The
<application>CVSup</application> service was phased out
as of February 28, 2013.</para>
</warning>
<sect2 id="ports-tree">
<title>Obtaining the Ports Collection</title>
<para>The Ports Collection is a set of
<filename>Makefiles</filename>, patches, and description files
stored in <filename>/usr/ports</filename>. This set of files
is used to compile and install applications on &os;. The
instructions below show several methods of obtaining the Ports
Collection if it was not installed during initial &os;
setup.</para>
<procedure>
<title>Portsnap Method</title>
<para><application>Portsnap</application> is a fast and
user-friendly tool for retrieving the Ports Collection, the
preferred choice for most users. See
<link linkend="updating-upgrading-portsnap">Using
Portsnap</link> for a detailed description of
<application>Portsnap</application>.</para>
<step>
<para>Download a compressed snapshot of the Ports Collection
into <filename
class="directory">/var/db/portsnap</filename>.</para>
<screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
</step>
<step>
<para>When running <application>Portsnap</application>
for the first time, extract the snapshot into
<filename class="directory">/usr/ports</filename>:</para>
<screen>&prompt.root; <userinput>portsnap extract</userinput></screen>
</step>
<step>
<para>After the first use of
<application>Portsnap</application> has been completed as
shown above,
<filename class="directory">/usr/ports</filename> can be
updated with:</para>
<screen>&prompt.root; <userinput>portsnap fetch</userinput>
&prompt.root; <userinput>portsnap update</userinput></screen>
</step>
</procedure>
<procedure>
<title>Subversion Method</title>
<para>If more control over the ports tree is needed (for
example, for maintaining local changes),
<application>Subversion</application> can be used to
obtain the Ports Collection. Refer to <ulink
url="&url.articles.committers-guide;/subversion-primer.html">the
Subversion Primer</ulink> for a detailed description of
<application>Subversion</application>.</para>
<step>
<para><application>Subversion</application> must be
installed before it can be used to check out the ports
tree. If a copy of the ports tree is already present,
install <application>Subversion</application> like
this:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/devel/subversion</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
<para>If the ports tree is not available,
<application>Subversion</application> can be installed as
a package:</para>
<screen>&prompt.root; <userinput>pkg_add -r subversion</userinput></screen>
<para>If <application>pkgng</application> is being used to
manage packages, <application>Subversion</application> can
be installed with it instead:</para>
<screen>&prompt.root; <userinput>pkg install subversion</userinput></screen>
</step>
<step>
<para>Check out a copy of the ports tree. Use a specific
<ulink
url="&url.books.handbook;/svn-mirrors.html">Subversion
mirror</ulink> close to your geographic location instead
of <replaceable>svn0.us-east.FreeBSD.org</replaceable> in the
command below for better performance. Committers should
read the <ulink
url="&url.articles.committers-guide;/subversion-primer.html">Subversion
Primer</ulink> first to be sure the correct protocol is
chosen.</para>
<screen>&prompt.root; <userinput>svn checkout https://<replaceable>svn0.us-east.FreeBSD.org</replaceable>/ports/head /usr/ports</userinput></screen>
</step>
<step>
<para>To update
<filename class="directory">/usr/ports</filename> after
the initial <application>Subversion</application>
checkout:</para>
<screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen>
</step>
</procedure>
<procedure>
<title>Sysinstall Method</title>
<para>This method involves using
<application>sysinstall</application> to install the Ports
Collection from the installation media. Note that the old
copy of Ports Collection from the date of the release will
be installed. If you have Internet access, you should
always use one of the methods mentioned above.</para>
<step>
<para>As <username>root</username>, run
<command>sysinstall</command> as shown below:</para>
<screen>&prompt.root; <userinput>sysinstall</userinput></screen>
</step>
<step>
<para>Scroll down and select
<guimenuitem>Configure</guimenuitem>, press
<keycap>Enter</keycap>.</para>
</step>
<step>
<para>Scroll down and select
<guimenuitem>Distributions</guimenuitem>, press
<keycap>Enter</keycap>.</para>
</step>
<step>
<para>Scroll down to <guimenuitem>ports</guimenuitem>, press
<keycap>Space</keycap>.</para>
</step>
<step>
<para>Scroll up to <guimenuitem>Exit</guimenuitem>, press
<keycap>Enter</keycap>.</para>
</step>
<step>
<para>Select your desired installation media, such as CDROM,
FTP, and so on.</para>
</step>
<step>
<para>Scroll up to <guimenuitem>Exit</guimenuitem> and press
<keycap>Enter</keycap>.</para>
</step>
<step>
<para>Press <keycap>X</keycap> to exit
<application>sysinstall</application>.</para>
</step>
</procedure>
</sect2>
<sect2 id="cvsup-migration">
<title>Migrating from
<application>CVSup</application>/<application>csup</application>
to <application>portsnap</application></title>
<warning>
<para>By February 28, 2013, the ports tree will no longer be
exported to <application>CVS</application> and therefore
<application>CVSup</application> and
<application>csup</application> will no longer provide
updates for the ports tree.</para>
</warning>
<procedure>
<title>Migration to Portsnap</title>
<para>The migration will require about 1 GB of disk space
on <filename class="directory">/usr</filename>, plus
<application>Portsnap</application> requires about
150 MB disk space on <filename
class="directory">/var</filename>.</para>
<step>
<para>Disable any automated ports updates you may use, such
as a &man.cron.8; job calling
<application>CVSup</application> or
<application>csup</application>.</para>
</step>
<step>
<para>Move the existing ports tree to a temporary
location:</para>
<screen>&prompt.root; <userinput>mv /usr/ports /usr/ports.old</userinput></screen>
</step>
<step>
<para>Fetch the new ports tree with
<application>Portsnap</application> and extract it to
<filename class="directory">/usr/ports</filename>:</para>
<screen>&prompt.root; <userinput>portsnap fetch extract</userinput></screen>
</step>
<step>
<para>Move distfiles and saved packages to the new ports
tree:</para>
<screen>&prompt.root; <userinput>mv /usr/ports.old/distfiles /usr/ports</userinput>
&prompt.root; <userinput>mv /usr/ports.old/packages /usr/ports</userinput></screen>
</step>
<step>
<para>Delete the old ports tree:</para>
<screen>&prompt.root; <userinput>rm -rf /usr/ports.old</userinput></screen>
</step>
<step>
<para>If <application>CVSup</application> was used before,
it can now be uninstalled:</para>
<screen>&prompt.root; <userinput>pkg_delete -r -v cvsup-without-gui-\*</userinput></screen>
<para>Users of <application>pkgng</application> can use the
following command:</para>
<screen>&prompt.root; <userinput>pkg delete cvsup-without-gui</userinput></screen>
</step>
</procedure>
<para>See <link linkend="updating-upgrading-portsnap">Using
Portsnap</link> for a detailed description of
<application>Portsnap</application> and how to update the
ports tree with <application>Portsnap</application>.</para>
</sect2>
<sect2 id="ports-skeleton">
<title>Installing Ports</title>
<indexterm>
<primary>ports</primary>
<secondary>installing</secondary>
</indexterm>
<para>A port skeleton is a set of files that tell &os; system
how to compile and install a program. Each port skeleton
includes:</para>
<itemizedlist>
<listitem>
<para><filename>Makefile</filename>: The
<filename>Makefile</filename> contains statements that
specify how the application should be compiled and where
its components should be installed.</para>
</listitem>
<listitem>
<para><filename>distinfo</filename>: This file contains
information about the files that must be downloaded to
build the port, and their checksums (using
&man.sha256.1;), to verify that files have not been
corrupted during the download.</para>
</listitem>
<listitem>
<para><filename>files/</filename>: This directory contains
any patches needed for the program to compile and install
on &os;. This directory may also contain other files used
to build the port.</para>
</listitem>
<listitem>
<para><filename>pkg-descr</filename>: This file provides a
more detailed description of the program.</para>
</listitem>
<listitem>
<para><filename>pkg-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>
<para>Some ports include 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, refer to the
<ulink url="&url.books.porters-handbook;/index.html">&os;
Porter's Handbook</ulink>.</para>
<para>The port does not include the actual source code, also
known as a <quote>distfile</quote>. Source code is distributed
in whatever manner the software author desires. The two
methods for installing a &os; port are described below.</para>
<note>
<para>You must be logged in as <username>root</username> to
install ports.</para>
</note>
<warning>
<para>Before compiling any port, be sure to have an
up-to-date Ports Collection and check <ulink
url="http://vuxml.freebsd.org/"></ulink> for security
issues related to your port. If <filename
role="package">ports-mgmt/portaudit</filename> is
installed, run <command>portaudit -F</command> before
installing a new port, to fetch the current vulnerabilities
database. A security audit and an update of the database
will be performed during the daily security system check.
For more information read the &man.portaudit.1; and
&man.periodic.8; manual pages.</para>
</warning>
<para>Using the Ports Collection assumes a working Internet
connection. Otherwise, manually obtain and place a copy of
the distfile into
<filename>/usr/ports/distfiles</filename>.</para>
<para>To begin, change to the directory of the port to
be installed:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput></screen>
<para>To compile, or <quote>build</quote>, the port, type
<command>make</command> at the prompt. You should see
messages similar to the ones in this example:</para>
<screen>&prompt.root; <userinput>make</userinput>
>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
>> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
===> Extracting for lsof-4.57
...
[extraction output snipped]
...
>> Checksum OK for lsof_4.57D.freebsd.tar.gz.
===> Patching for lsof-4.57
===> Applying FreeBSD patches for lsof-4.57
===> Configuring for lsof-4.57
...
[configure output snipped]
...
===> Building for lsof-4.57
...
[compilation output snipped]
...
&prompt.root;</screen>
<para>Once the compile is complete, you are returned to the
prompt. The next step is to install the port using
<command>make <maketarget>install</maketarget></command>:</para>
<screen>&prompt.root; <userinput>make install</userinput>
===> Installing for lsof-4.57
...
[installation output snipped]
...
===> Generating temporary packing list
===> Compressing manual pages for lsof-4.57
===> Registering installation for lsof-4.57
===> SECURITY NOTE:
This port has installed the following binaries which execute with
increased privileges.
&prompt.root;</screen>
<para>Once you are returned to the prompt, you should be able
to run the installed application. Since
<command>lsof</command> is a program that runs with increased
privileges, a security warning is shown. During the building
and installation of ports, take heed of any other warnings
that may appear.</para>
<para>It is a good idea to delete the working subdirectory,
which contains all the temporary files used during
compilation. Doing so saves disk space and minimizes the
chance of problems later when upgrading to the newer version
of the port.</para>
<screen>&prompt.root; <userinput>make clean</userinput>
===> Cleaning for lsof-4.57
&prompt.root;</screen>
<note>
<para>You can save two extra steps by just running
<command>make
<maketarget>install clean</maketarget></command>
instead of <command>make</command>,
<command>make <maketarget>install</maketarget></command>
and <command>make <maketarget>clean</maketarget></command>
as three separate steps.</para>
</note>
<note>
<para>Using only
<command>make <maketarget>install</maketarget></command>
means there will potentially be many
waiting periods between user interaction as the default
behaviour is to prompt the user for options. To avoid this
when there are many dependencies, first run <command>make
<maketarget>config-recursive</maketarget></command> to do
the configuration in one batch. Then run <command>make
<maketarget>install [clean]</maketarget></command>
afterwards.</para>
</note>
<tip>
<para>When using <maketarget>config-recursive</maketarget>,
the list of ports to configure are gathered by the
<maketarget>all-depends-list</maketarget> &man.make.1;
target. It is often recommended to run <command>make
<maketarget>config-recursive</maketarget></command>
until all dependent ports options have been defined, and
ports options &man.dialog.1; screens no longer
appear, to be certain all ports options have been
configured as intended.</para>
</tip>
<note>
<para>Some shells keep a cache of the commands that are
available in the directories listed in the
<envar>PATH</envar> environment variable, to speed up lookup
operations for the executable file of these commands. If
you are using <command>tcsh</command>, you might have to
type <command>rehash</command> so that a newly installed
command can be used without specifying its full path. Use
<command>hash -r</command> instead for the
<command>sh</command> shell. Refer to the documentation for
the shell for more information.</para>
</note>
<para>Some third-party DVD products such as the &os;
Toolkit from the <ulink url="http://www.freebsdmall.com/">&os;
Mall</ulink> contain distfiles. They can be used with the
Ports Collection. Mount the DVD on
<filename>/cdrom</filename>. If you use a different mount
point, set <makevar>CD_MOUNTPTS</makevar> make variable. The
needed distfiles will be automatically used if they are
present on the disk.</para>
<note>
<para>The licenses of a few ports do not allow their inclusion
on the DVD. This could be because a registration form
needs to be filled out before downloading or redistribution
is not allowed. If you wish to install a port not included
on the DVD, you will need to be connected to the
Internet.</para>
</note>
<para>The ports system uses &man.fetch.1; to download the
files, which honors various environment variables, including
<envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and
<envar>FTP_PASSWORD</envar>. You may need to set one or more
of these if you are behind a firewall, or need to use an
FTP/HTTP proxy. See &man.fetch.3; for the complete
list.</para>
<para>For users which cannot be connected all the time, the
<command>make <maketarget>fetch</maketarget></command> option
is provided. Run this command within
<filename>/usr/ports</filename> and the required files will
be downloaded. This command also works in the
lower level categories, such as
<filename>/usr/ports/net</filename>. Note that if a port
depends on libraries or other ports, this will
<emphasis>not</emphasis> fetch the distfiles of ports
from another category. Use
<command>make
<maketarget>fetch-recursive</maketarget></command>
to fetch
all the dependencies of a port.</para>
<note>
<para>You can build all the ports in a category or as a
whole by running <command>make</command> in the top level
directory. This is dangerous, however, as some ports cannot
co-exist. In other cases, some ports can install two
different files with the same filename.</para>
</note>
<para>In some rare cases, users may need to acquire the
tarballs from a site other than the default
<makevar>MASTER_SITES</makevar>. You can override the
<makevar>MASTER_SITES</makevar> option with the following
command:</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>
<para>In this example, <makevar>MASTER_SITES</makevar> is
changed to <hostid
role="fqdn">ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</hostid>.</para>
<note>
<para>Some ports provide build options which can be used to
enable/disable parts of the application which are unneeded,
provide security options, or allow for other customizations.
Examples include
<filename role="package">www/firefox</filename>,
<filename role="package">security/gpgme</filename>, and
<filename role="package">mail/sylpheed-claws</filename>. A
menu will be displayed at the beginning of a port
compile when compile options are available.</para>
</note>
<sect3>
<title>Overriding the Default Ports Directories</title>
<para>The <makevar>WRKDIRPREFIX</makevar> and
<makevar>PREFIX</makevar> variables can override the default
working and target directories. For example:</para>
<screen>&prompt.root; <userinput>make WRKDIRPREFIX=/usr/home/example/ports install</userinput></screen>
<para>will compile the port in
<filename>/usr/home/example/ports</filename> and install
everything under <filename>/usr/local</filename>.</para>
<screen>&prompt.root; <userinput>make PREFIX=/usr/home/example/local install</userinput></screen>
<para>will compile the port in <filename>/usr/ports</filename>
and install it in
<filename>/usr/home/example/local</filename>.</para>
<para>And</para>
<screen>&prompt.root; <userinput>make WRKDIRPREFIX=../ports PREFIX=../local install</userinput></screen>
<para>will combine the two.</para>
<para>Alternatively, these can be set as environmental
variables. Refer to the manual page for your shell
for instructions on how to set an environmental
variable.</para>
</sect3>
<sect3>
<title>Reconfiguring Ports</title>
<para>Certain ports provide an ncurses-based menu containing
build options. There are several ways to revisit this menu
in order to add, remove, or change these options after a
port has been built. One method is to
<command>cd</command> into the directory containing the
port and type
<command>make <maketarget>config</maketarget></command>.
Another option is to use
<command>make <maketarget>showconfig</maketarget></command>.
Another option is to execute
<command>make <maketarget>rmconfig</maketarget></command>
which will remove all selected options and allow you to
start over. All of these options, and others, are explained
in great detail in the manual page for &man.ports.7;.</para>
</sect3>
</sect2>
<sect2 id="ports-removing">
<title>Removing Installed Ports</title>
<indexterm>
<primary>ports</primary>
<secondary>removing</secondary>
</indexterm>
<para>Installed ports and packages are uninstalled using
the &man.pkg.delete.1; command:</para>
<screen>&prompt.root; <userinput>pkg_delete lsof-4.57</userinput></screen>
</sect2>
<sect2 id="ports-upgrading">
<title>Upgrading Ports</title>
<indexterm>
<primary>ports</primary>
<secondary>upgrading</secondary>
</indexterm>
<para>First, list outdated ports that have a newer version
available in the Ports Collection with the &man.pkg.version.1;
command:</para>
<screen>&prompt.root; <userinput>pkg_version -v</userinput></screen>
<sect3 id="ports-file-updating">
<title>Read <filename>/usr/ports/UPDATING</filename></title>
<para>Once you have updated your Ports Collection, before
attempting a port upgrade, you should check
<filename>/usr/ports/UPDATING</filename>. This file
describes various issues and additional steps users may
encounter and need to perform when updating a port,
including such things as file format changes, changes in
locations of configuration files, or other such
incompatibilities with previous versions.</para>
<para>If <filename>UPDATING</filename> contradicts something
you read here, <filename>UPDATING</filename> takes
precedence.</para>
</sect3>
<sect3 id="portupgrade">
<title>Upgrading Ports Using Portupgrade</title>
<indexterm>
<primary>portupgrade</primary>
</indexterm>
<para>The <application>portupgrade</application> utility is
designed to easily upgrade installed ports. It is available
from the
<filename role="package">ports-mgmt/portupgrade</filename>
port. Install it like any other port, using
<command>make <maketarget>install
clean</maketarget></command>:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portupgrade</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
<para>Scan the list of installed ports using
<command>pkgdb -F</command> and fix all the inconsistencies
it reports. It is a good idea to do this regularly, before
every upgrade.</para>
<para>Use <command>portupgrade -a</command> to upgrade all the
outdated ports installed on the system. Include
<option>-i</option> to be asked for confirmation of every
individual upgrade.</para>
<screen>&prompt.root; <userinput>portupgrade -ai</userinput></screen>
<para>To upgrade only a specified application instead of all
available ports, use <command>portupgrade
<replaceable>pkgname</replaceable></command>. Include
<option>-R</option> to first upgrade all the ports required
by the given application.</para>
<screen>&prompt.root; <userinput>portupgrade -R firefox</userinput></screen>
<para>To use packages instead of ports, include the
<option>-P</option> flag. With this option,
<application>portupgrade</application> searches the local
directories listed in <envar>PKG_PATH</envar>, then fetches
packages from a remote site if not found locally. If
packages can not be found locally or fetched remotely,
<application>portupgrade</application> will use ports. To
avoid using ports, specify <option>-PP</option>.</para>
<screen>&prompt.root; <userinput>portupgrade -PP gnome2</userinput></screen>
<para>To just fetch distfiles (or packages, if
<option>-P</option> is specified) without building or
installing anything, use <option>-F</option>. For further
information see &man.portupgrade.1;.</para>
</sect3>
<sect3 id="portmaster">
<title>Upgrading Ports Using
<application>portmaster</application></title>
<indexterm>
<primary>portmaster</primary>
</indexterm>
<para><filename
role="package">ports-mgmt/portmaster</filename> is another
utility for upgrading installed ports.
<application>portmaster</application> was designed to
use the tools found in the <quote>base</quote> system
without depending upon other ports. It uses the information
in <filename class="directory">/var/db/pkg/</filename> to
determine which ports to upgrade. To install the
port:</para>
<screen>&prompt.root; <userinput>cd <filename class="directory">/usr/ports/ports-mgmt/portmaster</filename></userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
<para><application>Portmaster</application> groups ports into
four categories:</para>
<itemizedlist>
<listitem>
<para>Root ports: no dependencies and is not depended on
by other ports</para>
</listitem>
<listitem>
<para>Trunk ports: no dependencies, but other ports depend
upon it</para>
</listitem>
<listitem>
<para>Branch ports: have dependencies and are depended
upon by other ports</para>
</listitem>
<listitem>
<para>Leaf ports: have dependencies but are not depended
upon by other ports</para>
</listitem>
</itemizedlist>
<para>To list all installed software and search for updates,
use <option>-L</option>:</para>
<screen>&prompt.root; <userinput>portmaster -L</userinput>
===>>> Root ports (No dependencies, not depended on)
===>>> ispell-3.2.06_18
===>>> screen-4.0.3
===>>> New version available: screen-4.0.3_1
===>>> tcpflow-0.21_1
===>>> 7 root ports
...
===>>> Branch ports (Have dependencies, are depended on)
===>>> apache22-2.2.3
===>>> New version available: apache22-2.2.8
...
===>>> Leaf ports (Have dependencies, not depended on)
===>>> automake-1.9.6_2
===>>> bash-3.1.17
===>>> New version available: bash-3.2.33
...
===>>> 32 leaf ports
===>>> 137 total installed ports
===>>> 83 have new versions available</screen>
<para>All the installed ports can be upgraded using this
command:</para>
<screen>&prompt.root; <userinput>portmaster -a</userinput></screen>
<note>
<para>By default, <application>portmaster</application> will
make a backup package before deleting the existing port.
If the installation of the new version is successful,
<application>portmaster</application> will delete the
backup. Using <option>-b</option> will instruct
<application>portmaster</application> not to automatically
delete the backup. Adding <option>-i</option> will start
<application>portmaster</application> in interactive mode,
prompting for confirmation before upgrading each
port.</para>
</note>
<para>If you encounter errors during the upgrade process, use
<option>-f</option> to upgrade/rebuild all ports:</para>
<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>
<para>You can also use <application>portmaster</application>
to install new ports on the system, upgrading all
dependencies before building and installing the new
port:</para>
<screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen>
<para>Refer to &man.portmaster.8; for more information.</para>
</sect3>
</sect2>
<sect2 id="ports-disk-space">
<title>Ports and Disk Space</title>
<indexterm>
<primary>ports</primary>
<secondary>disk-space</secondary>
</indexterm>
<para>Using the Ports Collection will use up disk space over
time. After building and installing a port, <command>make
<maketarget>clean</maketarget></command> will clean up the
temporary <filename class="directory">work</filename>
directory. To sweep the whole Ports Collection:</para>
<screen>&prompt.root; <userinput>portsclean -C</userinput></screen>
<para>A lot of out-dated source distribution files will collect
in <filename class="directory">distfiles</filename> over time.
The following command will delete all the distfiles that are
no longer referenced by any ports:</para>
<screen>&prompt.root; <userinput>portsclean -D</userinput></screen>
<para>To remove all distfiles not referenced by any port
currently installed on the system:</para>
<screen>&prompt.root; <userinput>portsclean -DD</userinput></screen>
<note>
<para>The <command>portsclean</command> utility is part of the
<filename role="package">ports-mgmt/portupgrade</filename>
suite.</para>
</note>
<para><filename
role="package">ports-mgmt/pkg_cutleaves</filename> automates
the task of removing installed ports that are no longer
needed.</para>
</sect2>
</sect1>
<sect1 id="ports-nextsteps">
<title>Working With Installed Ports</title>
<para>Most third party applications will need some level of
configuration after they were installed. This may be a simple
configuration file alteration, or perhaps the application will
just generate a configuration file. Most applications will
have documentation installed into
<filename class="directory">/usr/local/share/doc</filename> and
manual pages. This documentation should be consulted before
continuing. Some applications run services which must be added
to the <filename>/etc/rc.conf</filename> file before
starting.</para>
<para>The following list contains useful information for
post-install port management. In several cases, finding
the location of binaries if they were installed outside
of the <envar>PATH</envar>. Users of &man.csh.1; should run
<command>rehash</command> to rebuild the known binary
list in the shells <envar>PATH</envar>.</para>
<itemizedlist>
<listitem>
<para>The &man.pkg.info.1; command will print all installed
files and their location. For example, if the FooPackage
version 1.0.0 was just installed, then the following
command will show all the files installed with the
package.</para>
<screen>&prompt.root; <userinput>pkg_info -L <replaceable>foopackage-1.0.0</replaceable> | less</userinput></screen>
<para>Configuration files are always installed in
<filename class="directory">/usr/local/etc</filename>
and should definitely be consulted before attempting
to use the new application.</para>
<para>To determine which version of the application was
installed:</para>
<screen>&prompt.root; <userinput>pkg_info | grep -i <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> as
necessary.</para>
</listitem>
<listitem>
<para>These commands will also show the names of any manual
pages installed with the application. This additional
documentation will now be available to the &man.man.1;
command.</para>
</listitem>
<listitem>
<para>If the application has a web site, consult it for
additional documentation or a frequently asked questions
page. If the website is unknown, the following command
will be useful to print out this information if it's
available.</para>
<screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen>
<para>A <literal>WWW:</literal> line, if present, should
provide a URL for the application's web site.</para>
</listitem>
<listitem>
<para>Ports that should start at boot time usually install a
startup script in <filename>/usr/local/etc/rc.d</filename>.
Review this script for correctness and edit or rename it if
needed. See <link
linkend="configtuning-starting-services">Starting
Services</link> for more information.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="ports-broken">
<title>Dealing with Broken Ports</title>
<para>When coming across a port that does not build or install:</para>
<orderedlist>
<listitem>
<para>Find out if there is a fix pending for the port in
the <ulink url="&url.base;/support.html#gnats">Problem
Report database</ulink>. If so, the proposed fix may work.</para>
</listitem>
<listitem>
<para>Ask the maintainer of the port for help. Type
<command>make <maketarget>maintainer</maketarget></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.</para>
<note>
<para>Some ports are not maintained by an individual but
instead by a <ulink
url="&url.articles.mailing-list-faq;/article.html">mailing
list</ulink>. Many, but not all, of these addresses look
like <email
role="nolink">freebsd-listname@FreeBSD.org</email>.
Please take this into account when phrasing your
questions.</para>
<para>In particular, ports shown as maintained by
<email role="nolink">ports@FreeBSD.org</email> are
actually not maintained by anyone. Fixes and support, if
any, come from the general community who subscribe to that
mailing list. More volunteers are always needed!</para>
</note>
<para>If you do not get a response, use &man.send-pr.1; to
submit a bug report (see <ulink
url="&url.articles.problem-reports;/article.html">Writing
&os; Problem Reports</ulink>).</para>
</listitem>
<listitem>
<para>Fix it! The <ulink
url="&url.books.porters-handbook;/index.html">Porter's
Handbook</ulink> includes detailed information on the
<quote>Ports</quote> infrastructure so that you can fix the
occasional broken port or even submit your own!</para>
</listitem>
<listitem>
<para>Use &man.pkg.add.1; to instead install the
package.</para>
</listitem>
</orderedlist>
</sect1>
</chapter>