.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "APKBUILD" "5" "2024-10-22"
.PP
.SH NAME
.PP
\fBAPKBUILD\fR - metadata and instructions to build a package
.PP
.PP
.SH SYNOPSIS
.PP
/usr/src/packages/<repo>/<package>/APKBUILD
.PP
.PP
.SH DESCRIPTION
.PP
An \fBAPKBUILD\fR 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.\&
.PP
The \fBAPKBUILD\fR 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.\&
.PP
.PP
.SS Required Variables
.PP
The following variables must be set in all \fBAPKBUILD\fR files:
.PP
\fBpkgname\fR
.RS 4
Specifies the name of the package.\& This is typically the name of the
package upstream; however, note that all letters must be lowercased.\&
.PP
Libraries for scripting languages should have a prefix before the
library name describing the language.\& Such prefixes include \fIlua-\fR,
\fIperl-\fR, \fIpy-\fR, and \fIrb-\fR.\& 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.\&
.PP
.RE
\fBpkgver\fR
.RS 4
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).\&
.PP
After the final number (and optional single letter), a suffix may
be appended, which must be an underscore (_) followed by one of
\fIalpha\fR, \fIbeta\fR, \fIpre\fR, \fIrc\fR, \fIcvs\fR, \fIsvn\fR, \fIgit\fR, \fIhg\fR, or \fIp\fR,
optionally followed by another number.\& If the suffix is \fIalpha\fR,
\fIbeta\fR, \fIpre\fR, or \fIrc\fR, it is considered to be earlier than the
version without a suffix; if the suffix is \fIcvs\fR, \fIsvn, \fRgit_, \fIhg\fR,
or \fIp\fR, 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:
.PP
1.\&0, 1.\&1_alpha2, 1.\&1.\&3_pre, 1.\&1.\&3, 1.\&1.\&3_hg, 1.\&2, 1.\&2a, 1.\&2b
.PP
.RE
\fBpkgrel\fR
.RS 4
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 \fBpkgrel\fR when you
change the contents, dependencies, or metadata of a package.\& The
first release of a package is always 0.\&
.PP
.RE
\fBpkgdesc\fR
.RS 4
Specifies what the package contains.\& \fBpkgdesc\fR 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 \fBpkgdesc\fR for AbiWord.\&
.PP
.RE
\fBurl\fR
.RS 4
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 \fBurl\fR to an empty string ("").\&
.PP
.RE
\fBarch\fR
.RS 4
Specifies the architectures for which the package may be built.\& It
is highly recommended that you set this variable to "\fIall\fR" if the
package is portable.\&
.PP
You may use "\fInoarch\fR" 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 "\fIall\fR" is safe.\&
.PP
.RE
\fBlicense\fR
.RS 4
Specifies the license under which the package is distributed.\& The
value provided must match a SPDX license identifier.\&
.PP
.RE
\fBsource\fR
.RS 4
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.\&
.PP
.PP
.RE
.SS Optional Variables
.PP
The following variables are not required, but may be set in any \fBAPKBUILD\fR
file.\&
.PP
\fBcheckdepends\fR
.RS 4
Specifies test-time dependencies of the package.\& Common packages that
are used for testing include check, dejagnu, and perl-test-command.\&
.PP
.RE
\fBdepends\fR
.RS 4
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.\&
.PP
.RE
\fBinstall\fR
.RS 4
Specifies install scripts for the package, if any.\& See \fIInstall
Scripts\fR for more information about install scripts.\&
.PP
.RE
\fBinstall_if\fR
.RS 4
Specifies a condition when apk(8) should automatically install the
package (or subpackage).\& For instance, the OpenRC subpackages set
.PP
.nf
.RS 4
install_if="openrc ${subpkgname%-openrc}=$pkgver-r$pkgrel"
.fi
.RE
.PP
which means that the OpenRC subpackage will be automatically
installed if both OpenRC and the origin package are installed on
the same computer.\&
.PP
.RE
\fBmakedepends\fR
.RS 4
Specifies build dependencies for the package.\&
.PP
.RE
\fBpkggroups\fR
.RS 4
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 \fIInstall Scripts\fR for more
information about install scripts.\&
.PP
.RE
\fBpkgusers\fR
.RS 4
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 \fIInstall Scripts\fR for more
information about install scripts.\&
.PP
.RE
\fBprovides\fR
.RS 4
Specifies that the package "provides" the same contents as another
package.\&  There are two formats that you may use for \fBprovides\fR:
a provider name, and a provider name with version.\&
.PP
Specifying a provider name with version such as \fIfoobar=1.\&2\fR will
cause the package to be an "alias" of \fIfoobar\fR version \fI1.\&2\fR.\& It
will be automatically installed if a user then runs `apk add foobar`
or similar, and it will conflict with a package named \fIfoobar\fR.\&
.PP
Specifying a provider name without a version such as \fIbaz\fR will
cause the package to provide a "virtual" called \fIbaz\fR.\& 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 \fIbaz\fR and must select one and install it.\&
.PP
.RE
\fBprovider_priority\fR
.RS 4
Specifies the numeric value for apk(8) to use for the package when
considering which provider should be installed for the same \fBprovides\fR
virtual provider.\&
.PP
.RE
\fBreplaces\fR
.RS 4
Specifies packages that the package replaces.\& This is typically
used for packages renamed by upstream.\&
.PP
.RE
\fBreplaces_priority\fR
.RS 4
Specifies the numeric value that is used by apk(8) when multiple
packages with \fBreplaces\fR include the same file.\& It is also used
to decide which package should define the permissions of a directory
even without \fBreplaces\fR set.\&
.PP
.RE
\fBsubpackages\fR
.RS 4
Specifies subpackages or split packages built with this
package.\& Typically, this will include \fI$pkgname-dev\fR for development
files (such as \fI/usr/include\fR and static library files) and
\fI$pkgname-doc\fR for documentation (such as \fI/usr/share/doc\fR and
\fI/usr/share/man\fR).\&
.PP
Each subpackage may be specified using three different methods.\& The
first, and most common, is \fI$pkgname-foo\fR where \fIfoo\fR is the name
of the split function specified later in the file.\& Similar to the
\fBpackage\fR function, the \fIfoo\fR function must move files from \fI$pkgdir\fR
or \fI$srcdir\fR to \fI$subpkgdir\fR after creating \fI$subpkgdir\fR.\&
.PP
The second method is to simply call the subpackage \fIfoo\fR which will
create a package called \fIfoo\fR instead of \fI$pkgname-foo\fR.\&
.PP
However, \fIfoo\fR 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: \fIfoo:funcname\fR where \fIfoo\fR is the name
of the subpackage and \fIfuncname\fR is the name of the shell function
in the \fBAPKBUILD\fR that creates it.\&
.PP
.RE
\fBtriggers\fR
.RS 4
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:
.PP
.nf
.RS 4
$pkgname\&.trigger=/usr/share/man:/usr/local/share/man
.fi
.RE
.PP
This will run the package trigger script whenever files in
\fI/usr/share/man\fR or \fI/usr/local/share/man\fR are created, modified,
or removed.\&
.PP
.RE
\fBoptions\fR
.RS 4
The \fBoptions\fR 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.\&
.PP
\fB!\&archcheck\fR
.RS 4
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.\&
.PP
.RE
\fBbigdocs\fR
.RS 4
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).\&
.PP
.RE
\fBcharset.\&alias\fR
.RS 4
Specifies that the package ships a \fI/usr/lib/charset.\&alias\fR
file and that it should be installed on the user'\&s
system.\& This is almost never the case.\& Do not use this option.\&
.PP
.RE
\fB!\&check\fR
.RS 4
Specifies that the package will not run a test suite.\& The
reason for disabling the check phase should be noted in
a comment.\&
.PP
.RE
\fBcheckroot\fR
.RS 4
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.\&
.PP
.RE
\fB!\&dbg\fR
.RS 4
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.\&
.PP
.RE
\fB!\&fhs\fR
.RS 4
Specifies that the package violates FHS and installs to a
location such as \fI/usr/local\fR, \fI/opt\fR, or \fI/srv\fR.\&
.PP
.RE
\fBldpath-recursive\fR
.RS 4
Specifies that abuild(1) should use the \fB--recursive\fR argument
to scanelf(1) when attempting to find shared library (.\&so)
dependencies for the package.\&
.PP
.RE
\fBlib64\fR
.RS 4
Specifies that the package installs files under \fI/lib64\fR
or \fI/usr/lib64\fR 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.\&
.PP
.RE
\fBlibtool\fR
.RS 4
Specifies that the package requires its libtool (.\&la)
files.\& They will not be automatically removed by abuild(1).\&
.PP
.RE
\fBnet\fR
.RS 4
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.\&
.PP
.RE
\fB!\&strip\fR
.RS 4
Specifies that strip(1) should not be run on any of the
package'\&s binaries.\& This is automatically implying if the
\fI-dbg\fR subpackage is enabled, or if you are using DEFAULT_DBG.\&
.PP
.RE
\fBsuid\fR
.RS 4
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.\&
.PP
.RE
\fBsetcap\fR
.RS 4
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.\&
.PP
.RE
\fBtextrels\fR
.RS 4
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.\&
.PP
.RE
\fBtoolchain\fR
.RS 4
Specifies that the package is part of the base toolchain
set and may depend on packages like \fIg++\fR.\&
.PP
.RE
\fB!\&tracedeps\fR
.RS 4
Specifies that abuild(1) should not automatically populate
\fBdepends\fR with shared library (.\&so) or symlink target
dependencies.\&
.PP
.PP
.RE
.RE
.SS Automatic Variables
.PP
The following variables are defined for you by abuild(1), but may be
overridden if necessary.\&
.PP
\fBbuilddir\fR
.RS 4
Specifies the directory where the source code of the package will
be built.\&  The default value is \fI$srcdir/$pkgname-$pkgver\fR which
is appropriate for most source distributions.\& If the source tarball
does not create a \fI$pkgname-$pkgver\fR directory when it is unpacked,
you must override \fBbuilddir\fR.\&
.PP
.RE
\fBpkgdir\fR
.RS 4
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 \fI$startdir/pkg\fR
and you should not modify this variable.\&
.PP
.RE
\fBsrcdir\fR
.RS 4
Specifies the directory where the files specified in \fBsource\fR
are downloaded and unpacked.\& The default value is \fI$startdir/src\fR
and you should not need to modify this.\&
.PP
.RE
\fBstartdir\fR
.RS 4
Specifies the directory where the \fBAPKBUILD\fR file resides.\&
.PP
.RE
\fBsubpkgdir\fR
.RS 4
Specifies the directory where the subpackage'\&s files should be
placed.\& This variable is only set inside subpackage functions.\&
.PP
.PP
.RE
.SS Special Variables
.PP
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.\&
.PP
\fBdepends_dev\fR
.RS 4
Specifies the run-time dependencies of the \fI-dev\fR subpackage.\&
.PP
.RE
\fBdepends_doc\fR
.RS 4
Specifies the run-time dependencies of the \fI-doc\fR subpackage.\&
.PP
.RE
\fBdepends_libs\fR
.RS 4
Specifies the run-time dependencies of the \fI-libs\fR subpackage.\&
.PP
.RE
\fBdepends_openrc\fR
.RS 4
Specifies the run-time dependencies of the \fI-openrc\fR subpackage.\&
.PP
.RE
\fBdepends_static\fR
.RS 4
Specifies the run-time dependencies of the \fI-static\fR subpackage.\&
.PP
.RE
\fBgiturl\fR
.RS 4
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 \fB-b\fR \fIbranch\fR where
\fIbranch\fR is the branch to checkout.\&
.PP
.PP
.RE
.SS Functions
.PP
Functions specified here may be present in any \fBAPKBUILD\fR file, but with
the exception of \fBpackage\fR, are not strictly required.\&
.PP
\fBfetch\fR
.RS 4
This function is called to download the remote files in \fBsource\fR.\&
.PP
.RE
\fBunpack\fR
.RS 4
This function unpacks any archives in \fBsource\fR to \fBsrcdir\fR.\&
.PP
.RE
\fBprepare\fR
.RS 4
Prepares the source in \fBsrcdir\fR to be built.\& The default \fBprepare\fR
function ensures the build directories are set up correctly and
applies any \fI*.\&patch\fR files specified in \fBsource\fR.\& You must call
\fBdefault_prepare\fR if you write a custom \fBprepare\fR function.\&
.PP
.RE
\fBbuild\fR
.RS 4
Compiles the source in \fBbuilddir\fR.\& You must implement this function
yourself.\& If no compilation is required, you may omit it.\&
.PP
.RE
\fBcheck\fR
.RS 4
Runs the package'\&s test suite.\& This function must implemented unless
\fB!\&check\fR was specified in \fBoptions\fR.\&
.PP
.RE
\fBpackage\fR
.RS 4
Installs the package into \fBpkgdir\fR.\& Note that \fBpkgdir\fR 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.\&
.PP
.PP
.RE
.SS Install Scripts
.PP
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 \fI#!\&/bin/sh\fR
interpreter declaration as the first line.\& The \fBinstall\fR variable must
contain the install scripts needed by the package.\&
.PP
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.\&
.PP
The different actions that may have install scripts specified are as follows:
.PP
\fB$pkgname.\&pre-install\fR
.RS 4
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 \fBpkggroups\fR
and \fBpkgusers\fR.\&
.PP
.RE
\fB$pkgname.\&post-install\fR
.RS 4
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.\&
.PP
.RE
\fB$pkgname.\&pre-upgrade\fR
.RS 4
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.\&
.PP
.RE
\fB$pkgname.\&post-upgrade\fR
.RS 4
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.\&
.PP
.RE
\fB$pkgname.\&pre-deinstall\fR
.RS 4
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.\&
.PP
.RE
\fB$pkgname.\&post-deinstall\fR
.RS 4
Executed after the package is removed from the system.\& Exiting with
an error will have no effect.\&
.PP
.PP
.RE
.SH IMPLEMENTATION NOTES
.PP
Currently, \fBAPKBUILD\fR files are sourced as normal shells scripts.\& This may
change at a later date.\&
.PP
.PP
.SH COMPATIBILITY
.PP
The abuild(1) utility as distributed by Alpine Linux uses the BusyBox
Almquist shell, a part of busybox(1) that is currently undocumented.\& It is
mostly compliant with IEEE Std 1003.\&2 (“POSIX.\&2”), with some bash-like
extensions.\& The abuild(1) utility as distributed by Adélie uses the user'\&s
preferred /bin/sh, which is typically bash(1).\&
.PP
.PP
.SH SEE ALSO
.PP
SPDX license reference (on the Web at <https://spdx.\&org/licenses/>),
abuild(1), newapkbuild(1), apk(8), buildrepo(1).\&
.PP
.PP
.SH HISTORY
.PP
The \fBAPKBUILD\fR format and abuild(1) utility first appeared in Alpine
Linux 1.\&9.\&
.PP
.PP
.SH AUTHORS
.PP
Timo Teräs <\fItimo.\&teras@iki.\&fi\fR>
.br
Natanael Copa <\fIncopa@alpinelinux.\&org\fR>
.PP
Documentation:
.br
A.\& Wilcox <\fIawilfox@adelielinux.\&org\fR>
.PP