¬ just serendipity 🍀 (not just serendipity)

This document describes my workflow to manage PKGBUILDs for the AUR (Arch User Repository) in Arch Linux.

Disclaimer #

First of all, this post is not a substitute to the excellent ArchWiki 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.archlinux.org/title/Arch_User_Repository
• https://wiki.archlinux.org/title/Arch_package_guidelines
• https://wiki.archlinux.org/title/Creating_packages
• https://wiki.archlinux.org/title/PKGBUILD

This article is not a tutorial, as such it assumes you already know what a PKGBUILD is and how to use makepkg. In particular, you should have the base-devel and devtools packages installed in your system.

Structure #

I manage my packages with git plus Eli Schwartz’s excellent aurpublish. The tree structure is simple, with one PKGBUILD per directory:

$ git clone https://github.com/thiagowfx/PKGBUILDs && tree PKGBUILDs
PKGBUILDs
├── bkt
│   └── PKGBUILD
├── fpp-git
│   └── PKGBUILD
├── git-crecord
│   └── PKGBUILD
├── i3a
│   └── PKGBUILD
├── LICENSE
├── Makefile
├── README.md
├── ttf-camingocode
│   └── PKGBUILD
└── urlwatch.yml

aurpublish is used solely to automate certain interactions with the AUR, more about it later.

Bootstrapping #

I am going to illustrate with a package I added recently, bkt:

• Before you even begin, check if the package already exists, do a quick search in the AUR and also in the official repos¹.

• Start by copying over the standard PKGBUILD template:

$ cd PKGBUILDs
$ mkdir bkt && cd bkt
$ cp /usr/share/pacman/PKGBUILD.proto PKGBUILD
$ $EDITOR PKGBUILD

• Fill in PKGBUILD metadata like pkgname=, url=, etc. Refer to the ArchWiki for up-to-date best practices.

• The most important step is to refer to https://wiki.archlinux.org/title/Category:Arch_package_guidelines to figure out the package type.

bkt is a Rust package. This is my first time packaging for Rust, not a problem though, as I can just refer to https://wiki.archlinux.org/title/Rust_package_guidelines.

The rust package guidelines page contains the blueprint for prepare(), check(), build() and package(). Packaging is mostly a matter of gluing everything together. Read the project README.md and the wiki, and then combine the needed steps in the PKGBUILD.

By doing so, I produced the following PKGBUILD:

pkgname=bkt
pkgver=0.5.0
pkgrel=1
pkgdesc="A subprocess caching utility"
arch=('x86_64')
url="https://www.bkt.rs/"
license=('MIT')
makedepends=('cargo')
source=("$pkgname-$pkgver.tar.gz::https://github.com/dimo414/$pkgname/archive/refs/tags/$pkgver.tar.gz")
sha256sums=()

prepare() {
	cd "$srcdir/$pkgname-$pkgver"

	cargo fetch --locked --target "$CARCH-unknown-linux-gnu"
}

build() {
	cd "$srcdir/$pkgname-$pkgver"

	export RUSTUP_TOOLCHAIN=stable
	export CARGO_TARGET_DIR=target
	cargo build --frozen --release --all-features
}

check() {
	cd "$srcdir/$pkgname-$pkgver"

	export RUSTUP_TOOLCHAIN=stable
	cargo test --frozen --all-features
}

package() {
	cd "$srcdir/$pkgname-$pkgver"

	install -Dm0755 -t "$pkgdir/usr/bin/" "target/release/$pkgname"
	install -Dm644 LICENSE -t "$pkgdir/usr/share/licenses/$pkgname"
}

Note: $srcdir refers to the src/ directory within bkt. $pkgdir refers to the pkg/ directory within bkt.

Adjustments #

• Generate the checksums with updpkgsums. It will automatically update the PKGBUILD inplace.

• Download and extract package files with makepkg -o.

• ls src/ and check the directory structure. Update cd in your PKGBUILD to match it. Usually it will be cd $srcdir/$pkgname-$pkgver, but sometimes tiny adjustments are necessary.

• Then run makepkg -s. If everything goes well, your package will be successfully built² (bkt-0.5.0-1-x86_64.pkg.tar.zst), however that doesn’t mean it is a decent package yet.

• Run namcap PKGBUILD and namcap *.pkg.tar.zst to lint your package and catch common errors. Fix the errors, if any.

• To ensure all dependencies have been correctly declared and none of them are missing, run makepkg within a clean chroot. I like to use Graysky’s excellent ccm (Clean Chroot Manager) to do so. Run ccm s (=“run makepkg in the clean chroot”). If it produces any errors, it likely means you missed some dependencies. Adjust depends=, checkdepends= and makedepends= accordingly.

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 makepkg -i.

Otherwise, if the package might be potentially useful to other Arch users, you could consider uploading it to the AUR.

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:

1. AUR Issues, Discussion & PKGBUILD Requests BBS / Forums: Open a new thread, post your PKGBUILD (use [code][/code] tags if you paste it directly!) or a link to it³. Request folks to critique your work, mention that you’re looking for feedback. This kind of thread is generally well received in the official forums if you demonstrate you did diligent research before asking for help.

2. AUR General Mailing List: Send an email to the mailing list asking for help. In general, follow proper mailing list etiquette, good resources for that are https://useplaintext.email/ and https://man.sr.ht/lists.sr.ht/etiquette.md. TL;DR: Use plain-text instead of HTML in your email.

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 PKGBUILD to the AUR. Follow the up-to-date steps at https://wiki.archlinux.org/title/Arch_User_Repository#Submitting_packages.

TL;DR: If you don’t use aurpublish, do:

$ makepkg --printsrcinfo > .SRCINFO

Then you’ll need both the PKGBUILD and the .SRCINFO file, it’s basically a matter of committing your changes and pushing them to the right repository.

If you do use aurpublish this process is much easier, it’s mostly a matter of doing git commit, git push and aurpublish bkt. Aurpublish automatically generates the .SRCINFO and a commit message by the means of git hooks.

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, Alpine Linux APKBUILDs are very similar to PKGBUILDs. Gentoo EBUILDs and FreeBSD Makefiles are also reasonable approximations.
• Use makepkg -src to clean up after building a package.

Bonus: Track upstream #

Use a software like urlwatch or nvchecker to track future upstream changes so that you can update your packages in a timely fashion⁴. There’s also a web service called Release Monitoring, part of Fedora Infra. And there’s also https://changedetection.io/, but it’s overkill for this task. I use urlwatch the following way:

# urls for urlwatch(1)
---
name: "bkt"
command: "git ls-remote --tags https://github.com/dimo414/bkt"
---
name: "fpp"
command: "git ls-remote --tags https://github.com/facebook/PathPicker"
---
name: "git-crecord"
command: "git ls-remote --tags https://github.com/andrewshadura/git-crecord"
---
name: "i3a"
command: "git ls-remote --tags https://git.goral.net.pl/mgoral/i3a"
# ---
# name: "ttf-camingocode"
# N/A

# Run this command periodically via cron or systemd timer.
# Set up notifications e.g. via sendmail.
$ urlwatch --urls urlwatch.yml