void-packages/README

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

What is it?
-----------
`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 example illustrates it:
 +
 +
.................................
xbps-templates/
     |
     |----- srcpkgs/
             |
             |----- binutils/
             |----- gcc/
             |----- glibc/
             |----- ....
..................................

Requirements
------------
The following software is required in the host system to build XBPS
binary packages from source:

 - GNU awk
 - GNU bash
 - GNU bison
 - GNU gcc c++ (development package)
 - GNU gettext (development package)
 - GNU make
 - GNU patch
 - GNU texinfo
 - fakeroot
 - perl
 - sudo

`xbps-src` and its shell utilities need to be installed in a directory
for correct operation, that is accomplished by issuing:
-----------------------------------
$ cd 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 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. 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 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, 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, all source packages
are located in the `srcpkgs` directory, so to install glib:
------------------------------------------
$ cd srcpkgs/glib && sudo 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 copied all files from DESTDIR/<pkgname>.
 +

To remove a currently installed (and stowned) package, you can use:
-----------------------------------------
$ cd srcpkgs/glib && sudo 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/glib && sudo xbps-src stow
---------------------------------------

To unstow an already installed (stowned) package:
-----------------------------------------
$ cd srcpkgs/glib && sudo xbps-src unstow
-----------------------------------------

You can also print some stuff about any template build file, e.g:
----------------------------------
$ cd srcpkgs/glib && xbps-src info
----------------------------------

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

To only extract the distfiles, without configuring/building/installing:
------------------------------------
$ cd srcpkgs/foo && xbps-src extract
------------------------------------

To not remove the build directory after successful installation:
---------------------------------------------
$ cd srcpkgs/blah && sudo xbps-src -C install
---------------------------------------------

To only fetch the distfile:
-----------------------------------
$ cd srcpkgs/blah && xbps-src fetch
-----------------------------------

To only install the package, _without_ stowning it into the master directory:
--------------------------------------------------
$ cd srcpkgs/blob && sudo 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
----------------------------