Manual

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

The void-packages repository contains all the recipes to download, compile and build binary packages for Void Linux. These source package files are called templates.

The template files are shell scripts that define variables and functions to be processed by xbps-src, the package builder, to generate binary packages. The shell used by xbps-src is GNU bash; xbps-src doesn't aim to be compatible with POSIX sh.

By convention, all templates start with a comment saying that it is a template file for a certain package. Most of the lines should be kept under 80 columns; variables that list many values can be split into new lines, with the continuation in the next line indented by one space.

A simple template example is as follows:

# Template file for 'foo'
pkgname=foo
version=1.0
revision=1
build_style=gnu-configure
short_desc="Package description, no more than 72 characters"
maintainer="name <email>"
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 <pkgname>

a binary package named foo-1.0_1.<arch>.xbps will be generated in the local repository hostdir/binpkgs.

Package build phases

Building a package consist of the following phases:

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:

Example: wireshark -> subpkg libwireshark

Libraries have to be split into two sub packages: <name> and <name>-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:

<language>-<name>

If a package provides both, a module and a executable, it should be split into a package providing the executable named <name> and the module named <language>-<name>. 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: 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:

<name>-<language>

Example: gimp-python3, 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:

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:

Available variables

Mandatory variables

The list of mandatory variables for a template:

pkgname and version are forbidden to contain special characters. Hence, they don't need to be quoted, and by convention, they shouldn't be.

Optional variables

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 <tarball.ext> --to-stdout | sha256sum.

A special value noarch used to be available, but has since been removed.

About the many types of depends variables

So far, we have listed four types of depends variables: hostmakedepends, makedepends, checkdepends and depends. These different kinds of variables are necessary because xbps-src supports cross compilation and to avoid installing unnecessary packages in the build environment.

During a build process, there are programs that must be run on the host, such as yacc or the C compiler. The packages that contain these programs should be listed in hostmakedepends, and will be installed on the host when building the target package. Some of these packages are dependencies of the base-chroot package and don't need to be listed. It is possible that some of the programs necessary to build a project are located in -devel packages.

The target package can also depend on other packages for libraries to link against or header files. These packages should be listed in makedepends and will match the target architecture, regardless of the architecture of the build machine. Typically, makedepends will contain mainly -devel packages.

Furthermore, if XBPS_CHECK_PKGS is set or the -Q option is passed to xbps-src, the target package might require specific dependencies or libraries that are linked into its test binaries to run its test suite. These dependencies should be listed in checkdepends and will be installed as if they were part of hostmakedepends. Some dependencies that can be included in checkdepends are:

Lastly, a package may require certain dependencies at runtime, without which it is unusable. These dependencies, when they aren't detected automatically by XBPS, should be listed in depends.

Libraries linked by ELF objects are detected automatically by xbps-src, hence they must not be specified in templates via depends. This variable should list:

The runtime dependencies for ELF objects are detected by checking which SONAMEs they require and then the SONAMEs are mapped to a binary package name with a minimal required version. The common/shlibs file sets up the <SONAME> <pkgname>>=<version> mappings.

For example the foo-1.0_1 package provides the libfoo.so.1 SONAME and software requiring this library will link to libfoo.so.1; the resulting binary package will have a run-time dependency on foo>=1.0_1 package as specified in common/shlibs:

# common/shlibs
...
libfoo.so.1 foo-1.0_1
...

Dependencies declared via depends are not installed to the master directory, rather they are only checked if they exist as binary packages, and are built automatically by xbps-src if the specified version is not in the local repository.

As a special case, virtual dependencies may be specified as runtime dependencies in the depends template variable. Several different packages can provide common functionality by declaring a virtual name and version in the provides template variable (e.g. provides="vpkg-0.1_1"). Packages that rely on the common functionality without concern for the specific provider can declare a dependency on the virtual package name with the prefix virtual? (e.g., depends="virtual?vpkg-0.1_1"). When a package is built by xbps-src, providers for any virtual packages will be confirmed to exist and will be built if necessary. A map from virtual packages to their default providers is defined in etc/defaults.virtual. Individual mappings can be overridden by local preferences in etc/virtual. Comments in etc/defaults.virtual provide more information on this map.

Finally, as a general rule, if a package is built the exact same way whether or not a particular package is present in makedepends or hostmakedepends, that package shouldn't be added as a build time dependency.

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 their 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 certain classes of packages.

The following repository names are valid:

Checking for new upstream releases

New upstream versions can be automatically checked using ./xbps-src update-check <pkgname>. 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:

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 -Np1. 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:

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:

For packages that use the Python module build method (setup.py or PEP 517), you can choose one of the following:

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`

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:

Functions

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

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:

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:

After defining those required variables, you can check for the build_option_<option> variable to know if it has been set and adapt the source package accordingly. Additionally, the following functions are available:

The following example shows how to change a source package that uses GNU configure to enable a new build option to support PNG images:

# Template file for 'foo'
pkgname=foo
version=1.0
revision=1
build_style=gnu-configure
configure_args="... $(vopt_with png)"
makedepends="... $(vopt_if png libpng-devel)"
...

# Package build options
build_options="png"
desc_option_png="Enable support for PNG images"

# To build the package by default with the `png` option:
#
# build_options_default="png"

...

The supported build options for a source package can be shown with xbps-src:

$ ./xbps-src show-options foo

Build options can be enabled with the -o flag of xbps-src:

$ ./xbps-src -o option,option1 <cmd> foo

Build options can be disabled by prefixing them with ~:

$ ./xbps-src -o ~option,~option1 <cmd> foo

Both ways can be used together to enable and/or disable multiple options at the same time with xbps-src:

$ ./xbps-src -o option,~option1,~option2 <cmd> foo

The build options can also be shown for binary packages via xbps-query(8):

$ xbps-query -R --property=build-options foo

Permanent global package build options can be set via XBPS_PKG_OPTIONS variable in the etc/conf configuration file. Per package build options can be set via XBPS_PKG_OPTIONS_<pkgname>.

NOTE: if pkgname contains dashes, those should be replaced by underscores Example: XBPS_PKG_OPTIONS_xorg_server=opt.

The list of supported package build options and its description is defined in the common/options.description file.

INSTALL and REMOVE files

The INSTALL and REMOVE shell snippets can be used to execute certain actions at a specified stage when a binary package is installed, updated or removed. There are some variables that are always set by xbps when the scripts are executed:

An example of how an INSTALL or REMOVE script shall be created is shown below:

# INSTALL
case "$ACTION" in
pre)
    # Actions to execute before the package files are unpacked.
    ...
    ;;
post)
    if [ "$UPDATE" = "yes" ]; then
        # actions to execute if package is being updated.
        ...
    else
        # actions to execute if package is being installed.
        ...
    fi
    ;;
esac

subpackages can also have their own INSTALL and REMOVE files, simply create them as srcpkgs/<pkgname>/<subpkg>.INSTALL or srcpkgs/<pkgname>/<subpkg>.REMOVE respectively.

NOTE: always use paths relative to the current working directory, otherwise if the scripts cannot be executed via chroot(2) won't work correctly.

NOTE: do not use INSTALL/REMOVE scripts to print messages, see the next section for more information.

INSTALL.msg and REMOVE.msg files

The INSTALL.msg and REMOVE.msg files can be used to print a message at post-install or pre-remove time, respectively.

Ideally those files should not exceed 80 chars per line.

subpackages can also have their own INSTALL.msg and REMOVE.msg files, simply create them as srcpkgs/<pkgname>/<subpkg>.INSTALL.msg or srcpkgs/<pkgname>/<subpkg>.REMOVE.msg respectively.

This should only be used for critical messages, like warning users of breaking changes.

Creating system accounts/groups at runtime

There's a trigger along with some variables that are specifically to create system users and groups when the binary package is being configured. The following variables can be used for this purpose:

The system user is created by using a dynamically allocated uid/gid in your system and it's created as a system account, unless the uid is set. A new group will be created for the specified system account and used exclusively for this purpose.

System accounts and groups must be prefixed with an underscore to prevent clashing with names of user accounts.

NOTE: The underscore policy does not apply to old packages, due to the inevitable breakage of changing the username only new packages should follow it.

Writing runit services

Void Linux uses runit for booting and supervision of services.

Most information about how to write them can be found in their FAQ. The following are guidelines specific to Void Linux on how to write services.

If the service daemon supports CLI flags, consider adding support for changing it via the OPTS variable by reading a file called conf in the same directory as the daemon.

#!/bin/sh
[ -r conf ] && . ./conf
exec daemon ${OPTS:- --flag-enabled-by-default}

If the service requires the creation of a directory under /run or its link /var/run for storing runtime information (like Pidfiles) write it into the service file. It is advised to use install if you need to create it with specific permissions instead of mkdir -p.

#!/bin/sh
install -d -m0700 /run/foo
exec foo
#!/bin/sh
install -d -m0700 -o bar -g bar /run/bar
exec bar

If the service requires directories in parts of the system that are not generally in temporary filesystems. Then use the make_dirs variable in the template to create those directories when the package is installed.

If the package installs a systemd service file or other unit, leave it in place as a reference point so long as including it has no negative side effects.

Examples of when not to install systemd units:

  1. When doing so changes runtime behavior of the packaged software.
  2. When it is done via a compile time flag that also changes build dependencies.

32bit packages

32bit packages are built automatically when the builder is x86 (32bit), but there are some variables that can change the behavior:

Subpackages

In the example shown above just a binary package is generated, but with some simple tweaks multiple binary packages can be generated from a single template/build, this is called subpackages.

To create additional subpackages the template must define a new function with this naming: <subpkgname>_package(), Example:

# 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 <email>"
license="GPL-3.0-or-later"
homepage="http://www.foo.org"
distfiles="http://www.foo.org/foo-${version}.tar.gz"
checksum="fea0a94d4b605894f3e2d5572e3f96e4413bcad3a085aae7367c2cf07908b2ff"

# foo-devel is a subpkg
foo-devel_package() {
    short_desc+=" - development files"
    depends="${sourcepkg}>=${version}_${revision}"
    pkg_install() {
        vmove usr/include
        vmove "usr/lib/*.a"
        vmove "usr/lib/*.so"
        vmove usr/lib/pkgconfig
    }
}

All subpackages need an additional symlink to the main pkg, otherwise dependencies requiring those packages won't find its template Example:

 /srcpkgs
  |- foo <- directory (main pkg)
  |  |- template
  |- foo-devel <- symlink to `foo`

The main package should specify all required build dependencies to be able to build all subpackages defined in the template.

An important point of subpackages is that they are processed after the main package has run its install phase. The pkg_install() function specified on them commonly is used to move files from the main package destdir to the subpackage destdir.

The helper functions vinstall, vmkdir, vcopy and vmove are just wrappers that simplify the process of creating, copying and moving files/directories between the main package destdir ($DESTDIR) to the subpackage destdir ($PKGDESTDIR).

Subpackages are processed always in alphabetical order; To force a custom order, the subpackages variable can be declared with the wanted order.

Some package classes

Development packages

A development package, commonly generated as a subpackage, shall only contain files required for development, that is, headers, static libraries, shared library symlinks, pkg-config files, API documentation or any other script that is only useful when developing for the target software.

A development package should depend on packages that are required to link against the provided shared libraries, i.e if libfoo provides the libfoo.so.2 shared library and the linking needs -lbar, the package providing the libbar shared library should be added as a dependency; and most likely it shall depend on its development package.

If a development package provides a pkg-config file, you should verify what dependencies the package needs for dynamic or static linking, and add the appropriate development packages as dependencies.

Development packages for the C and C++ languages usually vmove the following subset of files from the main package:

Data packages

Another common subpackage type is the -data subpackage. This subpackage type used to split architecture independent, big(ger) or huge amounts of data from a package's main and architecture dependent part. It is up to you to decide, if a -data subpackage makes sense for your package. This type is common for games (graphics, sound and music), part libraries (CAD) or card material (maps). The main package must then have depends="${pkgname}-data-${version}_${revision}", possibly in addition to other, non-automatic depends.

Documentation packages

Packages intended for user interaction do not always unconditionally require their documentation part. A user who does not want to e.g. develop with Qt5 will not need to install the (huge) qt5-doc package. An expert may not need it or opt to use an online version.

In general a -doc package is useful, if the main package can be used both with or without documentation and the size of the documentation isn't really small. The base package and the -devel subpackage should be kept small so that when building packages depending on a specific package there is no need to install large amounts of documentation for no reason. Thus the size of the documentation part should be your guidance to decide whether or not to split off a -doc subpackage.

Python packages

Python packages should be built with the python3-module build style, if possible. This sets some environment variables required to allow cross compilation. Support to allow building a python module for multiple versions from a single template is also possible. The python3-pep517 build style provides means to build python packages that provide a build-system definition compliant with PEP 517 without a traditional setup.py script. The python3-pep517 build style does not provide a specific build backend, so packages will need to add an appropriate backend provider to hostmakedepends.

Python packages that rely on python3-setuptools should generally map setup_requires dependencies in setup.py to hostmakedepends in the template and install_requires dependencies to depends in the template; include python3 in depends if there are no other python dependencies. If the package includes a compiled extension, the python3-devel packages should be added to makedepends, as should any python packages that also provide native libraries against which the extension will be linked (even if that package is also included in hostmakedepends to satisfy setuptools).

NB: Python setuptools will attempt to use pip or EasyInstall to fetch any missing dependencies at build time. If you notice warnings about EasyInstall deprecation or python eggs present in ${wrksrc}/.eggs after building the package, then those packages should be added to hostmakedepends.

The following variables may influence how the python packages are built and configured at post-install time:

Also, a set of useful variables are defined to use in the templates:

Variable Value
py2_ver 2.X
py2_lib usr/lib/python2.X
py2_sitelib usr/lib/python2.X/site-packages
py2_inc usr/include/python2.X
py3_ver 3.X
py3_lib usr/lib/python3.X
py3_sitelib usr/lib/python3.X/site-packages
py3_inc usr/include/python3.Xm

NOTE: it's expected that additional subpkgs must be generated to allow packaging for multiple python versions.

Go packages

Go packages should be built with the go build style, if possible. The go build style takes care of downloading Go dependencies and setting up cross compilation.

The following template variables influence how Go packages are built:

The following environment variables influence how Go packages are built:

Occasionally it is necessary to perform operations from within the Go source tree. This is usually needed by programs using go-bindata or otherwise preping some assets. If possible do this in pre_build(). The path to the package's source inside $GOPATH is available as $GOSRCPATH.

Haskell packages

Haskell packages can be built either with the cabal or haskell-stack build style, use whichever is more convenient or better supported by upstream, sometimes only one of the two is possible. For packages that have haskell parts but use a different build style like gnu-makefile, make sure to use the haskell build helper.

The following variables influence how packages are built with cabal:

And these variables influence how packages are built with stack:

To patch dependencies of haskell packages they have to be fetched explicitly from hackage by adding them to distfiles instead of letting cabal or stack download them. Once extracted and patched, the path to the patched version can be added to packages in cabal.project or stack.yaml. Stack will find them automatically if no stack.yaml file exists by scanning the directory. The build tool will then use the patched version of the depencency instead of downloading it from hackage.

Font packages

Font packages are very straightforward to write, they are always set with the following variables:

Renaming a package

Removing a package

Follows a list of things that should be done to help guarantee that a package template removal and by extension its binary packages from Void Linux's repositories goes smoothly.

Before removing a package template:

When removing the package template:

XBPS Triggers

XBPS triggers are a collection of snippets of code, provided by the xbps-triggers package, that are added to the INSTALL/REMOVE scripts of packages either manually by setting the triggers variable in the template, or automatically, when specific conditions are met.

The following is a list of all available triggers, their current status, what each of them does and what conditions need to be for it to be included automatically on a package.

This is not a complete overview of the package. It is recommended to read the variables referenced and the triggers themselves.

appstream-cache

The appstream-cache trigger is responsible for rebuilding the appstream metadata cache.

During installation it executes appstreamcli refresh-cache --verbose --force --datapath $APPSTREAM_PATHS --cachepath var/cache/app-info/gv. By default APPSTREAM_PATHS are all the paths that appstreamcli will look into for metadata files.

The directories searched by appstreamcli are:

During removal of the AppStream package it will remove the var/cache/app-info/gv directory.

It is automatically added to packages that have XML files under one of the directories searched by appstreamcli.

binfmts

The binfmts trigger is responsible for registration and removal of arbitrary executable binary formats, know as binfmts.

During installation/removal it uses update-binfmts from the binfmt-support package to register/remove entries from the arbitrary executable binary formats database.

It is automatically added to packages that contain files in usr/share/binfmts. These files should be update-binfmts format files and will be imported with update-binfmts --import.

While it is not preferred, the trigger can also be added by using the binfmts variable, which should contain lines defining binfmts to register:

/path/to/interpreter [update-binfmts binary format specification arguments ...]
...

See update-binfmts(8) for more details.

dkms

The dkms trigger is responsible for compiling and removing dynamic kernel modules of a package.

During installation the trigger compiles and installs the dynamic module for all linux packages that have their corresponding linux-headers package installed. During removal the corresponding module will be removed

To include the trigger use the dkms_modules variable, as the trigger won't do anything unless it is defined.

gconf-schemas

The gconf-schemas trigger is responsible for registering and removing .schemas and .entries files into the schemas database directory

During installation it uses gconftool-2 to install .schemas and .entries files into usr/share/gconf/schemas. During removal it uses gconftool-2 to remove the entries and schemas belonging to the package that is being removed from the database.

To include it add gconf-schemas to triggers and add the appropriate .schemas in the gconf_schemas variable and .entries in gconf_entries.

It is automatically added to packages that have /usr/share/gconf/schemas present as a directory. All files with the schemas file extension under that directory are passed to the trigger.

gdk-pixbuf-loaders

The gdk-pixbuf-loaders trigger is responsible for maintaining the GDK Pixbuf loaders cache.

During installation it runs gdk-pixbuf-query-loaders --update-cache and also deletes the obsolete etc/gtk-2.0/gdk-pixbuf.loaders file if present. During removal of the gdk-pixbuf package it removes the cache file if present. Normally at usr/lib/gdk-pixbuf-2.0/2.10.0/loaders.cache.

It can be added by defining gdk-pixbuf-loaders in the triggers variable. It is also added automatically to any package that has the path usr/lib/gdk-pixbuf-2.0/2.10.0/loaders available as a directory.

gio-modules

The gio-modules trigger is responsible for updating the Glib GIO module cache with gio-querymodules from the glib package

During install and removal it just runs gio-querymodules to update the cache file present under usr/lib/gio/modules.

It is automatically added to packages that have /usr/lib/gio/modules present as a directory.

gsettings-schemas

The gsettings-schemas trigger is responsible for compiling Glib's GSettings XML schema files during installation and removing the compiled files during removal.

During installation it uses glib-compile-schemas from glib to compile the schemas into files with the suffix .compiled into /usr/share/glib-2.0/schemas.

During removal of the glib package it deletes all files inside /usr/share/glib-2.0/schemas that end with .compiled.

It is automatically added to packages that have /usr/share/glib-2.0/schemas present as a directory.

gtk-icon-cache

The gtk-icon-cache trigger is responsible for updating the gtk+ icon cache.

During installation it uses gtk-update-icon-cache to update the icon cache.

During removal of the gtk+ package it deletes the icon-theme.cache file in the directories defined by the variable gtk_iconcache_dirs.

It is automatically added on packages that have /usr/share/icons available as a directory, all directories under that directory have their absolute path passed to the trigger.

gtk-immodules

The gtk-immodules trigger is responsible for updating the IM (Input Method) modules file for gtk+.

During installation it uses gtk-query-immodules-2.0 --update-cache to update the cache file. It also removes the obsolete configuration file etc/gtk-2.0/gtk.immodules if present.

During removal of the gtk+ package it removes the cache file which is located at usr/lib/gtk-2.0/2.10.0/immodules.cache.

It is automatically added to packages that have /usr/lib/gtk-2.0/2.10.0/immodules present as a directory.

gtk-pixbuf-loaders

gtk-pixbuf-loaders is the old name for the current gdk-pixbuf-loaders trigger and is in the process of being removed. It currently re-execs into gdk-pixbuf-loaders as a compatibility measure.

For information about how it works refer to gdk-pixbuf-loaders.

gtk3-immodules

The gtk3-immodules trigger is responsible for updating the IM (Input Method) modules file for gtk+3.

During installation it executes gtk-query-immodules-3.0 --update-cache to update the cache file. It also removes the obsolete configuration file etc/gtk-3.0/gtk.immodules if present.

During removal of the gtk+3 package it removes the cache file which is located at usr/lib/gtk-3.0/3.0.0/immodules.cache.

It is automatically added to packages that have /usr/lib/gtk-3.0/3.0.0/immodules present as a directory.

hwdb.d-dir

The hwdb.d-dir trigger is responsible for updating the hardware database.

During installation and removal it runs usr/bin/udevadm hwdb --root=. --update.

It is automatically added to packages that have /usr/lib/udev/hwdb.d present as a directory.

info-files

The info-files trigger is responsible for registering and unregistering the GNU info files of a package.

It checks the existence of the info files presented to it and if it is running under another architecture.

During installation it uses install-info to register info files into usr/share/info.

During removal it uses install-info --delete to remove the info files from the registry located at usr/share/info.

If it is running under another architecture it tries to use the host's install-info utility.

initramfs-regenerate

The initramfs-regenerate trigger will trigger the regeneration of all kernel initramfs images after package installation or removal. The trigger must be manually requested.

This hook is probably most useful for DKMS packages because it will provide a means to include newly compiled kernel modules in initramfs images for all currently available kernels. When used in a DKMS package, it is recommended to manually include the dkms trigger before the initramfs-regenerate trigger using, for example,

```
triggers="dkms initramfs-regenerate"
```

Although xbps-src will automatically include the dkms trigger whenever dkms_modules is installed, the automatic addition will come after initramfs-regenerate, which will cause initramfs images to be recreated before the modules are compiled.

By default, the trigger uses dracut --regenerate-all to recreate initramfs images. If /etc/default/initramfs-regenerate exists and defines INITRAMFS_GENERATOR=mkinitcpio, the trigger will instead use mkinitcpio and loop over all kernel versions for which modules appear to be installed. Alternatively, setting INITRAMFS_GENERATOR=none will disable image regeneration entirely.

kernel-hooks

The kernel-hooks trigger is responsible for running scripts during installation/removal of kernel packages.

The available targets are pre-install, pre-remove, post-install and post-remove.

When run it will try to run all executables found under etc/kernel.d/$TARGET. The TARGET variable is one of the 4 targets available for the trigger. It will also create the directory if it isn't present.

During updates it won't try to run any executables when running with the pre-remove target.

It is automatically added if the helper variable kernel_hooks_version is defined. However it is not obligatory to have it defined.

mimedb

The mimedb trigger is responsible for updating the shared-mime-info database.

In all runs it will just execute update-mime-database -n usr/share/mime.

It is automatically added to packages that have /usr/share/mime available as a directory.

mkdirs

The mkdirs trigger is responsible for creating and removing directories dictated by the make_dirs variable.

During installation it takes the make_dirs variable and splits it into groups of 4 variables.

It will continue to split the values of make_dirs into groups of 4 until the values end.

During installation it will create a directory with dir then set mode with mode and permission with uid:gid.

During removal it will delete the directory using rmdir.

To include this trigger use the make_dirs variable, as the trigger won't do anything unless it is defined.

pango-modules

The pango-modules trigger is currently being removed since upstream has removed the code responsible for it.

It used to update the pango modules file with pango-modulesquery during installation of any package.

Currently it removes etc/pango/pango.modules file during removal of the pango package.

It can be added by defining pango-modules in the triggers variable and has no way to get added automatically to a package.

pycompile

The pycompile trigger is responsible for compiling python code into native bytecode and removing generated bytecode.

During installation it will compile all python code under the paths it is given by pycompile_dirs and all modules described in pycompile_module into native bytecode and update the ldconfig(8) cache.

During removal it will remove all the native bytecode and update the ldconfig(8) cache.

To include this trigger use the variables pycompile_dirs and pycompile_module. The trigger won't do anything unless at least one of those variables is defined.

A python_version variable can be set to direct behaviour of the trigger.

register-shell

The register-shell trigger is responsible for registering and removing shell entries into etc/shells.

During installation it will append the etc/shells file with the new shell and also change the permissions to 644 on the file.

During removal it will use sed to delete the shell from the file.

To include this trigger use the register_shell variable, as the trigger won't do anything unless it is defined.

system-accounts

The system-accounts trigger is responsible for creating and disabling system accounts and groups.

During removal it will disable the account by setting the Shell to /bin/false, Home to /var/empty, and appending ' - for uninstalled package $pkgname' to the Description. Example: transmission unprivileged user - for uninstalled package transmission

This trigger can only be used by using the system_accounts variable.

texmf-dist

The texmf-dist trigger is responsible for regenerating TeXLive's texmf databases.

During both installation and removal, it regenerates both the texhash and format databases using texhash and fmtutil-sys, to add or remove any new hashes or formats.

It runs on every package that changes /usr/share/texmf-dist. This is likely overkill, but it is much cleaner rather than checking each format directory and each directory that is hashed. In addition, it is very likely any package touching /usr/share/texmf-dist requires one of these triggers anyway.

update-desktopdb

The update-desktopdb trigger is responsible for updating the system's MIME database.

During installation it will execute update-desktop-database usr/share/applications which will result in a cache file being created at usr/share/applications/mimeinfo.cache.

During removal of the desktop-file-utils package it will remove the cache file that was created during installation.

It is automatically added to packages that have /usr/share/applications available as a directory.

x11-fonts

The x11-fonts trigger is responsible for rebuilding the fonts.dir and fonts.scale files for packages that install X11 fonts, and update fontconfig's cache for these fonts.

During installation and removal it executes mkfontdir, mkfontscale and fc-cache for all font directories it was given via the font_dirs variable.

To include this trigger use the font_dirs variable, as the trigger won't do anything unless it is defined.

xml-catalog

The xml-catalog trigger is responsible for registering and removing SGML/XML catalog entries.

During installation it uses xmlcatmgr to register all catalogs, passed to it by the sgml_entries and xml_entries variables, in usr/share/sgml/catalog and usr/share/xml/catalog respectively.

During removal it uses xmlcatmgr to remove all catalogs passed to it by the sgml_entries and xml_entries variables, in usr/share/sgml/catalog and usr/share/xml/catalog respectively.

To include this trigger use the sgml_entries variable or/and the xml_entries variable, as the trigger won't do anything unless either of them are defined.

Void specific documentation

When you want document details of package's configuration and usage specific to Void Linux, not covered by upstream documentation, put notes into srcpkgs/<pkgname>/files/README.voidlinux and install with vdoc "${FILESDIR}/README.voidlinux".

Notes

Contributing via git

To get started, fork the void-linux void-packages git repository on GitHub and clone it:

$ git clone git@github.com:<user>/void-packages.git

See CONTRIBUTING.md for information on how to format your commits and other tips for contributing.

Once you've made changes to your forked repository, submit a github pull request.

To keep your forked repository always up to date, setup the upstream remote to pull in new changes:

$ git remote add upstream https://github.com/void-linux/void-packages.git
$ git pull --rebase upstream master

Help

If after reading this manual you still need some kind of help, please join us at #xbps via IRC at irc.libera.chat.