document newer module and new framework (somewhat...)

document more stuff from Vstat.

2 files changed, 118 insertions, 23 deletions

diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod b/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod
index 94f3f747ef0..f2b80132e56 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.13 2010/01/08 18:01:54 espie Exp $
+$OpenBSD: OpenBSD::Intro.pod,v 1.14 2010/06/18 10:56:32 espie Exp $
 
 =head1 NAME
 
@@ -193,7 +193,6 @@ Lists of inter-dependencies are recorded in both directions
 subtleties (removing duplicates, keeping things ordered, and handling
 pretend operations).
 
-
 =item shared items
 
 Some items may be recorded multiple times within several packages (mostly
@@ -214,6 +213,24 @@ are handled through the L<OpenBSD::Vstat(3p)> module, which is designed
 to hide file system oddities, and to perform addition/deletion operations
 virtually before doing them for real.
 
+=item framework for user interaction
+
+Most commands are now implemented as perl modules, with C<pkg(1)> requiring
+the correct module C<M>, and invoking C<M-E<gt>parse_and_run("command")>.
+
+All those commands use a class derived from C<OpenBSD::State> for user
+interaction. Among other things, C<OpenBSD::State> provides for printable, 
+translatable messages, consistent option handling and usage messages.
+
+All commands that provide a progress meter use the derived module
+C<OpenBSD::AddCreateDelete>, which contains a derived state class
+C<OpenBSD::AddCreateDelete::State>, and a main command class
+C<OpenBSD::AddCreateDelete>, with consistent options.
+
+Eventually, this will allow third party tools to simply override the user
+interface part of C<OpenBSD::State>/C<OpenBSD::ProgressMeter> to provide
+alternate displays.
+
 =back
 
 =head1 BASIC ALGORITHMS
@@ -336,21 +353,9 @@ There are a few desireable changes that will happen in the future:
 
 =item *
 
-Version number handling does not yet extends to package signatures.
-Thus, some spurious downgrades may happen if the packagename itself does not
-change.
-
-=item *
-
 there should be some carefully designed mechanisms to register more
 `global' processing, to avoid exec/unexec.
 
-=item *
-
-some packages should be able to refuse automatic update, and to interact
-with the user. Again, to be carefully designed, so that one can still
-understand what's going on.
-
 =back
 
 =head1 LIST OF MODULES
@@ -361,6 +366,19 @@ understand what's going on.
 
 common operations related to a package addition.
 
+=item OpenBSD::AddCreateDelete
+
+common operations related to package addition/creation/deletion.
+Mainly C<OpenBSD::ProgressMeter> related.
+
+=item OpenBSD::AddDelete
+
+common operations used during addition and deletion.
+Mainly due to the fact that C<pkg_add(1)> will remove packages during
+updates, and that addition/suppression operations are only allowed to
+fail at specific times. Most updateset algorithms live there, as does
+the upper layer framework for handling signals safely.
+
 =item OpenBSD::ArcCheck
 
 additional layer on top of C<OpenBSD::Ustar> that matches extra
@@ -374,29 +392,60 @@ full list of installed files, and reports origin of existing files.
 
 =item OpenBSD::Delete
 
-common operations related to a package deletion
+common operations related to package deletion.
+
+=item OpenBSD::Dependencies
+
+looking up all kind of dependencies.  Contains rather complicated caching
+to speed things up.  Interacts with the global tracker object.
 
 =item OpenBSD::Error
 
-handles external calls through C<system(3p)>, exception mechanism,
-fatal errors and warnings.
+handles signal registration, the exception mechanism, and auto-caching 
+methods.  Most I/O operations have moved to C<OpenBSD::State>.
 
 =item OpenBSD::Getopt
 
 L<Getopt::Std(3p)>-like with extra hooks for special options.
 
+=item OpenBSD::Handle
+
+proxy class to go from a package location to an opened package with plist,
+including state information to cache errors.
+
 =item OpenBSD::IdCache
 
 caches uid and gid vs. user names and group names correspondences.
 
 =item OpenBSD::Interactive
 
-handles user questions (to be redesigned)
+handles user questions (do not call directly, go through C<OpenBSD::State>
+and derivatives).
+
+=item OpenBSD::LibSpec
+
+interactions between library objects from packing-lists, library specifications,
+and matching those against actual lists of libraries (from packages or from
+the system).
+
+=item OpenBSD::LibSpec::Build
+
+extends C<OpenBSD::LibSpec> for matching during ports builds.
+
+=item OpenBSD::Log
+
+component for printing information later, to be used by derivative classes
+of C<OpenBSD::State>.
 
 =item OpenBSD::Mtree
 
 simple parser for L<mtree(8)> specifications.
 
+=item OpenBSD::OldLibs
+
+code required by C<pkg_add(1)> to handle the removal of old libraries during
+update.
+
 =item OpenBSD::PackageInfo
 
 handles package meta-information (all the +CONTENTS, +DESCR, etc files)
@@ -431,10 +480,18 @@ because searching through a repository list has L<ld(1)>-like semantics
 all the packing-list elements class hierarchy, together with common
 methods that do not belong elsewhere.
 
+=item OpenBSD::PackingList
+
+responsible for reading/writing packing-lists, copying them, comparing them.
+
 =item OpenBSD::Paths
 
 hardcoded paths to external programs and locations.
 
+=item OpenBSD::PkgAdd, OpenBSD::PkgCreate, OpenBSD::PkgCheck, OpenBSD::PkgDelete, OpenBSD:PkgInfo
+
+implements corresponding commands.
+
 =item OpenBSD::PkgCfl
 
 conflict lists handling in an efficient way.
@@ -447,10 +504,8 @@ exist.
 
 =item OpenBSD::ProgressMeter
 
-handles display of a progress meter when a terminal is available.
-Provided as a singleton object so that a graphical interface could
-be used instead. In practice, most input-output of the package tools
-will need to be abstracted first.
+handles display of a progress meter when a terminal is available, devolves
+to nothings otherwise.
 
 =item OpenBSD::Replace
 
@@ -472,6 +527,15 @@ handles items that may be shared by several packages.
 
 shared library specificities when handled as dependencies.
 
+=item OpenBSD::Signature
+
+handles package signatures and the corresponding version comparison (do not
+confuse with cryptographic signatures, as handled through C<OpenBSD::x509>).
+
+=item OpenBSD::State
+
+base class to UI and option handling. 
+
 =item OpenBSD::Subst
 
 conventions used for substituting variables during L<pkg_create(1)>,
@@ -509,4 +573,10 @@ virtual file system (pretend) operations.
 
 simple interface to the L<Digest::MD5(3p)> module.
 
+=item OpenBSD::x509
+
+cryptographic signature through x509 certificates. Mostly calls C<openssl(1)>.
+Note that C<OpenBSD::ArcCheck>  is vital in ensuring archive meta-info have
+not been tampered with.
+
 =back
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod b/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod
index 3e7c0d2b39d..b5648e03eb0 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::Vstat.pod,v 1.5 2010/01/02 14:13:02 espie Exp $
+$OpenBSD: OpenBSD::Vstat.pod,v 1.6 2010/06/18 10:56:32 espie Exp $
 
 =head1 NAME
 
@@ -24,6 +24,9 @@ before doing them for real.
 The constructor C<new> expect a C<$state> object, that is, an object with
 C<$state-E<gt>{not}> and C<$state-E<gt>errsay> defined.
 
+Operations on the C<Vstat> object can modify C<$state-E<gt>{problems}> 
+and C<$state-E<gt>{overflow}>.
+
 The method C<add> (respectively C<remove>) can be used to add a filename to
 the file system (resp. remove a filename from the file system).
 The method C<exists> looks for
@@ -73,8 +76,30 @@ C<synchronize>: old files must be removed before
 adding the new files in order to properly account for collisions,
 but the old files occupy disk space while the new package gets extracted.
 
+Modifications to the virtual file system are stored until a call to
+C<synchronize>, which assumes the real file system will get those changes
+(and thus we can forget them), or C<drop_changes>, which assumes the changes
+won't get through, thus providing transactional semantics.
+
+In case of file system overflow, C<remove_first> can be used to indicate
+file removal happens before the creation of new files.
+
+Typical use is as follows:
+	do lot of changes to the Vstat object
+	check for overflow.
+	if so, drop_changes.
+	redo the changes, with remove_first used instead of remove.
+
+In case C<$state-E<gt>{not}> is true, the real file system will never store
+changes, and thus the C<Vstat> object is layered to allow full transactional
+back-out.
+
+
 =head1 BUGS AND LIMITATIONS
 
 C<OpenBSD::Vstat> now handles C<chroot(8)> situations gracefully, but
 it doesn't know about symbolic links to directories and will report bogus
 results in complicated cases.
+
+C<OpenBSD::Vstat> needs an interface to deal with removed directories that
+get replaced with files. Currently, it will report a conflict.