# The XBPS source packages manual This article contains an exhaustive manual of how to create new source packages for XBPS, the `Void Linux` native packaging system. ## Introduction The `void-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' pkgname="foo" version="1.0" revision=1 build_style=gnu-configure short_desc="A short description max 72 chars" maintainer="name " license="GPL-3" homepage="http://www.foo.org" distfiles="http://www.foo.org/foo-${version}.tar.gz" checksum="fea0a94d4b605894f3e2d5572e3f96e4413bcad3a085aae7367c2cf07908b2ff" ``` The template file contains definitions to download, build and install the package files to a `fake destdir`, and after this a binary package can be generated with the definitions specified on it. 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: `void-packages/srcpkgs/foo/template`. If everything went fine after running $ ./xbps-src pkg a binary package named `foo-1.0_1..xbps` will be generated in the local repository `hostdir/binpkgs`. ### Package build phases Building a package consist of the following phases: - `setup` This phase prepares the environment for building a package. - `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` This phase installs the `package files` into the package destdir `/destdir/-`, via `make install` or any other compatible method. - `pkg` This phase builds the `binary packages` with files stored in the `package destdir` and registers them into the local repository. - `clean` This phase cleans up the package (if defined). `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`). ### Package naming conventions #### Libraries Libraries are packages which provide shared objects (\*.so) in /usr/lib. They should be named like their upstream package name with the following exceptions: - The package is a subpackage of a front end application providing and provides shared objects used by the base package and other third party libraries. In that case it should be prefixed with 'lib'. An exception from that rule is: If an executable is only used for building that package, it moves to the -devel package. Example: wireshark -> subpkg libwireshark Libraries have to be split into two sub packages: and -devel. - `` should only contain those parts of a package which are needed to run a linked program. - `-devel` should contain all files which are needed to compile a package against this package. If the library is a sub package, its corresponding development package should be named `lib-devel` #### Language Modules Language modules are extensions to script or compiled languages. Those packages do not provide any executables themselves, but can be used by other packages written in the same language. The naming convention to those packages is: ``` - ``` If a package provides both, a module and a executable, it should be split into a package providing the executable named `` and the module named `-`. If a package starts with the languages name itself, the language prefix can be dropped. Short names for languages are no valid substitute for the language prefix. Example: python-pam, perl-URI, python-pyside #### Language Bindings Language Bindings are packages which allow programs or libraries to have extensions or plugins written in a certian language. The naming convention to those packages is: ``` - ``` Example: gimp-python, irssi-perl #### Programs Programs put executables under /usr/bin (or in very special cases in other .../bin directories) For those packages the upstream packages name should be used. Remember that in contrast to many other distributions, void doesn't lowercase package names. As a rule of thumb, if the tar.gz of a package contains uppercase letter, then the package name should contain them too; if it doesn't, the package name is lowercase. Programs can be split into program packages and library packages. The program package should be named as describe above. The library package should be prefix with "lib" (see section `Libraries`) ### Global functions The following functions are defined by `xbps-src` and can be used on any template: - *vinstall()* `vinstall []` Installs `file` with the specified `mode` into `targetdir` into the pkg `$DESTDIR` The optional 4th argument can be used to change the `file name`. - *vcopy()* `vcopy ` Copies resursively all files in `pattern` to `targetdir` into the pkg `$DESTDIR` - *vmove()* `vmove ` Moves `pattern` to the specified directory in the pkg `$DESTDIR` - *vmkdir()* `vmkdir []` Creates a directory in the pkg `$DESTDIR`. The 2nd optional argument sets the mode of the directory. - *vbin()* `vbin []` Installs `file` into `usr/bin` in the pkg `$DESTDIR` with the permissions 0755. The optional 2nd argument can be used to change the `file name`. - *vman()* `vman []` Installs `file` as a man page. `vman()` parses the name and determines the section as well as localization. Example mappings: `foo.1` -> `${DESTDIR}/usr/share/man/man1/foo.1` `foo.fr.1` -> `${DESTDIR}/usr/share/man/fr/man1/foo.1` `foo.1p` -> `${DESTDIR}/usr/share/man/man1/foo.1p` - *vdoc()* `vdoc []` Installs `file` into `usr/share/doc/` in the pkg `$DESTDIR`. The optional 2nd argument can be used to change the `file name`. - *vconf()* `vconf []` Installs `file` into `etc` in the pkg `$DESTDIR`. The optional 2nd argument can be used to change the `file name`. - *vsconf()* `vsconf []` Installs `file` into `usr/share/examples/` in the pkg `$DESTDIR`. The optional 2nd argument can be used to change the `file name`. - *vlicense()* `vlicense []` Installs `file` into `usr/share/licenses/` in the pkg `$DESTDIR`. The optional 2nd argument can be used to change the `file name`. - *vsv()* `vsv ` Installs `service` from `${FILESDIR}` to /etc/sv. The service must be a directory containing at least a `supervise` link and a run script. For further informations on how to create a new service directory see [The corresponding section the FAQ](http://smarden.org/runit/faq.html#create). > Shell wildcards must be properly quoted, i.e `vmove "usr/lib/*.a"`. ### 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` Set if the target chroot (masterdir) is ready for chroot builds. - `CROSS_BUILD` Set if `xbps-src` is cross compiling a package. - `DESTDIR` Full path to the fake destdir used by the source pkg, set to `/destdir/${sourcepkg}-${version}`. - `FILESDIR` Full path to the `files` package directory, i.e `srcpkgs/foo/files`. The `files` directory can be used to store additional files to be installed as part of the source package. - `PKGDESTDIR` Full path to the fake destdir used by the `pkg_install()` function in `subpackages`, set to `/destdir/${pkgname}-${version}`. - `XBPS_BUILDDIR` Directory to store the `source code` of the source package being processed, set to `/builddir`. The package `wrksrc` is always stored in this directory such as `${XBPS_BUILDDIR}/${wrksrc}`. - `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. - `XBPS_FETCH_CMD` The utility to fetch files from `ftp`, `http` of `https` servers. ### Available variables #### Mandatory variables The list of mandatory variables for a template: - `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 `. - `pkgname` A string with the package name, matching `srcpkgs/`. - `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, and that will be installed to the master directory. 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, and that will be installed to the master directory. 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"`. - `depends` The list of dependencies required to run the package. These dependencies are not installed to the master directory, rather are only checked if a binary package in the local repository exists to satisfy the required version. 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 `depends="foo blah>=1.0"`. See the `Runtime dependencies` section for more information. - `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 whitespaces. The files must end in `.tar.lzma`, `.tar.xz`, `.txz`, `.tar.bz2`, `.tbz`, `.tar.gz`, `.tgz`, `.gz`, `.bz2`, `.tar` or `.zip`. To define a target filename, append `>filename` to the URL. Example: distfiles="http://foo.org/foo-1.0.tar.gz http://foo.org/bar-1.0.tar.gz>bar.tar.gz" To avoid repetition, several variables for common hosting sites exist: | Variable | Value | |------------------|-------------------------------------------------| | CPAN_SITE | http://cpan.perl.org/modules/by-module | | DEBIAN_SITE | http://ftp.debian.org/debian/pool | | FREEDESKTOP_SITE | http://freedesktop.org/software | | GNOME_SITE | http://ftp.gnome.org/pub/GNOME/sources | | GNU_SITE | http://mirrors.kernel.org/gnu | | KERNEL_SITE | http://www.kernel.org/pub/linux | | MOZILLA_SITE | http://ftp.mozilla.org/pub/mozilla.org | | NONGNU_SITE | http://download.savannah.nongnu.org/releases | | PYPI_SITE | http://pypi.python.org/packages/source | | SOURCEFORGE_SITE | http://downloads.sourceforge.net/sourceforge | | UBUNTU_SITE | http://archive.ubuntu.com/ubuntu/pool | | XORG_HOME | http://xorg.freedesktop.org/wiki/ | | XORG_SITE | http://xorg.freedesktop.org/releases/individual | - `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"` - `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. - `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. By default set to `PREFIX=/usr DESTDIR=${DESTDIR}`. - `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 `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//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"`. - `nodebug` If enabled -dbg packages won't be generated even if `XBPS_DEBUG_PKGS` is set. - `force_debug_pkgs` If enabled binary packages with debugging symbols will be generated even if `XBPS_DEBUG_PKGS` is disabled in `void-packages/etc/conf` or in the `command line arguments`. - `conf_files` A list of configuration files the binary package owns; this expects full paths, and multiple entries can be separated by blanks, i.e: `conf_files="/etc/foo.conf /etc/foo2.conf"`. - `noarch` If set, the binary package is not architecture specific and can be shared by all supported architectures. - `repository` Defines the repository in which the package will be placed. See *Repositories* for a list of valid repositories. - `nostrip` If set, the ELF binaries with debugging symbols won't be stripped. By default all binaries are stripped. - `noshlibprovides` If set, the ELF binaries won't be inspected to collect the provided sonames in shared libraries. - `nocross` If set, cross compilation won't be allowed and will exit immediately. - `python_versions` A white space seperated list of python versions which will be used to build that package. This is only used by the `python-module` build style. - `subpackages` A white space separated list of subpackages (matching `foo_package()`) to override the guessed list. Only use this if a specific order of subpackages is required, otherwise the default would work in most cases. - `broken` If set, building the package won't be allowed because its state is currently broken. - `shlib_provides` A white space separated list of additional sonames the package provides on. This appends to the generated file rather than replacing it. - `shlib_requires` A white space separated list of additional sonames the package requires. This appends to the generated file rather than replacing it. - `reverts` xbps supports a unique feature which allows to downgrade from broken packages automatically. In the `reverts` field one can define a list of broken pkgver the resulting package should revert. This field *must* be defined before `version` and `revision` fields in order to work as expected. The versions defined in `reverts` must be lesser than the one defined in `version`. example: `reverts="2.0_1 2.0_2"` #### Repositories ##### Repositories defined by Branch The global repository takes the name of the current branch, except if the name of the branch is master. Then the resulting repository will be at the global scope. The usage scenario is that the user can update multiple packages in a second branch without polluting his local repository. ##### Package defined Repositories The second way to define a repository is by setting the `repository` variable in a template. This way the maintainer can define repositories for a specific package or a group of packages. This is currently used to distinguish between closed source packages, which are put in the `nonfree` repository and other packages which are at the root-repository. The following repository names are valid: * `nonfree`: Repository for closed source packages. #### Checking for new upstream releases New upstream versions can be automatically checked using `./xbps-src update-check `. In some cases you need to override the sensible defaults by assigning the following variables in a `update` file in the same directory as the relevant `template` file: - `site` contains the URL where the version number is mentioned. If unset, defaults to `homepage` and the directories where `distfiles` reside. - `pkgname` is the package name the default pattern checks for. If unset, defaults to `pkgname` from the template. - `pattern` is a perl-compatible regular expression matching the version number. Anchor the version number using `\K` and `(?=...)`. Example: `pattern='\K[\d.]+(?=)'`, this matches a version number enclosed in `...` tags. - `ignore` is a space-separated list of shell globs that match version numbers which are not taken into account for checking newer versions. Example: `ignore="*b*"` - `version` is the version number used to compare against upstream versions. Example: `version=${version//./_}` ### 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 `void-packages/common/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`. - `fetch` For packages that only fetch files and are installed as is via `do_install()`. - `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 via `make_install_target`. - `meta` For `meta-packages`, i.e packages that only install local files or simply depend on additional packages. This build style does not install dependencies to the root directory, and only checks if a binary package is available in repositories. - `ruby-module` For packages that are ruby modules and are installable via `ruby install.rb`. Additional install arguments can be specified via `make_install_args`. - `perl-ModuleBuild` For packages that use the Perl [Module::Build](http://search.cpan.org/~leont/Module-Build-0.4202/lib/Module/Build.pm) method. - `perl` For packages that use the Perl [ExtUtils::MakeMaker](http://perldoc.perl.org/ExtUtils/MakeMaker.html) build method. - `python-module` For packages that use the Python module build method (setup.py). By default the module will be built for python2. The `python_versions` variable may be defined to set the allowed python versions to be built, i.e: `python_versions="2.7 3.3"`. - `waf3` For packages that use the Python3 `waf` build method with python3. - `waf` For packages that use the Python `waf` method with python2. > If `build_style` is not set, the template must (at least) define a `do_install()` function and optionally more phases via `do_xxx()` functions. ### 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 package files into the `fake destdir`. - `post_install()` Actions to execute after `do_install()`. - `do_clean()` Actions to execute to clean up after a successful package phase. > A function defined in a template has preference over the same function defined by a `build_style` script. ### Build options Some packages might be built with different build options to enable/disable additional features; The XBPS source packages collection allows you to do this with some simple tweaks to the `template` file. The following variables may be set to allow package build options: - `build_options` Sets the build options supported by the source package. - `build_options_default` Sets the default build options to be used by the source package. - `desc_option_