--9jxsPFA5p3P2qPhR
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

I've attached a start of a user's guide to using pkgviews for those
users who wish to experiment with the new functionality in pkgsrc.

	Cheers,

	-- Johnny Lam <jlam@NetBSD.org>

--9jxsPFA5p3P2qPhR
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename=pkgviews_ug

 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 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

--9jxsPFA5p3P2qPhR--