APKBUILD Reference

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

This page is intended to serve as a quick 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 by italics and bold type (i.e., abuild checksum).

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.

Tip: All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., _builddir).

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 contain 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 contain the files for a subpackage. This variable should only be used from subpackage functions.

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

install

Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named $pkgname.{pre,post}-{install,upgrade,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.

license

License(s) for the package.

makedepends

Build-time dependency package(s).

md5sums

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.

options

Build-time options for the package. Can be: !strip - to avoid stripping symbols from binaries.

pkgdesc

Short description of the package.

pkggroups

System group(s) to be created during build-time. System group(s) should also be created in a $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.

Tip: 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 a $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.

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 sub-/package to another, or when a package gets renamed.

source

URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.

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 ways:

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

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.

abuild-defined functions

The following functions are provided by abuild and can be overridden:

fetch()

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

unpack()

Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in $srcdir to $srcdir.

dev()

Subpackage function for the $pkgname-dev package. Without specifying a custom dev() function, abuild will call it's internal dev() function, which in turn calls default_dev(), which will move "$pkgdir"/usr/include, *.a, *.la and similar files to $subpkgdir.

doc()

Subpackage function for the $pkgname-doc package. Without specifying a custom doc() function, abuild will call it's internal doc() function, which in turn calls default_doc(), which will move "$pkgdir"/usr/share/doc, "$pkgdir"/usr/share/man and similar to $subpkgdir.

User-defined functions

The following functions should be defined by the user:

prepare()

Optional. Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.

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

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" && return 0

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.

Examples

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

Subpackages Example

Consider the following APKBUILD snippet:

pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

It will ...

• create the following 5 packages:

1. foo (main)
2. foo-dev (sub)
3. foo-doc (sub)
4. py-foo (sub)
5. libfoo (sub)

• using the following 5 package functions (respectively) to fill them with files:

1. package(): will be provided by the user (and can make use of the $pkgdir variable).
2. dev(): will be provided by abuild unless we override it, by providing our own dev() function (which can make use of the $subpkgdir variable).
3. doc(): will be provided by abuild unless we override it, by providing our own doc() function (which can make use of the $subpkgdir variable).
4. pysub(): will be provided by the user (and can make use of the $subpkgdir variable).
5. libfoo(): will be provided by the user (and can make use of the $subpkgdir variable).

Simple APKBUILD

Simple APKBUILD with -doc subpackage, using abuild's default doc() function:

# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
	gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
	cd "$_builddir"
	patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
	cd "$_builddir"
	./configure --prefix=/usr
	make
}

package() {
	cd "$_builddir"
	make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd  m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe  gnulib-uclibc.patch"

APKBUILD with Multiple Subpackages

A more complex APKBUILD with -doc, -dev and python subpackages:

# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
	largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
	cd "$_builddir"
	for _i in "$srcdir"/*.patch; do
		patch -p1 -i "$_i"
	done
}

build() {
	cd "$_builddir"
	./configure --prefix=/usr \
		--sysconfdir=/etc \
		--mandir=/usr/share/man \
		--infodir=/usr/share/info 
	make
}

package() {
	cd "$_builddir"
	make -j1 DESTDIR="$pkgdir" install
	install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
	cd "$_builddir"
	pkgdesc="$pkgname python bindings"
	install -d "$subpkgdir"/usr/lib
	mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
	pkgdesc="XML utilities"
	replaces="libxml2"
	mkdir -p "$subpkgdir"/usr
	mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86  libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72  largefile64.patch"