$NetBSD: PKGVIEWS_UG,v 1.3 2006/12/15 12:46:24 martti 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 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