svn commit: r42829 - head/en_US.ISO8859-1/books/handbook/ports
Dru Lavigne
dru at FreeBSD.org
Fri Oct 4 18:43:32 UTC 2013
Author: dru
Date: Fri Oct 4 18:43:31 2013
New Revision: 42829
URL: http://svnweb.freebsd.org/changeset/doc/42829
Log:
This patch does the following:
- general tightening and clarification of content
- the section 3s were changed to section 2s to prevent this chapter from going too deep into headings and to be more consistent with the previous section; I will make igor happy with a white-space change after the rest of the changes to chapter 5 are complete
- listings were updated to latest version of pkgng
Approved by: gjb (mentor)
Modified:
head/en_US.ISO8859-1/books/handbook/ports/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Fri Oct 4 17:54:01 2013 (r42828)
+++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Fri Oct 4 18:43:31 2013 (r42829)
@@ -568,40 +568,37 @@ docbook =
<title>Using <application>pkgng</application> for Binary Package
Management</title>
- <para><application>pkgng</application> is an improved replacement
+ <para><application>pkgng</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. The first release of <application>pkgng</application>
- was in August, 2012.</para>
+ easier.</para>
<para><application>pkgng</application> is not a replacement for
port management tools like <filename
role="package">ports-mgmt/portmaster</filename> or <filename
- role="package">ports-mgmt/portupgrade</filename>. While
- <filename role="package">ports-mgmt/portmaster</filename> and
- <filename role="package">ports-mgmt/portupgrade</filename> can
+ role="package">ports-mgmt/portupgrade</filename>. These
+ tools can be used to
install third-party software from both binary packages and the
- Ports Collection, <application>pkgng</application> installs
+ Ports Collection, while <application>pkgng</application> installs
only binary packages.</para>
<sect2 id="pkgng-initial-setup">
<title>Getting Started with
<application>pkgng</application></title>
- <para>&os; 9.1 and later includes a "bootstrap"
- utility for <application>pkgng</application>. The bootstrap
- utility will download and install
- <application>pkgng</application>.</para>
+ <para>&os; 9.1 and later includes a bootstrap
+ utility which can be used to download and install
+ <application>pkgng</application>, along with its manual pages.</para>
<para>To bootstrap the system, run:</para>
<screen>&prompt.root; <userinput>/usr/sbin/pkg</userinput></screen>
<para>For earlier &os; versions,
- <application>pkgng</application> must be installed from the
- Ports Collection, or as a binary package.</para>
+ <application>pkgng</application> must instead be installed from the
+ Ports Collection or as a binary package.</para>
- <para>To install the <application>pkgng</application> port,
+ <para>To install the port,
run:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/pkg</userinput>
@@ -612,220 +609,181 @@ docbook =
<screen>&prompt.root; <userinput>pkg_add -r pkg</userinput></screen>
- <para>Existing &os; installations require conversion of the
- <application>pkg_install</application> package database to the
- new format. To convert the package database, run:</para>
+ <para>Once <application>pkgng</application> is 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>
<para>This step is not required for new installations that do
- not have third-party software installed.</para>
+ not yet have any third-party software installed.</para>
<important>
<para>This step is not reversible. Once the package database
has been converted to the <application>pkgng</application>
- format, the <application>pkg_install</application> tools
+ format, the traditional <literal>pkg_*</literal> tools
should not be used.</para>
</important>
<note>
<para>The package database conversion may emit errors as the
contents are converted to the new version. Generally, these
- errors can be safely ignored, however a list of third-party
+ errors can be safely ignored. However, a list of third-party
software that was not successfully converted will be listed
- after <command>pkg2ng</command> has finished. These must be
- fixed by hand.</para>
+ after <command>pkg2ng</command> has finished and these applications must be
+ manually reinstalled.</para>
</note>
- <para>To ensure the &os; Ports Collection registers new
+ <para>To ensure that the &os; Ports Collection registers new
software with <application>pkgng</application>, and not
- <application>pkg_install</application>, &os; versions earlier
+ the traditional packages format, &os; versions earlier
than 10.<replaceable>X</replaceable> require this line in
<filename>/etc/make.conf</filename>:</para>
<programlisting>WITH_PKGNG= yes</programlisting>
- </sect2>
-
- <sect2 id="pkgng-pkg-conf">
- <title>Configuring the <application>pkgng</application>
- Environment</title>
<para>The <application>pkgng</application> package management
system uses a package repository for most operations. The
default package repository location is defined in
- <filename>/usr/local/etc/pkg.conf</filename> or the
+ <filename>/usr/local/etc/pkg.conf</filename> or by the
<envar>PACKAGESITE</envar> environment variable, which
overrides the configuration file.</para>
<para>Additional <application>pkgng</application>
configuration options are described in
pkg.conf(5).</para>
- </sect2>
-
- <sect2 id="pkgng-basic-usage">
- <title>Basic <application>pkgng</application> Operations</title>
<para>Usage information for <application>pkgng</application> is
- available in the pkg(8) manual page, or by running
+ available in pkg(8) or by running
<command>pkg</command> without additional arguments.</para>
<para>Each <application>pkgng</application> command argument is
documented in a command-specific manual page. To read the
manual page for <command>pkg install</command>, for example,
- run either:</para>
+ run either of these commands:</para>
<screen>&prompt.root; <userinput>pkg help install</userinput></screen>
<screen>&prompt.root; <userinput>man pkg-install</userinput></screen>
- <sect3 id="pkgng-pkg-info">
- <title>Obtaining Information About Installed Packages with
- <application>pkgng</application></title>
-
- <para>Information about the packages installed on a system can
- be viewed by running <command>pkg info</command>. Similar
- to &man.pkg.info.1;, the package version and
- description for all packages will be listed.</para>
+ <para>The rest of this section demonstrates common binary package management
+ tasks which can be performed using <application>pkgng</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>
- <para>Information about a specific package is available by
- running:</para>
+ <sect2 id="pkgng-pkg-info">
+ <title>Obtaining Information About Installed Packages</title>
- <screen>&prompt.root; <userinput>pkg info <replaceable>packagename</replaceable></userinput></screen>
+ <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>pkgng</application> is installed on the system,
+ <application>pkgng</application> is installed,
run:</para>
<screen>&prompt.root; <userinput>pkg info pkg</userinput>
-pkg-1.0.2 New generation package manager</screen>
- </sect3>
+pkg-1.1.4_1</screen>
+ </sect2>
- <sect3 id="pkgng-installing-deinstalling">
- <title>Installing and Removing Packages with
- <application>pkgng</application></title>
+ <sect2 id="pkgng-installing-deinstalling">
+ <title>Installing and Removing Packages</title>
- <para>In general, most &os; users will install binary packages
- by running:</para>
+ <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><command>pkg install</command> uses repository data, as
- mentioned in <xref linkend="pkgng-pkg-conf"/>. Conversely,
- pkg-add(8) does not use repository data, nor does it use the
- defined <envar>PACKAGESITE</envar>, so dependencies may not
- be properly tracked, and missing dependencies will not be
- fetched from a remote source. This section covers usage of
- <command>pkg install</command>. For information on usage of
- <command>pkg add</command>, see pkg-add(8).</para>
-
- <para>Additional binary packages can be installed with
- <command>pkg install</command>. For example, to install
+ <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
-Repository catalogue is up-to-date, no need to fetch fresh copy
-The following packages will be installed:
+/usr/local/tmp/All/curl-7.31.0_1.txz 100% of 1181 kB 1380 kBps 00m01s
- Installing ca_root_nss: 3.13.5
- Installing curl: 7.24.0
+/usr/local/tmp/All/ca_root_nss-3.15.1_1.txz 100% of 288 kB 1700 kBps 00m00s
-The installation will require 4 MB more space
+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
-1 MB to be downloaded
+0 B to be downloaded
Proceed with installing packages [y/N]: <userinput>y</userinput>
-ca_root_nss-3.13.5.txz 100% 255KB 255.1KB/s 255.1KB/s 00:00
-curl-7.24.0.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
Checking integrity... done
-Installing ca_root_nss-3.13.5... done
-Installing curl-7.24.0... done</screen>
+[1/2] Installing ca_root_nss-3.15.5_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.13.5 The root certificate bundle from the Mozilla Project
-curl-7.24.0 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
-pkg-1.0.2 New generation package manager</screen>
+ca_root_nss-3.15.5_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, if it turns out
- that <application>curl</application> is not needed after
- all:</para>
+ <command>pkg delete</command>. For example:</para>
<screen>&prompt.root; <userinput>pkg delete curl</userinput>
The following packages will be deleted:
- curl-7.24.0_1
+ curl-7.31.0_1
The deletion will free 3 MB
Proceed with deleting packages [y/N]: <userinput>y</userinput>
-Deleting curl-7.24.0_1... done</screen>
- </sect3>
+[1/1] Deleting curl-7.31.0_1... done</screen>
+ </sect2>
- <sect3 id="pkgng-upgrading">
- <title>Upgrading Installed Packages with
- <application>pkgng</application></title>
+ <sect2 id="pkgng-upgrading">
+ <title>Upgrading Installed Packages</title>
<para>Packages that are outdated can be found with
<command>pkg version</command>. If a local ports tree
does not exist, pkg-version(8) will use the remote
- repository catalogue, otherwise the local ports tree will
+ repository catalogue. Otherwise, the local ports tree will
be used to identify package versions.</para>
- <para>Packages can be upgraded to newer versions with
- <application>pkgng</application>. Suppose a new version of
- <application>curl</application> has been released. The
- local package can be upgraded to the new version:</para>
-
- <screen>&prompt.root; <userinput>pkg upgrade</userinput>
-Updating repository catalogue
-repo.txz 100% 297KB 296.5KB/s 296.5KB/s 00:00
-The following packages will be upgraded:
-
- Upgrading curl: 7.24.0 -> 7.24.0_1
-
-1 MB to be downloaded
-
-Proceed with upgrading packages [y/N]: <userinput>y</userinput>
-curl-7.24.0_1.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
-Checking integrity... done
-Upgrading curl from 7.24.0 to 7.24.0_1... done</screen>
- </sect3>
+ <para>Installed packages can be upgraded to their latest versions
+ by typing <command>pkg upgrade</command>. This command
+ will compare the installed versions with those available
+ in the repository catalogue. When finished, it will list
+ the applications that have newer versions. Type
+ <userinput>y</userinput> to proceed with the upgrade or
+ <userinput>n</userinput> to cancel the upgrade.</para>
+ </sect2>
- <sect3 id="pkgng-auditing">
- <title>Auditing Installed Packages with
- <application>pkgng</application></title>
+ <sect2 id="pkgng-auditing">
+ <title>Auditing Installed Packages</title>
<para>Occasionally, software vulnerabilities may be discovered
- in software within the Ports Collection.
- <application>pkgng</application> includes built-in auditing,
- similar to the <filename
- role="package">ports-mgmt/portaudit</filename> package.
- To audit the software installed on the system, run:</para>
+ in third-party applications. To address this,
+ <application>pkgng</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>
- </sect3>
</sect2>
- <sect2 id="pkgng-advanced-usage">
- <title>Advanced <application>pkgng</application>
- Operations</title>
-
- <sect3 id="pkgng-autoremove">
- <title>Automatically Removing Leaf Dependencies with
- <application>pkgng</application></title>
-
- <para>Removing a package may leave behind unnecessary
- dependencies, like <filename
- role="package">security/ca_root_nss</filename> in the
- example above. Such packages are still installed, but
- nothing depends on them any more. Unneeded packages that
+ <sect2 id="pkgng-autoremove">
+ <title>Automatically Removing Leaf Dependencies</title>
+
+ <para>Removing a package may leave behind
+ dependencies which are no longer required. Unneeded packages that
were installed as dependencies can be automatically detected
- and removed:</para>
+ and removed using:</para>
<screen>&prompt.root; <userinput>pkg autoremove</userinput>
Packages to be autoremoved:
@@ -834,35 +792,31 @@ Packages to be autoremoved:
The autoremoval will free 723 kB
Proceed with autoremoval of packages [y/N]: <userinput>y</userinput>
-Deinstalling ca_root_nss-3.13.5... done</screen>
- </sect3>
+Deinstalling ca_root_nss-3.15.1_1... done</screen>
+ </sect2>
- <sect3 id="pkgng-backup">
- <title>Backing Up the <application>pkgng</application> Package
+ <sect2 id="pkgng-backup">
+ <title>Backing Up the Package
Database</title>
<para>Unlike the traditional package management system,
<application>pkgng</application> includes its own package
- database backup mechanism. To manually back up the package
- database contents, run:</para>
+ database backup mechanism. To manually back up the contents of the package
+ database, run the following command, replacing
+ <replaceable>pkgng.db</replaceable> with a suitable file
+ name:</para>
<screen>&prompt.root; <userinput>pkg backup -d <replaceable>pkgng.db</replaceable></userinput></screen>
- <note>
- <para>Replace the file name
- <replaceable>pkgng.db</replaceable> to a suitable file
- name.</para>
- </note>
-
<para>Additionally, <application>pkgng</application> includes
- a &man.periodic.8; script to automatically back up the
- package database daily if
+ a &man.periodic.8; script to automatically perform a daily back up of the
+ package database. This functionality is enabled if
<literal>daily_backup_pkgng_enable</literal> is set to
<literal>YES</literal> in &man.periodic.conf.5;.</para>
<tip>
- <para>To prevent the <application>pkg_install</application>
- periodic script from also backing up the package database,
+ <para>To disable the
+ periodic script from backing up the package database,
set <literal>daily_backup_pkgdb_enable</literal> to
<literal>NO</literal> in &man.periodic.conf.5;.</para>
</tip>
@@ -871,53 +825,38 @@ Deinstalling ca_root_nss-3.13.5... done<
backup, run:</para>
<screen>&prompt.root; <userinput>pkg backup -r <replaceable>/path/to/pkgng.db</replaceable></userinput></screen>
- </sect3>
+ </sect2>
- <sect3 id="pkgng-clean">
- <title>Removing Stale <application>pkgng</application>
+ <sect2 id="pkgng-clean">
+ <title>Removing Stale
Packages</title>
<para>By default, <application>pkgng</application> stores
- binary packages in a cache directory as defined by
+ binary packages in a cache directory defined by
<envar>PKG_CACHEDIR</envar> in pkg.conf(5). When
upgrading packages with <command>pkg upgrade</command>, old
versions of the upgraded packages are not automatically
removed.</para>
- <para>To remove the outdated binary packages, run:</para>
+ <para>To remove these outdated binary packages, run:</para>
<screen>&prompt.root; <userinput>pkg clean</userinput></screen>
- </sect3>
+ </sect2>
- <sect3 id="pkgng-set">
- <title>Modifying <application>pkgng</application> Package
+ <sect2 id="pkgng-set">
+ <title>Modifying Package
Metadata</title>
- <para>Historically, software within the &os; Ports
- Collection can undergo major version number changes. Unlike
- <application>pkg_install</application>,
+ <para>Software within the &os; Ports
+ Collection can undergo major version number changes. To address this,
<application>pkgng</application> has a built-in command to
- update package origins. For example, if <filename
- role="package">lang/php5</filename> was originally at
- version <literal>5.3</literal>, but has been renamed to
- <filename role="package">lang/php53</filename> for the
- inclusion of version <literal>5.4</literal>,
- <application>pkg_install</application> would require the use
- of additional software such as <filename
- role="package">ports-mgmt/portmaster</filename> to update
- the package database, reflecting from which port the
- installation originated.</para>
+ update package origins. This can be useful, for example, if <filename
+ role="package">lang/php5</filename> is renamed to
+ <filename role="package">lang/php53</filename> so that <filename
+ role="package">lang/php5</filename> can now represent
+ version <literal>5.4</literal>.</para>
- <para>Unlike the <filename
- role="package">ports-mgmt/portmaster</filename> and
- <filename role="package">ports-mgmt/portupgrade</filename>
- ports, the order in which the new and old versions are
- listed differ. For <application>pkgng</application>, the
- syntax is:</para>
-
- <screen>&prompt.root; <userinput>pkg set -o <replaceable>category/oldport</replaceable>:<replaceable>category/newport</replaceable></userinput></screen>
-
- <para>For example, to change the package origin for the above
+ <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>
@@ -936,14 +875,13 @@ Deinstalling ca_root_nss-3.13.5... done<
<screen>&prompt.root; <userinput>pkg set -o graphics/libglut:graphics/freeglut</userinput></screen>
<note>
- <para>When changing package origins, in most cases it is
+ <para>When changing package origins, it is
important to reinstall packages that are dependent on the
- package that has had the origin changed. To force a
+ 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>
- </sect3>
</sect2>
</sect1>
More information about the svn-doc-all
mailing list