💾 Archived View for ebc.li › posts › ebuilds-and-simplicity.gmi captured on 2022-01-08 at 13:51:29. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-11-30)
-=-=-=-=-=-=-
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'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:
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, 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.
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.
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.
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.
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.
🐺 · CC BY-SA 4.0 · me@ecmelberk.com