Merged ^/projects/pkgng revisions 39915 through 40152:
Import pkgng documentation. Reviewed by: bjk, wblock, matthew, rwatson, eadler[1], bapt[1] [1] Original version
This commit is contained in:
Glen Barber
parent
20e32ed03f
commit
fbf4614f3a
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=40153
1 changed files with 391 additions and 0 deletions
|
|
@ -654,6 +654,397 @@ docbook =
|
|||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="pkgng-intro">
|
||||
<title>Using <application>pkgng</application> for Binary Package
|
||||
Management</title>
|
||||
|
||||
<para><application>pkgng</application> is an improved replacement
|
||||
for the traditional &os; <application>pkg_install</application>
|
||||
package management tools, offering many features that make
|
||||
dealing with binary packages faster and easier. The first
|
||||
release of <application>pkgng</application> was in August,
|
||||
2012.</para>
|
||||
|
||||
<para><application>pkgng</application> is not a replacement for
|
||||
port management tools like <filename
|
||||
role="package">ports-mgmt/portmaster</filename> or <filename
|
||||
role="package">ports-mgmt/portupgrade</filename>. While
|
||||
<filename role="package">ports-mgmt/portmaster</filename> and
|
||||
<filename role="package">ports-mgmt/portupgrade</filename> can
|
||||
install third-party software from both binary packages and the
|
||||
Ports Collection, <application>pkgng</application> installs
|
||||
only binary packages.</para>
|
||||
|
||||
<sect2 id="pkgng-initial-setup">
|
||||
<title>Getting Started with
|
||||
<application>pkgng</application></title>
|
||||
|
||||
<para>&os; 9.1 and later includes a "bootstrap"
|
||||
utility for <application>pkgng</application>. The bootstrap
|
||||
utility will download and install
|
||||
<application>pkgng</application>.</para>
|
||||
|
||||
<para>To bootstrap the system, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>/usr/sbin/pkg</userinput></screen>
|
||||
|
||||
<para>For earlier &os; versions,
|
||||
<application>pkgng</application> must be installed from the
|
||||
Ports Collection, or as a binary package.</para>
|
||||
|
||||
<para>To install the <application>pkgng</application> port,
|
||||
run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/pkg</userinput>
|
||||
&prompt.root; <userinput>make</userinput>
|
||||
&prompt.root; <userinput>make install clean</userinput></screen>
|
||||
|
||||
<para>To install the binary package, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg_add -r pkg</userinput></screen>
|
||||
|
||||
<note>
|
||||
<para>The <application>pkgng</application> package management
|
||||
utility is not supported on
|
||||
&os; 7.<replaceable>X</replaceable> or
|
||||
&os; 8.0.</para>
|
||||
</note>
|
||||
|
||||
<para>Existing &os; installations require conversion of the
|
||||
<application>pkg_install</application> package database to the
|
||||
new format. To convert the package database, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg2ng</userinput></screen>
|
||||
|
||||
<para>This step is not required for new installations that do
|
||||
not have third-party software installed.</para>
|
||||
|
||||
<important>
|
||||
<para>This step is not reversible. Once the package database
|
||||
has been converted to the <application>pkgng</application>
|
||||
format, the <application>pkg_install</application> tools
|
||||
should not be used.</para>
|
||||
</important>
|
||||
|
||||
<note>
|
||||
<para>The package database conversion may emit errors as the
|
||||
contents are converted to the new version. Generally, these
|
||||
errors can be safely ignored, however a list of third-party
|
||||
software that was not successfully converted will be listed
|
||||
after <command>pkg2ng</command> has finished. These must be
|
||||
fixed by hand.</para>
|
||||
</note>
|
||||
|
||||
<para>To ensure the &os; Ports Collection registers new
|
||||
software with <application>pkgng</application>, and not
|
||||
<application>pkg_install</application>, &os; versions earlier
|
||||
than 10.<replaceable>X</replaceable> require this line in
|
||||
<filename>/etc/make.conf</filename>:</para>
|
||||
|
||||
<programlisting>WITH_PKGNG= yes</programlisting>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="pkgng-pkg-conf">
|
||||
<title>Configuring the <application>pkgng</application>
|
||||
Environment</title>
|
||||
|
||||
<para>The <application>pkgng</application> package management
|
||||
system uses a package repository for most operations. The
|
||||
default package repository location is defined in
|
||||
<filename>/usr/local/etc/pkg.conf</filename> or the
|
||||
<envar>PACKAGESITE</envar> environment variable, which
|
||||
overrides the configuration file.</para>
|
||||
|
||||
<para>Additional <application>pkgng</application>
|
||||
configuration options are described in
|
||||
pkg.conf(5).</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="pkgng-basic-usage">
|
||||
<title>Basic <application>pkgng</application> Operations</title>
|
||||
|
||||
<para>Usage information for <application>pkgng</application> is
|
||||
available in the pkg(8) manual page, or by running
|
||||
<command>pkg</command> without additional arguments.</para>
|
||||
|
||||
<para>Each <application>pkgng</application> command argument is
|
||||
documented in a command-specific manual page. To read the
|
||||
manual page for <command>pkg install</command>, for example,
|
||||
run either:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg help install</userinput></screen>
|
||||
|
||||
<screen>&prompt.root; <userinput>man pkg-install</userinput></screen>
|
||||
|
||||
<sect3 id="pkgng-pkg-info">
|
||||
<title>Obtaining Information about Installed Packages with
|
||||
<application>pkgng</application></title>
|
||||
|
||||
<para>Information about the packages installed on a system can
|
||||
be viewed by running <command>pkg info</command>. Similar
|
||||
to &man.pkg.info.1;, the package version and
|
||||
description for all packages will be listed.</para>
|
||||
|
||||
<para>Information about a specific package is available by
|
||||
running:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg info <replaceable>packagename</replaceable></userinput></screen>
|
||||
|
||||
<para>For example, to see which version of
|
||||
<application>pkgng</application> is installed on the system,
|
||||
run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg info pkg</userinput>
|
||||
pkg-1.0.2 New generation package manager</screen>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="pkgng-installing-deinstalling">
|
||||
<title>Installing and Removing Packages with
|
||||
<application>pkgng</application></title>
|
||||
|
||||
<para>In general, most &os; users will install binary packages
|
||||
by running:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg install <replaceable>packagename</replaceable></userinput></screen>
|
||||
|
||||
<para><command>pkg install</command> uses repository data, as
|
||||
mentioned in <xref linkend="pkgng-pkg-conf"/>. Conversely,
|
||||
pkg-add(8) does not use repository data, nor does it use the
|
||||
defined <envar>PACKAGESITE</envar>, so dependencies may not
|
||||
be properly tracked, and missing dependencies will not be
|
||||
fetched from a remote source. This section covers usage of
|
||||
<command>pkg install</command>. For information on usage of
|
||||
<command>pkg add</command>, see pkg-add(8).</para>
|
||||
|
||||
<para>Additional binary packages can be installed with
|
||||
<command>pkg install</command>. For example, to install
|
||||
<application>curl</application>:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg install curl</userinput>
|
||||
Updating repository catalogue
|
||||
Repository catalogue is up-to-date, no need to fetch fresh copy
|
||||
The following packages will be installed:
|
||||
|
||||
Installing ca_root_nss: 3.13.5
|
||||
Installing curl: 7.24.0
|
||||
|
||||
The installation will require 4 MB more space
|
||||
|
||||
1 MB to be downloaded
|
||||
|
||||
Proceed with installing packages [y/N]: <userinput>y</userinput>
|
||||
ca_root_nss-3.13.5.txz 100% 255KB 255.1KB/s 255.1KB/s 00:00
|
||||
curl-7.24.0.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
|
||||
Checking integrity... done
|
||||
Installing ca_root_nss-3.13.5... done
|
||||
Installing curl-7.24.0... done</screen>
|
||||
|
||||
<para>The new package and any additional packages that were
|
||||
installed as dependencies can be seen in the installed
|
||||
packages list:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg info</userinput>
|
||||
ca_root_nss-3.13.5 The root certificate bundle from the Mozilla Project
|
||||
curl-7.24.0 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
|
||||
pkg-1.0.2 New generation package manager</screen>
|
||||
|
||||
<para>Packages that are no longer needed can be removed with
|
||||
<command>pkg delete</command>. For example, if it turns out
|
||||
that <application>curl</application> is not needed after
|
||||
all:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg delete curl</userinput>
|
||||
The following packages will be deleted:
|
||||
|
||||
curl-7.24.0_1
|
||||
|
||||
The deletion will free 3 MB
|
||||
|
||||
Proceed with deleting packages [y/N]: <userinput>y</userinput>
|
||||
Deleting curl-7.24.0_1... done</screen>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="pkgng-upgrading">
|
||||
<title>Upgrading Installed Packages with
|
||||
<application>pkgng</application></title>
|
||||
|
||||
<para>Packages that are outdated can be found with
|
||||
<command>pkg version</command>. If a local ports tree
|
||||
does not exist, pkg-version(8) will use the remote
|
||||
repository catalogue, otherwise the local ports tree will
|
||||
be used to identify package versions.</para>
|
||||
|
||||
<para>Packages can be upgraded to newer versions with
|
||||
<application>pkgng</application>. Suppose a new version of
|
||||
<application>curl</application> has been released. The
|
||||
local package can be upgraded to the new version:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg upgrade</userinput>
|
||||
Updating repository catalogue
|
||||
repo.txz 100% 297KB 296.5KB/s 296.5KB/s 00:00
|
||||
The following packages will be upgraded:
|
||||
|
||||
Upgrading curl: 7.24.0 -> 7.24.0_1
|
||||
|
||||
1 MB to be downloaded
|
||||
|
||||
Proceed with upgrading packages [y/N]: <userinput>y</userinput>
|
||||
curl-7.24.0_1.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
|
||||
Checking integrity... done
|
||||
Upgrading curl from 7.24.0 to 7.24.0_1... done</screen>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="pkgng-auditing">
|
||||
<title>Auditing Installed Packages with
|
||||
<application>pkgng</application></title>
|
||||
|
||||
<para>Occasionally, software vulnerabilities may be discovered
|
||||
in software within the Ports Collection.
|
||||
<application>pkgng</application> includes built-in auditing,
|
||||
similar to the <filename
|
||||
role="package">ports-mgmt/portaudit</filename> package.
|
||||
To audit the software installed on the system, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg audit -F</userinput></screen>
|
||||
</sect3>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="pkgng-advanced-usage">
|
||||
<title>Advanced <application>pkgng</application>
|
||||
Operations</title>
|
||||
|
||||
<sect3 id="pkgng-autoremove">
|
||||
<title>Automatically Removing Leaf Dependencies with
|
||||
<application>pkgng</application></title>
|
||||
|
||||
<para>Removing a package may leave behind unnecessary
|
||||
dependencies, like <filename
|
||||
role="package">security/ca_root_nss</filename> in the
|
||||
example above. Such packages are still installed, but
|
||||
nothing depends on them any more. Unneeded packages that
|
||||
were installed as dependencies can be automatically detected
|
||||
and removed:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg autoremove</userinput>
|
||||
Packages to be autoremoved:
|
||||
ca_root_nss-3.13.5
|
||||
|
||||
The autoremoval will free 723 kB
|
||||
|
||||
Proceed with autoremoval of packages [y/N]: <userinput>y</userinput>
|
||||
Deinstalling ca_root_nss-3.13.5... done</screen>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="pkgng-backup">
|
||||
<title>Backing Up the <application>pkgng</application> Package
|
||||
Database</title>
|
||||
|
||||
<para>Unlike the <application>pkg_install</application>
|
||||
package management system, <application>pkgng</application>
|
||||
includes its own package database backup mechanism. To
|
||||
manually back up the package database contents, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg backup -d <replaceable>pkgng.db</replaceable></userinput></screen>
|
||||
|
||||
<note>
|
||||
<para>Replace the file name
|
||||
<replaceable>pkgng.db</replaceable> to a suitable file
|
||||
name.</para>
|
||||
</note>
|
||||
|
||||
<para>Additionally, <application>pkgng</application> includes
|
||||
a &man.periodic.8; script to automatically back up the
|
||||
package database daily if
|
||||
<literal>daily_backup_pkgng_enable</literal> is set to
|
||||
<literal>YES</literal> in &man.periodic.conf.5;.</para>
|
||||
|
||||
<tip>
|
||||
<para>To prevent the <application>pkg_install</application>
|
||||
periodic script from also backing up the package database,
|
||||
set <literal>daily_backup_pkgdb_enable</literal> to
|
||||
<literal>NO</literal> in &man.periodic.conf.5;.</para>
|
||||
</tip>
|
||||
|
||||
<para>To restore the contents of a previous package database
|
||||
backup, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg backup -r <replaceable>/path/to/pkgng.db</replaceable></userinput></screen>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="pkgng-clean">
|
||||
<title>Removing Stale <application>pkgng</application>
|
||||
Packages</title>
|
||||
|
||||
<para>By default, <application>pkgng</application> stores
|
||||
binary packages in a cache directory as defined by
|
||||
<envar>PKG_CACHEDIR</envar> in pkg.conf(5). When
|
||||
upgrading packages with <command>pkg upgrade</command>, old
|
||||
versions of the upgraded packages are not automatically
|
||||
removed.</para>
|
||||
|
||||
<para>To remove the outdated binary packages, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg clean</userinput></screen>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="pkgng-set">
|
||||
<title>Modifying <application>pkgng</application> Package
|
||||
Metadata</title>
|
||||
|
||||
<para>Historically, software within the &os; Ports
|
||||
Collection can undergo major version number changes. Unlike
|
||||
<application>pkg_install</application>,
|
||||
<application>pkgng</application> has a built-in command to
|
||||
update package origins. For example, if <filename
|
||||
role="package">lang/php5</filename> was originally at
|
||||
version <literal>5.3</literal>, but has been renamed to
|
||||
<filename role="package">lang/php53</filename> for the
|
||||
inclusion of version <literal>5.4</literal>,
|
||||
<application>pkg_install</application> would require the use
|
||||
of additional software such as <filename
|
||||
role="package">ports-mgmt/portmaster</filename> to update
|
||||
the package database, reflecting from which port the
|
||||
installation originated.</para>
|
||||
|
||||
<para>Unlike the <filename
|
||||
role="package">ports-mgmt/portmaster</filename> and
|
||||
<filename role="package">ports-mgmt/portupgrade</filename>
|
||||
ports, the order in which the new and old versions are
|
||||
listed differ. For <application>pkgng</application>, the
|
||||
syntax is:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg set -o <replaceable>category/oldport</replaceable>:<replaceable>category/newport</replaceable></userinput></screen>
|
||||
|
||||
<para>For example, to change the package origin for the above
|
||||
example, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg set -o lang/php5:lang/php53</userinput></screen>
|
||||
|
||||
<para>As another example, to update <filename
|
||||
role="package">lang/ruby18</filename> to <filename
|
||||
role="package">lang/ruby19</filename>, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg set -o lang/ruby18:lang/ruby19</userinput></screen>
|
||||
|
||||
<para>As a final example, to change the origin of the
|
||||
<filename>libglut</filename> shared libraries from <filename
|
||||
role="package">graphics/libglut</filename> to <filename
|
||||
role="package">graphics/freeglut</filename>, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg set -o graphics/libglut:graphics/freeglut</userinput></screen>
|
||||
|
||||
<note>
|
||||
<para>When changing package origins, in most cases it is
|
||||
important to reinstall packages that are dependent on the
|
||||
package that has had the origin changed. To force a
|
||||
reinstallation of dependent packages, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg install -Rf <replaceable>graphics/freeglut</replaceable></userinput></screen>
|
||||
</note>
|
||||
</sect3>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="ports-using">
|
||||
<title>Using the Ports Collection</title>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue