This tutorial is up to date as of September 29, 2024
This tutorial will guide you through packaging with xbps-src
, either for
inclusion in the void-packages
repository or for personal use.
Prerequisites
- use Void Linux (this is not a hard requirement, there are ways to build XBPS packages from foreign distros, but this is outside the scope of this tutorial)
- basic knowledge of Git
- basic knowledge of GitHub for contributing (have an account, know how to make a fork, know how to make a pull request)
- basics of CLI
- knowledge of the build system of the packaged program is preferable
- knowledge of libraries (what’s a static/shared library, why are they important, what’s a SONAME, etc.) is useful
- knowing what a patch is, how to make one, and how to apply it is preferable (they are used in packaging j4-dmenu-desktop section of this tutorial, but shouldn’t be necessary in more normal use)
Non-prerequisites
This tutorial assumes no prior knowledge of packaging systems.
Introduction
xbps-src
is a simple but capable build system. It is one of Void Linux’s major
strengths, but its official documentation can be difficult to understand for
those who do not have experience with packaging systems. This tutorial aims to
bridge that gap.
I try to cover the basics. Feel free to skip some sections. But don’t skip too much. This tutorial is written to be read from beginning to end.
This tutorial is divided into four sections: packaging
j4-dmenu-desktop
,
bat
, oniguruma
, and
rofimoji
. Packaging
j4-dmenu-desktop
showcases basic concepts of
xbps-src
and bat
,
oniguruma
and rofimoji
show additional concepts that couldn’t be shown on j4-dmenu-desktop
.
All four of these are already packaged in Void Linux. The first three are
compiled programs, rofimoji
is not.
Contributing the packages to
void-packages
is described in
Contributing.
Paths
If not said otherwise, relative paths are relative to the directory the
void-packages
repository
resides in.
Tabs
mdBook
automatically converts tabs to spaces in code
blocks. xbps-src
indents
templates with tabs. You’ll have to convert 4 spaces to tabs manually when
copying from code blocks in this tutorial.
Extended logs
Some logs in this tutorial are cut. You can expand them by clicking on the eye icon in the upper right corner of a code sample. The button will appear when you hover over the code block.
content
content
content
This isn't everything in the log!
content
content
content
Official documentation
I will try to update this tutorial as appropriate, but the official documentation will always contain more up-to-date info. The official documentation includes:
- void-packages
README,
which explains setting up the masterdir and some more exotic configurations of
xbps-src
. - the
Manual,
which contains everything there is to know about
xbps-src
- CONTRIBUTING,
which contains useful info about contributing packages to
void-packages
like commit message format requirements, package requirements (we’ll come back to this soon), and more
The Manual
is more akin to a reference manual, but the first few sections briefly explain
the basics of xbps-src
.
Obsolescence of this tutorial
I chose to package the latest versions of the programs I’m showcasing at the
time of writing this tutorial. But j4-dmenu-desktop
, bat
, oniguruma
, and
rofimoji
might have newer versions available by the time you read this,
rendering the packages I’m showcasing obsolete.
There’s nothing wrong with packaging an older version of a package, although outdated packages are unlikely to be accepted into the official Void repositories. If any of these packages have a version greater than that mentioned in the tutorial, it is left as an exercise for the reader to update them. The process is the same.
The tutorial focuses on the process of packaging, the packaged programs and libraries themselves “aren’t that important” here.
IRC
If you are unsure about some aspect of xbps-src
or your template is failing
and you do not know why, you can ask around in #voidlinux
or #xbps
Libera
Chat channels.
The channel consists mainly of volunteers. Do not expect people there to package complicated programs for you at your will.
When asking there, do not paste error logs or templates directly to the channel. You will likely be kicked for this. Use a paste site instead. You can use https://bpa.st/, https://0x0.st/, https://termbin.com/, or some other paste site.
It is often useful to pipe the output of a command directly to a paste site. Some paste sites like https://0x0.st/ and https://termbin.com/ support it.
To paste a file to 0x0, run this:
curl -F'file=@yourfile.png' https://0x0.st
To paste the output of a command to 0x0, run this:
command | curl -F'file=@-' https://0x0.st
Disclaimer
I, meator, am not a Void Linux member. I don’t have write privileges to any of the official Void Linux repositories nor can I merge pull requests.