Required Variables

The following variables must be set in all APKBUILD files:

pkgname

Specifies name of the package. This is typically the name of the package upstream; however, note that all letters must be lowercased.

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. For a definitive list, consult the PREFIXES file in the root directory of the repository you are using for packaging.

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), a suffix 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 the suffix is alpha, beta, pre, or rc, it is considered to be earlier than the version without a suffix; if the suffix is cvs, svn, git, hg, or p, it is considered to be later than the version without a suffix. 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, 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. The first release of a package is always 0.

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 many plugins” would be a sufficient pkgdesc for AbiWord.

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 ("").

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 are not sure what this means, using "all" is safe.

license

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

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, install scripts, configuration files, or other necessary files.

Optional Variables

The following variables are not required, but may be set in any APKBUILD file:

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.

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 to $pkgname=$pkgver openrc which means that the OpenRC subpackage will be automatically installed if the origin package and OpenRC are both installed on the same computer.

ldpath

Specifies a colon-separated list of additional paths to scan for shared libraries (.so files).

makedepends

Specifies build dependencies for the package.

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 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 ned 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 provided a list of packages that provide baz and must select one and install it.

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 replaces. This is typically used for packages renamed by upstream.

somask

Specifies a whitespace-separated list of shared object files that should be ignored by APKBUILD when calculating providers and dependencies. For example, internal libraries that are found in ldpath but not in a normal path searched by the dynamic linker should probably be listed here.

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).

Each subpackage may be specified using three different methods. The first, and most common, is $pkgname-foo where foo is the name of the split function specified later in the file. Similar to the package function, the foo function must move files from $pkgdir or $srcdir to $subpkgdir after creating $subpkgdir.

The second method is to simply call the subpackage foo which will create a package called foo instead of pkgname-foo.

However, foo in both of these examples cannot contain a hyphen, as shell function names cannot have hyphens in them. In this case, the third method may be used: foo:funcname where foo is the name of the subpackage and funcname is the name of the shell function in the APKBUILD that creates it.

Note that an additional colon may be used to specify an architecture for the subpackage; typically, this is used for marking miscellaneous files that are not architecture-specific as noarch. For example, $pkgname-doc $pkgname-foo $pkgname-foo-misc:foo_misc:noarch will create the $pkgname-doc package using the doc function, the $pkgname-foo package using the foo function, and the $pkgname-foo-misc package using the foo_misc function and set $pkgname-foo-misc as noarch.

triggers

Specifies a trigger script used by the package. 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 package trigger script whenever files in /usr/share/man or /usr/local/share/man are created, modified, or removed.

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.

!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 need to be used.

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.

!check

Specifies that the package will not run a test suite. The reason for disabling the check phase should be noted in a comment.

checkretry

Specifies that the package's test suite should be re-run multiple times in case of failure. The reason should be noted in a comment. Note that this option and checkroot cannot be used in the same package; checkretry will take precedence.

checkroot

Specifies that the package's test suite will be run in fakeroot(8). This is necessary for some test suites which fail when run as non-root.

checkx11

Specifies that the package's test suite requires a running X11 server. This will spawn a D-Bus session bus connected to an Xvfb on display number 7. The framebuffer can be monitored by running the command xwud -in /tmp/Xvfb_screen0 if desired.

!dbg

Specifies that the package should not be built with a debug information package. This is the default unless DEFAULT_DBG is set in the environment or abuild.conf(5). It is typically used on packages that do not generate debug information (such as pure Python packages) or packages that do not support debug information packages.

!fhs

Specifies that the package violates FHS and installs to a location such as /usr/local, /opt, or /srv.

ldpath-recursive

Specifies that abuild(1) should use the ---recursive argument to scanelf(1) when attempting to find shared library (.so) dependencies for the package.

libtool

Specifies that the package requires its libtool (.la) files. They will not be automatically removed by abuild(1).

net

Specifies that the package build system requires access to a network. This is discouraged and an issue should be filed with the package's authors.

!strip

Specifies that strip(1) should not be run on any of the package's binaries. This is automatically implied if the -dbg subpackage is enabled, or if you are using DEFAULT_DBG.

suid

Specifies that binaries in the package may be installed set-uid. This is a security risk and it is highly recommended to use capabilities or process separation instead of set-uid where available.

textrels

Specifies that the package's binaries are known to contain relocations against text segments. By default, abuild(1) will refuse to create such a package because this is a security concern.

toolchain

Specifies that the package is part of the base toolchain set and may depend on packages like g++.

!tracedeps

Specifies that abuild(1) should not automatically populate depends with shared library (.so) or symlink target dependencies.

Automatic Variables

The following variables are defined for you by abuild(1), but may be overridden if necessary.

builddir

Specifies the directory where the source code of the package will be built. The default value is $srcdir/$pkgname-$pkgver which is appropriate for most source distributions. If the source tarball does not create a $pkgname-$pkgver directory when it is unpacked, you must override builddir.

pkgdir

Specifies the directory where the built files will be installed. Typically, you will call make DESTDIR="$pkgdir" install or similar to install the files. The default value is $startdir/pkg and you should not modify this variable.

srcdir

Specifies the directory where the files specified in source are downloaded and unpacked. The default value is $startdir/src and you should not need to modify this.

startdir

Specifies the directory where the APKBUILD file resides.

subpkgdir

Specifies the directory where the subpackage's files should be placed. This variable is only set inside subpackage functions.

Special Variables

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

depends_dev

Specifies the run-time dependencies of the -dev subpackage.

giturl

Specifies the URL of the Git repository to use with abuild checkout. If the default branch of the repository is not desired, a different one may be specified by appending -b branch where branch is the branch to checkout.

Functions

Functions specified here may be present in any APKBUILD file, but with the exception of package, are not strictly required.

fetch

This function is called to download the remote files in source.

unpack

This function unpacks any archives in source to srcdir.

prepare

Prepares the source in srcdir to be built. The default prepare function ensures 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.

build

Compiles the source in builddir. You must implement this function 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.

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.

Install Scripts

An install script is run when an action is taken on a package by apk(8). An install script 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 needed by the package.

The install script will be run inside the root filesystem where the package is being installed. A single argument will be passed to all scripts, which is the version of the package being currently installed (or deinstalled). The pre-upgrade and post-upgrade scripts will have an additional second argument, which specifies the version of the package before the upgrade process.

The different actions that may have install scripts specified are as follows:

$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. This install script is 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 this script 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 this occurs.

$pkgname.pre-upgrade

Executed before the package is upgraded. If this script 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 this script 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 this occurs.

$pkgname.pre-deinstall

Executed before the package is removed from the system. If this script 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.