From owner-svn-doc-all@FreeBSD.ORG Fri Oct 4 18:43:32 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 02B16C65; Fri, 4 Oct 2013 18:43:32 +0000 (UTC) (envelope-from dru@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id D47942F4F; Fri, 4 Oct 2013 18:43:31 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r94IhVNg074596; Fri, 4 Oct 2013 18:43:31 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r94IhV3x074595; Fri, 4 Oct 2013 18:43:31 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201310041843.r94IhV3x074595@svn.freebsd.org> From: Dru Lavigne Date: Fri, 4 Oct 2013 18:43:31 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42829 - head/en_US.ISO8859-1/books/handbook/ports X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 04 Oct 2013 18:43:32 -0000 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 = Using <application>pkgng</application> for Binary Package Management - pkgng is an improved replacement + pkgng 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 pkgng - was in August, 2012. + easier. pkgng is not a replacement for port management tools like ports-mgmt/portmaster or ports-mgmt/portupgrade. While - ports-mgmt/portmaster and - ports-mgmt/portupgrade can + role="package">ports-mgmt/portupgrade. These + tools can be used to install third-party software from both binary packages and the - Ports Collection, pkgng installs + Ports Collection, while pkgng installs only binary packages. Getting Started with <application>pkgng</application> - &os; 9.1 and later includes a "bootstrap" - utility for pkgng. The bootstrap - utility will download and install - pkgng. + &os; 9.1 and later includes a bootstrap + utility which can be used to download and install + pkgng, along with its manual pages. To bootstrap the system, run: &prompt.root; /usr/sbin/pkg For earlier &os; versions, - pkgng must be installed from the - Ports Collection, or as a binary package. + pkgng must instead be installed from the + Ports Collection or as a binary package. - To install the pkgng port, + To install the port, run: &prompt.root; cd /usr/ports/ports-mgmt/pkg @@ -612,220 +609,181 @@ docbook = &prompt.root; pkg_add -r pkg - Existing &os; installations require conversion of the - pkg_install package database to the - new format. To convert the package database, run: + Once pkgng is installed, the package database + must be converted from the traditional format to the + new format by running this command: &prompt.root; pkg2ng This step is not required for new installations that do - not have third-party software installed. + not yet have any third-party software installed. This step is not reversible. Once the package database has been converted to the pkgng - format, the pkg_install tools + format, the traditional pkg_* tools should not be used. 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 pkg2ng has finished. These must be - fixed by hand. + after pkg2ng has finished and these applications must be + manually reinstalled. - To ensure the &os; Ports Collection registers new + To ensure that the &os; Ports Collection registers new software with pkgng, and not - pkg_install, &os; versions earlier + the traditional packages format, &os; versions earlier than 10.X require this line in /etc/make.conf: WITH_PKGNG= yes - - - - Configuring the <application>pkgng</application> - Environment The pkgng package management system uses a package repository for most operations. The default package repository location is defined in - /usr/local/etc/pkg.conf or the + /usr/local/etc/pkg.conf or by the PACKAGESITE environment variable, which overrides the configuration file. Additional pkgng configuration options are described in pkg.conf(5). - - - - Basic <application>pkgng</application> Operations Usage information for pkgng is - available in the pkg(8) manual page, or by running + available in pkg(8) or by running pkg without additional arguments. Each pkgng command argument is documented in a command-specific manual page. To read the manual page for pkg install, for example, - run either: + run either of these commands: &prompt.root; pkg help install &prompt.root; man pkg-install - - Obtaining Information About Installed Packages with - <application>pkgng</application> - - Information about the packages installed on a system can - be viewed by running pkg info. Similar - to &man.pkg.info.1;, the package version and - description for all packages will be listed. + The rest of this section demonstrates common binary package management + tasks which can be performed using pkgng. Each + demonstrated command provides many switches to customize its + use. Refer to a command's help or man page for details and + more examples. + - Information about a specific package is available by - running: + + Obtaining Information About Installed Packages - &prompt.root; pkg info packagename + Information about the packages installed on a system can + be viewed by running pkg info which, when run without any switches, will + list the package version for either all installed packages or the specified package. For example, to see which version of - pkgng is installed on the system, + pkgng is installed, run: &prompt.root; pkg info pkg -pkg-1.0.2 New generation package manager - +pkg-1.1.4_1 + - - Installing and Removing Packages with - <application>pkgng</application> + + Installing and Removing Packages - In general, most &os; users will install binary packages - by running: + To install a binary package + use the following command, where + packagename is the name of the + package to install: &prompt.root; pkg install packagename - pkg install uses repository data, as - mentioned in . Conversely, - pkg-add(8) does not use repository data, nor does it use the - defined PACKAGESITE, so dependencies may not - be properly tracked, and missing dependencies will not be - fetched from a remote source. This section covers usage of - pkg install. For information on usage of - pkg add, see pkg-add(8). - - Additional binary packages can be installed with - pkg install. For example, to install + 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 curl: &prompt.root; pkg install curl 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]: y -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 +[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 The new package and any additional packages that were installed as dependencies can be seen in the installed packages list: &prompt.root; pkg info -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 +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 Packages that are no longer needed can be removed with - pkg delete. For example, if it turns out - that curl is not needed after - all: + pkg delete. For example: &prompt.root; pkg delete curl 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]: y -Deleting curl-7.24.0_1... done - +[1/1] Deleting curl-7.31.0_1... done + - - Upgrading Installed Packages with - <application>pkgng</application> + + Upgrading Installed Packages Packages that are outdated can be found with pkg version. 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. - Packages can be upgraded to newer versions with - pkgng. Suppose a new version of - curl has been released. The - local package can be upgraded to the new version: - - &prompt.root; pkg upgrade -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]: y -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 - + Installed packages can be upgraded to their latest versions + by typing pkg upgrade. 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 + y to proceed with the upgrade or + n to cancel the upgrade. + - - Auditing Installed Packages with - <application>pkgng</application> + + Auditing Installed Packages Occasionally, software vulnerabilities may be discovered - in software within the Ports Collection. - pkgng includes built-in auditing, - similar to the ports-mgmt/portaudit package. - To audit the software installed on the system, run: + in third-party applications. To address this, + pkgng includes a built-in auditing mechanism. + To determine if there are any known vulnerabilities for the software installed on the system, run: &prompt.root; pkg audit -F - - - Advanced <application>pkgng</application> - Operations - - - Automatically Removing Leaf Dependencies with - <application>pkgng</application> - - Removing a package may leave behind unnecessary - dependencies, like security/ca_root_nss in the - example above. Such packages are still installed, but - nothing depends on them any more. Unneeded packages that + + Automatically Removing Leaf Dependencies + + 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: + and removed using: &prompt.root; pkg autoremove 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]: y -Deinstalling ca_root_nss-3.13.5... done - +Deinstalling ca_root_nss-3.15.1_1... done + - - Backing Up the <application>pkgng</application> Package + <sect2 id="pkgng-backup"> + <title>Backing Up the Package Database Unlike the traditional package management system, pkgng includes its own package - database backup mechanism. To manually back up the package - database contents, run: + database backup mechanism. To manually back up the contents of the package + database, run the following command, replacing + pkgng.db with a suitable file + name: &prompt.root; pkg backup -d pkgng.db - - Replace the file name - pkgng.db to a suitable file - name. - - Additionally, pkgng 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 daily_backup_pkgng_enable is set to YES in &man.periodic.conf.5;. - To prevent the pkg_install - periodic script from also backing up the package database, + To disable the + periodic script from backing up the package database, set daily_backup_pkgdb_enable to NO in &man.periodic.conf.5;. @@ -871,53 +825,38 @@ Deinstalling ca_root_nss-3.13.5... done< backup, run: &prompt.root; pkg backup -r /path/to/pkgng.db - + - - Removing Stale <application>pkgng</application> + <sect2 id="pkgng-clean"> + <title>Removing Stale Packages By default, pkgng stores - binary packages in a cache directory as defined by + binary packages in a cache directory defined by PKG_CACHEDIR in pkg.conf(5). When upgrading packages with pkg upgrade, old versions of the upgraded packages are not automatically removed. - To remove the outdated binary packages, run: + To remove these outdated binary packages, run: &prompt.root; pkg clean - + - - Modifying <application>pkgng</application> Package + <sect2 id="pkgng-set"> + <title>Modifying Package Metadata - Historically, software within the &os; Ports - Collection can undergo major version number changes. Unlike - pkg_install, + Software within the &os; Ports + Collection can undergo major version number changes. To address this, pkgng has a built-in command to - update package origins. For example, if lang/php5 was originally at - version 5.3, but has been renamed to - lang/php53 for the - inclusion of version 5.4, - pkg_install would require the use - of additional software such as ports-mgmt/portmaster to update - the package database, reflecting from which port the - installation originated. + update package origins. This can be useful, for example, if lang/php5 is renamed to + lang/php53 so that lang/php5 can now represent + version 5.4. - Unlike the ports-mgmt/portmaster and - ports-mgmt/portupgrade - ports, the order in which the new and old versions are - listed differ. For pkgng, the - syntax is: - - &prompt.root; pkg set -o category/oldport:category/newport - - For example, to change the package origin for the above + To change the package origin for the above example, run: &prompt.root; pkg set -o lang/php5:lang/php53 @@ -936,14 +875,13 @@ Deinstalling ca_root_nss-3.13.5... done< &prompt.root; pkg set -o graphics/libglut:graphics/freeglut - When changing package origins, in most cases it is + 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: &prompt.root; pkg install -Rf graphics/freeglut -