Warning: THE VOID WIKI IS DEPRECATED. It is no longer being maintained, contains outdated and incorrect information, and will eventually be shut down. Please refer to the Void Handbook, https://docs.voidlinux.org/, for the official documentation. If you can't find the information you're seeking, please raise an issue at https://github.com/void-linux/void-docs/issues


From Void Linux Wiki
Jump to navigation Jump to search

This article is a practical guide for creating and build packages from their templates (build recipes) with xbps-src. The official documentation with more technical details can be found here.


xtools is required for linting packages before submitting them and generating checksums; it also includes a variety of helpful programs:

 # xbps-install xtools

Choose a Fork or Clone repository

Fork the Repository

This is only necessary, if you want to make changes to the official Void Linux packages repository. Otherwise skip to the Quick Start section below.

Note: Make sure, that the software you'll package is compliant to the Contributing rules. We do not accept any packages containing non-release versions such as specific git- or svn-revisions.

 git clone git@github.com:yourusername/void-packages.git
 cd void-packages
 git remote add upstream https://github.com/void-linux/void-packages.git

Create a new branch

The steps above only need to be done once. Whenever you want to work on a new feature (for example adding a new package and its dependencies), fetch from upstream and create a new branch:

 git pull --rebase upstream master
 git checkout -b my-cool-new-package-branch

Clone the repository

Quick Start

Clone the void-packages git repository, install the bootstrap packages:

 $ git clone https://github.com/void-linux/void-packages
 $ cd void-packages
 $ ./xbps-src binary-bootstrap

Modify or create a template, depending on what you want to do. Take some time to read the packages manual for more information about the templates format. Please follow the package naming conventions.


The etc/defaults.conf file contains the possible settings that can be overridden through the etc/conf configuration file for the xbps-src utility; if that file does not exist, will try to read configuration settings from ~/.xbps-src.conf.

If you want to customize default CFLAGS, CXXFLAGS and LDFLAGS, don't override those defined in etc/defaults.conf, set them on etc/conf instead i.e:

 # nano etc/conf
 XBPS_CFLAGS="-march=native -O2 -pipe"
 XBPS_LDFLAGS="-march=native -O2 -pipe"

Or for i686:

 XBPS_CFLAGS="-march=i686 -O2 -pipe -fomit-frame-pointer"
 XBPS_LDFLAGS="-march=i686 -O2 -pipe -fomit-frame-pointer"

Or for other arch also MIPS https://gcc.gnu.org/onlinedocs/gcc-8.2.0/gcc/MIPS-Options.html#MIPS-Options

 XBPS_CFLAGS="-march=mips64 -O2 -pipe"
 XBPS_LDFLAGS="-march=mips64 -O2 -pipe"

Native and cross compiler/linker flags are set per architecture in common/build-profiles and common/cross-profiles respectively. Ideally those settings are good enough by default, and there's no need to set your own unless you know what you are doing.

Build a packages

The simplest form of building package is accomplished by running the pkg target in xbps-src:

 $ cd void-packages
 $ ./xbps-src pkg <pkgname>

You can install your package in to the void-packages (local-repository):

 xi <pkgname>

When the package and its required dependencies are built, the binary packages will be created and registered in the default local repository at hostdir/binpkgs; the path to this local repository can be added to any xbps configuration file (see xbps.d(5)) or by explicitly appending them via cmdline, i.e:

 $ xbps-install --repository=hostdir/binpkgs ...
 $ xbps-query --repository=hostdir/binpkgs ...

By default xbps-src will try to resolve package dependencies in this order:

   If a dependency exists in the local repository, use it (hostdir/binpkgs).
   If a dependency exists in a remote repository, use it.
   If a dependency exists in a source package, use it.

It is possible to avoid using remote repositories completely by using the -N flag.

NOTE* The default local repository may contain multiple sub-repositories: debug, multilib, etc.

Rebuilding and overwriting existing local packages

If for whatever reason a package has been built and it is available in your local repository and you have to rebuild it without bumping its version or revision fields, it is possible to accomplish this task easily with xbps-src:

