An APKBUILD file is used by tools such as abuild(1) to
build a package for eventual installation by the apk(8) package manager. It
defines metadata such as the name of the package, the version information,
the source license, and contact information for the developer. It
additionally contains the commands needed to build, test, and install the
package.
The APKBUILD format is similar to a typical shell script;
you set pre-defined variables and implement pre-defined functions, and the
abuild(1) (or similar) utility will use them to create the package.
The following variables must be set in all APKBUILD
files:
pkgname
Specifies the 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 package will allow the user to perform. For example,
“Fully-featured word processor with spell check and 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.
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="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.
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 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.
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.
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).
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 an
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.
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 be needed.
bigdocs
Specifies that this packages 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).
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.
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.
!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.
lib64
Specifies that the package installs files under
/lib64 or /usr/lib64 and that the test for those directories
should be skipped. This is discouraged and should only be used for packages
providing compatibility for GNU libc.
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 implying 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.
setcap
Specifies that binaries in the package may be installed
with extra setcap(8) capabilities. If this option is enabled, it is highly
recommended to only make these binaries executable by root and users of a
specific group, not by others.
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.
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.
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.
depends_doc
Specifies the run-time dependencies of the -doc
subpackage.
depends_libs
Specifies the run-time dependencies of the -libs
subpackage.
depends_openrc
Specifies the run-time dependencies of the -openrc
subpackage.
depends_static
Specifies the run-time dependencies of the -static
subpackage.
giturl
Specifies the URL of the Git repository to use with
`abuild snapshot`. 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 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
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.
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 call
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.