APKBUILD(5)

📦
version 3.17.0 · 6 versions
, in alpine 3.24

💖 NAME 💖

APKBUILD — the metadata and instructions to build a package. Yes bestie, that's the whole manual (APKBUILD(5)), welcome to the group chat 🫶

✨ SYNOPSIS ✨

/usr/src/packages/<repo>/<package>/APKBUILD

🦋 DESCRIPTION 🦋

okay so an APKBUILD file is what tools like abuild(1) read to build a package, and that package eventually gets installed by the apk(8) package manager. It's literally the whole personality of your package: it defines metadata like the name of the package, the version information, the source license, and contact information for the developer. On top of that it also contains the commands needed to build, test, and install the package. iconic behavior honestly 👑

The APKBUILD format is similar to a typical shell script: you set pre-defined variables and implement pre-defined functions, and abuild(1) (or a similar utility) will use them to create the package. That's it, that's the game 💅

🌸 REQUIRED VARIABLES 🌸

These variables must be set in all APKBUILD files. no skipping, bestie, these are non-negotiable 🎀

pkgname

Specifies the name of the package. This is typically the name of the package upstream — but heads up, all letters must be lowercased. lowercase supremacy fr fr.

Libraries for scripting languages should have a prefix before the library name describing the language. Such prefixes include lua-, perl-, py-, and rb-. Not all languages use prefixes though — for a definitive list, consult the PREFIXES file in the root directory of the repository you're using for packaging. iykyk 🧚

pkgver

Specifies the version of the software being packaged. The version of a package must consist of one or more numbers separated by the radix (decimal point). The final number may have a single letter following it, for upstreams that use such a versioning scheme (such as 1.5a, 1.5b, 1.5c).

After the final number (and optional single letter), one or more suffixes may be appended, which must be an underscore (_) followed by one of alpha, beta, pre, rc, cvs, svn, git, hg, or p, optionally followed by another number. If a suffix is alpha, beta, pre, or rc, it is considered to be earlier than the version without this suffix. If a suffix is cvs, svn, git_, hg, or p, it is considered to be later than the version without this suffix. Sorting lore, honestly 🤓

All of the following examples are valid versions, in order from lowest to highest:

1.0, 1.1_alpha2, 1.1.3_pre, 1.1.3_pre_p2, 1.1.3, 1.1.3_hg, 1.2, 1.2a, 1.2b

pkgrel

Specifies the package release number of this particular package version. This indicates when a package has changed without a corresponding change in version. Always increment pkgrel when you change the contents, dependencies, or metadata of a package. And the first release of a package is always 0 — no cap 🍓

pkgdesc

Specifies what the package contains. pkgdesc must be 128 characters or less, and should concisely describe what actions the software or items being packaged will allow the user to perform. For example, Fully-featured word processor with spell check and plugins would be a sufficient pkgdesc for AbiWord. short, sweet, informative — the trifecta ✨

url

Specifies the Web address of the package's upstream. This allows users and future maintainers to find documentation, release information, and contact information for the package. If no Web address is available for the package, you must set url to an empty string (""). rude but valid 🙈

arch

Specifies the architectures for which the package may be built. It is highly recommended that you set this variable to "all" if the package is portable.

You may use "noarch" if the package does not contain any architecture-specific binary files — that is, any files that are compiled for the target only. Such packages may include pure Python packages, shell script packages, and JARs. If you're not sure what this means, using "all" is safe. when in doubt, "all" it out 💀

Architectures can be negated using the ! character to exclude them from the list of supported architectures. E.g. arch="all !ppc64le" means that the package is allowed to be built on all architectures but the ppc64le architecture.

license

Specifies the license under which the package is distributed. The value provided must match a SPDX license identifier. legality era 👑

source

Specifies the location of both local and remote source files used to build the package. Typically, the remote source file(s) or archive(s) is specified, followed by any local patches, configuration files, or other necessary files.

🌈 OPTIONAL VARIABLES 🌈

These aren't required, but you may set them in any APKBUILD file. the "nice to have" collection 💜

checkdepends

Specifies test-time dependencies of the package. Common packages that are used for testing include check, dejagnu, and perl-test-command.

depends

Specifies the run-time dependencies of the package. The abuild(1) utility will automatically scan the resultant package for shared library (.so) dependencies — do not specify them here. let the tool cook 🔥

install

Specifies install scripts for the package, if any. See Install Scripts for more information about install scripts.

install_if

Specifies a condition when apk(8) should automatically install the package (or subpackage). For instance, the OpenRC subpackages set

install_if="openrc ${subpkgname%-openrc}=$pkgver-r$pkgrel"

which means that the OpenRC subpackage will be automatically installed if both OpenRC and the origin package are installed on the same computer. auto-install slay 🎀

makedepends

Specifies build dependencies for the package.

maintainer

The name and email of the package maintainer in RFC 2822 format. E.g.: maintainer="Joe Q. Public <john.q.public@example.com>". put your name on it, main character energy ⭐

pkggroups

Specifies a space-separated list of login groups to create during build-time. Note that you will need to create the login groups in a pre-install script as well — see Install Scripts for more information about install scripts.

pkgusers

Specifies a space-separated list of user logins to create during build-time. Note that you will need to create the user logins in a pre-install install script as well — see Install Scripts for more information about install scripts.

provides

Specifies that the package "provides" the same contents as another package. There are two formats that you may use for provides: a provider name, and a provider name with version.

Specifying a provider name with version such as foobar=1.2 will cause the package to be an "alias" of foobar version 1.2. It will be automatically installed if a user then runs apk add foobar or similar, and it will conflict with a package named foobar.

Specifying a provider name without a version such as baz will cause the package to provide a "virtual" called baz. Multiple packages with the same virtual provider can be installed on a system; however, if a user runs apk add baz they will be provided a list of packages that provide baz and must select one and install it. choose your fighter 🥊

provider_priority

Specifies the numeric value for apk(8) to use for the package when considering which provider should be installed for the same provides virtual provider.

replaces

Specifies packages that the package should replace files from when both are installed.

replaces_priority

Specifies the numeric value that is used by apk(8) when multiple packages with replaces include the same file. It is also used to decide which package should define the permissions of a directory even without replaces set.

subpackages

Specifies subpackages or split packages built with this package. Typically, this will include $pkgname-dev for development files (such as /usr/include and static library files) and $pkgname-doc for documentation (such as /usr/share/doc and /usr/share/man). splitting the package, splitting the vibe 🦋

By default the split function is the end of the package name after the last hyphen. So for $pkgname-foo and libfoo the split function is foo and libfoo respectively. A custom split function name can be set by using foo:funcname. Similar to the package function, the split function must move files from $pkgdir (which is the default cwd) or $srcdir to $subpkgdir after creating $subpkgdir.

By default arch determines whether or not a subpackage is considered arch independent or not. This can be changed by using foo::noarch or foo:funcname:all.

When multiple subpackages are specified their split functions are executed in the order in which they occur in subpackages. order matters, always 🎯

triggers

Specifies trigger scripts used by the specified (sub)packages. A trigger script is a shell script that is called whenever monitored files or directories are modified. You may specify the paths to monitor using the triggers variable as follows:

$pkgname.trigger=/usr/share/man:/usr/local/share/man

This will run the trigger script for $pkgname whenever files in /usr/share/man or /usr/local/share/man are created, modified, or removed. it's giving watchdog but make it cute 🐶

options

