Date: Fri, 16 Nov 2012 10:34:57 -0700 (MST) From: Warren Block <wblock@wonkity.com> To: Glen Barber <gjb@freebsd.org> Cc: freebsd-doc@freebsd.org Subject: Re: Request for Review: pkgng documentation for the Handbook Message-ID: <alpine.BSF.2.00.1211161012590.76158@wonkity.com> In-Reply-To: <20121116165810.GC1335@glenbarber.us> References: <20121116165810.GC1335@glenbarber.us>
next in thread | previous in thread | raw e-mail | index | archive | help
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: <alpine.BSF.2.00.1211161012592.76158@wonkity.com> 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 <quote> 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 <command>. "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 <screen> section: <screen>&prompt.root; <userinput>pkg install <replaceable>packagename</replaceable></userinput></screen> "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: <alpine.BSF.2.00.1211161012593.76158@wonkity.com> 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 @@ </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--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1211161012590.76158>