From Void Linux Wiki
Revision as of 16:00, 16 June 2018 by Piraty (talk | contribs) (point to new github org)
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/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

Quick Start

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

 git clone https://github.com/void-linux/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

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)