The options variable allows you to set parameters for the package at build time. There are a number of valid options you may set, and you may set multiple options by writing a space between each one. Custom option names can be used when they contain exactly one :. Options can be set for a specific (sub)packages by using subpkgname::option (or subpkgname:option for custom options).

  • !archcheck — Specifies that the package contains binaries that cannot run on the target architecture. This is primarily used for packages containing firmware, and should typically never be needed. im begging you, don't reach for this 😭
  • bigdocs — Specifies that this package intentionally has a large -doc subpackage. Thereby suppressing a warning to be emitted if the -doc subpackage exceeds a certain package size threshold (currently 2 MiB). big docs, big energy 📚
  • charset.alias — Specifies that the package ships a /usr/lib/charset.alias file and that it should be installed on the user's system. This is almost never the case. Do not use this option. like fr fr do not 🚩
  • !check — Specifies that the package will not run a test suite. The reason for disabling the check phase should be noted in a comment. leave a comment bestie, future you will thank you 💜
  • checkroot — Specifies that this package's test suite will be run in fakeroot(8). This is necessary for some test suites which fail when run as non-root. fake it till you make it 👑
  • !dbg — says "bestie, do NOT build a debug info package for this one." It's the default unless DEFAULT_DBG is set in the environment or in abuild.conf(5). You'll usually see it on packages that just don't generate debug info (pure Python packages, looking at you 🐍) or packages that don't support debug info packages at all.
  • !fhs — for the chaotic ones 💀 it declares that the package straight-up violates FHS and installs to a location like /usr/local, /opt, or /srv.
  • ldpath-recursive — tells abuild(1) to pass the --recursive argument to scanelf(1) when it's hunting down shared library (.so) dependencies for the package. Detective mode 🔍.
  • lib64 — the package installs files under /lib64 or /usr/lib64, so skip the test for those directories. It's discouraged ngl, and should only be used for packages providing compatibility for GNU libc.
  • libtool — the package actually needs its libtool (.la) files, so abuild(1) will not automatically remove them. Protect the .la files at all costs 🫶.
  • net — the build system needs access to a network. This is discouraged (!!) and you should file an issue with the package's authors. Network in build = messy vibes 🌐.
  • !strip — do not run strip(1) on any of the package's binaries. This is automatically implying if the DEBUG variable is set.
  • suid — binaries in the package may be installed set-uid. ⚠️ This is a security risk, and it's highly recommended to use capabilities or process separation instead of set-uid where available. Please, bestie, be careful.
  • setcap — binaries in the package may be installed with extra setcap(8) capabilities. If this option is enabled, it's highly recommended to only make these binaries executable by root and users of a specific group — not by others. Lock it down 🔒.
  • textrels — the package's binaries are known to contain relocations against text segments. By default abuild(1) will refuse to create such a package, because that's a security concern. It's giving red flag 🚩.
  • toolchain — the package is part of the base toolchain set and may depend on packages like g++.
  • !tracedeps — abuild(1) should not automatically populate depends and provides with shared library (.so), symlink target dependencies and similar. You're on your own for deps, iykyk.

🌸 Automatic Variables 🌸

These ones are literally defined for you by abuild(1) — but you may override them if you need to. Free real estate ✨.

  • builddir — the directory where the package's source code gets built. Default is $srcdir/$pkgname-$pkgver, which is appropriate for most source distributions. If the source tarball doesn't create a $pkgname-$pkgver directory when it's unpacked, you must override builddir.
  • pkgdir — where the built files get installed. Typically you'll call make DESTDIR="$pkgdir" install or similar to install the files. Default is $startdir/pkg, and you should not modify this variable!
  • srcdir — where the files listed in source get downloaded and unpacked. Default is $startdir/src, and you shouldn't need to modify this one.
  • startdir — the directory where the APKBUILD file lives. This should generally not be used.
  • subpkgdir — where the subpackage's files should be placed. Heads up: this variable is only set inside subpackage functions.

🦋 Special Variables 🦋

Only used in special circumstances, and may be required or optional depending on their usage and the contents of other variables.

  • depends_dev — run-time dependencies of the -dev subpackage.
  • depends_doc — run-time dependencies of the -doc subpackage.
  • depends_libs — run-time dependencies of the -libs subpackage.
  • depends_openrc — run-time dependencies of the -openrc subpackage.
  • depends_static — run-time dependencies of the -static subpackage.
  • depends_systemd — run-time dependencies of the -systemd subpackage.
  • depends_udev — run-time dependencies of the -udev subpackage.
  • giturl — URL of the Git repository to use with abuild snapshot. If the default branch of the repository is not the one you want, you can specify a different one by appending -b branch where branch is the branch to check out.

