Skip site navigation (1)Skip section navigation (2)
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;&nbsp;9.1 and later includes a &quot;bootstrap&quot;
+	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;&nbsp;7.<replaceable>X</replaceable> or early
+	  &os;&nbsp;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;&nbsp;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;&nbsp;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;&nbsp;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>