xbps-src - building packages from source
========================================

Introduction
------------
`xbps-src` is the utility used by the _X binary package system_ to build
binary packages from source distribution files. A root directory (`srcpkgs`)
contains multiple subdirs, each one to build a package as its name
indicates. The following directory structure illustrates it:
 +
.................................
  xbps-templates/
      |
      |-----srcpkgs/
               |
               |-----binutils/
               |-----gcc/
               |-----glibc/
..................................

A package subdirectory always has a `template` file, that are the
specifications to download and build the binary package from its source files.
Additionally some packages may have additional subdirs on it: `files`
and `patches`. The `files` subdir may contain configuration files, or
any other file required to build the package. The `patches` subdir contains
patches that are applied to the source before building.
 +

Some packages may provide `subpackages`; they are different binary packages
that are built from the same source package. Each `subpackage` in the directory
structure (as shown above) is a symlink to the `real` package subdir, like this:
 +
....................................
  srcpkgs/
     |
     |-----gcc/
     |-----libgomp -> gcc
     |-----libmudflap -> gcc
     |-----libstdc++ -> gcc
....................................

Each subpackage uses its own `template` build file that is contained in
the `real` package subdir, and they have exactly the same name than the
symlink pointing to the `real` package subdir. The following example
illustrates the structure used by the _udev_ package in the filesystem:
 +
.......................................
  srcpkgs/
    |
    |-----libgudev-devel -> udev
    |-----libgudev -> udev
    |-----libudev-devel -> udev
    |-----libudev -> udev
    |-----udev/
           |----template
           |----libgudev-devel.template
           |----libgudev.template
           |----libudev-devel.template
           |----libudev.template
.......................................
 +

Subpackages use a reduced version of the main `template` build file, because
the build and main install process is all done in the real `template` file.
Usually those `<subpkg>.template` files only move files and directories
to the `subpackage` destination directory, so they are always smaller.

Requirements
------------
The following software is required in the host system to install xbps-src
and its helpers:

 - GCC, make, sed and libcap (depelopment package and setcap(8) command).

To build binary packages with xbps-src also the following software needs
to be installed into the host system:

 - awk, bash, bison, gcc c++, gettext, path, texinfo, perl and fakeroot.
 - xbps static utilities, available from http://launchpad.net/xbps.

Additionally if you want to work as 'root':

 - sudo

Starting up
-----------
Firstly you'll have to download the `git` repository that contains `xbps-src`
and the build template files. To clone it with `git` use:

----------------------------------------------------
$ git clone git://repo.or.cz/xbps.git xbps-templates
----------------------------------------------------

`xbps-src` and its shell utilities need to be installed in a directory
for correct operation, that is accomplished by issuing:

--------------------------------------------------
$ cd xbps-templates/xbps-src && make install clean
--------------------------------------------------

This will install all files into `/usr/local` by default, can be changed
by specifying `PREFIX` and `DESTDIR` to make(1).

Building packages from source
-----------------------------
`xbps-src` always look for a `template` file in current directory, that's what
it specifies the package build definitions and such. The build templates
are located in the `srcpkgs` directory, you should change the cwd to the
directory matching the package that you want to work on, i.e for binutils,
its directory is `srcpkgs/binutils`.
 +
 +

If configuration file is not specified from the command line with the
`-c` flag, it will first try to use the default location at
`/usr/local/etc/xbps-src.conf` (or the installation prefix that was specified
to the make(1) command), and as last resort in the etc directory of the
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 required set of packages
that will be used in the chroot:

----------------------------------------------------------------
$ cd xbps-templates/srcpkgs/xbps-base-chroot && xbps-src install
----------------------------------------------------------------

This will build all required packages via fakeroot in masterdir, therefore you
can run it as normal user. Once 'xbps-src-chroot' has been built and installed
into the 'masterdir' all packages will be built inside of the chroot.
 +
 +

'xbps-src' supports building packages in the chroot with your normal user,
thanks to the *POSIX.1e Capabilities* support in the Linux kernel. To use this
the target filesystem must support *extended attributes*; right now they
are supported on almost all Linux filesytems, such as *ext2*, *ext3*, *ext4*,
*xfs*, and others. To enable this feature you have to uncomment the option
'XBPS_USE_CAPABILITIES' from *xbps-src.conf*. *PLEASE NOTE* that it's
commented out (disabled) by default.
 +
 +

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:

----------------------
$ xbps-src chroot
----------------------

Press Control + D to exit from the chroot. The following targets will require
to be done in the chroot (_once xbps-base-chroot is installed_):
*build, configure, install and install-destdir*.
 +
 +

Now let's explain some more about the targets that you can use. To start
installing packages you should use the install target, all source packages
are located in the `srcpkgs` directory, so to install glib:

------------------------------------------
$ cd srcpkgs/<pkgname> && xbps-src install
------------------------------------------

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

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

-----------------------------------------
$ cd srcpkgs/<pkgname> && xbps-src remove
-----------------------------------------

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

---------------------------------------
$ cd srcpkgs/<pkgname> && xbps-src stow
---------------------------------------

To unstow an already installed (stowned) package:

-----------------------------------------
$ cd srcpkgs/<pkgname> && xbps-src unstow
-----------------------------------------

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

---------------------------------------
$ cd srcpkgs/<pkgname> && xbps-src info
---------------------------------------

To list installed (stowned) packages, use this:
---------------
$ xbps-src list
---------------

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

------------------------------------------
$ cd srcpkgs/<pkgname> && xbps-src extract
------------------------------------------

To not remove the build directory after successful installation:

---------------------------------------------
$ cd srcpkgs/<pkgname> && xbps-src -C install
---------------------------------------------

To only fetch the distfile:
----------------------------------------
$ cd srcpkgs/<pkgname> && xbps-src fetch
----------------------------------------

To only install the package, _without_ stowning it into the master directory:
--------------------------------------------------
$ cd srcpkgs/<pkgname> && xbps-src install-destdir
--------------------------------------------------

To list files installed by a package, note that package must be installed
into destination directory first:
------------------------------
$ xbps-src listfiles <pkgname>
------------------------------

That should be enough to get you started. If you have any question or
suggestion about *xbps-src* and the build templates, don't forget that there
is a mailing list to talk about it on:

http://groups.google.com/xbps