a bit more documentation, including revisit of OpenBSD::Intro to reflect

the current state of things.

3 files changed, 49 insertions, 29 deletions

diff --git a/usr.sbin/pkg_add/pkg_add b/usr.sbin/pkg_add/pkg_add
index df6a27f761a..05fde5c6a94 100644
--- a/usr.sbin/pkg_add/pkg_add
+++ b/usr.sbin/pkg_add/pkg_add
@@ -1,7 +1,7 @@
 #! /usr/bin/perl
 
 # ex:ts=8 sw=4:
-# $OpenBSD: pkg_add,v 1.416 2009/12/05 14:41:03 espie Exp $
+# $OpenBSD: pkg_add,v 1.417 2009/12/05 23:13:01 espie Exp $
 #
 # Copyright (c) 2003-2009 Marc Espie <espie@openbsd.org>
 #
@@ -627,7 +627,7 @@ sub install_set
 our ($opt_a, $opt_A, $opt_P, $opt_Q, $opt_r, $opt_u, $opt_U, $opt_l, $opt_z);
 
 handle_options('aqchruUzl:A:P:Q:', {},
-    'pkg_add [-acIinqruvxz] [-A arch] [-B pkg-destdir] [-F keywords]',
+    'pkg_add [-acIinqruUvxz] [-A arch] [-B pkg-destdir] [-F keywords]',
     '[-L localbase] [-l file] [-P type] [-Q quick-destdir] pkg-name [...]');
 
 $state->{do_faked} = 0;
diff --git a/usr.sbin/pkg_add/pkg_add.1 b/usr.sbin/pkg_add/pkg_add.1
index 079301c7f7f..fd391d0cb1e 100644
--- a/usr.sbin/pkg_add/pkg_add.1
+++ b/usr.sbin/pkg_add/pkg_add.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pkg_add.1,v 1.86 2009/12/03 18:55:43 espie Exp $
+.\"	$OpenBSD: pkg_add.1,v 1.87 2009/12/05 23:13:01 espie Exp $
 .\"
 .\" Documentation and design originally from FreeBSD. All the code has
 .\" been rewritten since. We keep the documentation's notice:
@@ -15,7 +15,7 @@
 .\" Jordan K. Hubbard
 .\"
 .\"
-.Dd $Mdocdate: December 3 2009 $
+.Dd $Mdocdate: December 5 2009 $
 .Dt PKG_ADD 1
 .Os
 .Sh NAME
@@ -24,7 +24,7 @@
 .Sh SYNOPSIS
 .Nm pkg_add
 .Bk -words
-.Op Fl acIinqruvxz
+.Op Fl acIinqruUvxz
 .Op Fl A Ar arch
 .Op Fl B Ar pkg-destdir
 .Op Fl F Ar keywords
@@ -354,6 +354,8 @@ will update all installed packages.
 This relies on
 .Ev PKG_PATH
 to figure out the new package names.
+.It Fl U
+Update dependencies if required before installing the new package(s).
 .It Fl v
 Turn on verbose output.
 Several
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod b/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod
index b679bb33273..7b8d3be47d7 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::Intro.pod,v 1.10 2009/04/11 23:07:07 schwarze Exp $
+$OpenBSD: OpenBSD::Intro.pod,v 1.11 2009/12/05 23:13:01 espie Exp $
 
 =head1 NAME
 
@@ -120,10 +120,9 @@ for performance and simplicity reasons.)
 
 =item update sets
 
-This is a new notion (introduced around OpenBSD 4.1) which is not yet fully
-used throughout the package tools.  Each operation (installation, removal,
-or replacement of packages) is cut up into small atomic operations, in order
-to guarantee maximal stability of the installed system. The package tools
+Each operation (installation, removal, or replacement of packages) 
+is cut up into small atomic operations, in order to guarantee maximal 
+stability of the installed system. The package tools
 will try really hard to only deal with one or two packages at a time,
 in order to minimize combinatorial complexity, and to have a maximal number
 of safe points, where an update operation can stop without hosing the
