This document describes my workflow to manage APKBUILDs
for the
aports repository in Alpine Linux.
Disclaimer
First of all, this post is not a substitute to the AlpineWiki and it will likely get outdated at some point. In particular, refer to the following articles for up-to-date documentation that will outlive this blog:
- https://wiki.alpinelinux.org/wiki/APKBUILD_Reference
- https://wiki.alpinelinux.org/wiki/Abuild_and_Helpers
- https://wiki.alpinelinux.org/wiki/Aports_tree
- https://wiki.alpinelinux.org/wiki/Creating_an_Alpine_package
This article is not a tutorial, as such it assumes you already know what an
APKBUILD
is and how to use abuild
. In particular, you should have the
alpine-sdk
, atools
and spdx-licenses-list
packages installed in your
system.
Structure
I manage my packages with git
. Create a GitLab account on
https://gitlab.alpinelinux.org/, fork the aports
tree, and git clone
your fork.
The structure follows Alpine Linux repositories:
$ git clone https://gitlab.alpinelinux.org/alpine/aports.git && tree -L 1 aports
aports
├── CODINGSTYLE.md
├── COMMITSTYLE.md
├── README.md
├── community
├── main
├── non-free
├── scripts
├── testing
└── unmaintained
Bootstrapping
I am going to illustrate with a package I added recently, sensible-utils
:
Before you even begin, check if the package already exists, do a quick search in the Alpine Repositories1.
Start by scaffolding a new
APKBUILD
from the base template:
$ cd aports/testing # Always add new packages in testing/ first.
$ newapkbuild sensible-utils
$ cd sensible-utils
$ $EDITOR APKBUILD
Note: If you have a language-specific package (e.g. perl, python, rust),
use the language-specific template instead of the base one. Run newapkbuild -h
to list available templates. There are also some apkbuild-*
helpers such
as apkbuild-pypi
and apkbuild-cpan
.
Fill in
APKBUILD
metadata likepkgname=
,url=
, etc. Refer to the AlpineWiki for up-to-date best practices.By doing so, I produced the following
APKBUILD
:
pkgname=sensible-utils
pkgver=0.0.14
pkgrel=0
pkgdesc="Utilities for sensible alternative selection"
url="https://packages.debian.org/source/sensible-utils"
arch="all"
license="GPL-2.0-or-later"
makedepends="po4a"
subpackages="$pkgname-doc"
source="http://ftp.debian.org/debian/pool/main/s/$pkgname/${pkgname}_$pkgver.tar.xz"
builddir="$srcdir/$pkgname.git"
build() {
./configure --prefix=/usr
make
}
check() {
make -k check
}
package() {
make DESTDIR="$pkgdir/" install
# only works with update-alternatives, specific to debian
rm "$pkgdir/usr/bin/select-editor"
}
sha512sums="
15ba996f811ab3a9c1f5726f35766d74aafdf925c5c2392b33c6643d6c439796a742f9d0f4625c79de640e6b5e4a6a032b768eb1bc4ac31b448f9767b0ceed44 sensible-utils_0.0.14.tar.xz
"
Note: $srcdir
refers to the src/
directory within sensible-utils
. $pkgdir
refers to the pkg/
directory within sensible-utils
.
If you’re used to Arch Linux PKGBUILDs
you’ll notice a striking similarity to
APKBUILDs
. I highlighted a few notable differences in a previous post, My First APKBUILD
.
Adjustments
Generate the checksums with
abuild checksum
. It will automatically update theAPKBUILD
inplace.Download and extract package files with
abuild unpack
.ls src/
and check the directory structure. Update$builddir
in yourAPKBUILD
to match it. Usually it will be$srcdir/$pkgname-$pkgver
, but sometimes tiny adjustments are necessary. In this case, it was$srcdir/$pkgname.git
.Then run
abuild -r
. If everything goes well, your package (and subpackages, if any) will be successfully built2 in an isolated environment and placed in~/packages
(sensible-utils-0.0.14-r0.apk
andsensible-utils-doc-0.0.14-r0.apk
), however that doesn’t mean it is a decent package yet.Run
apkbuild-lint APKBUILD
andabuild sanitycheck
to lint your package and catch common errors. Fix the errors, if any.
Request feedback if needed
If the package is only relevant to you, stop here. git commit
, git push
, and then you’re done. Install the package with doas apk add <pkg>
.
Otherwise, if the package might be potentially useful to other Alpine users, you could consider uploading it to the aports repository.
Before you do so, stop for a moment and make an honest judgment whether this is a high quality package and whether you’re confident it is clean and polished enough, following the best practices documented in the Wiki. The answer doesn’t need to be positive, it’s perfectly OK to commit mistakes and everyone is a newbie at some point.
If the answer is negative, or if you’re new to this process and would like some help, fear no more! There are at least two decent community resources wherein to ask for help:
#alpine-devel
on OFTC IRC Drew DeVault wrote a good post about IRC etiquette.
If you’re part of any other community (e.g. Reddit, Discord) feel free to ask therein as well. Avoid posting everywhere though, pick one community, draft your post and then patiently wait.
Publish your package
If all is well, it’s time to publish your APKBUILD
. Follow the up-to-date
steps at
https://wiki.alpinelinux.org/wiki/Creating_an_Alpine_package#Code_review. There are basically two options:
Send a gitlab merge request (MR). This follows the standard git forge workflow (GitHub / BitBucket / GitLab) wherein you fork the main repository, create a branch in your own clone, push it and then initiate a pull request3.
Alternatively, send an email with your patch to the
aports
mailing list withgit send-email
:
$ git config sendemail.to "alpine-aports@lists.alpinelinux.org"
$ git send-email -1 # Implicitly uses --to=alpine-linux@lists.alpinelinux.org as set above
Tip: The second approach has a steep learning curve, however once you figure it out it’s actually faster, simpler and more streamlined. Whenever a new email is sent to the aports mailing list, a MR is automatically created on GitLab.
Note: If you adopt the email workflow and need to send a follow-up to your
initial patch, do not use --in-reply-to
. Instead, create a new email thread.
This is needed because as of this post new GitLab MRs are only created when new
email threads are created. Replies to existing email threads do not update the
MR patch.
And that’s all! Other useful tips:
- Use repology to look for preexisting packages in other Linux (or even BSD) distributions, it’s very handy as a starting point if you have no idea how to package a given package. In particular, Arch Linux
PKGBUILDs
are very similar toAPKBUILDs
. GentooEBUILDs
and FreeBSDMakefiles
are also reasonable approximations. - Use
abump
to bump pkgver inAPKBUILD
files if the package gets an update to a newer upstream release. - Use
apkgrel
to bump or reset thepkgrel
value of yourAPKBUILD
. - Use
urlwatch
to track upstream updates.
If you use https://duckduckgo.com/, query for
!alpine sensible-utils
. ↩︎Package debugging is out of scope of this post. ↩︎
In GitLab it’s called Merge Request (MR). The list of all aports MRs is here. ↩︎