From owner-freebsd-doc@FreeBSD.ORG Fri Nov 16 17:35:04 2012 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 85EF1C7C; Fri, 16 Nov 2012 17:35:04 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 22CA98FC14; Fri, 16 Nov 2012 17:35:03 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.5/8.14.5) with ESMTP id qAGHYvhv076515; Fri, 16 Nov 2012 10:34:57 -0700 (MST) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.5/8.14.5/Submit) with ESMTP id qAGHYvS5076512; Fri, 16 Nov 2012 10:34:57 -0700 (MST) (envelope-from wblock@wonkity.com) Date: Fri, 16 Nov 2012 10:34:57 -0700 (MST) From: Warren Block To: Glen Barber Subject: Re: Request for Review: pkgng documentation for the Handbook In-Reply-To: <20121116165810.GC1335@glenbarber.us> Message-ID: References: <20121116165810.GC1335@glenbarber.us> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: MULTIPART/Mixed; BOUNDARY=qtZFehHsKgwS5rPz Content-ID: Content-Disposition: INLINE X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.2.7 (wonkity.com [127.0.0.1]); Fri, 16 Nov 2012 10:34:57 -0700 (MST) Cc: freebsd-doc@freebsd.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 16 Nov 2012 17:35:04 -0000 This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. --qtZFehHsKgwS5rPz Content-Type: TEXT/PLAIN; CHARSET=US-ASCII; format=flowed Content-ID: Content-Disposition: INLINE On Fri, 16 Nov 2012, Glen Barber wrote: > 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 Nice! I do have some suggestions: pkgng is not a replacement for port management tools like ports-mgmt/portmaster or ports-mgmt/portupgrade. That sentence ends a little abruptly. A second sentence could elaborate a little on why those two tools still work or are needed. "Getting Started with pkgng" Markup on bootstrap should be tags. "Existing FreeBSD installations require conversion of the pkg_install package database" pkg_install should be a man page ref. To ensure the FreeBSD Ports Collection registers new software with pkgng, and not pkg_install, add the following lines to /etc/make.conf: pkg_install should be a man page ref. I'd also suggest "these" or "this" instead of "the following". The visually-disruptive Note at the end of that step about it not being required on 10.x could be added to the preceding paragraph: For versions of &os; before 10.X, add this line to /etc/make.conf: "Configuring the pkgng Environment" is kind of confusing, and could be simplified. Is it necessary to mention the environment variable at all? 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 PACKAGESITE environment variable which overrides the configuration file. "Basic pkgng Operations" pkg(8) should be a man page ref. "Obtaining Information about Installed Packages with pkgng" pkg_info should be a man page ref rather than . "Installing and Removing Packages with pkgng" In general, most FreeBSD users will install binary packages by running pkg install packagename. The example command should be split out into a section: &prompt.root; pkg install packagename "Upgrading Installed Packages with pkgng" pkg-version(8) seems to be text, not a man page ref. "Modifying pkgng Package Metadata" "Unlike pkg_install, pkgng has a built-in command" pkg_install should be a man page ref. --qtZFehHsKgwS5rPz Content-Type: TEXT/PLAIN; CHARSET=us-ascii Content-Transfer-Encoding: QUOTED-PRINTABLE Content-ID: Content-Description: Content-Disposition: ATTACHMENT; FILENAME=pkgngdoc.diff.txt 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 @@ =20 + + Using <application>pkgng</application> for Binary Package + Management + + pkgng is an improved replacement + for the traditional &os; pkg_install + package management tools, offering many features that make + dealing with binary packages faster and easier. The first + release of pkgng was in August, + 2012. + + pkgng is not a replacement for + port management tools like ports-mgmt/portmaster or ports-mgmt/portupgrade. + + + 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. +=09 + 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. + + To install the pkgng port, + run: + + &prompt.root; cd /usr/ports/ports-mgmt/pkg +&prompt.root; make +&prompt.root; make install clean + + To install the binary package, run: + + &prompt.root; pkg_add -r pkg + + + The pkgng package management + utility is not supported on + &os; 7.X or early + &os; 8.X versions. + + + Existing &os; installations require conversion of the + pkg_install package database to the + new format. To convert the package database, run: + + &prompt.root; pkg2ng + + This step is not required for new installations that do + not have third-party software installed. + + + 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 pkg2ng has finished. These must be + fixed by hand. + + + To ensure the &os; Ports Collection registers new + software with pkgng, and not + pkg_install, add the following + lines to /etc/make.conf: + + WITH_PKGNG=3D yes + + + This step is not required on + &os; 10.X. + + + + + Configuring the <application>pkgng</application> + Environment + + The pkgng package management + system uses a package repository for most operations. The + default package repository location is the + PACKAGESITE defined in + /usr/local/etc/pkg.conf unless + PACKAGESITE is defined in the local + environment. + + + If PACKAGESITE is defined in the + environment, the pkg.conf(5) + PACKAGESITE will be ignored. + + + 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 + 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: + + &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 pkg_info, the package version and + description for all packages will be listed. + + Information about a specific package is available by + running pkg info + packagename. For + example, to see which version of + pkgng is installed on the system, + run: + + &prompt.root; pkg info pkg +pkg-1.0.2 New generation package manager + + + + Installing and Removing Packages with + <application>pkgng</application> + + In general, most &os; users will install binary packages + by running pkg install + packagename. + pkg install uses repository data, as + mentioned in . Conversely, + pkg add 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 + 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: + + 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]: 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 + + 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) se= rvers +pkg-1.0.2 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: + + &prompt.root; pkg delete curl +The following packages will be deleted: + + curl-7.24.0_1 + +The deletion will free 3 MB + +Proceed with deleting packages [y/N]: y +Deleting curl-7.24.0_1... done + + + + Upgrading Installed Packages with + <application>pkgng</application> + + 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 + 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 + + + + Auditing Installed Packages with + <application>pkgng</application> + + 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: + + &prompt.root; pkg audit + + + If running pkg audit for the first + time, the audit database file must be downloaded. Run + pkg audit -F to fetch the audit + database file. + + + + + + + Advanced <application>pkgng</application> + Operations + + + Automatically Removing Leaf Dependencies with + <application>pkgng</application> + + Removing a package may leave behind unnecessary + dependencies, like ca_root_nss 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: + + &prompt.root; pkg autoremove +Packages to be autoremoved: + ca_root_nss-3.13.5 + +The autoremoval will free 723 kB + +Proceed with autoremoval of packages [y/N]: y +Deinstalling ca_root_nss-3.13.5... done + + + + Backing Up the <application>pkgng</application> Package + Database + + Unlike the pkg_install + package management system, pkgng + includes its own package database backup mechanism. To + manually backup the package database contents, run: + + &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 backup the + package database daily 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, + set daily_backup_pkgdb_enable to + NO in &man.periodic.conf.5;. + + + To restore the contents of a previous package database + backup, run: + + &prompt.root; pkg backup -r /path/to/pkgn= g.db + + + + Removing Stale <application>pkgng</application> + Packages + + By default, pkgng stores + binary packages in a cache directory as 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 from the system, + run: + + &prompt.root; pkg clean + + + + Modifying <application>pkgng</application> Package + Metadata + + Historically, software within the &os; Ports + Collection can undergo major version number changes. Unlike + pkg_install, + 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. + + 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 pkg set -o + category/oldport:category/new= port. + + For example, to change the package origin for the above + example, run: + + &prompt.root; pkg set -o lang/php5:lang/php53 + + As another example, to update lang/ruby18 to lang/ruby19, run: + + &prompt.root; pkg set -o lang/ruby18:lang/ruby19 + + As a final example, to change the origin of the + libglut shared libraries from graphics/libglut to graphics/freeglut, run: + + &prompt.root; pkg set -o graphics/libglut:graphics/fre= eglut + + + 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: + + &prompt.root; pkg install -Rf graphics/= freeglut + + + + + Using the Ports Collection =20 --qtZFehHsKgwS5rPz--