$ ./xbps-src -f pkg xbps

Reinstalling this package in your target rootdir can be easily done too:

$ xbps-install --repository=/path/to/local/repo -yff xbps-0.25_1

   Please note that the package expression must be properly defined to explicitly pick up the package from the desired repository.

Distfiles mirror(s)

In etc/conf you may optionally define a mirror or a list of mirrors to search for distfiles.

 $ echo 'XBPS_DISTFILES_MIRROR=""' >> etc/conf

If more than one mirror is to be searched, you can either specify multiple URLs separated with blanks, or add to the variable like this

 $ echo 'XBPS_DISTFILES_MIRROR+="http://repo.voidlinux.de/distfiles"' >> etc/conf

Make sure to put the blank after the first double quote in this case.

The mirrors are searched in order for the distfiles to build a package until the checksum of the downloaded file matches the one specified in the template.

Ultimately, if no mirror carries the distfile, or in case all downloads failed the checksum verification, the original download location is used.

If you use proot or uchroot for your XBPS_CHROOT_CMD, you may also specify a local path using the file:// prefix or simply an absolute path on your build host (e.g. /mnt/distfiles).

   $ echo 'XBPS_DISTFILES_MIRROR+="file://mnt/distfiles"' >> etc/conf

Mirror locations specified this way are bind mounted inside the chroot environment under $XBPS_MASTERDIR and searched for distfiles just the same as remote locations.

Create a new package

To create a new package (with the help of xtools), run:

 xnew my-cool-new-package

This will set up a basic template file. Note that you may have to add user credentials to git first.

To generate the sha256 checksums for new or changed distribution files:

 xgensum -f srcpkgs/my-cool-new-package/template

Note: You can also use the xgensum command to debug your do_fetch() function, as it shows more output than xbps-src. For example git submodule will fail, if perl is not listed in hostmakedepends.

Build your package:

 ./xbps-src pkg my-cool-new-package

This will most-likely fail on the first approach, so fix your package and run xbps-src again. You can run all package build phases independently. If you did not change the dependencies on the second run, use the -I flag to save some time by skipping the autoremoval and reinstall steps:

 ./xbps-src -I build my-cool-new-package

Once the package-step ran through successfully, you can install your package:

 sudo xbps-install --repository=hostdir/binpkgs/my-cool-new-package-branch my-cool-new-package

or (with the help of xtools)

 xi my-cool-new-package

(xi automatically favours your local repository, if it is run inside a void-packages structure)

If you have modified a package and do not wish to put the change in the official packages repository, put it on hold mode:

 xbps-pkgdb -m hold <pkgname>

Push Changes

Run the program you have installed on your own computer and test if everything works as it should. Then lint your package and fix all issues before you continue:

 xlint srcpkgs/my-cool-new-package/template

Commit your changes with a message that follows the commit rules:

 git add srcpkgs/my-cool-new-package
 git commit -m "New package: my-cool-new-package-1337"

Note: If you made a mistake, use git commit --amend now to fix it.

Push to your own repository:

 git push -u origin my-cool-new-package-branch

Huge packages

In case you know your pull request will not finish on Travis-CI because it takes too long (more than ~40 minutes) or produces too much log output (more than 10.000 lines or 4MiB), you can avoid triggering the CI run for your pull request by including the tag [ci skip] somewhere in the commit message.

Examples for packages which, if you want to modify them in your PR, should make use of this tag

gcc, cross-*, webkit{,2}gtk, firefox{,-esr}, qt, qt5, libreoffice, qemu, …

Judge by the results of your local build times and log output.

Pull Request

Make a pull request and follow the instructions described in the Contributing article.

More tips

  • in case you encounter conflicts with current upstream/master or want to build the package locally without rebuilding old packages, or you want to utilize a recent change in upstream's repo, you need to rebase your branch onto upstream's current master. This might be of help: pull upstream master --rebase --autostash (you may consider adding it as an alias to your .gitconfig if you have to rebuild packages alot)
  • you can use xbps-src -f pkg and xbps-install -f without having to increase the version or revision while working on the template