Attachment 214216 Details for Bug 246091 – Small change to the Handbook to fix this problem

Small change to the Handbook to fix this problem

chapter.xml (text/plain), 68.26 KB, created by donaldcallen on 2020-05-07 02:28:22 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: donaldcallen

Created: 2020-05-07 02:28:22 UTC

Size: 68.26 KB

patch

obsolete

><?xml version="1.0" encoding="iso-8859-1"?>
>
><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 bootstrap</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>Makefiles</filename>, 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.  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,
>	<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>10amd64</replaceable> -v <replaceable>10.0-RELEASE</replaceable></userinput>
>====&gt;&gt; Creating 10amd64 fs... done
>====&gt;&gt; Fetching base.txz for FreeBSD 10.0-RELEASE amd64
>/poudriere/jails/10amd64/fromftp/base.txz      100% of   59 MB 1470 kBps 00m42s
>====&gt;&gt; Extracting base.txz... done
>====&gt;&gt; Fetching src.txz for FreeBSD 10.0-RELEASE amd64
>/poudriere/jails/10amd64/fromftp/src.txz       100% of  107 MB 1476 kBps 01m14s
>====&gt;&gt; Extracting src.txz... done
>====&gt;&gt; Fetching games.txz for FreeBSD 10.0-RELEASE amd64
>/poudriere/jails/10amd64/fromftp/games.txz     100% of  865 kB  734 kBps 00m01s
>====&gt;&gt; Extracting games.txz... done
>====&gt;&gt; Fetching lib32.txz for FreeBSD 10.0-RELEASE amd64
>/poudriere/jails/10amd64/fromftp/lib32.txz     100% of   14 MB 1316 kBps 00m12s
>====&gt;&gt; Extracting lib32.txz... done
>====&gt;&gt; Cleaning up... done
>====&gt;&gt; Jail 10amd64 10.0-RELEASE amd64 is ready to be used</screen>
>
>      <screen>&prompt.root; <userinput>poudriere ports -c -p <replaceable>local</replaceable></userinput>
>====&gt;&gt; Creating local fs... done
>====&gt;&gt; Extracting portstree "local"...
>Looking up portsnap.FreeBSD.org mirrors... 7 mirrors found.
>Fetching public key from ec2-eu-west-1.portsnap.freebsd.org... done.
>Fetching snapshot tag from ec2-eu-west-1.portsnap.freebsd.org... done.
>Fetching snapshot metadata... done.
>Fetching snapshot generated at Tue Feb 11 01:07:15 CET 2014:
>94a3431f0ce567f6452ffde4fd3d7d3c6e1da143efec76100% of   69 MB 1246 kBps 00m57s
>Extracting snapshot... done.
>Verifying snapshot integrity... done.
>Fetching snapshot tag from ec2-eu-west-1.portsnap.freebsd.org... done.
>Fetching snapshot metadata... done.
>Updating from Tue Feb 11 01:07:15 CET 2014 to Tue Feb 11 16:05:20 CET 2014.
>Fetching 4 metadata patches... done.
>Applying metadata patches... done.
>Fetching 0 metadata files... done.
>Fetching 48 patches.
>(48/48) 100.00%  done.
>done.
>Applying patches...
>done.
>Fetching 1 new ports or files... done.
>/poudriere/ports/tester/CHANGES
>/poudriere/ports/tester/COPYRIGHT
>
>[...]
>
>Building new INDEX files... 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>10amd64-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>10amd64-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>10amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>10amd64-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>10amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>10amd64-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>10amd64</replaceable></filename>,
>	where <filename><replaceable>10amd64</replaceable></filename>
>	is the name of the build.</para>
>
>      <para>If the URL to the package repository is:
>	<literal>http://pkg.example.com/10amd64</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/10amd64</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>

Actions: View

Attachments on bug 246091: 214216