Arch build system

Related articles
Arch package guidelines
Arch User Repository
Creating packages
Kernel/Arch build system
Official repositories
Patching packages
The
Arch build system
(ABS) is a system for building and packaging software from source code. While
pacman
is the specialized Arch tool for binary package management, the Arch build system is a collection of tools for compiling source into installable
.pkg.tar.zst
packages.
The Arch build system can be compared to
ports
for *BSD, which automates the process of building software from source code. The system uses a
port
to download, unpack, patch, compile, and install the given software. A
port
is merely a small directory on the user's computer, named after the corresponding software to be installed, that contains a few files with the instructions for building and installing the software from source. This makes installing software as simple as typing
make
or
make install clean
within the port's directory.
The Arch build system is based on a similar concept. It comprises a collection of git repositories for every package available in Arch Linux. Each repository contains a
PKGBUILD
file (and sometimes other files), and does not contain the software source nor binary. By running
makepkg
inside a directory, the software sources are downloaded, the software is compiled, and then packaged within the build directory. Then you can use
pacman
to install the package.
Toolchain
The Arch build system includes and relies on several components and tools that are used in the process of building packages from source:
Repository
The directory structure containing files needed to build all official packages but not the packages themselves nor the source files of the software. It is available in the form of
Git
repositories hosted on
gitlab.archlinux.org
. See the section
#Repository structure
for more information.
PKGBUILD
A
Bash
script that contains the URL of the source code along with the compilation and packaging instructions.
makepkg
A shell command tool which reads the
PKGBUILD
files, automatically downloads and compiles the sources and creates a
.pkg.tar*
according to the
PKGEXT
array in
makepkg.conf
. You may also use
makepkg
to make your own custom packages from the
Arch User Repository
(AUR) or third-party sources. See
Creating packages
for more information.
pacman
pacman
is completely separate, but is necessarily invoked, either by
makepkg
or manually, to install and remove the built packages and for fetching dependencies.
devtools
pkgctl
devtools(7)
are the tools for the Arch Linux distribution for building and maintaining official repository packages.
pkgctl(1)
is a high-level tool to help with building Arch Linux packages from their source repositories and releasing them to the binary repositories.
AUR
The Arch User Repository is separate from the official repository of
PKGBUILD
files, but packages from the AUR can be built using the same tools. It contains many thousands of user-contributed
PKGBUILD
files for software which is unavailable as an official Arch package. If you need to build a package outside the official Arch tree, chances are it is in the AUR.
Warning
Official
PKGBUILD
files assume that packages are built in a
clean chroot
. Building software on a
dirty
build system may fail or cause unexpected behaviour at runtime, because if the build system detects dependencies dynamically, the result depends on what packages are available on the build system.
Repository structure
Each package has its own
source
repository in the
archlinux/packaging/packages
namespace on the Arch Linux
GitLab instance
. Each repository contains the
PKGBUILD
file and files used in official builds. Also some files which are used by the developers for the build process can be found there.
For example, the tree for
acl
looks like this:
acl
├── keys
│   └── pgp
│       ├── 259B3792B3D6D319212CC4DCD5BF9FEB0313653A.asc
│       ├── 600CD204FBCEA418BD2CA74F154343260542DF34.asc
│       └── B902B5271325F892AC251AD441633B9FE837F581.asc
├── PKGBUILD
└── .SRCINFO
The source code for the package is not present in the directory. Instead, the
PKGBUILD
file contains a URL that will download the source code when the package is built.
When an official package is built, it is released into one of the
official repositories
:
core
,
extra
,
multilib
, or some testing repository first. These repositories are
binary
and not hosted on GitLab, but rather served by
mirrors
.
Use cases
The Arch build system automates certain tasks related to compilation from source. Its use cases are:
Any use case that requires you to compile or recompile a package.
Build official binary packages for Arch Linux by developers and packagers.
Make and install new packages from source of software for which no packages are yet available (see
Creating packages
).
Customize existing packages to fit your needs (e.g. enabling or disabling options, patching).
Rebuild your entire system using your compiler flags, "à la FreeBSD".
Cleanly build and install your own custom kernel (see
Kernel compilation
).
Get kernel modules working with a custom kernel.
Easily compile and install a newer, older, beta, or development version of an Arch package by editing the version number in the PKGBUILD.
Usage
Retrieve PKGBUILD source
To retrieve the
PKGBUILD
file required to build a certain package from source, you can either use the
pkgctl
tool or directly use
Git
.
Using the pkgctl tool
As a precondition,
install
the
devtools
package.
pkgctl
is a tool to help work with building source files for Arch Linux packages.
To clone the git repository that contains the latest build files for the package
pkgname
using
pkgctl
, the following command is used:
$ pkgctl repo clone
pkgbase
Tip
This clones over SSH by default so if you have not set an SSH key in your Arch GitLab account, you need to clone over HTTPS:
pkgctl repo clone --protocol=https
pkgbase
.
Note that here, build source files refers to
PKGBUILD
, possibly with some few other required files, such as keys. That is, the essential files that are required for Arch Linux build system. It does not refer to the source files of the package that were written by the team that authored the package, such as C or Python files.
This will give you not only the current source build files, but also their previous versions. Furthermore, you can use all other
git
commands to checkout an older version of the package or to track custom changes.
If you want to get a specific version of a package you can use something like the following:
$ pkgctl repo clone --switch="2:1.19.5-1" go
Do read
pkgctl-repo-clone(1)
for more insight, and for the other commands available.
Using git directly
Use the following git command to clone a package:
$ git clone https://gitlab.archlinux.org/archlinux/packaging/packages/
pkgname
.git
For example, to copy the Apache build files:
$ git clone https://gitlab.archlinux.org/archlinux/packaging/packages/apache.git
Build package
Configure
makepkg
for building packages from the
PKGBUILDs
you have checked out, as explained in
makepkg#Configuration
.
Then, copy the directory containing the
PKGBUILD
you wish to modify to a new location. Make the desired modifications there and use
makepkg
there as described in
makepkg#Usage
to create and install the new package.
Tips and tricks
Preserve modified packages
Updating the system with
pacman
will replace a modified package with the package of the same name from the official repositories. See the following instructions for how to avoid this.
Insert a group array into the
PKGBUILD
, and add the package to a group called
modified
.
PKGBUILD
groups=('modified')
Add this group to the section
IgnoreGroup
in
/etc/pacman.conf
.
/etc/pacman.conf
IgnoreGroup = modified
If new versions are available in the official repositories during a system update, pacman prints a note that it is skipping this update because it is in the IgnoreGroup section. At this point, the modified package should be rebuilt to avoid
partial upgrades
.