From Void Linux Wiki
Jump to: navigation, 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:

 sudo xbps-install xtools

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/voidlinux/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 fetch upstream
 git checkout -b my-cool-new-package-branch upstream/master

Quick Start

Clone the packages repository, if you haven't already:

 git clone https://github.com/voidlinux/void-packages
 cd void-packages

Create the bootstrap environment:

 ./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.

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

Pull Request

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