Arch build system - ArchWiki

Jump to content

# Arch build system

From ArchWiki

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.

Categories:

- About Arch
- Package development
- Package management

Arch build system
Add topic