Ebuilds: Why You Should Have Good Documentation If You Cannot Make It Simple

Ebuilds: Why You Should Have Good Documentation If You Cannot Make It Simple

Posted on 2020-08-05

In most Linux distributions, software are built into packages, which the end-user can install via the command line or a graphical interface.

If you are technical enough, you might want to create your own packages for software you created, or just couldn't find in the default repositories.

All distributions have their own tooling for this process. And I want to focus on the tooling of three particular distributions. The distributions I will talk about are Arch, KISS, and Gentoo.

Arch Linux and PKGBUILDs: Documentation

Arch Linux

Arch Linux's PKGBUILD scripts are definitely simple once you get the hang of them (and it's not that hard to do so!), but the point I want to make about them are the quality of the documentation. It's beautiful.

Of course, being the distribution behind the excellent Arch Wiki, that shouldn't be that big of a surprise to anyone familiar with it.

The essential PKGBUILD documentation consists mainly of these two wiki pages, with the other related and linked pages allowing you to dive deeper into what you're trying to accomplish:

Creating Packages - Arch Wiki
PKGBUILD - Arch Wiki

With the first page giving you the basic outline of the process, and using the second as a reference, I am pretty sure anyone with just about enough shell scripting knowledge can create a PKGBUILD and have the resulting package installed in about half an hour, probably even less.

KISS Linux and ./build: Simplicity

KISS Linux

KISS Linux, taking it's name from "Keep It Simple, Stupid", might not have the excellent documentation of the Arch Wiki, but I'd argue that it doesn't need to, because of how simple it's packaging system is.

To create a package in KISS Linux, you create a new folder, write the download links in the sources file, the version in the version file, and just dump all the build instructions in a shell script named build¹. Run a command to generate checksums, and you are done.

Package System - KISS

The main point I want to get to, is that KISS doesn't need all the in-depth documentation of PKGBUILDs, because it doesn't have that much to document. And if you're actually using KISS comfortably enough to create your own packages, you probably can understand what you'll need to do for any specific build system.

Gentoo and ebuilds: What Not to Do

Gentoo Linux

Here is the main part of the article: ebuilds. The opposite of what you should do.

Basic Guide to Write Ebuilds - Gentoo Wiki
Quickstart Ebuild Guide - Gentoo Development Guide

The Gentoo Wiki has guides on how to start writing Ebuilds, and even some examples to get you started. All good, right?

The problem isn't with the documented parts. It's with the abundance of un-documented parts.

An Example

As far as I could tell, there is NO documentation on downloading and using files without extracting them.

Doing the obvious thing of just putting download links into the source URL variable will make the package manager yell at you about a missing directory, which it assumes the existence of, because a majority of Gentoo package sources are tar archives. As far as I could tell, there is NO documentation on this behavior.

What I had to do was to tell the package manager to not look for any extracted folders, so I could manually move the files into the correct places it expected them to be in, even before doing the installation, which is essentially moving those files into yet another directory. (The package doesn't need to do any processing at all! It's just a few data files.)

How did I finally make it work in the end? I just jumped into IRC and asked. The existing documentation was little to no use, aside from de-constructing the solution they gave to understand what I needed to do.

Complexity: eclasses

Gentoo's ebuilds have this feature called "eclasses", which try to abstract away common build script boilerplate to make ebuilds simpler.

Unfortunately, this only adds to the complexity, because it now does things in the background with source code that's very hard to skim through to find what you need and get out.


So, if you are making anything, either make it so simple that people will "get it" in a few minutes, or write enough documentation for everybody to understand. Try considering the assumptions you make in your system. Document every assumption your systems have, and how to work around them should it need to be broken.

Why? Because in the sea of all the archives you automatically extract, there will eventually be a regular file, and when that time comes, you don't want people to be left confused, looking for answers.


1: It doesn't have to be a shell script, anything executable will do. But I don't think anyone uses anything other than shell scripts, because compiling software requires shell commands, and there aren't anything better than shell scripts to execute them.

You seem to be blocking JavaScript, keep up the good work!
This message is just here to remind you that my blog also is available via Gemini, if you wish to read it through a protocol that's lighter and has more than three proper browsers.

Replace https://ecmelberk.com with gemini://ebc.li on the page address to read it from there.
Send comments and replies to ~admicos/public-inbox@lists.sr.ht (mailing list etiquette)