# 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.
*Table of Contents*
* [Introduction](#Introduction)
* [Quality Requirements](#quality_requirements)
* [Package build phases](#buildphase)
* [Package naming conventions](#namingconvention)
* [Libraries](#libs)
* [Language Modules](#language_modules)
* [Language Bindings](#language_bindings)
* [Programs](#programs)
* [Global functions](#global_funcs)
* [Global variables](#global_vars)
* [Available variables](#available_vars)
* [Mandatory variables](#mandatory_vars)
* [Optional variables](#optional_vars)
* [About the depends variables](#explain_depends)
* [Repositories](#repositories)
* [Repositories defined by Branch](#repo_by_branch)
* [Package defined repositories](#pkg_defined_repo)
* [Checking for new upstream releases](#updates)
* [Handling patches](#patches)
* [Build style scripts](#build_scripts)
* [Build helper scripts](#build_helper)
* [Functions](#functions)
* [Build options](#build_options)
* [Runtime dependencies](#deps_runtime)
* [INSTALL and REMOVE files](#install_remove_files)
* [INSTALL.msg and REMOVE.msg files](#install_remove_files_msg)
* [Creating system accounts/groups at runtime](#runtime_account_creation)
* [Writing runit services](#writing_runit_services)
* [32bit packages](#32bit_pkgs)
* [Subpackages](#pkgs_sub)
* [Development packages](#pkgs_development)
* [Data packages](#pkgs_data)
* [Documentation packages](#pkgs_documentation)
* [Python packages](#pkgs_python)
* [Go packages](#pkgs_go)
* [Haskell packages](#pkgs_haskell)
* [Font packages](#pkgs_font)
* [Removing a package](#pkg_remove)
* [XBPS Triggers](#xbps_triggers)
* [appstream-cache](#triggers_appstream_cache)
* [binfmts](#triggers_binfmts)
* [dkms](#triggers_dkms)
* [gconf-schemas](#triggers_gconf_schemas)
* [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders)
* [gio-modules](#triggers_gio_modules)
* [gettings-schemas](#triggers_gsettings_schemas)
* [gtk-icon-cache](#triggers_gtk_icon_cache)
* [gtk-immodules](#triggers_gtk_immodules)
* [gtk-pixbuf-loaders](#triggers_gtk_pixbuf_loaders)
* [gtk3-immodules](#triggers_gtk3_immodules)
* [hwdb.d-dir](#triggers_hwdb.d_dir)
* [info-files](#triggers_info_files)
* [kernel-hooks](#triggers_kernel_hooks)
* [mimedb](#triggers_mimedb)
* [mkdirs](#triggers_mkdirs)
* [pango-modules](#triggers_pango_module)
* [pycompile](#triggers_pycompile)
* [register-shell](#triggers_register_shell)
* [system-accounts](#triggers_system_accounts)
* [texmf-dist](#triggers_texmf_dist)
* [update-desktopdb](#triggers_update_desktopdb)
* [x11-fonts](#triggers_x11_fonts)
* [xml-catalog](#triggers_xml_catalog)
* [Notes](#notes)
* [Contributing via git](#contributing)
* [Help](#help)
## 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.
By convention, all templates start with a comment briefly explaining what they
are. In addition, pkgname and version can't have any characters in them that
would require them to be quoted, so they are not quoted.
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.0-or-later"
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`, Example: `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`.
### Quality Requirements
To be included in the Void repository, software must meet at least one
of the following requirements. Exceptions to the list are possible,
and might be accepted, but are extremely unlikely. If you believe you have an
exception, start a PR and make an argument for why that particular piece of
software, while not meeting any of the following requirements, is a good candidate for
the Void packages system.
1. System: The software should be installed system-wide, not per-user.
1. Compiled: The software needs to be compiled before being used, even if it is
software that is not needed by the whole system.
1. Required: Another package either within the repository or pending inclusion
requires the package.
In particular, new themes and small shell scripts are highly unlikely
to be accepted. New fonts are welcome if they provide value beyond
aesthetics (e.g. they contain glyphs for a script missing in already
packaged fonts).
Browser forks, including those based on Chromium and Firefox, are generally not
accepted. Such forks require heavy patching, maintenance and hours of build time.
### 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`.
- `patch` This phase applies all patches in the patches directory of the package and
can be used to perform other operations before configuring the 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.
- `check` This optional phase checks the result of the `build` phase for example by running `make -k check`.
- `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 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, python3-pyside2
#### Language Bindings
Language Bindings are packages which allow programs or libraries to have
extensions or plugins written in a certain 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 described above. The library package should be
prefixed 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` in the pkg `$DESTDIR`.
The optional 4th argument can be used to change the `file name`.
- *vcopy()* `vcopy `
Copies recursively all files in `pattern` to `targetdir` in 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. Also transparently
converts gzipped (.gz) and bzipped (.bz2) manpages into plaintext.
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`
- `foo.1.gz` -> `${DESTDIR}/usr/share/man/man1/foo.1`
- `foo.1.bz2` -> `${DESTDIR}/usr/share/man/man1/foo.1`
- *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`. See [license](#var_license) for when to use it.
- *vsv()* `vsv `
Installs `service` from `${FILESDIR}` to /etc/sv. The service must
be a directory containing at least a run script. Note the `supervise`
symlink will be created automatically by `vsv` and that the run script
is automatically made executable by this function.
For further information on how to create a new service directory see
[The corresponding section the FAQ](http://smarden.org/runit/faq.html#create).
- *vsed()* `vsed -i -e `
Wrapper around sed that checks sha256sum of a file before and after running
the sed command to detect cases in which the sed call didn't change anything.
Takes any arbitrary amount of files and regexes by calling `-i file` and
`-e regex` repeatedly, at least one file and one regex must be specified.
Note that vsed will call the sed command for every regex specified against
every file specified, in the order that they are given.
- *vcompletion()* ` []`
Installs shell completion from `file` for `command`, in the correct location
and with the appropriate filename for `shell`. If `command` isn't specified,
it will default to `pkgname`. The `shell` argument can be one of `bash`,
`fish` or `zsh`.
> Shell wildcards must be properly quoted, Example: `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 `xbps-uhelper arch`.
- `XBPS_ENDIAN` The machine's endianness ("le" or "be").
- `XBPS_LIBC` The machine's C library ("glibc" or "musl").
- `XBPS_WORDSIZE` The machine's word size in bits (32 or 64).
- `XBPS_NO_ATOMIC8` The machine lacks native 64-bit atomics (needs libatomic emulation).
- `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_TARGET_ENDIAN` The target machine's endianness ("le" or "be").
- `XBPS_TARGET_LIBC` The target machine's C library ("glibc" or "musl").
- `XBPS_TARGET_WORDSIZE` The target machine's word size in bits (32 or 64).
- `XBPS_TARGET_NO_ATOMIC8` The target machine lacks native 64-bit atomics (needs libatomic emulation).
- `XBPS_FETCH_CMD` The utility to fetch files from `ftp`, `http` of `https` servers.
- `XBPS_WRAPPERDIR` Full path to where xbps-src's wrappers for utilities are stored.
- `XBPS_CROSS_BASE` Full path to where cross-compile dependencies are installed, varies according to the target architecture triplet. i.e `aarch64` -> `aarch64-unknown-linux-gnu`.
- `XBPS_RUST_TARGET` The target architecture triplet used by `rustc` and `cargo`.
### Available variables
#### Mandatory variables
The list of mandatory variables for a template:
- `homepage` A string pointing to the `upstream` homepage.
-
`license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
`Public Domain`, or string prefixed with `custom:` for other licenses.
Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, custom:Hugware`.
Empty meta-packages that don't include any files
which thus have and require no license, should have set
`license="BSD-2-Clause"`.
Note: `MIT`, `BSD`, `ISC` and custom licenses
require the license file to be supplied with the binary package.
- `maintainer` A string in the form of `name `. The
email for this field must be a valid email that you can be reached
at. Packages using `users.noreply.github.com` emails will not be
accepted.
- `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 or underscore
and at least one digit is required. Shell's variable substition usage is not allowed.
#### Optional variables
- `hostmakedepends` The list of `host` dependencies required to build the package, and
that will be installed to the master directory. There is no need to specify a version
because the current version in srcpkgs will always be required.
Example: `hostmakedepends="foo blah"`.
- `makedepends` The list of `target` dependencies required to build the package, and that
will be installed to the master directory. There is no need to specify a version
because the current version in srcpkgs will always be required.
Example: `makedepends="foo blah"`.
- `checkdepends` The list of dependencies required to run the package checks, i.e.
the script or make rule specified in the template's `do_check()` function.
Example: `checkdepends="gtest"`.
- `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.
- `conflicts` An optional list of packages conflicting with this package.
Conflicts 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: `conflicts="foo blah>=0.42.3"`.
- `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 | https://cpan.perl.org/modules/by-module |
| DEBIAN_SITE | http://ftp.debian.org/debian/pool |
| FREEDESKTOP_SITE | https://freedesktop.org/software |
| GNOME_SITE | https://ftp.gnome.org/pub/GNOME/sources |
| GNU_SITE | https://ftp.gnu.org/gnu |
| KERNEL_SITE | https://www.kernel.org/pub/linux |
| MOZILLA_SITE | https://ftp.mozilla.org/pub |
| NONGNU_SITE | https://download.savannah.nongnu.org/releases |
| PYPI_SITE | https://files.pythonhosted.org/packages/source |
| SOURCEFORGE_SITE | https://downloads.sourceforge.net/sourceforge |
| UBUNTU_SITE | http://archive.ubuntu.com/ubuntu/pool |
| XORG_SITE | https://www.x.org/releases/individual |
| KDE_SITE | https://download.kde.org/stable |
- `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"`
If a distfile changes its checksum for every download because it is packaged
on the fly on the server, like e.g. snapshot tarballs from any of the
`https://*.googlesource.com/` sites, the checksum of the `archive contents`
can be specified by prepending a commercial at (@).
For tarballs you can find the contents checksum by using the command
`tar xf --to-stdout | sha256sum`.
- `wrksrc` The directory name where the package sources are extracted, by default
set to `${pkgname}-${version}`. If the top level directory of a package's `distfile` is different from the default, `wrksrc` must be set to the top level directory name inside the archive.
- `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`.
- `build_style` This specifies the `build method` for a package. Read below to know more
about the available package `build methods` or effect of leaving this not set.
- `build_helper` Whitespace-separated list of files in `common/build-helper` to be
sourced and its variables be made available on the template. i.e. `build_helper="rust"`.
- `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_check_args` The arguments to be passed in to `${make_cmd}` at the check 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_check_target` The target to be passed in to `${make_cmd}` at the check phase if
`${build_style}` is set to `configure`, `gnu-configure` or `gnu-makefile`
build methods. By default set to `check`.
- `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 during `do_patch()`. 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.
- `conf_files` A list of configuration files the binary package owns; this expects full
paths, wildcards will be extended, and multiple entries can be separated by blanks.
Example: `conf_files="/etc/foo.conf /etc/foo2.conf /etc/foo/*.conf"`.
- `mutable_files` A list of files the binary package owns, with the expectation
that those files will be changed. These act a lot like `conf_files` but
without the assumption that a human will edit them.
- `make_dirs` A list of entries defining directories and permissions to be
created at install time. Each entry should be space separated, and will
itself contain spaces. `make_dirs="/dir 0750 user group"`. User and group and
mode are required on every line, even if they are `755 root root`. By
convention, there is only one entry of `dir perms user group` per line.
- `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.
- `nostrip_files` White-space separated list of ELF binaries that won't be stripped of
debugging symbols.
- `noshlibprovides` If set, the ELF binaries won't be inspected to collect the provided
sonames in shared libraries.
- `noverifyrdeps` If set, the ELF binaries and shared libaries won't be inspected to collect
their reverse dependencies. You need to specify all dependencies in the `depends` when you
need to set this.
- `skiprdeps` White space separated list of filenames specified by their absolute path in
the `$DESTDIR` which will not be scanned for runtime dependencies. This may be useful to
skip files which are not meant to be run or loaded on the host but are to be sent to some
target device or emulation.
- `nocross` If set, cross compilation won't be allowed and will exit immediately.
This should be set to a string describing why it fails, or a link to a travis
buildlog demonstrating the failure.
- `restricted` If set, xbps-src will refuse to build the package unless
`etc/conf` has `XBPS_ALLOW_RESTRICTED=yes`. The primary builders for Void
Linux do not have this setting, so the primary repositories will not have any
restricted package. This is useful for packages where the license forbids
redistribution.
- `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.
This should be set to a string describing why it is broken, or a link to a travis
buildlog demonstrating the failure.
- `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.
- `nopie` Only needs to be set to something to make active, disables building the package with hardening
features (PIE, relro, etc). Not necessary for most packages.
- `nopie_files` White-space seperated list of ELF binaries that won't be checked
for PIE.
- `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 bigger than the one defined in `version`.
Example:
```
reverts="2.0_1 2.0_2"
version=1.9
revision=2
```
- `alternatives` A white space separated list of supported alternatives the package provides.
A list is composed of three components separated by a colon: group, symlink and target.
Example: `alternatives="vi:/usr/bin/vi:/usr/bin/nvi ex:/usr/bin/ex:/usr/bin/nvi-ex"`.
- `font_dirs` A white space separated list of directories specified by an absolute path where a
font package installs its fonts.
It is used in the `x11-fonts` xbps-trigger to rebuild the font cache during install/removal
of the package.
Example: `font_dirs="/usr/share/fonts/TTF /usr/share/fonts/X11/misc"`
- `dkms_modules` A white space separated list of Dynamic Kernel Module Support (dkms) modules
that will be installed and removed by the `dkms` xbps-trigger with the install/removal of the
package.
The format is a white space separated pair of strings that represent the name of the module,
most of the time `pkgname`, and the version of the module, most of the time `version`.
Example: `dkms_modules="$pkgname $version zfs 4.14"`
- `register_shell` A white space separated list of shells defined by absolute path to be
registered into the system shells database. It is used by the `register-shell` trigger.
Example: `register_shell="/bin/tcsh /bin/csh"`
- `tags` A white space separated list of tags (categories) that are registered into the
package metadata and can be queried with `xbps-query` by users.
Example for qutebrowser: `tags="browser chromium-based qt5 python3"`
- `perl_configure_dirs` A white space separate list of directories relative to `wrksrc`
that contain Makefile.PL files that need to be processes for the package to work. It is
used in the perl-module build_style and has no use outside of it.
Example: `perl_configure_dirs="blob/bob foo/blah"`
- `preserve` If set, files owned by the package in the system are not removed when
the package is updated, reinstalled or removed. This is mostly useful for kernel packages
that shouldn't remove the kernel files when they are removed in case it might break the
user's booting and module loading. Otherwise in the majority of cases it should not be
used.
- `fetch_cmd` Executable to be used to fetch URLs in `distfiles` during the `do_fetch` phase.
- `archs` Whitespace separated list of architectures that a package can be
built for, available architectures can be found under `common/cross-profiles`
alongside the `noarch` value for packages that do not contain any machine code.
In general, `archs` should only be set if the upstream software explicitly targets
certain architectures or there is a compelling reason why the software should not be
available on some supported architectures.
Examples:
```
# Build package only for musl architectures
archs="*-musl"
# Build package for x86_64-musl and any non-musl architecture
archs="x86_64-musl ~*-musl"
# Default value (all arches)
archs="*"
# Packages that do not depend on architecture-specific objects
archs=noarch
```
#### About the many types of `depends` variable.
So far we have listed four types of `depends`, there are `hostmakedepends`,
`makedepends`, `checkdepends` and plain old `depends`.To understand the difference
between them, understand this: Void Linux cross compiles for many arches.
Sometimes in a build process, certain programs must be run, for example `yacc`, or the
compiler itself for a C program. Those programs get put in `hostmakedepends`.
When the build runs, those will be installed on the host to help the build
complete.
Then there are those things for which a package either links against or
includes header files. These are `makedepends`, and regardless of the
architecture of the build machine, the architecture of the target machine must
be used. Typically the `makedepends` will be the only one of the three types of
`depends` to include `-devel` packages, and typically only `-devel` packages.
Then there are those things that are required for a package to run its testsuite
`dejagnu` or libraries it must link to when building test binaries like `cmocka`.
These are `checkdepends` and they are installed like they are part of `makedepends`.
the difference is that they are only installed when `XBPS_CHECK_PKGS` is defined.
The final variable, `depends`, is for those things the package needs at
runtime and without which is unusable, and that xbps can't auto-detect.
These are not all the packages the package needs at runtime, but only those
that are not linked against. This variable is most useful for non-compiled
programs.
Finally, as a general rule, if something compiles the exact same way whether or
not you add a particular package to `makedepends` or `hostmakedepends`, it
shouldn't be added.
#### 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//./_}`
- `single_directory` can be set to disable
detecting directory containing one version of sources in url,
then searching new version in adjacent directories.
- `vdprefix` is a perl-compatible regular expression matching
part that precedes numeric part of version directory
in url. Defaults to `(|v|$pkgname)[-_.]*`.
- `vdsuffix` is a perl-compatible regular expression matching
part that follows numeric part of version directory
in url. Defaults to `(|\.x)`.
### Handling patches
Sometimes software needs to be patched, most commonly to fix bugs that have
been found or to fix compilation with new software.
To handle this, xbps-src has patching functionality. It will look for all files
that match the glob `srcpkgs/$pkgname/patches/*.{diff,patch}` and will
automatically apply all files it finds using `patch(1)` with `-Np0`. This happens
during the `do_patch()` phase. The variable `PATCHESDIR` is
available in the template, pointing to the `patches` directory.
The patching behaviour can be changed in the following ways:
- A file called `series` can be created in the `patches` directory with a newline
separated list of patches to be applied in the order presented. When present
xbps-src will only apply patches named in the `series` file.
- A file with the same name as one of the patches but with `.args` as extension can
be used to set the args passed to `patch(1)`. As an example, if `foo.patch` requires
special arguments to be passed to `patch(1)` that can't be used when applying other
patches, `foo.patch.args` can be created containing those args.
### 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:
- If `build_style` is not set, the template must (at least) define
`do_install()` function and optionally more build phases such as
`do_configure()`, `do_build()`, etc., and may overwrite default `do_fetch()` and
`do_extract()` that fetch and extract files defined in `distfiles` variable.
- `cargo` For packages written in rust that use Cargo for building.
Configuration arguments (such as `--features`) can be defined in the variable
`configure_args` and are passed to cargo during `do_build`.
- `cmake` For packages that use the CMake build system, configuration arguments
can be passed in via `configure_args`. The `cmake_builddir` variable may be
defined to specify the directory for building under `build_wrksrc` instead of
the default `build`.
- `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 overridden via `make_build_target` and the install target
via `make_install_target`. This build style tries to compensate for makefiles
that do not respect environment variables, so well written makefiles, those
that do such things as append (`+=`) to variables, should have `make_use_env`
set in the body of the template.
- `go` For programs written in Go that follow the standard package
structure. The variable `go_import_path` must be set to the package's
import path, e.g. `github.com/github/hub` for the `hub` program. If
the variable `go_get` is set to `yes`, the package will be
downloaded with `go get`. Otherwise (the default) it's expected that
the distfile contains the package. In both cases, dependencies will
be downloaded with `go get`.
- `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.
- `R-cran` For packages that are available on The Comprehensive R Archive
Network (CRAN). The build style requires the `pkgname` to start with
`R-cran-` and any dashes (`-`) in the CRAN-given version to be replaced
with the character `r` in the `version` variable. The `distfiles`
location will automatically be set as well as the package made to depend
on `R`.
- `gemspec` For packages that use
[gemspec](https://guides.rubygems.org/specification-reference/) files for building a ruby
gem and then installing it. The gem command can be overridden by `gem_cmd`. `configure_args`
can be used to pass arguments during compilation. If your package does not make use of compiled
extensions consider using the `gem` build style instead.
- `gem` For packages that are installed using gems from [RubyGems](https://rubygems.org/).
The gem command can be overridden by `gem_cmd`. `archs` is set to `noarch` unconditionally
and `distfiles` is set by the build style if the template does not do so. If your gem
provides extensions which must be compiled consider using the `gemspec` build style instead.
- `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](https://metacpan.org/pod/Module::Build) method.
- `perl-module` For packages that use the Perl
[ExtUtils::MakeMaker](http://perldoc.perl.org/ExtUtils/MakeMaker.html) build method.
- `raku-dist` For packages that use the Raku `raku-install-dist` build method with rakudo.
- `waf3` For packages that use the Python3 `waf` build method with python3.
- `waf` For packages that use the Python `waf` method with python2.
- `slashpackage` For packages that use the /package hierarchy and package/compile to build,
such as `daemontools` or any `djb` software.
- `qmake` For packages that use Qt4/Qt5 qmake profiles (`*.pro`), qmake arguments
for the configure phase can be passed in via `configure_args`, make build arguments can
be passed in via `make_build_args` and install arguments via `make_install_args`. The build
target can be overridden via `make_build_target` and the install target
via `make_install_target`.
- `meson` For packages that use the Meson Build system, configuration options can be passed
via `configure_args`, the meson command can be overridden by `meson_cmd` and the location of
the out of source build by `meson_builddir`
For packages that use the Python module build method (`setup.py`), you
can choose one of the following:
- `python-module` to build *both* Python 2.x and 3.x modules
- `python2-module` to build Python 2.x only modules
- `python3-module` to build Python 3.x only modules
Environment variables for a specific `build_style` can be declared in a filename
matching the `build_style` name, Example:
`common/environment/build-style/gnu-configure.sh`
- `texmf` For texmf zip/tarballs that need to go into /usr/share/texmf-dist. Includes
duplicates handling.
### build helper scripts
The `build_helper` variable specifies shell snippets to be sourced that will create a
suitable environment for working with certain sets of packages.
The current list of available `build_helper` scripts is the following:
- `rust` specifies environment variables required for cross-compiling crates via cargo and
for compiling cargo -sys crates.
- `gir` specifies dependencies for native and cross builds to deal with
GObject Introspection. The following variables may be set in the template to handle
cross builds which require additional hinting or exhibit problems. `GIR_EXTRA_LIBS_PATH` defines
additional paths to be searched when linking target binaries to be introspected.
`GIR_EXTRA_OPTIONS` defines additional options for the `g-ir-scanner-qemuwrapper` calling
`qemu--static` when running the target binary. You can for example specify
`GIR_EXTRA_OPTIONS="-strace"` to see a trace of what happens when running that binary.
- `qemu` sets additional variables for the `cmake` and `meson` build styles to allow
executing cross-compiled binaries inside qemu.
It sets `CMAKE_CROSSCOMPILING_EMULATOR` for cmake and `exe_wrapper` for meson
to `qemu--static` and `QEMU_LD_PREFIX` to `XBPS_CROSS_BASE`.
It also creates the `vtargetrun` function to wrap commands in a call to
`qemu--static` for the target architecture.
- `qmake` creates the `qt.conf` configuration file (cf. `qmake` `build_style`)
needed for cross builds and a qmake-wrapper to make `qmake` use this configuration.
This aims to fix cross-builds for when the build-style is mixed: e.g. when in a
`gnu-configure` style the configure script calls `qmake` or a `Makefile` in
`gnu-makefile` style, respectively.
### Functions
The following functions can be defined to change the behavior of how the
package is downloaded, compiled and installed.
- `pre_fetch()` Actions to execute before `do_fetch()`.
- `do_fetch()` if defined and `distfiles` is not set, use it to fetch the required sources.
- `post_fetch()` Actions to execute after `do_fetch()`.
- `pre_extract()` Actions to execute after `post_fetch()`.
- `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_patch()` Actions to execute after `post_extract()`.
- `do_patch()` if defined use it to prepare the build environment and run hooks to apply patches.
- `post_patch()` Actions to execute after `do_patch()`.
- `pre_configure()` Actions to execute after `post_patch()`.
- `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.
Current working directory for functions is set as follows:
- For pre_fetch, pre_extract, do_clean: ``.
- For do_fetch, post_fetch: `XBPS_BUILDDIR`.
- For do_extract, post_extract, pre_patch, do_patch, post_patch: `wrksrc`.
- For pre_configure through post_install: `build_wrksrc`
if it is defined, otherwise `wrksrc`.
### 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_