void-packages/doc/README

-----------------------------------------------------------------------------
 WHAT IS IT?
-----------------------------------------------------------------------------

xbps - xtraeme's build package system.

It is a simple build package system that installs packages inside of
a chroot in a destination directory. Once the package has been installed
into this directory, you can make it appear/unappear at the master directory
at any time. It's in spirit the same than GNU stow, but the files are just
copied (there are no soft/hard links).

xbps has been designed for Linux, and for the moment I'm not interested to
make it work on any other random OS. I've been a NetBSD developer for some
years and I do not want to come back... also the experience has helped to
me to start xbps and not to use pkgsrc, which is very portable but also
not so fast.

-----------------------------------------------------------------------------
 REQUIREMENTS
-----------------------------------------------------------------------------

xbps uses proplib, a property container object library and it's almost the
same one available for NetBSD. Be sure to have it installed before using
xbps. You can get it at:

http://code.google.com/p/portableproplib/

I'm also the human maintaining the portable proplib package. I'd suggest you
to install it into /usr/local to avoid issues with your distribution packages.

Additionally the following software is required to be able to use xbps:

	* GNU Make
	* GNU Binutils
	* GNU GCC (plus GMP and MPFR) development packages.
	* GNU Bison
	* GNU m4
	* wget
	* fakeroot

Super-user privileges are required as well, because all packages are built
in a chroot (except the ones that are included in a virtual package to be
able to build a minimal system for the chroot).

PLEASE NOTE THAT fakechroot or fakeroot-ng DO NOT WORK.

------------------------------------------------------------------------------
 HOW TO USE IT
------------------------------------------------------------------------------

Before using xbps, some required utilities need to be built and installed into
the utils/ directory. You can do this by issuing "make" in the top level
directory and edit the configuration file located at the xbps directory.
By default it uses the xbps directory in your $HOME.

If configuration file is not specified from the command line with the
-c flag, it will first try to use the default location at
/etc/xbps.conf, and as last resort in current directory.

To avoid problems with libtool and configure scripts finding stuff that is
available in the host system, almost all packages must be built inside of a
chroot. So the first thing would be to create the binary packages with:

	$ xbps-src.sh install xbps-base-chroot

This will build all required packages via fakeroot in masterdir, therefore you
can run it as normal user. Next commands will require super-user privileges
and all package handling will be done within the chroot. I believe it's the
most easier and faster way to handle clean dependencies; another reason would
be that xbps packages are meant to be used in a system and not just for
ordinary users. So once all packages are built, you can create and enter
to the chroot with:

	$ sudo xbps-src.sh chroot

Press Control + D to exit from the chroot. The following targets will require
to be done in the chroot:

	build, configure, install, install-destdir, remove, stow and unstow.

Now let's explain some more about the targets that you can use. To start
installing packages you should use the install target:

	$ sudo xbps-src.sh install glib

If the package is properly installed, it will be "stowned" automatically.
``stowned<65><64> means that this package is available in the master directory,
on which xpbs has copied all files from DESTDIR/<pkgname>.

To remove a currently installed (and stowned) package, you can use:

	$ sudo xbps-src.sh remove glib

Please note that when you remove it, the package will also be removed
from XBPS_DESTDIR and previously "unstowned".

To stow an already installed package (from XBPS_DESTDIR/<pkgname>):

	$ sudo xbps-src.sh stow glib

and to unstow an already installed (stowned) package:

	$ sudo xbps-src.sh unstow glib

You can also print some stuff about any template build file, e.g:

	$ xbps-src.sh info glib

To list installed (stowned) packages, use this:

	$ xbps-src.sh list

To only extract the distfiles, without configuring/building/installing:

	$ xbps-src.sh extract foo

To not remove the build directory after successful installation:

	$ sudo xbps-src.sh -C install blah

To only fetch the distfile:

	$ xbps-src.sh fetch blah

To only install the package, _without_ stowning it into the master directory:

	$ sudo xbps-src.sh install-destdir blob

To list files installed by a package, note that package must be installed
into destination directory first:

	$ xbps-src.sh listfiles blob

------------------------------------------------------------------------------
 PERFORMANCE
------------------------------------------------------------------------------

xbps is really fast, trust me. That was one of my reasons to make my own
pkgsrc/ports alike system.

If you want benchmarks, here is one: building libX11 and all its dependencies
required (not included building xstow) with xbps:

	251.20s real   121.36s user    53.94s system

versus pkgsrc (make install clean clean-depends and digest previously
installed):

	450.41s real   167.58s user    97.31s system

That's more or less 40% faster! that's the price you pay for having those
wrappers in pkgsrc that aren't very useful on NetBSD :-)

------------------------------------------------------------------------------
	Juan Romero Pardines <xtraeme@gmail.com>