APKBUILD Reference

APKBUILDs are the scripts that are created in order to build Alpine packages using the abuild tool.

See aports for details on Alpine's official ports repository.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see Creating an Alpine package.

Legend

The following notes will assist you in understanding this document.

In description text:

• If a variable is not prefixed with a $, it will be represented by italics (i.e., srcdir ).
• Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., build() ).
• Shell commands will be represented like this.

Variables

Note: Variables that contain a path (e.g. $srcdir and $pkgdir) should always be quoted using double quotes (i.e., "$srcdir"). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.

Note: All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (for example, _luaversions).

abuild-defined variables

The following variables are defined by abuild:

startdir

The directory where the APKBUILD script is.

srcdir

The directory where sources, from the source variable, are downloaded to and unpacked to.

pkgdir

This directory should receive the files for the main package. For example, a normal autotools package would have make DESTDIR="$pkgdir" install in the package() function.

subpkgdir

This directory should receive the files for a subpackage. This variable should only be used from subpackage functions.

builddir

This variable should point to the directory inside the srcdir where the main package source is unpacked. This is typically $srcdir/$pkgname-$pkgver. It’s used by the default prepare() function as a working directory when applying patches.

User-defined variables

The following variables should be defined by the user:

arch

Package architecture(s) to build for. Can be one of: x86, x86_64, armhf, aarch64, ppc64le, s390x, all, or noarch, where all means all architectures, and noarch means it's architecture-independent (e.g., a pure-python package).

Tip: To determine if your APKBUILD can use noarch: First specify all and then build the package by executing abuild -r. Watch the output towards the end for warnings saying that noarch can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that noarch can be used, then you can use noarch.

depends

Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.

depends_dev

Run-time dependency package(s) for the $pkgname-dev subpackage.