@@ -137,7 +136,22 @@ under construction.  We have already met with update situations where
 dependencies between packages invert (A-1.0 depends on B-1.0, but B-0.0
 depends on A-0.0), or where files move between packages, which in
 theory will require update-sets with two new packages that replace two
-old packages.  Currently, we cheat.
+old packages.  We still cheat in a few cases, but in most cases, pkg_add
+will recognize those situations, and merge updatesets as required.
+
+=item updater and tracker
+
+Updatesets contain some initial information, such as a package name to
+install, or a package location to update.
+
+This information will be completed incrementally by a 
+C<OpenBSD::Update> updater object, which is responsible for figuring out 
+how to update each element of an updateset, if it is an older package, or
+to resolve a hint to a package name to a full package location.
+
+In order to avoid loops, a C<OpenBSD::Tracker> tracker
+object keeps track of all the package name statuses: what's queued for 
+update, what is uptodate, or what can't be updated.
 
 =item dependency information
 
@@ -283,10 +297,15 @@ old shared libraries are kept around in a stub .lib-* package, so that
 software that depends on them keeps running. (Thus, it is vital that porters
 pay attention to shared library version numbers during an update.)
 
-An update operation starts by figuring out which packages to update (walking
-the selected packages dependency trees). 
+An update operation starts with update sets that contain only old packages.
+There is some specific code (the C<OpenBSD::Update> module) which is used 
+to figure out the new package name from the old one.
+
+In every update or replacement, pkg_add will first try to install or update
+the quirks package, which contains a global list of exceptions, such as
+extra stems to search for (allowing for package renames), or packages to
+remove as they've become part of base OpenBSD.
 
-Then it looks for new packages to replace the old ones.
 This search relies on stem names first (e.g., to update package
 foo-1.0, pkg_add -u will look for foo-* in the PKG_PATH), then it trims
 the search results by looking more closely inside the package candidates. 
@@ -296,10 +315,11 @@ that comes from category/someport/snapshot will never replace a package
 that comes from category/someport/stable. Likewise for flavors.
 
 Finally, pkg_add -u decides whether the update is needed by comparing
-the package signatures: a package signature is composed of
+the package version and the package signatures: a package will not be
+downgraded to an older version. A package signature is composed of
 the name of a package, together with relevant dependency information: 
 all wantlib versions, and all run dependencies versions. 
-If anything is different, it means the new package must replace the old one.
+pkg_add only replaces packages with different signatures.
 
 Currently, pkg_add -u stops at the first entry in the PKG_PATH from which
 suitable candidates are found.
@@ -312,19 +332,13 @@ There are a few desireable changes that will happen in the future:
 
 =item *
 
-pkg_add -u should be able to find updates with a stem change.
-This requires an extra mechanism that would say `oh, this package changed
-name', as we cannot afford to look into every single package.
+some complicated update scenarios are not fully handled through updatesets.
 
 =item *
 
-more complicated update scenarios could happen, once UpdateSets are fully
-functional.
-
-=item *
-
-pkg_add has no real notion of version number. Thus, updates work only
-in so far as you direct your PKG_PATH to a more recent repository.
+Version number handling does not yet extends to package signatures. 
+Thus, some spurious downgrades may happen if the packagename itself does not
+change.
 
 =item *
 
@@ -468,15 +482,19 @@ and related algorithms.
 safe creation of temporary files as a light-weight module that also
 deals with signal issues.
 
+=item OpenBSD::Tracker
+
+tracks all package names through update operations, in order to avoid
+loops while doing incremental updates.
+
 =item OpenBSD::Update
 
-computes lists of package replacements required by an update.
+incremental computation of package replacements required by an update or
+installation.
 
 =item OpenBSD::UpdateSet
 
 common operations to all package tools that manipulate update sets.
-Lots of things to do.
-
 
 =item OpenBSD::Ustar