void-packages/doc/manual.txt

The XBPS source packages manual
===============================
Juan RP <xtraeme@gmail.com>
:Author Initials: JRP
:toc:
:icons:
:numbered:
:website: http://www.voidlinux.eu

This article contains an exhaustive manual of how to create new source
packages for XBPS, the package manager of the *Void Linux distribution*.

Introduction
------------
The `xbps-packages` repository contains all `source` packages that are the
recipes to download, compile and build binary packages for `Void`.
Those `source` package files are called `templates`.

The `template files` are `GNU bash` shell scripts that must define some required/optional
`variables` and `functions` that are processed by `xbps-src` (the package builder)
to generate the resulting binary packages.

A simple `template` example is as follows:

--------------------------------------------------------------------------
# Template file for 'foo'

## source section
pkgname="foo"
version="1.0"
revision="1"
build_style="gnu-configure"
short_desc="A short description max 72 chars"
maintainer="name <email>"
license="GPL-3"
homepage="http://www.foo.org"
distfiles="http://www.foo.org/foo-${version}.tar.gz"
checksum="fea0a94d4b605894f3e2d5572e3f96e4413bcad3a085aae7367c2cf07908b2ff"

## package section
foo_package() {
  pkg_install() {
    vmove all
  }
}
---------------------------------------------------------------------------


There are two main `sections` in a template: the `source section` and the
`package section`. The `source section` contains definitions to download, build
and install the package files to a `fake destdir`. The `package section`
contains the definitions to how the resulting binary packages are generated.

A template always requires at least a `source section` and a `package section`;
multiple `package sections` can be defined to generate `multiple binary packages`.

Don't worry if anything is not clear as it should be. The reserved `variables`
and `functions` will be explained later. This `template` file should be created
in a directory matching `$pkgname`, i.e: `xbps-packages/srcpkgs/foo/template`.
If everything went fine after running `xbps-src build-pkg` a binary package
called `foo-1.0_1.<arch>.xbps` will be generated in the local repository.