Note: From ncopa on IRC: To find out if you need to add a package to depends_dev have a look at *requires* in usr/lib/pkgconfig/*.pc. With libtool it gets more complicated, but we should delete the .la files. Also check if there are any /usr/bin/*-configure #!/bin/bash #!/usr/bin/perl or Python. Sometimes scripts or similar are generated at build time (i.e autoconf automake) then you normally don't need add those to depends_dev. You can also just add all -dev makedepends to depends_dev but it will slow the build process a little bit (more build dependencies).

giturl

Git repository from which abuild checkout checks out. You can checkout a specific branch in git by adding -b $branch.

install

There are 6 different types of install scripts. Install scripts are named $pkgname.action, where action can be: pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall, or post-deinstall. For example, if pkgname is set to mypackage and install is set to $pkgname.post-install, then a script named mypackage.post-install must exist along-side the APKBUILD.

Note: Always use /bin/sh for the command-line interpreter on the shebang line of your install scripts.

The following are the different types of install scripts in detail:

$pkgname.pre-install

This script is executed before installing the package. Typical use is when the package needs a group and a user to be created. For example:

#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /bin/false -G clamav -g clamav clamav 2>/dev/null

exit 0

Note: If the script exits with a failure (e.g., if the user already exists), the package will not be installed and apk will exit with failure, hence the exit 0 at the end.

$pkgname.post-install

This script is executed after installing the package.

$pkgname.pre-upgrade

This script is executed before upgrading/downgrading/reinstalling the package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

$pkgname.post-upgrade

This script is executed after upgrading/downgrading/reinstalling the package.

$pkgname.pre-deinstall

This script is executed before uninstalling the package.

Note: If the script exits with failure, apk will not uninstall the package.

$pkgname.post-deinstall

This script is executed after uninstalling the package.

install_if

install_if can be used when a package needs to be installed when some packages are already installed or are in the dependency tree. It works in reverse to the recommends feature, that other package managers provide.

Example: When package A has install_if="B C", and the user runs apk add B C, then package A will get automatically installed.

Example 2: A real use-case in Alpine is open-vm-tools. Currently it contains the userspace tools and separate packages for the kernel modules (grsec and vserver). When we install the userspace tools, apk should automatically install the correct kernel modules and will need to figure out for which kernel. This is where install_if jumps in. For any of the kernel modules package we would use:

install_if="linux-${_flavor}=${_kernelver} open-vm-tools"

This will automatically install the package when the specified packages are installed or are in dependency tree.

license

License(s) for the package, for example GPL-3.0-or-later, BSD-2-Clause or MIT (details).

makedepends

Build-time dependency package(s).

md5sums/sha256sums/sha512sums

Checksums for the files/URLs listed in source. The checksums are normally generated and updated by executing abuild checksum and should be the last item in the APKBUILD.

New packages should use only sha512sums.

options

Build-time options for the package.

Option	Description
!archcheck	Do not try to verify that the architecture of the binary files is the same architecture as abuild should build for. One example where it makes sense to set this are packages with firmware files, that get executed on another CPU (such as WiFi firmware).
!check	Do not try to run the check() function. Please always add a short comment after the !check about why it's disabled. [1] Creating a very simple check function, that calls program --version is better than disabling tests completely. [2]
!strip	Avoid stripping symbols from binaries.
suid	Allow setuid binaries.
!tracedeps	Do not automatically find dependencies (e.g. by using ldd to find dynamic libraries, which the resulting binary links against).

pkgdesc

A brief, one-line description of what the package does.

Here's an example from the OpenSSH client package:

pkgdesc="Port of OpenBSD's free SSH release - client"

pkggroups

System group(s) to be created during build-time. System group(s) should also be created in the $pkgname.pre-install script, so that the system group(s) are also created prior to package installation for run-time use.

pkgname

The name of the package. All letters should be lowercase.

Note: When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: lua-, perl-, php-, and py-. Search aports for other common prefixes.

pkgrel

Alpine package release number. Starts at 0 (zero). Always increment pkgrel when making updates to an aport; reset pkgrel to 0 (zero) when incrementing pkgver.

pkgusers

System user(s) to be created during build-time. System user(s) should also be created in the $pkgname.pre-install script, so that the system user(s) are also created prior to package installation for run-time use.

pkgver

The version of the software being packaged. Format for valid versions: {digit}{.digit}...{letter}{_suf{#}}...{-r#} [3]

A Suffix suf in the above format can be one of the following to indicate that the release is less recent than the version without the suffix: alpha, beta, pre, rc [4]

These are for indicating more recent releases: cvs, svn, git, hg, p [5]

All other suffices are invalid. To package a specific git commit, the date of the commit gets appended to the latest release, e.g. 1.0.0_git20180204.

provides

List of package names (and optionally version info) this package provides.

If package with a version is provided (provides='foo=1.2') apk will consider it as an alternate name and it will automatically consider the package for installation by the alternate name, and conflict with other packages having the same name, or provides.

If version is not provided (provides='foo'), apk will consider it as virtual package name. Several package with same non-versioned provides can be installed simultaneously. However, none of them will be installed by default when requested by the virtual name - instead, error message is given and user is asked to choose which package providing the virtual name should be installed.

provider_priority

A numeric value which is used by apk-tools to break ties when choosing a virtual package to satisfy a dependency. Higher values have higher priority. The primary use case is to specify the primary package that satisfies a virtual (provider).

replaces

Package(s) that this package replaces. This package will "take over" files owned by packages listed in the replaces variable. This is useful when files move from one package to another, or when a package gets renamed.

replaces_priority

The priority of the replaces. If multiple packages replace each other, then will the package with highest replaces_priority win.

source

The source variable is not only used to list the remote source files to fetch, it is also used to list the local files that abuild will need in order to build the apk. Examples of such local files include: init.d files, conf.d files, install files (see install variable), patches, and all other necessary files.

Here are few things to note:

• When you are finished adding local and/or remote files to source, you can execute the following command to add their checksums to the APKBUILD file:

abuild checksum

Note: When later updating the content of source, or updating a file that is listed in source, you must also update their checksums again with the same command.

• When the remote file is hosted at SourceForge, it's best to specify the special mirrors link used by SourceForge:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

• You can set target filename (eg 'save as...') by prefixing the URI with filename::. This is useful when the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:

http://oss.example.org/?get=software&ver=1.0

or when the filename is braindead, like githubs' download tags:

https://github.com/software/software/archive/v$pkgver.tar.gz

The above two examples needs a target filename prefix:

$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver

and:

$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz

• abuild currently supports the following protocols for remote file retrieval:
  • http
  • https
  • ftp

• abuild currently supports the following archive types/archive file extensions in (2.7):
  • .tar.gz / .tgz
  • .tar.bz2
  • .tar.lzma
  • .tar.xz
  • .zip
• abuild master/edge/2.9.1 adds additional support types/archive file extensions for:
  • .tar
  • .tar.lz

Note: Legacy APKBUILD scripts define source variable as "saveas-[brain-dead-url]/[target-filename]" format instead of the modern [target-filename]::[brain-dead-url].
BAD: source="saveas-http://releases.ddvtech.com/download.php?pack=libmist_dist&ver=RC/$pkgname-$pkgver.tar.gz"
GOOD: source=$pkgname-$pkgver.tar.gz::http://releases.ddvtech.com/download.php?pack=libmist_dist&ver=RC"

subpackages

Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must move files that do not belong in the main package, from $pkgdir to $subpkgdir. Files and directories can also be copied from $startdir and $srcdir to $subpkgdir.

The split function can be specified in 1 of 3 different methods:

1. subpkgname:splitfunc
2. $pkgname-splitfunc
3. splitfunc

Note: Split function names cannot use hyphens; use the first method above if the subpackage name contains a hyphen (-) character, like this: subpkg-name:subpkg_name, where subpkg-name is the name of the subpackage and subpkg_name is the name of the subpackage's split function.

Tip: For more information, see the Subpackages example.

triggers

Apk-tools can "monitor" directories and execute a trigger if any package installed/uninstalled any file in the monitored dir. The triggers are always execute after the apk action (install, uninstall, upgrade).

The triggers are specified in the format: scriptname=pathlist where scriptname is the (sub)package name + .trigger suffix and pathlist is : separated list of the dirs to monitor.

The triggers variable must include the triggers for subpackages too if they have any.

It is possible to use wildcards (*) in the dir list.

url

The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

Functions

Note: All functions should consider the current working directory as undefined, and should therefore use the abuild-defined directory variables to their advantage.

sanitycheck() -> clean()-> fetch() -> verify() -> unpack() -> prepare() -> build() -> check() -> package() -> subpackages() -> language packs -> apk -> cleanup()

abuild-defined functions

The following functions are provided by abuild and can be overridden, but it is strongly discouraged on code review for some functions:

fetch()

Downloads remote sources listed in source to SRCDEST (SRCDEST is configured in /etc/abuild.conf) and creates symlinks in $srcdir.

unpack()

unpack() will call default_unpack().

master/edge/2.9.1 behavior: default_unpack() has the same set as 2.7 but adds support for unpacking .tar and .tar.lz from $SRCDEST to $srcdir.

2.7 behavior: default_unpack() unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives from $SRCDEST to $srcdir.

dev()

Subpackage function for the $pkgname-dev package is used to collect developer files and folders for use in other packages in the compilation process nothing more. Without specifying a custom dev() function, abuild will call it's internal dev() function, which in turn calls default_dev().

master/edge/2.9.1 behavior: default_dev() will move any include folder and folders containing *.[acho] (static archive, c source, c header file, object file), *.prl file extension patterns in "$pkgdir"/{lib,usr} to "$subpkgdir"/{lib,usr} recursively; and *.so files from "$pkgdir"/{lib,usr/lib} to "$subpkgdir"/{lib,usr/lib}. It will also scan and move usr/{include,lib/{pkgconfig,cmake,qt*/mkspecs},share/{aclocal,gettext,vala/vapi,gir-[0-9]*,qt*/mkspecs},bin/*-config}} build time folders in $pkgdir and transfer them to $subpkgdir.

2.7 behavior: default_dev() will move any include folder and folders containing *.[acho] (static archive, c source, c header file, object file), *.la file extension patterns in "$pkgdir"/usr to "$subpkgdir"/usr recursively; and *.so files from "$pkgdir"/{lib,usr/lib} to "$subpkgdir"/{lib,usr/lib}. It will also scan and move usr/{include,lib/pkgconfig,share/{aclocal,gettext,vala/vapi,gir-[0-9]*},bin/*-config}} build time folders in $pkgdir and transfer them to $subpkgdir.

In general, default_dev() will support packages that use pkgconfig, c programming language, autotools, gettext, vala programming language, python gobject introspection for both 2.7 and 2.9. Post 2.7 adds additional support for qt and cmake. If you have packages that have c++, other languages, other build system, etc; you need to manually move those developer files.

Important: For default_dev() to be called as in no dev(), you need to explicitly add subpkgdir="$pkgname-dev".

doc()

Subpackage function for the $pkgname-doc package whose job is only to collect documentation folders from $pkgdir nothing more. Without specifying a custom doc() function, abuild will call it's internal doc() function, which in turn calls default_doc().

master/edge/2.9.1 behavior: default_doc() will move the same set as 2.7 but will move 2 more folders "$pkgdir"/usr/share/{ri,help} to $subpkgdir.

2.7 behavior: default_doc() will move "$pkgdir"/usr/share/{doc,man,info,html,sgml,licenses,gtk-doc} to $subpkgdir.

Overriding this function is strongly discouraged. Packaging docs should be done in the package() function while letting abuild automatically collect the doc folders.

User-defined functions

The following functions should be defined by the user:

prepare()

Note: Please adjust old APKBUILDs, which still have a prepare() function that does the same as the default_prepare() when you edit them anyway.

Optional. Used for build preparation: patches, etc, should be applied here. When you don't specify a custom prepare(), the built-in default_prepare() from abuild will be used. It applies patches already (always prepare them in the -p1 format), so usually it makes sense to not create a custom prepare() function at all! If you do create one, call default_prepare() inside it:

prepare() {
    default_prepare
    # your custom code here
}

build()

Required. This is the compilation stage. This function will be called as the current user (unless the package() function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: return 0

To enable or disable CFLAGS, CXXFLAGS, CMake with option, or configure option per arch, use the CARCH variable:

local cmakeoptions=
case "$CARCH" in
        aarch64*|arm*|ppc64le|x86|s390x) cmakeoptions="$cmakeoptions -DWITH_OPENMP=OFF" ;;
        x86_64)                          cmakeoptions="$cmakeoptions -DWITH_OPENMP=ON" ;;
        *)                               msg "Unable to determine architecture from (CARCH=$CARCH)" ; return 1 ;;
esac

The block can be used in other parts of the APKBUILD even in global.

check()

Recommended. This function is called right after the build stage. It should check that the packaged thing is actually working, typically by running (integration) tests, if provided by upstream. If there’s no (easy) way how to test the package, you can declare that it does not want to use check() by adding "!check" into the options variable (options="!check").

package()

Required. This is the packaging stage. Here, the built application and support files should be installed into $pkgdir. If this is a metapackage, this function can contain a single line: mkdir -p "$pkgdir"

Note: Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.

snapshot()

Optional. For live APKBUILDs or those with a _git in their version number, you should create a snapshot function. The purpose of the snapshot function is to create an archive of the source code so that the package source code is deterministic, and it doesn't waste time to fetch the source code but bypasses the download step after snapshotting. Those that download the source code from a git repository will follow head or the latest change to the source code. It is better to archive the source code as a zip / tar.gz / tar.bz2 up to the commit or the tag which you are trying to build a package. If it is not deterministic or not every part of the code frozen in time for every dependency and the main project, then the patches will fail or the package may fail to compile when you revisit the package months or years to backport a patch.

See APKBUILD_examples:Git_checkout to how to use it with git. It takes 2-3 general steps. Clone the repository; check it out at a specific revision/commit or tag; then you use an archiver to dump it in the $SRCDEST variable which points to the distfiles folder and the base path to the full path to the archive that you want to create. You do this for every internal dependency that the package pulls.

After you have created your snapshot function, you use abuild snapshot to run it.

The archives produced by the snapshot will be saved in /var/cache/distfiles. You may need to create symlinks to the archive if the archive is not saved to the Alpine server.

After you snapshot it, you need to produce the checksums with abuild checksum to use it in the APKBUILD creation process.

This feature is available in 2.9 but not in 2.7.

Examples

The APKBUILD examples page will assist you in understanding how to create an APKBUILD.