Commit the buildlink3 developer's guide and the pkgviews user's guide until

they're polished enough to be included into Packages.txt.

1 files changed, 222 insertions, 0 deletions

diff --git a/mk/buildlink3/PKGVIEWS_UG b/mk/buildlink3/PKGVIEWS_UG
new file mode 100644
index 00000000000..6e586e3d898
--- /dev/null
+++ b/mk/buildlink3/PKGVIEWS_UG
@@ -0,0 +1,222 @@
+$NetBSD: PKGVIEWS_UG,v 1.1 2004/01/29 06:03:15 jlam Exp $
+
+ 0 User's Guide to pkgviews
+ ==========================
+
+This is a tutorial for pkgsrc users who wish to experiment with the
+new "pkgviews" implementation in pkgsrc.  More information about
+pkgviews may be found in pkgsrc/mk/buildlink3/README.  That document
+also explains why you might want to use pkgviews.  Some reasons
+include:
+
+	* fully dynamic PLISTs
+	* multiple version of the same package can co-exist
+	* no or non-fatal conflicting packages
+
+
+ 0.1 CAVEAT (USE AT YOUR OWN RISK!)
+ ==================================
+
+Pkgviews is *completely experimental* at this point in time.  Bug
+reports on pkgviews will be treated with a fairly low priority by the
+general pkgsrc developers, though I may personally be more responsive.
+However, the major thrust of the next several weeks of pkgsrc
+development for me will revolve around testing and integrating the
+buildlink3 framework into pkgsrc and deprecating buildlink2.  Any
+work on pkgviews during that time is strictly happenstance.
+
+
+ 0.1 Preparing your system to use pkgviews
+ =========================================
+
+You will need to start with a clean system to use pkgviews.  Depoted
+packages, a.k.a "pkgviews" packages (packages that are built using
+pkgviews) cannot depend on non-depoted packages, a.k.a.  "overwrite"
+packages, although the reverse is possible.  If you have _any_
+packages installed, you will need to pkg_delete them before you can
+start building depoted packages.  In fact, it's best to completely
+nuke /usr/pkg (or wherever you choose for your ${LOCALBASE}) as
+pkgviews manages all of its own directories.
+
+Next you will need to add the following line to /etc/mk.conf:
+
+	PKG_INSTALLATION_PREFS=	pkgviews overwrite
+
+This creates pkgviews packages instead of overwrite packages for any
+packages that support it.  The packages that do support pkgviews
+can be identified by searching the package Makefile for the the
+following line:
+
+	PKG_INSTALLATION_TYPES=	overwrite pkgviews
+
+
+ 0.2 Installing your first pkgviews package
+ ==========================================
+
+The first package you will need to install is pkgsrc/pkgtools/digest.
+
+===> Checking for vulnerabilities in digest-20021220
+===> Extracting for digest-20021220
+===> Checking for vulnerabilities in digest-20021220
+===> Patching for digest-20021220
+===> Overriding tools for digest-20021220
+===> Buildlinking for digest-20021220
+===> Configuring for digest-20021220
+configure: WARNING: If you wanted to set the --build type, don't use --host.
+    If a cross compiler is detected then cross compile mode will be used.
+checking build system type... i386-unknown-netbsdelf1.6.2.
+checking host system type... i386--netbsdelf
+...
+configure: creating ./config.status
+config.status: creating Makefile
+config.status: creating config.h
+===> Building for digest-20021220
+cc -DHAVE_CONFIG_H -I. -I. -DHOST=\"i386--netbsdelf\" -DVERSION=\"20021220\"  -O2 -mcpu=pentiumpro -c bits.c -o bits.o
+...
+cc -O2 -mcpu=pentiumpro  -o digest digest.o md5c.o rmd160.o rmd160hl.o sha2.o sha2hl.o  md5hl.o sha1.o sha1hl.o 
+=> Fixing buildlink references in files-to-be-installed.
+===> Installing for digest-20021220
+===> Becoming root@blossom.hq.williamlam.com to install digest.
+sudo /bin/sh ./mkinstalldirs /usr/pkg/packages/digest-20021220/bin
+mkdir /usr/pkg/packages/digest-20021220/bin
+install -c -s -o root -g wheel -m 555 digest /usr/pkg/packages/digest-20021220/bin/digest
+/bin/sh ./mkinstalldirs /usr/pkg/packages/digest-20021220/man/man1
+mkdir /usr/pkg/packages/digest-20021220/man
+mkdir /usr/pkg/packages/digest-20021220/man/man1
+install -c -o root -g wheel -m 444 digest.1 /usr/pkg/packages/digest-20021220/man/man1/digest.1
+===> Registering installation for digest-20021220
+===> Building views for digest-20021220
+=> Performing package view clash check for digest-20021220 in standard view
+=> Performing package view overwrite check for digest-20021220 in standard view
+=> Linking package into standard view
+
+Notice in the transcript that the digest package has been installed
+into /usr/pkg/packages/digest-20021220 and then subsequently linked
+into the "standard view".  The standard view is simply /usr/pkg, which
+means that the digest executable is accessible as /usr/pkg/bin/digest.
+
+
+ 0.3 The contents of /usr/pkg (${LOCALBASE})
+ ===========================================
+
+There is a directory /usr/pkg/packages that contains all of the
+depoted packages.  The contents of /usr/pkg/packages after installing
+digest are:
+
+/usr/pkg/packages/digest-20021220/+BUILD_INFO
+/usr/pkg/packages/digest-20021220/+BUILD_VERSION
+/usr/pkg/packages/digest-20021220/+COMMENT
+/usr/pkg/packages/digest-20021220/+CONTENTS
+/usr/pkg/packages/digest-20021220/+DESC
+/usr/pkg/packages/digest-20021220/+SIZE_ALL
+/usr/pkg/packages/digest-20021220/+SIZE_PKG
+/usr/pkg/packages/digest-20021220/+VIEWS
+/usr/pkg/packages/digest-20021220/bin/digest
+/usr/pkg/packages/digest-20021220/man/man1/digest.1
+
+Note that all of the files related to the package, including the
+package metadata files used by the pkg_* tools, are stored in the
+"depot directory" for digest (/usr/pkg/packages/digest-20021220).
+
+The digest package was also linked into the standard view.  Looking
+inside /usr/pkg shows us the following symlinks:
+
+/usr/pkg/bin/digest -> /usr/pkg/packages/digest-20021220/bin/digest
+/usr/pkg/man/man1/digest.1 -> /usr/pkg/packages/digest-20021220/man/man1/digest.1
+
+Since digest is present in /usr/pkg/bin, it can be used as always
+without any changes needed by the typical user with /usr/pkg/bin in
+his PATH, and "man digest" will continue to work as expected.
+
+
+ 0.4 Creating new views
+ ======================
+
+The following commands will install both pkgsrc/www/lynx and
+pkgsrc/www/lynx-current onto the same system using pkgviews:
+
+	cd /usr/pkgsrc/www/lynx; make install
+	cd /usr/pkgsrc/www/lynx-current; make install PKGVIEWS=devel
+
+The stable version of lynx (2.8.4.1nb2) is linked into the standard
+view, while the -current version of lynx (2.8.5.0.7nb3) is linked into
+the "devel" view.  The lynx-related files in /usr/pkg are:
+
+/usr/pkg/bin/lynx -> /usr/pkg/packages/lynx-2.8.4.1nb2/bin/lynx
+/usr/pkg/man/man1/lynx.1 -> /usr/pkg/packages/lynx-2.8.4.1nb2/man/man1/lynx.1
+/usr/pkg/share/locale/cs/LC_MESSAGES/lynx.mo -> ...
+...
+
+/usr/pkg/devel/bin/lynx -> /usr/pkg/packages/lynx-2.8.5.0.7nb3/bin/lynx
+/usr/pkg/devel/man/man1/lynx.1 -> /usr/pkg/packages/lynx-2.8.5.0.7nb3/man/man1/lynx.1
+/usr/pkg/devel/share/locale/cs/LC_MESSAGES/lynx.mo -> ...
+...
+
+Note that the files for pkgsrc/www/lynx have been symlinked into
+/usr/pkg as usual, but the files for pkgsrc/www/lynx-current have been
+symlinked into the "devel" subdirectory of /usr/pkg.  The files in
+in the "devel" view can be accessed by adding /usr/pkg/devel/bin to
+the PATH and adding /usr/pkg/devel/man to MANPATH in the appropriate
+place.
+
+
+ 0.5 Managing views using pkg_* tools
+ ====================================
+
+Adding and removing package instances to and from views is always a
+safe operation as the true package files are left untouched.  All that
+happens is that linkfarms are being added or removed, thus changes are
+always easy to reverse.
+
+Adding a depoted package into a view may be accomplished with:
+
+	pkg_view -w devel add gmake-3.80nb2
+
+This adds the gmake-3.80nb2 package (already present on the system) to
+the "devel" view.  The "devel" view is created if it doesn't already
+exist.
+
+Removing a package from a view may be accomplished with either of the
+following commands:
+
+	pkg_view -w devel delete gmake-3.80nb2
+	pkg_delete -K /usr/pkg/devel/.pkgdb gmake
+
+Either of these will remove the gmake-3.80nb2 package from the "devel"
+view if the package exists in the view.
+
+Removing a package from the standard view may be accomplished with
+either of the following commands
+
+	pkg_view delete gmake-3.80nb2
+	pkg_delete gmake
+
+The latter one is recommended for speed.
+
+
+ 0.6 Completely removing a package
+ =================================
+
+Removing a depoted package from the system (removing it from all views
+and removing the depot directory) is done with:
+
+	pkg_delete -K /usr/pkg/packages gmake-3.80nb2
+
+If you know that only a single gmake is present on your system, then
+you can specify "gmake" instead of the full package name to
+pkg_delete(1).  However, I recommend being explicit about the package
+you are removing to avoid any surprises.
+
+
+ 0.6 Where to learn more about pkgviews
+ ======================================
+
+There are several shell environment variables that may be set to
+affect the default behaviour of the pkg_* tools.  Please read the
+pkg_view(1) man page for more information.
+
+For a more complete understanding of the motivations and principles
+behind pkgviews, the following paper by Alistair Crooks is highly
+recommended:
+
+	http://www.NetBSD.org/Documentation/software/pkgviews.pdf