aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1
diff options
context:
space:
mode:
authorRyusuke SUZUKI <ryusuke@FreeBSD.org>2021-05-01 16:51:45 +0000
committerRyusuke SUZUKI <ryusuke@FreeBSD.org>2021-05-01 16:51:45 +0000
commitff3df39394cc4faf4300a4b19954f93a0fd46868 (patch)
treea6130a8b6c2aacfcb6f73fbfe57aeabf0e1f6fba /en_US.ISO8859-1
parent731e05fde11b8af827a9a4ce7d48dd2dcfac1bd8 (diff)
downloaddoc-ff3df39394cc4faf4300a4b19954f93a0fd46868.tar.gz
doc-ff3df39394cc4faf4300a4b19954f93a0fd46868.zip
a67af5a97b -> e633f0b9df
Diffstat (limited to 'en_US.ISO8859-1')
-rw-r--r--en_US.ISO8859-1/books/handbook/ports/chapter.xml1831
1 files changed, 1831 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.xml b/en_US.ISO8859-1/books/handbook/ports/chapter.xml
new file mode 100644
index 0000000000..110d47f3b6
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.xml
@@ -0,0 +1,1831 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!--
+ The FreeBSD Documentation Project
+
+ $FreeBSD$
+-->
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="ports">
+
+ <title>Installing Applications: Packages and Ports</title>
+
+ <sect1 xml: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. In addition, &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:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The difference between binary packages and ports.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to find third-party software that has been ported
+ to &os;.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to manage binary packages using
+ <application>pkg</application>.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to build third-party software from source using the
+ Ports Collection.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to find the files installed with the application
+ for post-installation configuration.</para>
+ </listitem>
+
+ <listitem>
+ <para>What to do if a software installation fails.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 xml: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>Find and 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. This
+ is typically a tarball compressed with a program such as
+ &man.compress.1;, &man.gzip.1;, &man.bzip2.1; or
+ &man.xz.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.</para>
+ </step>
+
+ <step>
+ <para>Test and install the software.</para>
+ </step>
+ </procedure>
+
+ <para>A &os; <emphasis>port</emphasis> 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>If the software has not already been adapted and tested
+ on &os;, the source code might need editing in
+ order for it to install and run properly.</para>
+
+ <para>However, over <link
+ xlink:href="&url.base;/ports/index.html">&os.numports;</link>
+ third-party applications have already been ported to &os;. When
+ feasible, these applications are made available for download as
+ pre-compiled <emphasis>packages</emphasis>.</para>
+
+ <para>Packages
+ can be manipulated with the &os; package management
+ commands.</para>
+
+ <para>Both packages and ports understand dependencies. If a
+ package or port is used to install an application and a
+ dependent library is not already installed, the library will
+ automatically be installed first.</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 the
+ &man.pkg.8; commands, such as
+ <command>pkg install</command>.</para>
+
+ <para>While the two technologies are 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>Port 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. Such software 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>Source code is needed in
+ order to apply custom patches.</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 <link
+ xlink:href="https://vuxml.freebsd.org/"></link>
+ for security issues related to the application or type
+ <command>pkg audit -F</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 xml: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 <link
+ xlink:href="&url.base;/ports/index.html">https://www.FreeBSD.org/ports/</link>.
+ The ports can be searched by application name or by
+ software category.</para>
+ </listitem>
+
+ <listitem>
+ <indexterm><primary>FreshPorts</primary></indexterm>
+
+ <para>Dan Langille maintains <link
+ xlink:href="http://www.FreshPorts.org/">FreshPorts.org</link>
+ 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>SourceForge</primary></indexterm>
+
+ <para>If finding a particular application becomes challenging,
+ try searching a site like <link
+ xlink:href="http://www.sourceforge.net/">SourceForge.net</link>
+ or <link
+ xlink:href="http://www.github.com/">GitHub.com</link> then
+ check back at the <link
+ xlink:href="&url.base;/ports/index.html">&os; site</link>
+ to see if the application has been ported.</para>
+ </listitem>
+
+ <listitem>
+ <indexterm>
+ <primary>pkg</primary>
+ <secondary>search</secondary>
+ </indexterm>
+
+ <para xml:id="pkg-search">To search the binary package
+ repository for an application:</para>
+
+ <screen>&prompt.root; <userinput>pkg search <replaceable>subversion</replaceable></userinput>
+git-subversion-<replaceable>1.9.2</replaceable>
+java-subversion-<replaceable>1.8.8_2</replaceable>
+p5-subversion-<replaceable>1.8.8_2</replaceable>
+py27-hgsubversion-<replaceable>1.6</replaceable>
+py27-subversion-<replaceable>1.8.8_2</replaceable>
+ruby-subversion-<replaceable>1.8.8_2</replaceable>
+subversion-<replaceable>1.8.8_2</replaceable>
+subversion-book-<replaceable>4515</replaceable>
+subversion-static-<replaceable>1.8.8_2</replaceable>
+subversion16-<replaceable>1.6.23_4</replaceable>
+subversion17-<replaceable>1.7.16_2</replaceable></screen>
+
+ <para>Package names include the version number and, in the
+ case of ports based on python, the version number of the
+ version of python the package was built with. Some ports
+ also have multiple versions available. In the case of
+ <application>Subversion</application>, there are different
+ versions available, as well as different compile options.
+ In this case, the statically linked version of
+ <application>Subversion</application>. When indicating
+ which package to install, it is best to specify the
+ application by the port origin, which is the path in the
+ ports tree. Repeat the <command>pkg search</command> with
+ <option>-o</option> to list the origin of each
+ package:</para>
+
+ <screen>&prompt.root; <userinput>pkg search -o <replaceable>subversion</replaceable></userinput>
+devel/git-subversion
+java/java-subversion
+devel/p5-subversion
+devel/py-hgsubversion
+devel/py-subversion
+devel/ruby-subversion
+devel/subversion16
+devel/subversion17
+devel/subversion
+devel/subversion-book
+devel/subversion-static</screen>
+
+ <para>Searching by shell globs, regular expressions, exact
+ match, by description, or any other field in the repository
+ database is also supported by <command>pkg search</command>.
+ After installing <package>ports-mgmt/pkg</package> or
+ <package>ports-mgmt/pkg-devel</package>, see
+ &man.pkg-search.8; for more details.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the Ports Collection is already installed, there are
+ several methods to query the local version of the ports
+ tree. 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 also return any matched files
+ downloaded into the
+ <filename>/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
+ search name=program-name</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.88.d,8
+Path: /usr/ports/sysutils/lsof
+Info: Lists information about open files (similar to fstat(1))
+Maint: ler@lerctr.org
+Index: sysutils
+B-deps:
+R-deps: </screen>
+
+ <tip>
+ <para>The built-in search mechanism uses a file
+ of index information. If a message indicates that 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.88.d,8
+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 search
+ key=<replaceable>string</replaceable></command> or
+ <command>make quicksearch
+ 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 <buildtarget>search</buildtarget> or
+ <buildtarget>quicksearch</buildtarget>, 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 xml:id="pkgng-intro">
+ <title>Using <application>pkg</application> for Binary Package
+ Management</title>
+
+ <para><application>pkg</application> is the next generation
+ replacement for the traditional &os; package management tools,
+ offering many features that make dealing with binary packages
+ faster and easier.</para>
+
+ <para>For sites wishing to only use prebuilt binary packages
+ from the &os; mirrors, managing packages with
+ <application>pkg</application> can be sufficient.</para>
+
+ <para>However, for those sites building from source or using their
+ own repositories, a separate <link
+ linkend="ports-upgrading-tools">port management tool</link>
+ will be needed.</para>
+
+ <para>Since <application>pkg</application> only works with
+ binary packages, it
+ is not a replacement for such tools. Those tools can be
+ used to install software from both binary packages
+ and the Ports Collection, while
+ <application>pkg</application> installs only binary
+ packages.</para>
+
+ <sect2 xml:id="pkgng-initial-setup">
+ <title>Getting Started with
+ <application>pkg</application></title>
+
+ <para>&os; includes a bootstrap utility which can be used to
+ download and install <application>pkg</application>
+ and its manual pages. This utility is designed to work
+ with versions of &os; starting with
+ 10.<replaceable>X</replaceable>.</para>
+
+ <note>
+ <para>Not all &os; versions and architectures
+ support this bootstrap process. The current list is at
+ <link xlink:href="https://pkg.freebsd.org/"></link>.
+ For other cases,
+ <application>pkg</application> must instead be installed
+ from the Ports Collection or as a binary package.</para>
+
+ </note>
+
+ <para>To bootstrap the system, run:</para>
+
+ <screen>&prompt.root; <userinput>/usr/sbin/pkg</userinput></screen>
+
+ <para>You must have a working Internet connection for the
+ bootstrap process to succeed.</para>
+
+ <para>Otherwise, to install the 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>When upgrading an existing system that originally used the
+ older pkg_* tools, the database must be converted to the
+ new format, so that the new tools are aware of the already
+ installed packages. Once <application>pkg</application> has
+ been installed, the
+ package database must be converted from the traditional format
+ to the new format by running this command:</para>
+
+ <screen>&prompt.root; <userinput>pkg2ng</userinput></screen>
+
+ <note><para>This step is not required for new installations that
+ do not yet have any third-party software
+ installed.</para></note>
+
+ <important>
+ <para>This step is not reversible. Once the package database
+ has been converted to the <application>pkg</application>
+ format, the traditional <literal>pkg_*</literal> tools
+ should no longer 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
+ software that was not successfully converted
+ is shown after <command>pkg2ng</command> finishes.
+ These applications must be manually reinstalled.</para>
+ </note>
+
+ <para>To ensure that the Ports Collection registers
+ new software with <application>pkg</application> instead of
+ the traditional packages database, &os; versions earlier than
+ 10.<replaceable>X</replaceable> require this line in
+ <filename>/etc/make.conf</filename>:</para>
+
+ <programlisting>WITH_PKGNG= yes</programlisting>
+
+ <para>By default, <application>pkg</application> uses the
+ binary packages from the &os;
+ package mirrors (the <emphasis>repository</emphasis>).
+ For information about building a custom
+ package repository, see
+ <xref linkend="ports-poudriere"/>.</para>
+
+ <para>Additional <application>pkg</application> configuration
+ options are described in &man.pkg.conf.5;.</para>
+
+ <para>Usage information for <application>pkg</application> is
+ available in the &man.pkg.8; manual page or by running
+ <command>pkg</command> without additional arguments.</para>
+
+ <para>Each <application>pkg</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 of these commands:</para>
+
+ <screen>&prompt.root; <userinput>pkg help install</userinput></screen>
+
+ <screen>&prompt.root; <userinput>man pkg-install</userinput></screen>
+
+ <para>The rest of this section demonstrates common binary
+ package management tasks which can be performed using
+ <application>pkg</application>. Each demonstrated command
+ provides many switches to customize its use. Refer to a
+ command's help or man page for details and more
+ examples.</para>
+ </sect2>
+
+ <sect2 xml:id="quarterly-latest-branch">
+ <title>Quarterly and Latest Ports Branches</title>
+
+ <para>The <literal>Quarterly</literal> branch provides users
+ with a more predictable and stable experience for port and
+ package installation and upgrades. This is done essentially
+ by only allowing non-feature updates. Quarterly branches aim
+ to receive security fixes (that may be version updates, or
+ backports of commits), bug fixes and ports compliance or
+ framework changes. The Quarterly branch is cut from HEAD at
+ the beginning of every (yearly) quarter in January, April,
+ July, and October. Branches are named according to the year
+ (YYYY) and quarter (Q1-4) they are created in. For example,
+ the quarterly branch created in January 2016, is named 2016Q1.
+ And the <literal>Latest</literal> branch provides the latest
+ versions of the packages to the users.</para>
+
+ <para>To switch from quarterly to latest run the following
+ commands:</para>
+
+ <screen>&prompt.root; <userinput>cp /etc/pkg/FreeBSD.conf /usr/local/etc/pkg/repos/FreeBSD.conf</userinput></screen>
+
+ <para>Edit the file
+ <filename>/usr/local/etc/pkg/repos/FreeBSD.conf</filename>
+ and change the string <emphasis>quarterly</emphasis> to
+ <emphasis>latest</emphasis> in the <literal>url:</literal>
+ line.</para>
+
+ <para>The result should be similar to the following:</para>
+
+ <programlisting>FreeBSD: {
+ url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
+ mirror_type: "srv",
+ signature_type: "fingerprints",
+ fingerprints: "/usr/share/keys/pkg",
+ enabled: yes
+}</programlisting>
+
+ <para>And finally run this command to update from the new
+ (latest) repository metadata.</para>
+
+ <screen>&prompt.root; <userinput>pkg update -f</userinput></screen>
+
+ </sect2>
+
+ <sect2 xml:id="pkgng-pkg-info">
+ <title>Obtaining Information About Installed Packages</title>
+
+ <para>Information about the packages installed on a system
+ can be viewed by running <command>pkg info</command> which,
+ when run without any switches, will list the package version
+ for either all installed packages or the specified
+ package.</para>
+
+ <para>For example, to see which version of
+ <application>pkg</application> is installed, run:</para>
+
+ <screen>&prompt.root; <userinput>pkg info pkg</userinput>
+pkg-1.1.4_1</screen>
+ </sect2>
+
+ <sect2 xml:id="pkgng-installing-deinstalling">
+ <title>Installing and Removing Packages</title>
+
+ <para>To install a binary package use the following command,
+ where <replaceable>packagename</replaceable> is the name of
+ the package to install:</para>
+
+ <screen>&prompt.root; <userinput>pkg install <replaceable>packagename</replaceable></userinput></screen>
+
+ <para>This command uses repository data to determine which
+ version of the software to install and if it has any
+ uninstalled dependencies. For example, to install
+ <application>curl</application>:</para>
+
+ <screen>&prompt.root; <userinput>pkg install curl</userinput>
+Updating repository catalogue
+/usr/local/tmp/All/curl-7.31.0_1.txz 100% of 1181 kB 1380 kBps 00m01s
+
+/usr/local/tmp/All/ca_root_nss-3.15.1_1.txz 100% of 288 kB 1700 kBps 00m00s
+
+Updating repository catalogue
+The following 2 packages will be installed:
+
+ Installing ca_root_nss: 3.15.1_1
+ Installing curl: 7.31.0_1
+
+The installation will require 3 MB more space
+
+0 B to be downloaded
+
+Proceed with installing packages [y/N]: <userinput>y</userinput>
+Checking integrity... done
+[1/2] Installing ca_root_nss-3.15.1_1... done
+[2/2] Installing curl-7.31.0_1... done
+Cleaning up cache files...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.15.1_1 The root certificate bundle from the Mozilla Project
+curl-7.31.0_1 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
+pkg-1.1.4_6 New generation package manager</screen>
+
+ <para>Packages that are no longer needed can be removed with
+ <command>pkg delete</command>. For example:</para>
+
+ <screen>&prompt.root; <userinput>pkg delete curl</userinput>
+The following packages will be deleted:
+
+ curl-7.31.0_1
+
+The deletion will free 3 MB
+
+Proceed with deleting packages [y/N]: <userinput>y</userinput>
+[1/1] Deleting curl-7.31.0_1... done</screen>
+ </sect2>
+
+ <sect2 xml:id="pkgng-upgrading">
+ <title>Upgrading Installed Packages</title>
+
+ <para>Installed packages can be upgraded to their latest
+ versions by running:</para>
+
+ <screen>&prompt.root; <userinput>pkg upgrade</userinput></screen>
+
+ <para>This command will compare the installed versions with
+ those available in the repository catalogue and upgrade them
+ from the repository.</para>
+ </sect2>
+
+ <sect2 xml:id="pkgng-auditing">
+ <title>Auditing Installed Packages</title>
+
+ <para>Software vulnerabilities are regularly discovered
+ in third-party applications. To address this,
+ <application>pkg</application> includes a built-in auditing
+ mechanism. To determine if there are any known
+ vulnerabilities for the software installed on the system,
+ run:</para>
+
+ <screen>&prompt.root; <userinput>pkg audit -F</userinput></screen>
+ </sect2>
+
+ <sect2 xml:id="pkgng-autoremove">
+ <title>Automatically Removing Unused Packages</title>
+
+ <para>Removing a package may leave behind dependencies which
+ are no longer required. Unneeded packages that were installed
+ as dependencies (leaf packages) can be automatically detected
+ and removed using:</para>
+
+ <screen>&prompt.root; <userinput>pkg autoremove</userinput>
+Packages to be autoremoved:
+ ca_root_nss-3.15.1_1
+
+The autoremoval will free 723 kB
+
+Proceed with autoremoval of packages [y/N]: <userinput>y</userinput>
+Deinstalling ca_root_nss-3.15.1_1... done</screen>
+
+ <para>Packages installed as dependencies are
+ called <emphasis>automatic</emphasis> packages. Non-automatic
+ packages, i.e the packages that were explicity installed not
+ as a dependency to another package, can be listed
+ using:</para>
+
+ <screen>&prompt.root; <userinput>pkg prime-list</userinput>
+nginx
+openvpn
+sudo</screen>
+
+ <para><command>pkg prime-list</command> is an alias command
+ declared in <filename>/usr/local/etc/pkg.conf</filename>.
+ There are many others that can be used to query the package
+ database of the system. For instance, command
+ <command>pkg prime-origins</command> can be used to get the
+ origin port directory of the list mentioned above:</para>
+
+ <screen>&prompt.root; <userinput>pkg prime-origins</userinput>
+www/nginx
+security/openvpn
+security/sudo</screen>
+
+ <para>This list can be used to rebuild all packages
+ installed on a system using build tools such as <package>
+ ports-mgmt/poudriere</package> or <package>
+ ports-mgmt/synth</package>.</para>
+
+ <para>Marking an installed package as automatic can be
+ done using:</para>
+
+ <screen>&prompt.root; <userinput>pkg set -A 1 devel/cmake</userinput></screen>
+
+ <para>Once a package is a leaf package and is marked
+ as automatic, it gets selected by
+ <command>pkg autoremove</command>.</para>
+
+ <para>Marking an installed package as <emphasis>not</emphasis>
+ automatic can be done using:</para>
+
+ <screen>&prompt.root; <userinput>pkg set -A 0 devel/cmake</userinput></screen>
+
+ </sect2>
+
+ <sect2 xml:id="pkgng-backup">
+ <title>Restoring the Package Database</title>
+
+ <para>Unlike the traditional package management system,
+ <application>pkg</application> includes its own package
+ database backup mechanism. This functionality is enabled by
+ default.</para>
+
+ <tip>
+ <para>To disable the periodic script from backing up the
+ package database, set
+ <literal>daily_backup_pkgdb_enable="NO"</literal> in
+ &man.periodic.conf.5;.</para>
+ </tip>
+
+ <para>To restore the contents of a previous package database
+ backup, run the following command replacing
+ <replaceable>/path/to/pkg.sql</replaceable> with the location
+ of the backup:</para>
+
+ <screen>&prompt.root; <userinput>pkg backup -r <replaceable>/path/to/pkg.sql</replaceable></userinput></screen>
+
+ <note>
+ <para>If restoring a backup taken by the periodic script,
+ it must be decompressed prior to being restored.</para>
+ </note>
+
+ <para>To run a manual backup of the
+ <application>pkg</application> database, run the following
+ command, replacing <replaceable>/path/to/pkg.sql</replaceable>
+ with a suitable file name and location:</para>
+
+ <screen>&prompt.root; <userinput>pkg backup -d <replaceable>/path/to/pkg.sql</replaceable></userinput></screen>
+ </sect2>
+
+ <sect2 xml:id="pkgng-clean">
+ <title>Removing Stale Packages</title>
+
+ <para>By default, <application>pkg</application> stores
+ binary packages in a cache directory defined by
+ <envar>PKG_CACHEDIR</envar> in &man.pkg.conf.5;. Only copies
+ of the latest installed packages are kept. Older versions of
+ <application>pkg</application> kept all previous packages. To
+ remove these outdated binary packages, run:</para>
+
+ <screen>&prompt.root; <userinput>pkg clean</userinput></screen>
+
+ <para>The entire cache may be cleared by running:</para>
+
+ <screen>&prompt.root; <userinput>pkg clean -a</userinput></screen>
+ </sect2>
+
+ <sect2 xml:id="pkgng-set">
+ <title>Modifying Package Metadata</title>
+
+ <para>Software within the &os;&nbsp;Ports Collection can
+ undergo major version number changes. To address this,
+ <application>pkg</application> has a built-in command to
+ update package origins. This can be useful, for example, if
+ <package>lang/php5</package> is renamed to
+ <package>lang/php53</package> so that
+ <package>lang/php5</package> can now
+ represent version <literal>5.4</literal>.</para>
+
+ <para>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
+ <package>lang/ruby18</package> to
+ <package>lang/ruby19</package>, 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
+ <package>graphics/libglut</package> to
+ <package>graphics/freeglut</package>, run:</para>
+
+ <screen>&prompt.root; <userinput>pkg set -o graphics/libglut:graphics/freeglut</userinput></screen>
+
+ <note>
+ <para>When changing package origins, it is important to
+ reinstall packages that are dependent on the package with
+ the modified origin. To force a reinstallation of dependent
+ packages, run:</para>
+
+ <screen>&prompt.root; <userinput>pkg install -Rf <replaceable>graphics/freeglut</replaceable></userinput></screen>
+ </note>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="ports-using">
+ <title>Using the Ports Collection</title>
+
+ <para>The Ports Collection is a set of
+ <filename>Makefile</filename>s, patches, and description files.
+ Each set of these files is used to compile and install an
+ individual application on &os;, and is called a
+ <emphasis>port</emphasis>.</para>
+
+ <para>By default, the Ports Collection itself is stored as a
+ subdirectory of <filename>/usr/ports</filename>.</para>
+
+ <para>Before an application can be compiled using a port, the
+ Ports Collection must first be installed. If it was not
+ installed during the installation of &os;, use one of the
+ following methods to install it:</para>
+
+ <procedure xml:id="ports-using-portsnap-method">
+ <title>Portsnap Method</title>
+
+ <para>The base system of &os; includes
+ <application>Portsnap</application>. This is a fast and
+ user-friendly tool for retrieving the Ports Collection and
+ is the recommended choice for most users not running
+ &os.current;. This utility
+ connects to a &os; site, verifies the secure key, and
+ downloads a new copy of the Ports Collection. The key is used
+ to verify the integrity of all downloaded files.</para>
+
+ <step>
+ <para>To download a compressed snapshot of the Ports
+ Collection into
+ <filename>/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>/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>/usr/ports</filename> can be updated
+ as needed by running:</para>
+
+ <screen>&prompt.root; <userinput>portsnap fetch</userinput>
+&prompt.root; <userinput>portsnap update</userinput></screen>
+
+ <para>When using <literal>fetch</literal>, the
+ <literal>extract</literal> or the <literal>update</literal>
+ operation may be run consecutively, like so:</para>
+
+ <screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="ports-using-subversion-method">
+ <title>Subversion Method</title>
+
+ <para>If more control over the ports tree is needed or if local
+ changes need to be maintained, or if running &os.current;,
+ <application>Subversion</application> can be used to obtain
+ the Ports Collection. Refer to <link
+ xlink:href="&url.articles.committers-guide;/subversion-primer.html">the
+ Subversion Primer</link> 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, or
+ <application>pkg</application> is being used to manage
+ packages, <application>Subversion</application> can be
+ installed as a package:</para>
+
+ <screen>&prompt.root; <userinput>pkg install subversion</userinput></screen>
+
+ </step>
+
+ <step>
+ <para>Check out a copy of the ports tree:</para>
+
+ <screen>&prompt.root; <userinput>svn checkout https://svn.FreeBSD.org/ports/head /usr/ports</userinput></screen>
+ </step>
+
+ <step>
+ <para>As needed, update <filename>/usr/ports</filename> after
+ the initial <application>Subversion</application>
+ checkout:</para>
+
+ <screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen>
+ </step>
+ </procedure>
+
+ <para>The Ports Collection contains directories
+ for software categories. Inside each category are
+ subdirectories for individual applications. Each application
+ subdirectory contains a set of files that
+ tells &os; how to compile and install that program,
+ called a <emphasis>ports skeleton</emphasis>. Each port
+ skeleton includes these files and directories:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><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>: contains the names and
+ checksums of the files that must be downloaded to build the
+ port.</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>: provides a more detailed
+ description of the program.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>pkg-plist</filename>: a list of all the
+ files that will be installed by the port. It also tells
+ the ports system which files to remove upon
+ deinstallation.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Some ports include <filename>pkg-message</filename> or
+ other files to handle special situations. For more details
+ on these files, and on ports in general, refer to the <link
+ xlink:href="&url.books.porters-handbook;/index.html">&os;
+ Porter's Handbook</link>.</para>
+
+ <para>The port does not include the actual source code, also
+ known as a <filename>distfile</filename>. The extract portion
+ of building a port will automatically save the downloaded
+ source to <filename>/usr/ports/distfiles</filename>.</para>
+
+ <sect2 xml:id="ports-skeleton">
+ <title>Installing Ports</title>
+
+ <indexterm>
+ <primary>ports</primary>
+ <secondary>installing</secondary>
+ </indexterm>
+
+ <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>Before compiling any port, be sure to update the Ports
+ Collection as described in the previous section. Since
+ the installation of any third-party software can introduce
+ security vulnerabilities, it is recommended to first check
+ <link xlink:href="https://vuxml.freebsd.org/"></link>
+ for known security issues related to the port. Alternately,
+ run <command>pkg audit -F</command> before installing a new
+ port. This command can be configured to automatically
+ perform a security audit and an update of the vulnerability
+ database during the daily security system check. For more
+ information, refer to &man.pkg-audit.8; and
+ &man.periodic.8;.</para>
+ </warning>
+
+ <para>Using the Ports Collection assumes a working Internet
+ connection. It also requires superuser privilege.</para>
+
+ <para>To compile and install the port, change to the directory
+ of the port to be installed, then type <command>make
+ install</command> at the prompt. Messages will indicate
+ the progress:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
+&prompt.root; <userinput>make install</userinput>
+&gt;&gt; lsof_4.88D.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.88
+...
+[extraction output snipped]
+...
+&gt;&gt; Checksum OK for lsof_4.88D.freebsd.tar.gz.
+===&gt; Patching for lsof-4.88.d,8
+===&gt; Applying FreeBSD patches for lsof-4.88.d,8
+===&gt; Configuring for lsof-4.88.d,8
+...
+[configure output snipped]
+...
+===&gt; Building for lsof-4.88.d,8
+...
+[compilation output snipped]
+...
+
+===&gt; Installing for lsof-4.88.d,8
+...
+[installation output snipped]
+...
+===&gt; Generating temporary packing list
+===&gt; Compressing manual pages for lsof-4.88.d,8
+===&gt; Registering installation for lsof-4.88.d,8
+===&gt; SECURITY NOTE:
+ This port has installed the following binaries which execute with
+ increased privileges.
+/usr/local/sbin/lsof
+&prompt.root;</screen>
+
+ <para>Since <command>lsof</command> is a program that runs
+ with increased privileges, a security warning is displayed
+ as it is installed. Once the installation is complete, the
+ prompt will be returned.</para>
+
+ <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. Users
+ of the <command>tcsh</command> shell should 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>
+
+ <para>During installation, a working subdirectory is created
+ which contains all the temporary files used during
+ compilation. Removing this directory 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-88.d,8
+&prompt.root;</screen>
+
+ <note>
+ <para>To save this extra step, instead use <command>make
+ install clean</command> when compiling the port.</para>
+ </note>
+
+ <sect3>
+ <title>Customizing Ports Installation</title>
+
+ <para>Some ports provide build options which can be used to
+ enable or disable application components, provide security
+ options, or allow for other customizations. Examples
+ include <package>www/firefox</package>,
+ <package>security/gpgme</package>, and
+ <package>mail/sylpheed-claws</package>. If the port depends
+ upon other ports which have configurable options, it may
+ pause several times for user interaction as the default
+ behavior is to prompt the user to select options from a
+ menu. To avoid this and do all of the configuration in one
+ batch, run <command>make config-recursive</command> within
+ the port skeleton. Then, run <command>make install
+ [clean]</command> to compile and install the port.</para>
+
+ <tip>
+ <para>When using
+ <buildtarget>config-recursive</buildtarget>, the list of
+ ports to configure are gathered by the
+ <buildtarget>all-depends-list</buildtarget> target. It is
+ recommended to run <command>make
+ config-recursive</command> until all dependent ports
+ options have been defined, and ports options screens no
+ longer appear, to be certain that all dependency options
+ have been configured.</para>
+ </tip>
+
+ <para>There are several ways to revisit a port's build options
+ 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 config</command>. Another
+ option is to use <command>make showconfig</command>.
+ Another option is to execute <command>make
+ rmconfig</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
+ &man.ports.7;.</para>
+
+ <para>The ports system uses &man.fetch.1; to download the
+ source files, which supports various environment variables.
+ The <envar>FTP_PASSIVE_MODE</envar>,
+ <envar>FTP_PROXY</envar>, and <envar>FTP_PASSWORD</envar>
+ variables may need to be set if the &os; system is behind
+ a firewall or FTP/HTTP proxy. See &man.fetch.3; for the
+ complete list of supported variables.</para>
+
+ <para>For users who cannot be connected to the Internet all
+ the time, <command>make fetch</command> can be run within
+ <filename>/usr/ports</filename>, to fetch all distfiles, or
+ within a category, such as
+ <filename>/usr/ports/net</filename>, or within the specific
+ port skeleton. Note that if a port has any dependencies,
+ running this command in a category or ports skeleton will
+ <emphasis>not</emphasis> fetch the distfiles of ports from
+ another category. Instead, use <command>make
+ fetch-recursive</command> to also fetch the distfiles for
+ all the dependencies of a port.</para>
+
+ <para>In rare cases, such as when an organization has a local
+ distfiles repository, the <varname>MASTER_SITES</varname>
+ variable can be used to override the download locations
+ specified in the <filename>Makefile</filename>. When using,
+ specify the alternate location:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
+&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
+<replaceable>ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/</replaceable> fetch</userinput></screen>
+
+ <para>The <varname>WRKDIRPREFIX</varname> and
+ <varname>PREFIX</varname> 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>. And:</para>
+
+ <screen>&prompt.root; <userinput>make WRKDIRPREFIX=../ports PREFIX=../local install</userinput></screen>
+
+ <para>will combine the two.</para>
+
+ <para>These can also be set as environmental variables. Refer
+ to the manual page for your shell for instructions on how to
+ set an environmental variable.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 xml:id="ports-removing">
+ <title>Removing Installed Ports</title>
+
+ <indexterm>
+ <primary>ports</primary>
+ <secondary>removing</secondary>
+ </indexterm>
+
+ <para>Installed ports can be uninstalled using <command>pkg
+ delete</command>. Examples for using this command can be
+ found in the &man.pkg-delete.8; manual page.</para>
+
+ <para>Alternately, <command>make deinstall</command> can be
+ run in the port's directory:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
+&prompt.root; <userinput>make deinstall</userinput>
+===&gt; Deinstalling for sysutils/lsof
+===&gt; Deinstalling
+Deinstallation has been requested for the following 1 packages:
+
+ lsof-4.88.d,8
+
+The deinstallation will free 229 kB
+[1/1] Deleting lsof-4.88.d,8... done</screen>
+
+ <para>It is recommended to read the messages as the port is
+ uninstalled. If the port has any applications that depend
+ upon it, this information will be displayed but the
+ uninstallation will proceed. In such cases, it may be better
+ to reinstall the application in order to prevent broken
+ dependencies.</para>
+ </sect2>
+
+ <sect2 xml:id="ports-upgrading">
+ <title>Upgrading Ports</title>
+
+ <indexterm>
+ <primary>ports</primary>
+ <secondary>upgrading</secondary>
+ </indexterm>
+
+ <para>Over time, newer versions of software become available
+ in the Ports Collection. This section describes how to
+ determine which software can be upgraded and how to perform
+ the upgrade.</para>
+
+ <para>To determine if newer versions of installed ports are
+ available, ensure that the latest version of the ports tree is
+ installed, using the updating command described in either
+ <xref linkend="ports-using-portsnap-method"/> or
+ <xref linkend="ports-using-subversion-method"/>. On &os; 10
+ and later, or if the system has been converted to
+ <application>pkg</application>, the following command will
+ list the installed ports which are out of date:</para>
+
+ <screen>&prompt.root; <userinput>pkg version -l "&lt;"</userinput></screen>
+
+ <para>For &os; 9.<replaceable>X</replaceable> and lower, the
+ following command will list the installed ports that are out
+ of date:</para>
+
+ <screen>&prompt.root; <userinput>pkg_version -l "&lt;"</userinput></screen>
+
+ <important>
+ <para>Before
+ attempting an upgrade, read
+ <filename>/usr/ports/UPDATING</filename> from the top of
+ the file to the date closest to the last time ports were
+ upgraded or the system was installed. 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 any incompatibilities with previous
+ versions. Make note of any instructions which match any of
+ the ports that need upgrading and follow these instructions
+ when performing the upgrade.</para>
+ </important>
+
+ <sect3 xml:id="ports-upgrading-tools">
+ <title>Tools to Upgrade and Manage Ports</title>
+
+ <indexterm>
+ <primary>ports</primary>
+ <secondary>upgrading-tools</secondary>
+ </indexterm>
+
+ <para>The Ports Collection contains several utilities to
+ perform the actual upgrade. Each has its strengths and
+ weaknesses.</para>
+
+ <para>Historically, most installations used either
+ <application>Portmaster</application> or
+ <application>Portupgrade</application>.
+ <application>Synth</application> is a newer
+ alternative.</para>
+
+ <note>
+ <para>The choice of which tool is best for a particular
+ system is up to the system administrator. It is
+ recommended practice to back up your data before using any
+ of these tools.</para>
+ </note>
+
+ </sect3>
+
+ <sect3 xml:id="portmaster">
+ <title>Upgrading Ports Using
+ <application>Portmaster</application></title>
+
+ <indexterm>
+ <primary>portmaster</primary>
+ </indexterm>
+
+ <para><package>ports-mgmt/portmaster</package> is a very
+ small utility for upgrading installed ports.
+ It is designed to use the tools installed with the &os;
+ base system
+ without depending on other ports or databases.
+ To install this utility
+ as a port:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portmaster</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+ <para><application>Portmaster</application> defines four
+ categories of ports:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Root port: has no dependencies and is not a
+ dependency of any other ports.</para>
+ </listitem>
+
+ <listitem>
+ <para>Trunk port: has no dependencies, but other ports
+ depend upon it.</para>
+ </listitem>
+
+ <listitem>
+ <para>Branch port: has dependencies and other ports
+ depend upon it.</para>
+ </listitem>
+
+ <listitem>
+ <para>Leaf port: has dependencies but no other ports
+ depend upon it.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To list these categories and search for updates:</para>
+
+ <screen>&prompt.root; <userinput>portmaster -L</userinput>
+===&gt;&gt;&gt; Root ports (No dependencies, not depended on)
+===&gt;&gt;&gt; ispell-3.2.06_18
+===&gt;&gt;&gt; screen-4.0.3
+ ===&gt;&gt;&gt; New version available: screen-4.0.3_1
+===&gt;&gt;&gt; tcpflow-0.21_1
+===&gt;&gt;&gt; 7 root ports
+...
+===&gt;&gt;&gt; Branch ports (Have dependencies, are depended on)
+===&gt;&gt;&gt; apache22-2.2.3
+ ===&gt;&gt;&gt; New version available: apache22-2.2.8
+...
+===&gt;&gt;&gt; Leaf ports (Have dependencies, not depended on)
+===&gt;&gt;&gt; automake-1.9.6_2
+===&gt;&gt;&gt; bash-3.1.17
+ ===&gt;&gt;&gt; New version available: bash-3.2.33
+...
+===&gt;&gt;&gt; 32 leaf ports
+
+===&gt;&gt;&gt; 137 total installed ports
+ ===&gt;&gt;&gt; 83 have new versions available</screen>
+
+ <para>This command is used to upgrade all outdated
+ ports:</para>
+
+ <screen>&prompt.root; <userinput>portmaster -a</userinput></screen>
+
+ <note>
+ <para>By default, <application>Portmaster</application>
+ makes a backup package before deleting the existing port.
+ If the installation of the new version is successful,
+ <application>Portmaster</application> deletes the
+ backup. Using <option>-b</option> instructs
+ <application>Portmaster</application> not to automatically
+ delete the backup. Adding <option>-i</option> starts
+ <application>Portmaster</application> in interactive mode,
+ prompting for confirmation before upgrading each port.
+ Many other options are available. Read through the
+ manual page for &man.portmaster.8; for details regarding
+ their usage.</para>
+ </note>
+
+ <para>If errors are encountered during the upgrade process,
+ add <option>-f</option> to upgrade and rebuild all
+ ports:</para>
+
+ <screen>&prompt.root; <userinput>portmaster -af</userinput></screen>
+
+ <para><application>Portmaster</application> can also be used
+ to install new ports on the system, upgrading all
+ dependencies before building and installing the new
+ port. To use this function, specify the location of the
+ port in the Ports Collection:</para>
+
+ <screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen>
+
+ <para>More information about
+ <package>ports-mgmt/portmaster</package> may be found in its
+ <filename>pkg-descr</filename>.</para>
+ </sect3>
+
+ <sect3 xml:id="portupgrade">
+ <title>Upgrading Ports Using Portupgrade</title>
+
+ <indexterm>
+ <primary>portupgrade</primary>
+ </indexterm>
+
+ <para><package>ports-mgmt/portupgrade</package> is another
+ utility that can be used to upgrade ports. It installs a
+ suite of applications which can be used to manage ports.
+ However, it is dependent upon Ruby. To install the
+ port:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portupgrade</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+ <para>Before performing an upgrade using this utility, it is
+ recommended to scan the list of installed ports using
+ <command>pkgdb -F</command> and to fix all the
+ inconsistencies it reports.</para>
+
+ <para>To upgrade all the outdated ports installed on the
+ system, use <command>portupgrade -a</command>. Alternately,
+ 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>. It is very
+ important to 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>If
+ <option>-P</option> is included,
+ <application>Portupgrade</application> searches for
+ available packages in the local directories listed in
+ <envar>PKG_PATH</envar>. If none are available locally, it
+ then fetches packages from a remote site. If packages can
+ not be found locally or fetched remotely,
+ <application>Portupgrade</application> will use ports. To
+ avoid using ports entirely, specify <option>-PP</option>.
+ This last set of options tells
+ <application>Portupgrade</application> to abort if no
+ packages are available:</para>
+
+ <screen>&prompt.root; <userinput>portupgrade -PP gnome3</userinput></screen>
+
+ <para>To just fetch the port distfiles, or packages, if
+ <option>-P</option> is specified, without building or
+ installing anything, use <option>-F</option>. For further
+ information on all of the available switches, refer to the
+ manual page for <command>portupgrade</command>.</para>
+
+ <para>More information about
+ <package>ports-mgmt/portupgrade</package> may be found in
+ its <filename>pkg-descr</filename>.</para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 xml: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, running
+ <command>make clean</command> within the ports skeleton will
+ clean up the temporary <filename>work</filename> directory.
+ If <application>Portmaster</application> is used to install a
+ port, it will automatically remove this directory unless
+ <option>-K</option> is specified. If
+ <application>Portupgrade</application> is installed, this
+ command will remove all <filename>work</filename> directories
+ found within the local copy of the Ports Collection:</para>
+
+ <screen>&prompt.root; <userinput>portsclean -C</userinput></screen>
+
+ <para>In addition, outdated source distribution files
+ accumulate in <filename>/usr/ports/distfiles</filename> over
+ time. To use <application>Portupgrade</application> to
+ delete all the distfiles that are no longer
+ referenced by any ports:</para>
+
+ <screen>&prompt.root; <userinput>portsclean -D</userinput></screen>
+
+ <para><application>Portupgrade</application> can remove
+ all distfiles not referenced by any port currently installed
+ on the system:</para>
+
+ <screen>&prompt.root; <userinput>portsclean -DD</userinput></screen>
+
+ <para>If <application>Portmaster</application> is installed,
+ use:</para>
+
+ <screen>&prompt.root; <userinput>portmaster --clean-distfiles</userinput></screen>
+
+ <para>By default, this command is interactive and prompts
+ the user to confirm if a distfile should be deleted.</para>
+
+ <para>In addition to these commands,
+ <package>ports-mgmt/pkg_cutleaves</package>
+ automates the task of removing installed ports that are no
+ longer needed.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="ports-poudriere">
+ <title>Building Packages with
+ <application>Poudriere</application></title>
+
+ <para><application>Poudriere</application> is a
+ <acronym>BSD</acronym>-licensed utility for creating and testing
+ &os; packages. It uses &os; jails to set up isolated
+ compilation environments. These jails can be used to build
+ packages for versions of &os; that are different from the system
+ on which it is installed, and also to build packages for i386 if
+ the host is an &arch.amd64; system. Once the packages are
+ built, they are in a layout identical to the official mirrors.
+ These packages are usable by &man.pkg.8; and other package
+ management tools.</para>
+
+ <para><application>Poudriere</application> is installed using
+ the <package role="port">ports-mgmt/poudriere</package> package
+ or port. The installation includes a sample configuration
+ file <filename>/usr/local/etc/poudriere.conf.sample</filename>.
+ Copy this file to
+ <filename>/usr/local/etc/poudriere.conf</filename>. Edit the
+ copied file to suit the local configuration.</para>
+
+ <para>While <acronym>ZFS</acronym> is not required on the system
+ running <application>poudriere</application>, it is beneficial.
+ When <acronym>ZFS</acronym> is used,
+ <varname>ZPOOL</varname> must be specified in
+ <filename>/usr/local/etc/poudriere.conf</filename> and
+ <varname>FREEBSD_HOST</varname> should be set to a nearby
+ mirror. Defining <varname>CCACHE_DIR</varname> enables the use
+ of <package role="port">devel/ccache</package> to cache
+ compilation and reduce build times for frequently-compiled code.
+ It may be convenient to put
+ <application>poudriere</application> datasets in an isolated
+ tree mounted at <filename
+ >/poudriere</filename>. Defaults for the
+ other configuration values are adequate.</para>
+
+ <para>The number of processor cores detected is used to define how
+ many builds will run in parallel. Supply enough virtual memory,
+ either with <acronym>RAM</acronym> or swap space. If virtual
+ memory runs out, the compilation jails will stop and be torn
+ down, resulting in weird error messages.</para>
+
+ <sect2 xml:id="poudriere-initialization">
+ <title>Initialize Jails and Port Trees</title>
+
+ <para>After configuration, initialize
+ <application>poudriere</application> so that it installs a
+ jail with the required &os; tree and a ports tree. Specify a
+ name for the jail using <option>-j</option> and the &os;
+ version with <option>-v</option>. On systems running
+ &os;/&arch.amd64;, the architecture can be set with
+ <option>-a</option> to either <literal>i386</literal> or
+ <literal>amd64</literal>. The default is the
+ architecture shown by <command>uname</command>.</para>
+
+ <screen>&prompt.root; <userinput>poudriere jail -c -j <replaceable>11amd64</replaceable> -v <replaceable>11.4-RELEASE</replaceable></userinput>
+[00:00:00] Creating 11amd64 fs at /poudriere/jails/11amd64... done
+[00:00:00] Using pre-distributed MANIFEST for FreeBSD 11.4-RELEASE amd64
+[00:00:00] Fetching base for FreeBSD 11.4-RELEASE amd64
+/poudriere/jails/11amd64/fromftp/base.txz 125 MB 4110 kBps 31s
+[00:00:33] Extracting base... done
+[00:00:54] Fetching src for FreeBSD 11.4-RELEASE amd64
+/poudriere/jails/11amd64/fromftp/src.txz 154 MB 4178 kBps 38s
+[00:01:33] Extracting src... done
+[00:02:31] Fetching lib32 for FreeBSD 11.4-RELEASE amd64
+/poudriere/jails/11amd64/fromftp/lib32.txz 24 MB 3969 kBps 06s
+[00:02:38] Extracting lib32... done
+[00:02:42] Cleaning up... done
+[00:02:42] Recording filesystem state for clean... done
+[00:02:42] Upgrading using ftp
+/etc/resolv.conf -&gt; /poudriere/jails/11amd64/etc/resolv.conf
+Looking up update.FreeBSD.org mirrors... 3 mirrors found.
+Fetching public key from update4.freebsd.org... done.
+Fetching metadata signature for 11.4-RELEASE from update4.freebsd.org... done.
+Fetching metadata index... done.
+Fetching 2 metadata files... done.
+Inspecting system... done.
+Preparing to download files... done.
+Fetching 124 patches.....10....20....30....40....50....60....70....80....90....100....110....120.. done.
+Applying patches... done.
+Fetching 6 files... done.
+The following files will be added as part of updating to
+11.4-RELEASE-p1:
+/usr/src/contrib/unbound/.github
+/usr/src/contrib/unbound/.github/FUNDING.yml
+/usr/src/contrib/unbound/contrib/drop2rpz
+/usr/src/contrib/unbound/contrib/unbound_portable.service.in
+/usr/src/contrib/unbound/services/rpz.c
+/usr/src/contrib/unbound/services/rpz.h
+/usr/src/lib/libc/tests/gen/spawnp_enoexec.sh
+The following files will be updated as part of updating to
+11.4-RELEASE-p1:
+[&hellip;]
+Installing updates...Scanning //usr/share/certs/blacklisted for certificates...
+Scanning //usr/share/certs/trusted for certificates...
+ done.
+11.4-RELEASE-p1
+[00:04:06] Recording filesystem state for clean... done
+[00:04:07] Jail 11amd64 11.4-RELEASE-p1 amd64 is ready to be used</screen>
+
+ <screen>&prompt.root; <userinput>poudriere ports -c -p <replaceable>local</replaceable> -m svn+https</userinput>
+[00:00:00] Creating local fs at /poudriere/ports/local... done
+[00:00:00] Checking out the ports tree... done</screen>
+
+ <para>On a single computer, <application>poudriere</application>
+ can build ports with multiple configurations, in multiple
+ jails, and from different port trees. Custom configurations
+ for these combinations are called <emphasis>sets</emphasis>.
+ See the CUSTOMIZATION section of &man.poudriere.8; for details
+ after <package>ports-mgmt/poudriere</package> or
+ <package>ports-mgmt/poudriere-devel</package> is
+ installed.</para>
+
+ <para>The basic configuration shown here puts a single jail-,
+ port-, and set-specific <filename>make.conf</filename> in
+ <filename
+ >/usr/local/etc/poudriere.d</filename>.
+ The filename in this example is created by combining the jail
+ name, port name, and set name:
+ <filename><replaceable>11amd64-local-workstation</replaceable>-make.conf</filename>.
+ The system <filename>make.conf</filename> and this new file
+ are combined at build time to create the
+ <filename>make.conf</filename> used by the build jail.</para>
+
+ <para>Packages to be built are entered in
+ <filename><replaceable>11amd64-local-workstation</replaceable>-pkglist</filename>:</para>
+
+ <programlisting>editors/emacs
+devel/git
+ports-mgmt/pkg
+...</programlisting>
+
+ <para>Options and dependencies for the specified ports are
+ configured:</para>
+
+ <screen>&prompt.root; <userinput>poudriere options -j <replaceable>11amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>11amd64-local-workstation-pkglist</replaceable></userinput></screen>
+
+ <para>Finally, packages are built and a package
+ repository is created:</para>
+
+ <screen>&prompt.root; <userinput>poudriere bulk -j <replaceable>11amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>11amd64-local-workstation-pkglist</replaceable></userinput></screen>
+
+ <para>While running, pressing <keycombo
+ action="simul"><keycap>Ctrl</keycap><keycap>t</keycap></keycombo>
+ displays the current state of the build.
+ <application>Poudriere</application> also builds files in
+ <filename>/poudriere/logs/bulk/<replaceable>jailname</replaceable></filename>
+ that can be used with a web server to display build
+ information.</para>
+
+ <para>After completion, the new packages are now available for
+ installation from the <application>poudriere</application>
+ repository.</para>
+
+ <para>For more information on using
+ <application>poudriere</application>, see &man.poudriere.8;
+ and the main web site, <link
+ xlink:href="https://github.com/freebsd/poudriere/wiki"></link>.</para>
+ </sect2>
+ <sect2>
+ <title>Configuring pkg Clients to Use a Poudriere
+ Repository</title>
+
+ <para>While it is possible to use both a custom repository along
+ side of the official repository, sometimes it is useful to
+ disable the official repository. This is done by creating a
+ configuration file that overrides and disables the official
+ configuration file. Create
+ <filename>/usr/local/etc/pkg/repos/FreeBSD.conf</filename>
+ that contains the following:</para>
+
+ <programlisting>FreeBSD: {
+ enabled: no
+}</programlisting>
+
+ <para>Usually it is easiest to serve a poudriere repository to
+ the client machines via HTTP. Set up a webserver to serve up
+ the package directory, for instance:
+ <filename>/usr/local/poudriere/data/packages/<replaceable>11amd64</replaceable></filename>,
+ where <filename><replaceable>11amd64</replaceable></filename>
+ is the name of the build.</para>
+
+ <para>If the URL to the package repository is:
+ <literal>http://pkg.example.com/11amd64</literal>, then the
+ repository configuration file in
+ <filename>/usr/local/etc/pkg/repos/custom.conf</filename>
+ would look like:</para>
+
+ <programlisting>custom: {
+ url: "<replaceable>http://pkg.example.com/11amd64</replaceable>",
+ enabled: yes,
+}</programlisting>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="ports-nextsteps">
+ <title>Post-Installation Considerations</title>
+
+ <para>Regardless of whether the software was installed from a
+ binary package or port, most third-party applications require
+ some level of configuration after installation. The following
+ commands and locations can be used to help determine what was
+ installed with the application.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Most applications install at least one default
+ configuration file in <filename>/usr/local/etc</filename>.
+ In cases where an application has a large number of
+ configuration files, a subdirectory will be created to hold
+ them. Often, sample configuration files are installed which
+ end with a suffix such as <filename>.sample</filename>. The
+ configuration files should be reviewed and possibly
+ edited to meet the system's needs. To edit a sample file,
+ first copy it without the <filename>.sample</filename>
+ extension.</para>
+ </listitem>
+
+ <listitem>
+ <para>Applications which provide documentation will install
+ it into <filename>/usr/local/share/doc</filename> and many
+ applications also install manual pages. This documentation
+ should be consulted before continuing.</para>
+ </listitem>
+
+ <listitem>
+ <para>Some applications run services which must be added
+ to <filename>/etc/rc.conf</filename> before starting the
+ application. These applications usually install a startup
+ script in <filename>/usr/local/etc/rc.d</filename>. See
+ <link linkend="configtuning-starting-services">Starting
+ Services</link> for more information.</para>
+
+ <note>
+ <para>By design, applications do not run their startup
+ script upon installation, nor do they run their stop
+ script upon deinstallation or upgrade. This decision
+ is left to the individual system administrator.</para>
+ </note>
+
+ </listitem>
+
+ <listitem>
+ <para>Users of &man.csh.1; should run
+ <command>rehash</command> to rebuild the known binary list
+ in the shells <envar>PATH</envar>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Use <command>pkg info</command> to determine which
+ files, man pages, and binaries were installed with the
+ application.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 xml:id="ports-broken">
+ <title>Dealing with Broken Ports</title>
+
+ <para>When a port does not build or
+ install, try the following:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Search to see if there is a fix pending for the port in
+ the <link xlink:href="&url.base;/support.html">Problem
+ Report database</link>. If so, implementing the proposed
+ fix may fix the issue.</para>
+ </listitem>
+
+ <listitem>
+ <para>Ask the maintainer of the port for help. Type
+ <command>make maintainer</command>
+ in the ports skeleton or read the port's
+ <filename>Makefile</filename> to find the maintainer's
+ email address. Remember to include the
+ <literal>&dollar;FreeBSD:</literal> line from the port's
+ <filename>Makefile</filename> and the output leading up to
+ the error in the email to the maintainer.</para>
+
+ <note>
+ <para>Some ports are not maintained by an individual but
+ instead by a group maintainer represented by a <link
+ xlink:href="&url.articles.mailing-list-faq;/article.html">mailing
+ list</link>. Many, but not all, of these addresses look
+ like <email
+ role="nolink">freebsd-<replaceable>listname</replaceable>@FreeBSD.org</email>.
+ Please take this into account when sending an
+ email.</para>
+
+ <para>In particular, ports maintained by
+ <email role="nolink">ports@FreeBSD.org</email> are not
+ maintained by a specific individual. Instead, any fixes
+ and support come from the general community who subscribe
+ to that mailing list. More volunteers are always
+ needed!</para>
+ </note>
+
+ <para>If there is no response to the email, use
+ Bugzilla to submit a bug report using the
+ instructions in <link
+ xlink:href="&url.articles.problem-reports;/article.html">Writing
+ &os; Problem Reports</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Fix it! The <link
+ xlink:href="&url.books.porters-handbook;/index.html">Porter's
+ Handbook</link> includes detailed information on the
+ ports infrastructure so that you can fix the occasional
+ broken port or even submit your own!</para>
+ </listitem>
+
+ <listitem>
+ <para>Install the package instead of the port using the
+ instructions in <xref linkend="pkgng-intro"/>.</para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+</chapter>