🎀 Functions 🎀

Functions listed here may be present in any APKBUILD file — but apart from package, they're not strictly required. Pick and choose, main character energy 👑.

  • fetch — called to download the remote files in source.
  • unpack — unpacks any archives in source into srcdir.
  • prepare — prepares the source in srcdir to be built. The default prepare function makes sure the build directories are set up correctly and applies any *.patch files specified in source. You must call default_prepare if you write a custom prepare function! A custom prepare function may also call update_config_sub or update_config_guess to update the config.sub and config.guess files respectively.
  • build — compiles the source in builddir. You have to implement this one yourself. If no compilation is required, you may omit it.
  • check — runs the package's test suite. This function must be implemented unless !check was specified in options. Gotta run those tests 🧪.
  • package — installs the package into pkgdir. Note that pkgdir is not created for you; if this package installs no files (for example, a metapackage), you must use mkdir -p "$pkgdir" to skip the package phase. Small detail, big consequences 😭.

💅 Install Scripts 💅

An install script runs when apk(8) takes an action on a package. It must be written in shell and must have a #!/bin/sh interpreter declaration as the first line. The install variable must contain the install scripts the package needs.

The install script runs inside the root filesystem where the package is being installed. A single argument gets passed to call scripts: the version of the package being currently installed (or deinstalled). The pre-upgrade and post-upgrade scripts get an additional second argument, which specifies the version of the package before the upgrade process. Extra info, slay ✨.

Here are all the actions that may have install scripts:

  • $pkgname.pre-install — executed before the package is installed. If this script exits with an error (non-zero exit code), apk(8) will halt the installation and the package will not be installed. Typically used to create any users or groups needed as described in pkggroups and pkgusers.
  • $pkgname.post-install — executed after the package is installed. If it exits with an error (non-zero exit code), apk(8) will mark the package as broken. The apk fix command will attempt to re-run the post-install script if that happens.
  • $pkgname.pre-upgrade — executed before the package is upgraded. If it exits with an error (non-zero exit code), apk(8) will mark the package as broken.
  • $pkgname.post-upgrade — executed after the package is upgraded. If it exits with an error (non-zero exit code), apk(8) will mark the package as broken. The apk fix command will attempt to re-run the post-upgrade script if that happens.
  • $pkgname.pre-deinstall — executed before the package is removed from the system. If it exits with an error (non-zero exit code), apk(8) will not remove the package from the system.
  • $pkgname.post-deinstall — executed after the package is removed from the system. Exiting with an error will have no effect. No thoughts, head empty 🙈.

🧚 IMPLEMENTATION NOTES 🧚

Currently, APKBUILD files are sourced as normal shell scripts. This may change at a later date. Consider yourself warned, bestie 💀.

🌈 COMPATIBILITY 🌈

The abuild(1) utility as distributed by Alpine Linux uses the BusyBox Almquist shell — a part of busybox(1) that is currently undocumented. It's mostly compliant with IEEE Std 1003.2 ("POSIX.2"), with some bash-like extensions. Meanwhile, the abuild(1) utility as distributed by Adélie uses the user's preferred /bin/sh, which is typically bash(1).

⭐ SEE ALSO ⭐

SPDX license reference (on the Web at <https://spdx.org/licenses/>), abuild(1), newapkbuild(1), apk(8), buildrepo(1), ap(1), checkapk(1).

📜 HISTORY 📜

The APKBUILD format and abuild(1) utility first appeared in Alpine Linux 1.9. OG status fr fr 🫶.

👑 AUTHORS 👑

Timo Teräs <timo.teras@iki.fi> Natanael Copa <ncopa@alpinelinux.org>

Documentation: A. Wilcox <awilfox@adelielinux.org>

That's the whole page, bestie — sourced from the Alpine APKBUILD(5) page dated 2026-06-05, version APKBUILD(5). Go forth and package iconic things 💖✨🎀

📦 where this page comes from