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

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!--
     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>

	<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 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>There are several different tools used to manage packages on
      &os;:</para>

    <itemizedlist>
      <listitem>
	<para>The <command>sysinstall</command> utility can be invoked
	  on a running system to install, delete, and list available
	  and installed packages.  For more information, see
	  <xref linkend="packages"/>.</para>
      </listitem>

      <listitem>
	<para>The package management command line tools, which are
	  the subject of the rest of this section.</para>
      </listitem>
    </itemizedlist>

    <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.
	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;&nbsp;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;&nbsp;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 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 found in the local ports tree.</entry>
	    </row>

	    <row>
	      <entry>&lt;</entry>
	      <entry>The installed version is older than the one
		available in the local ports tree.</entry>
	    </row>

	    <row>
	      <entry>&gt;</entry><entry>The installed version is newer
		than the one found 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>

    <sect2>
      <title>Miscellaneous</title>

      <para>All package information, including the file list and
	descriptions of each installed package is stored within the
	<filename>/var/db/pkg</filename> directory.</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;&nbsp;9.1 and later includes a &quot;bootstrap&quot;
	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;&nbsp;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;&nbsp;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&nbsp;GB of disk space
	  on <filename class="directory">/usr</filename>, plus
	  <application>Portsnap</application> requires about
	  150&nbsp;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>
&gt;&gt; lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
&gt;&gt; Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
===&gt;  Extracting for lsof-4.57
...
[extraction output snipped]
...
&gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
===&gt;  Patching for lsof-4.57
===&gt;  Applying FreeBSD patches for lsof-4.57
===&gt;  Configuring for lsof-4.57
...
[configure output snipped]
...
===&gt;  Building for lsof-4.57
...
[compilation output snipped]
...
&prompt.root;</screen>

      <para>Once the compile is complete, you are returned to the
	prompt.  The next step is to install the port using
	<maketarget>make install</maketarget>:</para>

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

      <para>Once you are returned to 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>
===&gt;  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)
===>>> apache-2.2.3
        ===>>> New version available: apache-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
	  <application>portupgrade</application> 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>Post-installation Activities</title>

    <para>After installing a new application you will normally want to
      read any documentation it may have included, edit any
      required configuration files, and ensure that the
      application's service starts at boot time.</para>

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

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

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

	<para>will show all the files installed by the package.  Pay
	  special attention to files located in
	  <filename>man/</filename>, which will be manual pages,
	  <filename>etc/</filename>, which will be configuration
	  files, and <filename>doc/</filename>, which will be more
	  comprehensive documentation.</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>Once you have identified where the application's manual
	  pages have been installed, review them using &man.man.1;.
	  Review the sample configuration files and any additional
	  documentation that may have been provided.</para>
      </listitem>

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

	<screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen>

	<para>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>If you come across a port that does not compile:</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, you may be able to use
	  the proposed fix.</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>&dollar;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>