Additional binary packages (those defined in `_package() blocks` need a
symlink to the `main` package, like this:

----------------------------------

 /srcpkgs
  |- foo <- directory
  |  |- template
  |- foo-devel <- symlink to `foo`

----------------------------------

Otherwise dependencies requiring those packages won't find its `template`
file.

Package build phases
--------------------
Building a package consist of the following phases:

*fetch*::
    This phase downloads required sources for a `source package`, as defined by
    the `distfiles` variable or `do_fetch()` function.

*extract*::
    This phase extracts the `distfiles` files into `$wrksrc` or executes the `do_extract()`
    function, which is the directory to be used to compile the `source package`.

*configure*::
    This phase executes the `configuration` of a `source package`, i.e `GNU configure scripts`.

*build*::
    This phase compiles/prepares the `source files` via `make` or any other compatible method.

*install-destdir*::
    This phase installs the `package files` into a `fake destdir`, via `make install` or
    any other compatible method.

*build-pkg*::
    This phase builds the `binary packages` with files stored in the `package destdir`.

`xbps-src` supports running just the specified phase, and if it ran
successfully, the phase will be skipped later (unless its work directory
`${wrksrc}` is removed with `xbps-src clean`).

Global functions
----------------
The following functions are defined by `xbps-src` and can be used on any template:

*vinstall()*::
    `vinstall <file> <mode> <targetdir> [<name>]`

    Installs `file` with the specified `mode` into `targetdir` in `$DESTDIR`
    (if called from a `source section`) or `$PKGDESTDIR` (if called from a `package section`).
    The optional 4th argument can be used to change the `file name`.

*vcopy()*::
    `vcopy <pattern> <targetdir>`

    Copies resursively all files in `pattern` to `targetdir` on `$DESTDIR`
    (if called from a `source section`) or `$PKGDESTDIR` (if called from a `package section`).

*vmove()*::
    `vmove <pattern>`

    Moves `pattern` to the specified directory in `$DESTDIR`
    (if called from a `source section`) or `$PKGDESTDIR` (if called from a `package section`).

*vmkdir()*::
    `vmkdir <directory> [<mode>]`

    Creates a directory in `$DESTDIR` (if called from a `source section`) or
    $PKGDESTDIR` (if called from a `package section`). The 2nd optional argument
    sets the mode of the directory.

NOTE: shell wildcards must be properly quoted.

Global variables
----------------
The following variables are defined by `xbps-src` and can be used on any template:

*makejobs*::
    Set to `-jX` if `XBPS_MAKEJOBS` is defined, to allow parallel jobs with `GNU make`.

*sourcepkg*::
    Set to the to main package name, can be used to match the main package
    rather than additional binary package names.

*CHROOT_READY*::
    True if the target chroot (masterdir) is ready for chroot builds.

*CROSS_BUILD*::
    True if `xbps-src` is cross compiling a package.

*DESTDIR*::
    Full path to the fake destdir used by the `source section`, set to
    `${XBPS_MASTERDIR}/destdir/${sourcepkg}-${version}`.

*PKGDESTDIR*::
    Full path to the fake destdir used by the `pkg_install()` function in the
    `package section`, set to `${XBPS_MASTERDIR}/destdir/pkg-${pkgname}-${version}`.

*XBPS_MACHINE*::
    The machine architecture as returned by `uname -m`.

*XBPS_SRCDISTDIR*::
    Full path to where the `source distfiles` are stored, i.e `$XBPS_HOSTDIR/sources`.

*XBPS_SRCPKGDIR*::
    Full path to the `srcpkgs` directory.

*XBPS_TARGET_MACHINE*::
    The target machine architecture when cross compiling a package.


Source section
--------------
Mandatory variables
~~~~~~~~~~~~~~~~~~~
The list of mandatory variables in the `source section`:

*homepage*::
    A string pointing to the `upstream` homepage.

*license*::
    A string matching any license file available in `/usr/share/licenses`.
    Multiple licenses should be separated by commas, i.e `GPL-3, LGPL-2.1`.

*maintainer*::
    A string in the form of `name <user@domain>`.

*pkgname*::
    A string with the package name, matching `srcpkgs/<pkgname>`.

*revision*::
    A number that must be set to 1 when the `source package` is created, or
    updated to a new `upstream version`. This should only be increased when
    the generated `binary packages` have been modified.

*short_desc*::
    A string with a brief description for this package. Max 72 chars.

*version*::
    A string with the package version. Must not contain dashes and at least
    one digit is required.


Optional variables
~~~~~~~~~~~~~~~~~~
*hostmakedepends*::
    The list of `host` dependencies required to build the package. Dependencies
    can be specified with the following version comparators: `<`, `>`, `<=`, `>=`
    or `foo-1.0_1` to match an exact version. If version comparator is not
    defined (just a package name), the version comparator is automatically set to `>=0`.
    Example `hostmakedepends="foo blah<1.0"`.

*makedepends*::
    The list of `target` dependencies required to build the package. Dependencies
    can be specified with the following version comparators: `<`, `>`, `<=`, `>=`
    or `foo-1.0_1` to match an exact version. If version comparator is not
    defined (just a package name), the version comparator is automatically set to `>=0`.
    Example `makedepends="foo blah>=1.0"`.

*bootstrap*::
    If enabled the source package is considered to be part of the `bootstrap`
    process and required to be able to build packages in the chroot. Only a
    small number of packages must set this property.

*distfiles*::
    The full URL to the `upstream` source distribution files. Multiple files
    can be separated by blanks. The files must end in `.tar.lzma`, `.tar.xz`,
    `.txz`, `.tar.bz2`, `.tbz`, `.tar.gz`, `.tgz`, `.gz`, `.bz2`, `.tar` or
    `.zip`. Example `distfiles="http://foo.org/foo-1.0.tar.gz"`

*checksum*::
    The `sha256` digests matching `${distfiles}`. Multiple files can be
    separated by blanks. Please note that the order must be the same than
    was used in `${distfiles}`. Example `checksum="kkas00xjkjas"`

*long_desc*::
   A long description of the main package. Max 80 chars per line and must
   not contain the following characters: `&`, `<`, `>`.

*wrksrc*::
    The directory name where the package sources are extracted, by default
    set to `${pkgname}-${version}`.

*build_wrksrc*::
    A directory relative to `${wrksrc}` that will be used when building the package.

*create_wrksrc*::
    Enable it to create the `${wrksrc}` directory. Required if a package
    contains multiple `distfiles`.

*only_for_archs*::
    This expects a separated list of architectures where the package can be
    built matching `uname -m` output. Example `only_for_archs="x86_64 armv6l"`

*build_style*::
    This specifies the `build method` for a package. Read below to know more
    about the available package `build methods`. If `build_style` is not set,
    the package must define at least a `do_install()` function, and optionally
    more build phases as such `do_configure()`, `do_build()`, etc.

*create_srcdir*::
    This creates a directory in `${XBPS_SRCDISTDIR}` as such `${pkgname}-${version}`
    to store the package sources at the `extract` phase. Required in packages that
    use unversioned ${distfiles}`.

*configure_script*::
    The name of the `configure` script to execute at the `configure` phase if
    `${build_style}` is set to `configure` or `gnu-configure` build methods.
    By default set to `./configure`.

*configure_args*::
    The arguments to be passed in to the `configure` script if `${build_style}`
    is set to `configure` or `gnu-configure` build methods. By default, prefix
    must be set to `/usr`. In `gnu-configure` packages, some options are already
    set by default: `--prefix=/usr --sysconfdir=/etc --infodir=/usr/share/info --mandir=/usr/share/man --localstatedir=/var`.

*make_cmd*::
    The executable to run at the `build` phase if `${build_style}` is set to
    `configure`, `gnu-configure` or `gnu-makefile` build methods.
    By default set to `make`.

*make_build_args*::
    The arguments to be passed in to `${make_cmd}` at the build phase if
    `${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
    build methods. Unset by default.

*make_install_args*::
    The arguments to be passed in to `${make_cmd}` at the `install-destdir`
    phase if `${build_style}` is set to `configure`, `gnu-configure` or
    `gnu_makefile` build methods. Unset by default.

*make_build_target*::
    The target to be passed in to `${make_cmd}` at the build phase if
    `${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
    build methods. Unset by default (`all` target).

*make_install_target*::
    The target to be passed in to `${make_cmd}` at the `install-destdir` phase
    if `${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
    build methods. By default set to `DESTDIR=${DESTDIR} install`.

*patch_args*::
    The arguments to be passed in to the `patch(1)` command when applying
    patches to the package sources after `do_extract()`. Patches are stored in
    `srcpkgs/<pkgname>/patches` and must be in `-p0` format. By default set to `-Np0`.

*disable_parallel_build*::
    If set the package won't be built in parallel and `XBPS_MAKEJOBS` has no effect.

*keep_libtool_archives*::
    If enabled the `GNU Libtool` archives won't be removed. By default those
    files are always removed automatically.

*skip_extraction*::
    A list of filenames that should not be extracted in the `extract` phase.
    This must match the basename of any url defined in `${distfiles}`.
    Example `skip_extraction="foo-${version}.tar.gz"`.

*force_debug_pkgs*::
    If enabled binary packages with debugging symbols will be generated
    even if `XBPS_DEBUG_PKGS` is disabled in `xbps-src.conf` or in the
    `command line arguments`.

build style scripts
~~~~~~~~~~~~~~~~~~~
The `build_style` variable specifies the build method to build and install a
package. It expects the name of any available script in the
`/usr/share/xbps-src/build_style` directory. Please note that required packages
to execute a `build_style` script must be defined via `hostmakedepends`.

The current list of available `build_style` scripts is the following:

*cmake*::
    For packages that use the CMake build system, configuration arguments
    can be passed in via `configure_args`.

*configure*::
    For packages that use non-GNU configure scripts, at least `--prefix=/usr`
    should be passed in via `configure_args`.

*gnu-configure*::
    For packages that use GNU configure scripts, additional configuration
    arguments can be passed in via `configure_args`.

*gnu-makefile*::
    For packages that use GNU make, build arguments can be passed in via
    `make_build_args` and install arguments via `make_install_args`. The build
    target can be overriden via `make_build_target` and the install target

*meta*::
    For `meta-packages`, i.e packages that only install local files or simply
    depend on additional packages.

*perl-ModuleBuild*::
    For packages that use the Perl
    http://search.cpan.org/~leont/Module-Build-0.4202/lib/Module/Build.pm[Module::Build] method.

*perl*::
    For packages that use the Perl
    http://perldoc.perl.org/ExtUtils/MakeMaker.html[ExtUtils::MakeMaker] build method.

*python-module*::
    For packages that use the Python module build method (setup.py).

*waf3*::
   For packages that use the Python3 `waf` build method with python3.

*waf*::
   For packages that use the Python `waf` method with python2.

Functions
~~~~~~~~~
The following functions can be defined to change the behavior of how the
package is downloaded, compiled and installed.

*do_fetch()*::
    if defined and `distfiles` is not set, use it to fetch the required sources.

*do_extract()*::
    if defined and `distfiles` is not set, use it to extract the required sources.

*post_extract()*::
    Actions to execute after `do_extract()`.

*pre_configure()*::
    Actions to execute after `post_extract()`.

*do_configure()*::
    Actions to execute to configure the package; `${configure_args}` should
    still be passed in if it's a GNU configure script.

*post_configure()*::
    Actions to execute after `do_configure()`.

*pre_build()*::
    Actions to execute after `post_configure()`.

*do_build()*::
    Actions to execute to build the package.

*post_build()*::
    Actions to execute after `do_build()`.

*pre_install()*::
    Actions to execute after `post_build()`.

*do_install()*::
    Actions to execute to install the packages files into the `fake destdir`.

*post_install()*::
    Actions to execute after `do_install()`.

NOTE: A function defined in a template has preference over the same function
defined by a `build_style` script.

Contributing via git
~~~~~~~~~~~~~~~~~~~~

You can fork the `xbps-packages` git repository on github and then set up
a remote to pull in new changes:

----------------------------------------------------------------------
$ git remote add upstream git://github.com/voidlinux/xbps-packages.git
----------------------------------------------------------------------

To pull in new changes from `upstream`:

--------------------------
$ git pull upstream master
--------------------------

Once you've made changes to your `forked` repository you can submit
a github pull request; see
https://help.github.com/articles/fork-a-repo[github's help]
for more information.

For commit messages please use the following rules:

- If you've imported a new package use `New package: <pkgver>`.
- If you've updated a package use `<pkgname>: updated to <version>`.
- If you've removed a package use `<pkgname>: removed ...`.