Date: Fri, 16 Nov 2012 11:58:10 -0500 From: Glen Barber <gjb@FreeBSD.org> To: freebsd-doc@FreeBSD.org Subject: Request for Review: pkgng documentation for the Handbook Message-ID: <20121116165810.GC1335@glenbarber.us>
next in thread | raw e-mail | index | archive | help
--pQhZXvAqiZgbeUkD
Content-Type: multipart/mixed; boundary="qtZFehHsKgwS5rPz"
Content-Disposition: inline
--qtZFehHsKgwS5rPz
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Hi,
I would like to get feedback on recent commits to the projects/pkgng/
branch, which adds documentation for pkgng to the Handbook.
There are a few sections on my todo list, but I feel what is there now
covers the basics for FreeBSD users.
The diff is attached, and rendered output is here:
http://people.freebsd.org/~gjb/pkgng/data/doc/en/books/handbook/pkgng-intro.html
I would like to merge this into head/ when 9.1-RELEASE is announced.
Thanks,
Glen
--qtZFehHsKgwS5rPz
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="pkgngdoc.diff.txt"
Content-Transfer-Encoding: quoted-printable
Index: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml (revision 40037)
+++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml (working copy)
@@ -638,6 +638,401 @@
</sect2>
</sect1>
=20
+ <sect1 id=3D"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=3D"package">ports-mgmt/portmaster</filename> or <filename
+ role=3D"package">ports-mgmt/portupgrade</filename>.</para>
+
+ <sect2 id=3D"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>
+=09
+ <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</useri=
nput>
+&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 early
+ &os; 8.<replaceable>X</replaceable> versions.</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>
+
+ <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>, add the following
+ lines to <filename>/etc/make.conf</filename>:</para>
+
+ <programlisting>WITH_PKGNG=3D yes</programlisting>
+
+ <note>
+ <para>This step is not required on
+ &os; 10.<replaceable>X</replaceable>.</para>
+ </note>
+ </sect2>
+
+ <sect2 id=3D"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 the
+ <envar>PACKAGESITE</envar> defined in
+ <filename>/usr/local/etc/pkg.conf</filename> unless
+ <envar>PACKAGESITE</envar> is defined in the local
+ environment.</para>
+
+ <note>
+ <para>If <envar>PACKAGESITE</envar> is defined in the
+ environment, the pkg.conf(5)
+ <envar>PACKAGESITE</envar> will be ignored.</para>
+ </note>
+
+ <para>Additional <application>pkgng</application>
+ configuration options are described in
+ pkg.conf(5).</para>
+ </sect2>
+
+ <sect2 id=3D"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></scree=
n>
+
+ <screen>&prompt.root; <userinput>man pkg-install</userinput></screen>
+
+ <sect3 id=3D"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 <command>pkg_info</command>, the package version and
+ description for all packages will be listed.</para>
+
+ <para>Information about a specific package is available by
+ running <command>pkg info
+ <replaceable>packagename</replaceable></command>. 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=3D"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 <command>pkg install
+ <replaceable>packagename</replaceable></command>.
+ <command>pkg install</command> uses repository data, as
+ mentioned in <xref linkend=3D"pkgng-pkg-conf"/>. Conversely,
+ <command>pkg add</command> 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) se=
rvers
+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=3D"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=3D"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=3D"package">ports-mgmt/portaudit</filename> package.
+ To audit the software installed on the system, run:</para>
+
+ <screen>&prompt.root; <userinput>pkg audit</userinput></screen>
+
+ <tip>
+ <para>If running <command>pkg audit</command> for the first
+ time, the audit database file must be downloaded. Run
+ <command>pkg audit -F</command> to fetch the audit
+ database file.</para>
+ </tip>
+
+ </sect3>
+ </sect2>
+
+ <sect2 id=3D"pkgng-advanced-usage">
+ <title>Advanced <application>pkgng</application>
+ Operations</title>
+
+ <sect3 id=3D"pkgng-autoremove">
+ <title>Automatically Removing Leaf Dependencies with
+ <application>pkgng</application></title>
+
+ <para>Removing a package may leave behind unnecessary
+ dependencies, like <filename
+ role=3D"package">ca_root_nss</filename> in the example
+ above. Those 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=3D"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 backup the package database contents, run:</para>
+
+ <screen>&prompt.root; <userinput>pkg backup -d <replaceable>pkgng.db</rep=
laceable></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 backup 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/pkgn=
g.db</replaceable></userinput></screen>
+ </sect3>
+
+ <sect3 id=3D"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 from the system,
+ run:</para>
+
+ <screen>&prompt.root; <userinput>pkg clean</userinput></screen>
+ </sect3>
+
+ <sect3 id=3D"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=3D"package">lang/php5</filename> was originally at
+ version <literal>5.3</literal>, but has been renamed to
+ <filename role=3D"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=3D"package">ports-mgmt/portmaster</filename> to update
+ the package database, reflecting from which port the
+ installation originated.</para>
+
+ <para>Unlike the <filename
+ role=3D"package">ports-mgmt/portmaster</filename> and
+ <filename role=3D"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 <command>pkg set -o
+ <replaceable>category/oldport</replaceable>:<replaceable>category/new=
port</replaceable></command>.</para>
+
+ <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</userinp=
ut></screen>
+
+ <para>As another example, to update <filename
+ role=3D"package">lang/ruby18</filename> to <filename
+ role=3D"package">lang/ruby19</filename>, run:</para>
+
+ <screen>&prompt.root; <userinput>pkg set -o lang/ruby18:lang/ruby19</user=
input></screen>
+
+ <para>As a final example, to change the origin of the
+ <filename>libglut</filename> shared libraries from <filename
+ role=3D"package">graphics/libglut</filename> to <filename
+ role=3D"package">graphics/freeglut</filename>, run:</para>
+
+ <screen>&prompt.root; <userinput>pkg set -o graphics/libglut:graphics/fre=
eglut</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=3D"ports-using">
<title>Using the Ports Collection</title>
=20
--qtZFehHsKgwS5rPz--
--pQhZXvAqiZgbeUkD
Content-Type: application/pgp-signature
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (FreeBSD)
iQEcBAEBCAAGBQJQpnCiAAoJEFJPDDeguUaj7xMIAK5roJ3Lr5EjFkkHgn9JW3FR
icpRE+ZVabw9jtv8Vd0tzWI3ZRvLd49indGEBRwtq4YKfRcM1KSP2rIGIeW2eolA
HFluiAKHFja9j89jwqIuDL5DVyvZwUIubJ/OHNylPsZhdexfLQhqB272iT74TgBy
d/bB3LWZ/Sg8+dNKtOjsMWCe3NkQDZLYp+Gw+dawxVEH9mKfYjaPZAYsUPwxI6jW
B4U8NeoUNCDK5La8e9eot1kEHOIIwJjYOoiVqK5aRxuymsKv9Gnad2j0z/f4b16s
EDCjDjwOF0ceAVP7gjJ5SCZVL5OKAvOm69SUF8PvZOE244T4jprB02Sx4D1NLsE=
=S3gQ
-----END PGP SIGNATURE-----
--pQhZXvAqiZgbeUkD--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20121116165810.GC1335>