Alpine Linux - User contributions [en]

Alpine Package Keeper

2024-01-12T11:56:56Z

Papiris: /* Commit hooks */ : replace advice about symlinking executables, with advice about using absolute paths; for security

{{TOC right}}

Because Alpine Linux is designed to run from RAM, package management involves two phases:
* Installing / Upgrading / Deleting packages on a running system.
* Restoring a system to a previously configured state (e.g. after reboot), including all previously installed packages and locally modified configuration files. '''(RAM-Based Installs Only)'''
 
'''apk''' is the tool used to install, upgrade, or delete software on a running system. 
'''lbu''' is the tool used to capture the data necessary to restore a system to a previously configured state.

This page documents the [https://git.alpinelinux.org/apk-tools/ apk tool] - See the [[Alpine_local_backup|Alpine Local Backup page]] for the lbu tool.

= Overview =

The '''apk''' tool supports the following operations:

{|
| [[#Add a Package|add]]
| Add new packages or upgrade packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| fix
| Attempt to repair or upgrade an installed package
|-
| [[#Update the Package list|update]]
| Update the index of available packages
|-
| [[#Information on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Cache maintenance|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|-
| dot
| Create a [https://graphviz.org/ graphviz] graph description for a given package
|-
| [[#apk_policy|policy]]
| Display the repository that updates a given package, plus repositories that also offer the package
|-
| stats
| Display statistics, including number of packages installed and available, number of directories and files, etc.
|-
| manifest
| Display checksums for files contained in a given package
|}

= Packages and Repositories =

Software packages for Alpine Linux are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata. They have the extension <code>.apk</code>, and are often called "a-packs".

The packages are stored in one or more ''repositories''. A repository is simply a directory with a collection of *.apk files. The directory must include a special index file, named {{Path|APKINDEX.tar.gz}} to be considered a repository.

The '''apk''' utility can install packages from multiple repositories. The list of repositories to check is stored in {{Path|/etc/apk/repositories}}, one repository per line. If you booted from a USB stick ({{Path|/media/sda1}}) or CD-ROM ({{Path|/media/cdrom}}), your repository file probably looks something like this:

{{Cat|/etc/apk/repositories|/media/sda1/apks/}}

In addition to local repositories, the '''apk''' utility uses '''busybox wget''' to fetch packages using ''http:'', ''https:'', ''ftp:'' or ''rsync:'' protocols. The following is a valid repository file:

{{Cat|/etc/apk/repositories|
/media/sda1/apks
http://dl-3.alpinelinux.org/alpine/v2.6/main
https://dl-3.alpinelinux.org/alpine/v2.6/main
ftp://dl-3.alpinelinux.org/alpine/v2.6/main
}}

{{Note| A list of public repositories is in [https://mirrors.alpinelinux.org/ mirrors.alpinelinux.org]. Accepted protocols vary.}}

== Repository pinning ==

You can specify additional "tagged" repositories in {{Path|/etc/apk/repositories}}:

{{Cat|/etc/apk/repositories|
https://dl-cdn.alpinelinux.org/alpine/v3.18/main
https://dl-cdn.alpinelinux.org/alpine/v3.18/community
@personal https:/personal-repo.example.com/alpine-apks/
}}

After which you can "pin" dependencies to these tags using:

{{cmd|apk add application@personal}}

apk will by default only use the untagged repositories, but adding a package with a @tag:

1. will prefer the repository with that tag for the named package, even if a later version of the package is available in another repository

2. ''allows'' pulling in dependencies for the tagged package from the tagged repository (though it ''prefers'' to use untagged repositories to satisfy dependencies if possible)

== Commandline repository options ==

By default, the '''apk''' utility will use the system repositories for all operations. This behavior can be overridden by the following options:

{|
| --repositories-file REPOFILE
| Override the system repositories by specifying a repositories file.
|-
| <nowiki>-X|--repository REPO</nowiki>
| Specify a supplemental repository that will be used in addition to the system repositories. This option can be provided multiple times.
|}

= Update the Package list =

Remote repositories change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. The command downloads the {{Path|APKINDEX.tar.gz}} from each repository and stores it in the local cache, typically {{Path|/var/cache/apk/}}, {{Path|/var/lib/apk/}} or {{Path|/etc/apk/cache/}}.

{{Cmd|apk update}}



Adding the <code>--update-cache</code>, or for short <code>-U</code> switch to another apk command, as in <code>apk --update-cache upgrade</code> or <code>apk -U add ...</code>, the command has the same effect as first running <code>apk update</code> before the other apk command.

{{Tip|With remote repositories, it is a good idea to always do an '''update''' right '''before''' doing an '''upgrade or add''' command. That way the command will install the latest available packages.}}

= Add a Package =

Use '''add''' to install packages from a repository. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package.

{{Cmd|apk add openssh
apk add openssh openntp vim}}

If you only have the main repository enabled in your configuration, apk will not include packages from the other repositories. To install a package from the edge/testing repository without changing your repository configuration file, use the command below. This will tell apk to use that particular repository.

{{cmd|apk add cherokee --update-cache --repository https://dl-cdn.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}

{{Note|Be careful when using third-party or the testing repository. Your system can go down.}}

= Add a local Package =

To install a locally available apk package, for example if this device has no internet access but you can upload apk packages directly to it, use the '''--allow-untrusted''' flag:

{{cmd|apk add --allow-untrusted /path/to/file.apk}}

Note that multiple packages can be given. When installing a local package, all dependencies should also be specified. For example:

{{cmd|apk add --allow-untrusted /var/tig-2.2-r0.apk /var/git-2.11.1-20.apk}}

= Remove a Package =
Use '''del''' to remove a package (and dependencies that are no longer needed.)

{{cmd|apk del openssh
apk del openssh openntp vim}}

= Upgrade a Running System =

=== Packages in general ===

To get the latest security upgrades and bugfixes available for the ''installed'' packages of a running system, first '''update''' the list of available packages and then '''upgrade''' the installed packages:

{{cmd|apk update
apk upgrade
}}

Or, combining the same into one single command:

{{cmd|apk -U upgrade
}}

Here is an example, showing the procedure on a system that has several additional [[#Repository_pinning|repositories pinned]]:

# apk update
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz</nowiki>
v3.6.2-191-gf98d79930f <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/main]</nowiki>
v3.6.2-190-ga5d68c47df <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/community]</nowiki>
v3.6.0-4618-g0bf77c9821 <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/main]</nowiki>
v3.6.0-4605-g85ed51dd83 <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/community]</nowiki>
v3.6.0-4624-g11f1b9c8ab <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/testing]</nowiki>
OK: 20118 distinct packages available

# apk upgrade
(1/2) Upgrading extra-cmake-modules@testing (5.38.0-r0 -> 5.39.0-r0)
(2/2) Upgrading extra-cmake-modules-doc@testing (5.38.0-r0 -> 5.39.0-r0)
Executing mdocml-apropos-1.14.1-r0.trigger
OK: 2635 MiB in 803 packages

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them:

{{cmd|apk update
apk upgrade busybox
}}

To enable unattended, automatic upgrades of packages, see the {{pkg|apk-autoupdate}} package.

To upgrade to a newer release, refer to the corresponding release notes and [[Upgrading_Alpine]].

=== Upgrading "diskless" and "data" disk mode installs ===

If booting a "diskless" system from a read-only device, or iso image on writable media, it's not possible to update the boot files (kernel, modules, firmware, ...) that reside on that device.

It becomes possible to update the boot files, though, if using a boot device that is writable and has been prepared with <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code>.

However, even then, the kernel, with its modules and firmware files, can still not be updated directly through regular packages updates. Instead, there is the <code>update-kernel</code> script that can generate initfs images and install them together with upgraded kernels.

Upgrading can be done as follows.
{{cmd|apk add mkinitfs
}}
This package is required for the generation of the initial filesystem used during boot.
* Additional initfs features that are missing in the default configuration, like the [[Btrfs|btrfs]] filesystem support (at the time of writing, to allow loading .apkovl configs and package cache during boot), may be enabled in <code>/etc/mkinitfs/mkinitfs.conf</code>.
* Available initfs features may be listed with <code>ls /etc/mkinitfs/features.d</code>
{{cmd|ls /etc/mkinitfs/features.d
apk add nano
nano /etc/mkinitfs/mkinitfs.conf
lbu commit
}}
Finally update the kernel and its boot environment.
{{cmd|update-kernel /media/sdXY/boot/
}}
* An <code>update-kernel</code> run needs at least 8 GB free ram memory to avoid a broken modloop-image.
* See <code>update-kernel --help</code> for options to manually add additional module or firmware packages.

= Search for Packages =
The '''search''' command searches the repository Index files for installable packages.

The return format is '''Package'''-'''Version'''. Omit '''Version''' for ''apk add '''Package'''''

Examples:
* To list all packages available, along with their descriptions: {{cmd|apk search -v}}
* To list all packages are part of the ACF system: {{cmd|apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description, use the ''-d'' or ''--description'' option: {{cmd|apk search -v --description 'NTP' }}

= Information on Packages =

== apk info ==

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information), or all information displayed with the ''-a'' command.

Example: {{cmd|apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>https://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package (''-d'' or ''--description'')
* The '''webpage''' where the application is hosted (''-w'' or ''--webpage'')
* The '''size''' the package will require once installed (in bytes) (''-s'' or ''--size'')
* What packages are required to use this one ('''depends''') (''-R'' or ''--depends'')
* What packages require this one to be installed ('''required by''') (''-r'' or ''--rdepends'')
* The '''contents''' of the package, that is, which files it installs (''-L'' or ''--contents'')
* Any '''triggers''' this package sets. (''-t'' or ''--triggers'') Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

{{Tip|The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|apk info --who-owns /sbin/lbu}} will display

/sbin/lbu is owned by alpine-conf-x.x-rx
}}

=== Listing installed packages ===

To list all installed packages, use:

{{Cmd|apk info}}

To list all installed packages in alphabetical order, with a description of each, do:

{{Cmd|apk -vv info|sort}}

The apk tool does not have a subcommand to list manually-installed packages that do not have reverse dependencies. To get this information on a traditional system that is not using [[Alpine local backup|lbu]], try this script. Note that this approach will also list core packages like alpine-base that should not be removed.

<pre>#!/bin/sh
apk info | grep -ve '-doc$' | sort | while read pkg
do
rdep=`apk info -qr "$pkg"`
[ -z "$rdep" ] && echo $pkg
done</pre>

== apk policy ==

To display the repository a package was installed from and will be updated from, plus any [[#Repository_pinning|tagged]] or enabled repositories where it is also offered, if any, for this architecture - its '''policy''':

{{Cmd|apk policy ''package''}}

For example:
<pre>
$ apk policy vlc
vlc policy:
2.2.6-r1:
lib/apk/db/installed
https://dl-3.alpinelinux.org/alpine/v3.7/community
3.0.0_rc2-r1:
@edgecommunity https://dl-3.alpinelinux.org/alpine/edge/community
</pre>

= Additional apk Commands =
In progress...

= Local Cache =

{{:Local_APK_cache}}

= Advanced APK Usage =

== Holding a specific package back ==

In certain cases, you may want to upgrade a system, but keep a specific package at a back level. It is possible to add "sticky" or versioned dependencies. For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:
{{cmd|1=apk add asterisk=1.6.0.21-r0}}
or
{{cmd|apk add 'asterisk<1.6.1'}}

after which a {{cmd|apk upgrade}}

will upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level

To later upgrade to the current version,

{{cmd|apk add 'asterisk>1.6.1'}}

will ensure that 1.6.1 is the minimum version used.

You can also use "fuzzy" version matching to pin the version to a major/minor release. For example:

{{cmd|1=apk add 'asterisk=~1.6'}}

will match any version of asterisk that starts with 1.6 (such as 1.6.0.21-r0 or 1.6.9.31-r9) <ref>[https://git.alpinelinux.org/apk-tools/commit/?id=693b4bcdb0f22904a521a7c8ac4f13e697dc4d71 Alpine source commit message]</ref>

If you desire deterministic, repeatable package installation (such as with containerized environments) via package pinning, it is important to understand your package repo's version retention rules. For example, most Alpine package repos contain an "edge" branch, which may drop package versions that are not deemed fit to make it into a stable branch. This means that pinning to a version on the edge branch may stop working after the package version is revoked from the repo. Always pin to a package version that is intended for your current Alpine Linux version.

== Commit hooks ==

If you'd like to trigger an action or run a certain script on every commit made by apk, there's a built-in method for that. On every commit apk looks for executables located in the "/etc/apk/commit_hooks.d/" directory, and executes them both before and after the commit. To provide some way to selectively run hooks either before or after a change is commited by apk, the scripts are called with "pre-commit" or "post-commit" as argument 1.
This is an example of a hook to do different things before and after commit:

{{cmd|1=#!/bin/sh

if [ "$1" = "pre-commit" ]; then
do_something

elif [ "$1" = "post-commit" ]; then
do_something_else
fi}}

Commit hooks are $PATH-aware, so for the sake of security it's recommended to specify absolute paths to executables.
 

= Table of comparison with other Linux/Unix-like OSes for packages =

{| class="wikitable"
|-
! OS !! File Format !! Tools
|-
| Alpine || .apk || apk
|-
| Debian || .deb || apt, aptitude, dpkg
|-
| Gentoo || .tbz2 || emerge
|-
| FreeBSD || .txz || pkg
|}

 

= Troubleshooting =

== "apk-tools is old" ==

'''apk update''', '''apk upgrade''' or '''apk add''' may report the following:
WARNING: This apk-tools is OLD! Some packages might not function properly

This may happen if you are running Alpine Linux stable version with a certain edge/main, edge/community or testing package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge is already [https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management#Repository_pinning tagged] in your repositories, then try:

{{Cmd|apk add --upgrade apk-tools@edge}}

== ERROR: UNTRUSTED signature ==

This happens when the release version changes. You need to update the local apk keys.

If you have already updated your repositories, allow them to update without the trusted key:
{{Cmd|apk update --allow-untrusted}}

Then install the keys upgrade:
{{Cmd|apk fix --upgrade --allow-untrusted alpine-keys}}

Now updates and upgrades should proceed normally.

Alternative, the updated alpine-keys package may be obtained, verified, installed directly, as covered earlier, prior to a repository update.

= External Links =
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples] Vivek Gite 2019

[[Category:Package Manager]]

Talk:Governance

2024-01-04T10:43:39Z

Papiris: question: is governance information still valid?

This page was last edited four years ago, and currently has no pages linking to it.

Is the information still valid?
If so, maybe we should make it more easily reached.

If not, maybe we should revise it and then make it more easily reached.

User:Papiris

2023-11-26T16:09:59Z

Papiris: Add user papiris

[https://hackaday.io/papiris Maintainer and developer of Free software, -hardware and -culture projects ]

Alpine Linux:Glossary

2023-11-23T16:50:53Z

Papiris: Add entry for "community" repo

{{TOC right}}
The Glossary is an extensive list of terms and Alpine Linux features with definitions and considerable explanations. A great place for reference and general browsing.

== A ==


{{Define|abuild|The tool to build packages from sources using APKBUILD is [[Abuild and Helpers|abuild]].
}}

{{Define|ACF|'''A'''lpine Linux '''C'''onfiguration '''F'''ramework is an [[Glossary#MVC |mvc-style]] application for configuring an Alpine Linux device. The primary focus is for a web interface - ACF's main goal is to be a light-weight MVC "[https://en.wikipedia.org/wiki/Webmin webmin]".
}}

{{Define|apk|'''A'''lpine Linux '''P'''ackage '''K'''eeper - A) The [[:category:Package Manager |package manager]] for Alpine, used to install, query and remove software packages on a running Alpine system. Also the suffix of the binary packages, even if those basically are gzipped tar files.
}}

{{Define|APKBUILD|A build recipe that is used to build Alpine packages for ''apk''. It holds information of package name, version, license, dependencies, sources etc and how to compile the sources and package the binaries.
}}

{{Define |apkovl |[[Alpine local backup#Committing_your_changes |'''A'''pkovl]] is a file storing configuration files that have changed from the default ones. It is used when running from ram. The contents are overlaid on top of the contents of the apks that are loaded on boot. The filename is <hostname>.apkovl.tar.gz and is stored on removable media whose path is defined in /etc/lbu/lbu.conf.
}}

== B ==
{{Define|Busybox| [https://www.busybox.net/ Busybox] is a utility that combines many common Linux tools into a single program. Most of the command-line tools in the core Alpine distribution are part of Busybox.
}}


{{Define|bash| [https://www.gnu.org/software/bash/ bash] is a command-line interpreter or "shell" that provides a command line user interface.
}}

== C ==
{{Define|cgit|[https://git.zx2c4.com/cgit/ cgit] provides easy access to all [https://git.alpinelinux.org/ git repositories] hosted on the Alpine infrastructure.
}}

{{Define|community|The so-called [https://nl.alpinelinux.org/alpine/edge/community/ <tt>community</tt>] repository contains software. Packages in community are considered stable, but aren't considered as vital as those in the main repository.
}}



== E ==
{{Define|edge|[[Repositories#Edge|edge]] is the name of the development tree of Alpine Linux.
}}

== F ==
{{Define |Flatpak |[[Flatpak]] is a technology for distributing [[:category: desktop |desktop]] applications on GNU/Linux.
}}

== G ==
{{Define|git|The distributed version control system that Alpine uses. ([[:category: Git]])}}



== I ==
{{Define|IRC| Internet Relay Chat (IRC) is a protocol for Internet text messaging in real-time. Alpine-specific details can be found [[IRC| here]].}}



== L ==
{{Define|lbu|[[Alpine local backup |Local Backup Utility]]. A tool to make backups of user configuration. Since the system typically runs from RAM, '''lbu''' is used to save the state of the system to a file that is restored to bring the system back to its previous state.
}}

{{Define|LEAF|Linux Embedded Appliance Framework. Alpine Linux started as a fork of the LEAF project. A secure, feature-rich, customizable embedded Linux network appliance for use in a variety of network topologies. Although it can be used in other ways; it's primarily used as a Internet gateway, router, firewall, and wireless access point.
}}

== M ==
{{Define|main|The so-called [https://nl.alpinelinux.org/alpine/v3.10/main/ <tt>main</tt>] repository contains software. Those packages are mature.
}}

{{Define|MVC|The [https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller MVC] design pattern is used in ACF to separate presentation information from control logic. By MVC we mean:
:*'''M'''odel - code that reads / writes a config file, starts / stops daemons, or does other work modifying the router.
:*'''V'''iew - code that formats data for output
:*'''C'''ontroller - code that glues the two together
}}

{{Define|mkinitfs|Tool to generate the [https://en.wikipedia.org/wiki/Initial_ramdisk initramfs image] for the kernel.
}}

{{Define|modloop|Loopback [https://en.wikipedia.org/wiki/Cramfs cramfs] image where kernel modules are stored for tmpfs installs.
}}

{{define |musl |[https://www.etalabs.net/compare_libcs.html musl] is a C standard library implementation for GNU/Linux. Musl libc is not [https://en.wikipedia.org/wiki/Application_binary_interface ABI] compatible with [[Running_glibc_programs | uClibc]].
}}

== N ==
{{Define|NTP|Network Time Protocol ([https://en.wikipedia.org/wiki/Network_Time_Protocol NTP]) is a protocol for synchronizing the clocks of computer systems. Alpine provides <tt>[[Alpine setup scripts#setup-ntp|setup-ntp]]</tt> for setting up.''([http://lists.busybox.net/pipermail/busybox/2014-September/081668.html What's the easiest way to make Busybox keep correct time?] 2014)''}}{{insecure url|Server presents invalid certificate}}

== O ==
{{Define|OpenRC|[https://wiki.gentoo.org/wiki/Project:OpenRC OpenRC] is a dependency based universal init system that works with the system provided [[Writing Init Scripts | init program]].
}}



== S ==
{{Define|setup-*|Alpine contains a lot of scripts to configure a system. All those scripts start with <tt>setup-*</tt>. The most important one is <tt>[[Setup-alpine|setup-alpine]]</tt>.(<tt>find / -name setup* -print | sort</tt>)
}}

== T ==
{{Define|testing|The so-called <tt>testing</tt> repository contains software packages which are new/untested/experimental.
}}

{{Define|tmpfs|[https://en.wikipedia.org/wiki/Tmpfs tmpfs] is a filesystem that exists in (virtual) memory only, like a [https://en.wikipedia.org/wiki/RAM_drive RAM disk].}}

== U ==
{{Define|uClibc| [https://en.wikipedia.org/wiki/UClibc uClibc] (aka µClibc/pronounced yew-see-lib-see) is a C library for developing embedded Linux systems. It is much smaller than the [https://www.gnu.org/software/libc/libc.html GNU C Library], but nearly all applications supported by glibc also work perfectly with uClibc.
}}

== V ==
{{Define|vServer|[https://en.wikipedia.org/wiki/Linux-VServer Linux-VServer] provides virtualization for GNU/Linux systems by kernel level isolation. This way it's possible to run multiple virtual units at once.}}



== X ==
{{Define|Xfce| [https://www.xfce.org/ Xfce] is a lightweight [[:category: desktop |desktop environment]] that is available in the Alpine Linux repositories.
}}



[[category: Newbie]]

Alpine Package Keeper

2023-11-12T20:29:11Z

Papiris: /* Advanced APK Usage */ : Add paragraph about apk commit hooks

{{TOC right}}

Because Alpine Linux is designed to run from RAM, package management involves two phases:
* Installing / Upgrading / Deleting packages on a running system.
* Restoring a system to a previously configured state (e.g. after reboot), including all previously installed packages and locally modified configuration files. '''(RAM-Based Installs Only)'''
 
'''apk''' is the tool used to install, upgrade, or delete software on a running system. 
'''lbu''' is the tool used to capture the data necessary to restore a system to a previously configured state.

This page documents the [https://git.alpinelinux.org/apk-tools/ apk tool] - See the [[Alpine_local_backup|Alpine Local Backup page]] for the lbu tool.

= Overview =

The '''apk''' tool supports the following operations:

{|
| [[#Add a Package|add]]
| Add new packages or upgrade packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| fix
| Attempt to repair or upgrade an installed package
|-
| [[#Update the Package list|update]]
| Update the index of available packages
|-
| [[#Information on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Cache maintenance|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|-
| dot
| Create a [https://graphviz.org/ graphviz] graph description for a given package
|-
| [[#apk_policy|policy]]
| Display the repository that updates a given package, plus repositories that also offer the package
|-
| stats
| Display statistics, including number of packages installed and available, number of directories and files, etc.
|-
| manifest
| Display checksums for files contained in a given package
|}

= Packages and Repositories =

Software packages for Alpine Linux are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata. They have the extension <code>.apk</code>, and are often called "a-packs".

The packages are stored in one or more ''repositories''. A repository is simply a directory with a collection of *.apk files. The directory must include a special index file, named {{Path|APKINDEX.tar.gz}} to be considered a repository.

The '''apk''' utility can install packages from multiple repositories. The list of repositories to check is stored in {{Path|/etc/apk/repositories}}, one repository per line. If you booted from a USB stick ({{Path|/media/sda1}}) or CD-ROM ({{Path|/media/cdrom}}), your repository file probably looks something like this:

{{Cat|/etc/apk/repositories|/media/sda1/apks/}}

In addition to local repositories, the '''apk''' utility uses '''busybox wget''' to fetch packages using ''http:'', ''https:'', ''ftp:'' or ''rsync:'' protocols. The following is a valid repository file:

{{Cat|/etc/apk/repositories|
/media/sda1/apks
http://dl-3.alpinelinux.org/alpine/v2.6/main
https://dl-3.alpinelinux.org/alpine/v2.6/main
ftp://dl-3.alpinelinux.org/alpine/v2.6/main
}}

{{Note| A list of public repositories is in [https://mirrors.alpinelinux.org/ mirrors.alpinelinux.org]. Accepted protocols vary.}}

== Repository pinning ==

You can specify additional "tagged" repositories in {{Path|/etc/apk/repositories}}:

{{Cat|/etc/apk/repositories|
https://dl-cdn.alpinelinux.org/alpine/v3.18/main
https://dl-cdn.alpinelinux.org/alpine/v3.18/community
@personal https:/personal-repo.example.com/alpine-apks/
}}

After which you can "pin" dependencies to these tags using:

{{cmd|apk add application@personal}}

apk will by default only use the untagged repositories, but adding a package with a @tag:

1. will prefer the repository with that tag for the named package, even if a later version of the package is available in another repository

2. ''allows'' pulling in dependencies for the tagged package from the tagged repository (though it ''prefers'' to use untagged repositories to satisfy dependencies if possible)

== Commandline repository options ==

By default, the '''apk''' utility will use the system repositories for all operations. This behavior can be overridden by the following options:

{|
| --repositories-file REPOFILE
| Override the system repositories by specifying a repositories file.
|-
| <nowiki>-X|--repository REPO</nowiki>
| Specify a supplemental repository that will be used in addition to the system repositories. This option can be provided multiple times.
|}

= Update the Package list =

Remote repositories change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. The command downloads the {{Path|APKINDEX.tar.gz}} from each repository and stores it in the local cache, typically {{Path|/var/cache/apk/}}, {{Path|/var/lib/apk/}} or {{Path|/etc/apk/cache/}}.

{{Cmd|apk update}}



Adding the <code>--update-cache</code>, or for short <code>-U</code> switch to another apk command, as in <code>apk --update-cache upgrade</code> or <code>apk -U add ...</code>, the command has the same effect as first running <code>apk update</code> before the other apk command.

{{Tip|With remote repositories, it is a good idea to always do an '''update''' right '''before''' doing an '''upgrade or add''' command. That way the command will install the latest available packages.}}

= Add a Package =

Use '''add''' to install packages from a repository. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package.

{{Cmd|apk add openssh
apk add openssh openntp vim}}

If you only have the main repository enabled in your configuration, apk will not include packages from the other repositories. To install a package from the edge/testing repository without changing your repository configuration file, use the command below. This will tell apk to use that particular repository.

{{cmd|apk add cherokee --update-cache --repository https://dl-cdn.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}

{{Note|Be careful when using third-party or the testing repository. Your system can go down.}}

= Add a local Package =

To install a locally available apk package, for example if this device has no internet access but you can upload apk packages directly to it, use the '''--allow-untrusted''' flag:

{{cmd|apk add --allow-untrusted /path/to/file.apk}}

Note that multiple packages can be given. When installing a local package, all dependencies should also be specified. For example:

{{cmd|apk add --allow-untrusted /var/tig-2.2-r0.apk /var/git-2.11.1-20.apk}}

= Remove a Package =
Use '''del''' to remove a package (and dependencies that are no longer needed.)

{{cmd|apk del openssh
apk del openssh openntp vim}}

= Upgrade a Running System =

=== Packages in general ===

To get the latest security upgrades and bugfixes available for the ''installed'' packages of a running system, first '''update''' the list of available packages and then '''upgrade''' the installed packages:

{{cmd|apk update
apk upgrade
}}

Or, combining the same into one single command:

{{cmd|apk -U upgrade
}}

Here is an example, showing the procedure on a system that has several additional [[#Repository_pinning|repositories pinned]]:

# apk update
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz</nowiki>
v3.6.2-191-gf98d79930f <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/main]</nowiki>
v3.6.2-190-ga5d68c47df <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/community]</nowiki>
v3.6.0-4618-g0bf77c9821 <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/main]</nowiki>
v3.6.0-4605-g85ed51dd83 <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/community]</nowiki>
v3.6.0-4624-g11f1b9c8ab <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/testing]</nowiki>
OK: 20118 distinct packages available

# apk upgrade
(1/2) Upgrading extra-cmake-modules@testing (5.38.0-r0 -> 5.39.0-r0)
(2/2) Upgrading extra-cmake-modules-doc@testing (5.38.0-r0 -> 5.39.0-r0)
Executing mdocml-apropos-1.14.1-r0.trigger
OK: 2635 MiB in 803 packages

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them:

{{cmd|apk update
apk upgrade busybox
}}

To enable unattended, automatic upgrades of packages, see the {{pkg|apk-autoupdate}} package.

To upgrade to a newer release, refer to the corresponding release notes and [[Upgrading_Alpine]].

=== Upgrading "diskless" and "data" disk mode installs ===

If booting a "diskless" system from a read-only device, or iso image on writable media, it's not possible to update the boot files (kernel, modules, firmware, ...) that reside on that device.

It becomes possible to update the boot files, though, if using a boot device that is writable and has been prepared with <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code>.

However, even then, the kernel, with its modules and firmware files, can still not be updated directly through regular packages updates. Instead, there is the <code>update-kernel</code> script that can generate initfs images and install them together with upgraded kernels.

Upgrading can be done as follows.
{{cmd|apk add mkinitfs
}}
This package is required for the generation of the initial filesystem used during boot.
* Additional initfs features that are missing in the default configuration, like the [[Btrfs|btrfs]] filesystem support (at the time of writing, to allow loading .apkovl configs and package cache during boot), may be enabled in <code>/etc/mkinitfs/mkinitfs.conf</code>.
* Available initfs features may be listed with <code>ls /etc/mkinitfs/features.d</code>
{{cmd|ls /etc/mkinitfs/features.d
apk add nano
nano /etc/mkinitfs/mkinitfs.conf
lbu commit
}}
Finally update the kernel and its boot environment.
{{cmd|update-kernel /media/sdXY/boot/
}}
* An <code>update-kernel</code> run needs at least 8 GB free ram memory to avoid a broken modloop-image.
* See <code>update-kernel --help</code> for options to manually add additional module or firmware packages.

= Search for Packages =
The '''search''' command searches the repository Index files for installable packages.

The return format is '''Package'''-'''Version'''. Omit '''Version''' for ''apk add '''Package'''''

Examples:
* To list all packages available, along with their descriptions: {{cmd|apk search -v}}
* To list all packages are part of the ACF system: {{cmd|apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description, use the ''-d'' or ''--description'' option: {{cmd|apk search -v --description 'NTP' }}

= Information on Packages =

== apk info ==

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information), or all information displayed with the ''-a'' command.

Example: {{cmd|apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>https://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package (''-d'' or ''--description'')
* The '''webpage''' where the application is hosted (''-w'' or ''--webpage'')
* The '''size''' the package will require once installed (in bytes) (''-s'' or ''--size'')
* What packages are required to use this one ('''depends''') (''-R'' or ''--depends'')
* What packages require this one to be installed ('''required by''') (''-r'' or ''--rdepends'')
* The '''contents''' of the package, that is, which files it installs (''-L'' or ''--contents'')
* Any '''triggers''' this package sets. (''-t'' or ''--triggers'') Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

{{Tip|The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|apk info --who-owns /sbin/lbu}} will display

/sbin/lbu is owned by alpine-conf-x.x-rx
}}

=== Listing installed packages ===

To list all installed packages, use:

{{Cmd|apk info}}

To list all installed packages in alphabetical order, with a description of each, do:

{{Cmd|apk -vv info|sort}}

The apk tool does not have a subcommand to list manually-installed packages that do not have reverse dependencies. To get this information on a traditional system that is not using [[Alpine local backup|lbu]], try this script. Note that this approach will also list core packages like alpine-base that should not be removed.

<pre>#!/bin/sh
apk info | grep -ve '-doc$' | sort | while read pkg
do
rdep=`apk info -qr "$pkg"`
[ -z "$rdep" ] && echo $pkg
done</pre>

== apk policy ==

To display the repository a package was installed from and will be updated from, plus any [[#Repository_pinning|tagged]] or enabled repositories where it is also offered, if any, for this architecture - its '''policy''':

{{Cmd|apk policy ''package''}}

For example:
<pre>
$ apk policy vlc
vlc policy:
2.2.6-r1:
lib/apk/db/installed
https://dl-3.alpinelinux.org/alpine/v3.7/community
3.0.0_rc2-r1:
@edgecommunity https://dl-3.alpinelinux.org/alpine/edge/community
</pre>

= Additional apk Commands =
In progress...

= Local Cache =

{{:Local_APK_cache}}

= Advanced APK Usage =

== Holding a specific package back ==

In certain cases, you may want to upgrade a system, but keep a specific package at a back level. It is possible to add "sticky" or versioned dependencies. For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:
{{cmd|1=apk add asterisk=1.6.0.21-r0}}
or
{{cmd|apk add 'asterisk<1.6.1'}}

after which a {{cmd|apk upgrade}}

will upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level

To later upgrade to the current version,

{{cmd|apk add 'asterisk>1.6.1'}}

will ensure that 1.6.1 is the minimum version used.

You can also use "fuzzy" version matching to pin the version to a major/minor release. For example:

{{cmd|1=apk add 'asterisk=~1.6'}}

will match any version of asterisk that starts with 1.6 (such as 1.6.0.21-r0 or 1.6.9.31-r9) <ref>[https://git.alpinelinux.org/apk-tools/commit/?id=693b4bcdb0f22904a521a7c8ac4f13e697dc4d71 Alpine source commit message]</ref>

If you desire deterministic, repeatable package installation (such as with containerized environments) via package pinning, it is important to understand your package repo's version retention rules. For example, most Alpine package repos contain an "edge" branch, which may drop package versions that are not deemed fit to make it into a stable branch. This means that pinning to a version on the edge branch may stop working after the package version is revoked from the repo. Always pin to a package version that is intended for your current Alpine Linux version.

== Commit hooks ==

If you'd like to trigger an action or run a certain script on every commit made by apk, there's a built-in method for that. On every commit apk looks for executables located in the "/etc/apk/commit_hooks.d/" directory, and executes them both before and after the commit. To provide some way to selectively run hooks either before or after a change is commited by apk, the scripts are called with "pre-commit" or "post-commit" as argument 1.
This is an example of a hook to do different things before and after commit:

{{cmd|1=#!/bin/sh

if [ "$1" = "pre-commit" ]; then
do_something

elif [ "$1" = "post-commit" ]; then
do_something_else
fi}}

If you have a script or piece of software that accepts "pre-commit" and "post-commit" arguments directly, you can save a bit of space by softlinking it into the hooks directory rather than using a helper script.
 

= Table of comparison with other Linux/Unix-like OSes for packages =

{| class="wikitable"
|-
! OS !! File Format !! Tools
|-
| Alpine || .apk || apk
|-
| Debian || .deb || apt, aptitude, dpkg
|-
| Gentoo || .tbz2 || emerge
|-
| FreeBSD || .txz || pkg
|}

 

= Troubleshooting =

== "apk-tools is old" ==

'''apk update''', '''apk upgrade''' or '''apk add''' may report the following:
WARNING: This apk-tools is OLD! Some packages might not function properly

This may happen if you are running Alpine Linux stable version with a certain edge/main, edge/community or testing package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge is already [https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management#Repository_pinning tagged] in your repositories, then try:

{{Cmd|apk add --upgrade apk-tools@edge}}

== ERROR: UNTRUSTED signature ==

This happens when the release version changes. You need to update the local apk keys.

If you have already updated your repositories, allow them to update without the trusted key:
{{Cmd|apk update --allow-untrusted}}

Then install the keys upgrade:
{{Cmd|apk fix --upgrade --allow-untrusted alpine-keys}}

Now updates and upgrades should proceed normally.

Alternative, the updated alpine-keys package may be obtained, verified, installed directly, as covered earlier, prior to a repository update.

= External Links =
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples] Vivek Gite 2019

[[Category:Package Manager]]

Creating an Alpine package

2023-11-08T22:37:14Z

Papiris: Add reference to CODINGSTYLE.md and COMMITSTYLE.md in =code review= section

{{TOC right}}

== Requirements ==

To build a package for Alpine Linux you need an Alpine Linux installation. Check the [[Installation]] page to see all available installation options.

== Setup your system and account ==
{{:Include:Setup_your_system_and_account_for_building_packages}}

== Getting some help ==

It might be wise to start by checking what the [[Abuild|abuild]] program can/cannot do.

{{Cmd|abuild -h}}

For real help, you can also go on #alpine-devel on [[IRC]].

A reference for APKBUILD files is available as [[APKBUILD Reference]] wiki page or a man page in the 'abuild-doc' package:

{{Cmd|man APKBUILD}}

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file {{Pkg|newapkbuild}} can serve you a template to start with. It will create a directory with the given package name, place an example/template APKBUILD file to the given directory, and fill some variables if those are provided. Please check the [[Package_policies| package policies]] page about naming details.

If you doubt to which repository your package belongs to you can safely use '''testing'''. Building package in your aports/testing directory is not mandatory but this way the package is already at the right place.

{{:Include:Newapkbuild}}

{{Note|On older Alpine systems, abuild -c -n ''packagename'' was the way to create APKBUILD files. The 'packagename' was a parameter to the -n option so order of -c and -n matters. }}

[[Abuild_and_Helpers#apkbuild-cpan|apkbuild-cpan]] simplifies the creation of perl packages from CPAN and [[Abuild_and_Helpers#apkbuild-pypi|apkbuild-pypi]] ease the generation of APKBUILD files for python packages from PyPi.

If you are creating a daemon package which needs initd scripts you can add the -c making it:

{{Cmd|newapkbuild -c ''packagename''}}

This will copy the sample initd and confd files to the build directory. 
A third file sample.install file will be copied as well (we will discuss this later on).

=== Modify your APKBUILD ===
Edit APKBUILD and fill in the needed info (especially pkgname, pkgver, pkgdesc, url, license, depends and source).

If you are going to use any of the variables for directories like $pkgdir, always make sure they are double quoted like:

"$pkgdir"/somedir

This will prevent issues with spaces/special characters in the future.

{{Note|If you like syntax highlighting we suggest you to install vim. We have setup vim to recognize the APKBUILD file as a bash scripts so its easier to read them.}}

=== APKBUILD variables/functions ===

==== 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 [[Creating an Alpine package#install|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:
: {{cmd|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:
: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
: (or similar depending on the package).

* When the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:
: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
: You must prepend '${pkgname}-${pkgver}.tar.gz::' to the protocol, like so:
: <pre>source="${pkgname}-${pkgver}.tar.gz::http://oss.example.org/?get=software&ver=1.0"</pre>
: This causes the file to be saved as ''software-1.0.tar.gz'' where abuild can use it, instead of ''?get=software&ver=1.0'', where abuild cannot use it.

* Some projects didn't provide a release tarball. Beware that some git services (gitweg, cgit, …?) doesn’t provide ''stable'' tarballs, so when you point source to an tarball like <tt>https://repo.or.cz/w/gitstats.git/snapshot/ad7efbb9399e60cee6cb217c6b47e604174a8093.tar.gz</tt>, then you will run into issues because the checksum changes when downloading on the build system. This is not a problem on GitHub, GitLab and other decent services provides, they provide ''stable'' tarballs.

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



* abuild currently supports the following archive types/archive file extensions:
** .tar
** .tar.gz / .tgz
** .tar.bz2
** .tar.lz (only in Alpine >=3.7)
** .tar.lzma
** .tar.xz
** .zip

==== depends & makedepends ====

Depends are the actual running dependencies that a package would need when it is running. Makedepends are only needed when you are building a package. If you set a package in depends, you do not need to add it to makedepends as well. The best way to find out what the depends and makedepends of a package are is to [https://en.wikipedia.org/wiki/Rtfm RTFM].

No kidding, lots of important information can be found in the package INSTALL and README files (or the likes). Another good way is the run <code>./configure --help</code> from the source directory to see which options are needed for configure to finish without errors. If you do not yet have a source directory you can create one with the command:

{{Cmd|abuild unpack}}

Running <code>configure</code> will also show you how you can disable a specific option for this package. For instance, a good example is "--disable-nls" which will disable native language support and thus does not depend on gettext (libiconv, glib, ...).

Alpine likes to keep things small, so we try to disable as much as possible without losing too many features. The exact disable/enable options are decided by the package builder but please try to follow Alpine's design concept as much as possible.

An easy way of quickly finding out the build info for a package is to check Arch Linux (Alpine package management and build scripts are similar) or Gentoo Linux ebuilds (previous versions of Alpine were based on Gentoo).

* [https://gitweb.gentoo.org/repo/gentoo.git/tree/ Gentoo Ebuilds]
* [https://archlinux.org/packages/?q=search Arch Linux packages] [https://aur.archlinux.org/ Arch Linux User Repository]

==== license ====

The '''license''' tag must reflect the license of the source code. Please check the source tarball for COPYING, LICENSE, or other files with names that indicates that it contains licensing information. Beside the license file most developer include headers in the source code files with licensing details.

If the license is on the [https://spdx.org/licenses/ SPDX License List] or [https://spdx.org/licenses/exceptions-index.html SPDX License Exceptions], use the identifier specified by SPDX.

If a package has a special/custom license or is not listed as [https://opensource.org/licenses/alphabetical OSI approved], use the identifier "custom". We additionally need to provide the license file with the release. Because we want to save space and don't like to have licenses all over our system we have decided to include the license in the doc subpackage. Please follow the following guidelines to add a proper license. Locate the license file inside the source package. Add the doc subpackage to the $subpackages variable as follows:

subpackages="$pkgname-doc"

Add a similar line to the following to your package() function, depending on the license description file:

{{Cmd|install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING}}

If you follow these steps then abuild will automatically add the license to the package-doc apk for you.

{{Warning|It is not acceptable to package software with "unknown" license! If you can't find the license of the source code, please contact the author and ask them to specify the license. }}

==== arch ====

The package architecture(s) to build for. This 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'', build the package for your architecture and then run "scanelf -R pkg" from the directory that the APKBUILD resides in, in order to scan for ELF files in the ''./pkg'' directory. If you do NOT get output from this, then ''noarch'' can be used.}}

==== url ====

Website address for the program. This is useful later on when either finding documentation or other information about the package.

==== pkgdesc ====

A brief, one line, description of what the package does. Useful for the package management system. It should start with a capital letter and does '''not''' end with a period.

Here is an example from apk_info for the OpenSSH client package:

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

==== pkgver ====

Provide the release number of the package you are building.

==== pkgrel ====

The $pkgrel versioning is made so that if you change something in your APKBUILD file without changing the actual $pkgver, you can increment pkgrel so apk tools will detect it as an update. For instance, if you forget to add a dependency, you can add it afterward and you can +1 pkgver so apk finds this update and adds the missing dependency. When there's an upstream version change, we reset the pkgrel to 0.

==== pkgname ====

The base name of the package you are creating. For Freeswitch 1.0.6, you would use "freeswitch"

==== install ====

There are 6 different kinds of install scripts. Each script is called with the $pkgname.''<action>'' where ''<action>'' is one of the following:

<dl>
<dt>$pkgname.pre-install
<dd>This script is executed before package is installed. Typical use is when package needs a group and a user to be created. For example:
<pre>
#!/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
</pre>
Note the ''exit 0'' at the end. If the script exits with failure (if the user already exist), the package will not be installed and <code>apk add</code> will exit with failure.

<dt>$pkgname.post-install
<dd>This script is executed after the package is installed.

<dt>$pkgname.pre-upgrade
<dd>Same as pre-install but is executed before upgrading/downgrading/reinstalling an already installed package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

<dt>$pkgname.post-upgrade
<dd>Same as post-install but is executed after upgrading/downgrading/reinstalling an already installed package.

<dt>$pkgname.pre-deinstall
<dd>This script is executed before uninstalling a package. If script exits with failure apk will not uninstall the package.

<dt>$pkgname.post-deinstall
<dd>This script is executed after a package have been uninstalled. For example, can be used to restore busybox links:
<pre>
#!/bin/sh
busybox --install -s
</pre>

</dl>

If the package has a pre-install and post-install script the APKBUILD should have the ''install'' variable defined:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"

...
</pre>

==== subpackages ====

$subpackages are made to split up the normal "make install" into separate packages. The most common subpackages we use are doc and dev. Because we like to keep our target system small we move documentation and development files (only needed when building packages) into separate packages. To use the specific program a user only need to install the base apk without package-doc or package-dev, but if he wants to read the manual he will need to install package-doc.

The easiest way to find out if you need to use -dev and -doc is to first build the package without these options set and wait until the build finishes. When its finished you should have a pkg directory which is the fake root directory. Inside this directory you will see the structure as how it would be installed in / on the target system.

To see if you need the -dev package you can run the following cmd:

{{Cmd|find pkg/usr/ -name '*.[acho]' -o -name '*.la'}}

If this returns any files you need to include the -dev package.

 To see if you need the -doc package you can run the following cmd:

{{Cmd|find pkg/usr/share -name doc -o -name man -o -name info -o -name html -o -name sgml -o -name licenses}}

If this returns any directories you need to include the -doc package.

===== Custom subpackages =====

Some software additionally has non-essential files that do not qualify as either documentation or development content. These files should be placed in their own, specialized subpackage(s). Some packages include large test suites which are only needed in specific circumstances or binaries which have depends which we prefer not to install. To handle those we create our own package/function. In the APKBUILD below the build() function we create another function:

test() {
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/package-test "$subpkgdir"/usr/
# or amove usr/package-test
}

We also need to add the package info to $subpackages variable:

subpackages="$pkgname-doc $pkgname-dev $pkgname-test"

After we finish building the package you should see another apk called packagename-test.apk which includes the files which we moved to the $subpkgdir dir.

The above mentioned variables can also be used in our custom function. If we want for instance to build the test() function with perl support we would add:

depends="perl"
makedepends="perl-dev"

If we would install the base package it would not install perl, but if we install the package-test package it would.

==== Patches ====

Please make sure you always submit human readable patches. Ways to create them are:

directory compare:

{{Cmd|diff -Nurp original_directory new_directory > filename.patch}}

file compare:

{{Cmd|diff -up original.file new.file > filename.patch}}

If a patch contains a completely new file but not *.rej or *.orig file, you need to add -N option to diff, but you may need to add exclusions with <code>--exclude PATTERN</code> so that you do not inadvertently add files. You may need to manually delete unwanted files inside the patch file.

Because multiple patches can patch the same file, they can change the offsets required by subsequent patches. To make sure we always patch in a specific way, we should number the patches as follows:

10-patch1.patch 20-patch2.patch 30-patch3.patch

This way we are always sure that patch 1 is applied first, and if we want to add additional patches between them we can use appropriate indexes (e.g. 11, 12, 21, 22).

Add the names of the patch files to the ''source'' variable. If you haven't declared a custom ''prepare'' function, no further action is necessary. Otherwise, be sure to call ''default_prepare'' in your ''prepare'' function. For example:

prepare() {
default_prepare

# do your stuff
}

Note: Some older packages contain a ''for'' loop in the ''prepare'' function to apply patches. This is not needed anymore, as patches are handled by ''default_prepare''.

In Alpine >=3.4 you can define patch_args to supply the patch level. This only works if all the patches have the same patch level. If there are a lot of patches from different sources, there is a good chance that you may need to edit them, as discussed below.

To automatically patch the package (available only in Alpine >=3.4) if it uses a patch level (-pX) other than the default (-p1), you need to carefully modify the patch. First, you'll need a text editor that does not automatically convert between Windows and Unix new lines (or, disable this feature) so that it preserves the old code. The next thing you'll need to do is modify the paths on "+++" and "---" lines in the .patch file. You can begin the path with a/ and b/ like shown below. Next, you need to adjust the paths so that the relative base path is from inside $builddir. Anything to the left of $builddir, including $builddir itself, needs to be removed from the path. So, if $builddir is /home/USER/aports/community/chromium/src/chromium-65, you need to erase it on the "+++" and "---" lines. Inside the chromium-65 folder you can see a src folder that has 3rdparty as a descendant. If a patch originally has a deeper patch level, you may need to fill in the missing portion of the path. For example, use the <code>find . -name "Assertions.cpp"</code> command to find the full path to the file relative to the base.

{{Cat|example.patch|<nowiki>
Author: John Doe <johndoe@mail.com>
URL: http://.....
Summary: Fixes musl compatibility
----
--- a/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp.orig
+++ b/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp
@@ -142,7 +142,7 @@
};

FrameToNameScope::FrameToNameScope(void* addr) : m_name(0), m_cxaDemangled(0) {
-#if OS(MACOSX) || (OS(LINUX) && !defined(__UCLIBC__))
+#if OS(MACOSX) || (OS(LINUX) && defined(__GLIBC__))
Dl_info info;
if (!dladdr(addr, &info) || !info.dli_sname)
return;
</nowiki>}}

Portions of the patch may be outdated, removed completely as in the source code file completely removed, or moved or renamed files. You need to delete that section of the patch or find where that section of code changed and re-diff it.

It is good etiquette to give credit at the top and the location of where you originally found them with notes.

Excluding patches with global variable resembling patch_opts is not available on Alpine. To exclude patches you need to create your own custom prepare().

If you have a monolithic patch where there are a bunch of patches in one big patch, you could use filterdiff which is available in the patchutils package.

Just do something like:

<pre>
makedepends="patchutils"

prepare() {
...
cd "$builddir"
filterdiff -x '*drivers/video/logo*' "$srcdir"/original.patch > "$builddir"/modified.patch
patch -p1 -i "$builddir"/modified.patch
}
</pre>

You need to put the wildcard pattern in single quotes for it to work.

==== Configure options ====

Alpine has some default configure options we set by default. We use /usr for prefix to make sure everything is installed with /usr in front of it. If you notice that anything is installed in the wrong directory please run {{Cmd|./configure --help}} and see if you can set the correct location.

We are not covering the depend switches here we have discussed this already in the depend section.

==== Make options ====

If you notice weird problems when compiling or installing the package with make/make install you could try to disable [https://www.gnu.org/software/make/manual/make.html#Parallel parallel] building/installing. A normal make line would be:

{{Cmd|make}}

To disable parallel we use:

{{Cmd|make -j1}}

We can use the same for make install.

Because we do not want to install the package in our build environment but we want to install it in a fake root directory we need to tell 'make install' to use another destination directory instead of '/'. We do this by setting a variable when we execute make install as followed:

{{Cmd|make DESTDIR{{=}}"$pkgdir" install}}

Please note that some Makefiles do not support this variable and will always install software in '/'. To make sure you do not mess up your build system NEVER run your build system as root but always use a custom user and doas when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

==== builddir ====
If you used <tt>newapkbuild</tt> to create your APKBUILD file, you must specify the path to your unpacked sources. Inside the sections during the prepare/build/install process ''builddir'' is used. Most of the time a combination of ''$srcdir'' and ''$pkgname-$pkgver'' will work. When not, check the /src directory or the source tarball for the right string. Especially when you are working with automatically generated tarballs (like from github and gitorious), this needs to be adjusted.

<pre>
builddir="$srcdir"/$pkgname-$pkgver
</pre>

==== Additional files ====

If you want/need to install additional files not mentioned above you can use the following cmd (this is an example of a conf file):

{{Cmd|install -Dm644 doc/$pkgname.conf "$pkgdir"/etc/$pkgname.conf}}

== Build the package ==

If you did not already create the checksums as mentioned above you can do so now:

{{Cmd|cd $pkgname
abuild checksum}}

It's about time we build our package. Because a build system should never have all the package installed to prevent linking to packages we don't want it to link we use a abuild recursively with the '''-r''' switch. It will install all dependencies from your repository and builds it, afterwards it will uninstall all those depending packages again.

{{Cmd|abuild -r}}

See also [[Abuild_and_Helpers|Abuild and Helpers]].

== Testing the package locally ==

When it completes, your package will be found in a subfolder of <code>~/packages</code>. You may want to test it on your machine but only if the package is not a critical system package like musl or apk-tools package. To avoid borking your system (as in making it impossible to use <code>apk add</code> or to restore back the system and the compiler toolchain) for a critical system package, you should test on a chroot first before using it live.

The best way to test a package locally is to modify your <code>/etc/apk/repositories</code> so that it includes the indexes to your locally built packages - the directories that contain <code>ARCH/APKINDEX.tar.gz</code>. For example the <code>/etc/apk/repositories</code> below includes locally built packages in testing, community and main. To use this example change <code>USER</code> to your login name.

{{Cat|/etc/apk/repositories|/home/USER/packages/testing/
/home/USER/packages/main/
/home/USER/packages/community/
https://dl-cdn.alpinelinux.org/alpine/edge/main
https://dl-cdn.alpinelinux.org/alpine/edge/community
https://dl-cdn.alpinelinux.org/alpine/edge/testing
}}

If you prefer to test a package without changing any other configuration you can use the <code>-X, --repository</code> option to <code>apk</code>:

{{Cmd|doas apk add --repository /home/USER/packages/testing $pkgname}}

== Code review ==

To successfully have your package pass through code reviewers (as of Feb 18, 2018 are nmeum and jirutka on GitHub) and possible increased acceptance, the following conventions need to be followed:

# Custom global variables should be prefixed with underscore (_).
# Compact code as in merged commands, removed unused variables, removal of functions that do the same thing that are automatically handled by abuild.
# Versioning is done properly. For details see [[APKBUILD_Reference#pkgver]].
# Licensing is done properly. Remove unnecessary copying of licensing that is already OSI approved.
# Naming conventions rules for unofficial variables as in _gitrev is preferred over commit.
# Indent with tabs not spaces.
# Removal of explicit return 1. (They are still found the old APKBUILD files if you are learning but are now strongly discouraged.)
# Disabling check() requires either (1) a comment (#) stating next to options="!check" that there is no test suite/unit tests or (2) functioning working check() function.
# Explicit call to subpackages="$pkgname-doc" must be used instead of explicit gzip man page compression.
# Ideally, lines should be no more than 80 columns wide

Additionally, make sure to run the linter on your package:
{{Cmd|doas apk add atools
apkbuild-lint APKBUILD}}

For more information see [[Development using git:Quality assurance]] and [[Package_policies]].
Also check out [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/COMMITSTYLE.md?ref_type=heads aports/COMMITSTYLE.md] and [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/CODINGSTYLE.md?ref_type=heads aports/CODINGSTYLE.md]

== Commit your work ==

After you successfully build your package and properly followed the conventions and requirements in the code review section, you can submit your APKBUILD to Alpine's git repository.

Update your git repo, before adding new files:

{{Cmd|cd $aportsdir
git pull}}

This should pull all the changes made by others into your local git repo.

When you think you are ready you can add your files to git:

NOTE: when using our Gitlab instance, you can create MR's for each package. Please squash all commits related to the same package into a single one per MR.

{{Cmd|cd $aportsdir
git add testing/$pkgdir (include any other files needed for the build; $pkgname.install...)
git commit}}

Use the following commit message template for new aports (without the comments):

{{Cat|template|testing/$pkgname: new aport # this will be the subject line
# a blank line
$url # project homepage
$pkgdesc # one line description}}

Or you could add the following and <code>chmod +x ports/.git/hooks/prepare-commit-msg</code> to automatically generate commit message which the default aports/.githooks/ does not:

{{Cat|aports/.git/hooks/prepare-commit-msg|<nowiki>#!/bin/sh
case "$2,$3" in
,|template,)
if git diff-index --diff-filter=A --name-only --cached HEAD \
| grep -q '/APKBUILD$'; then
meta() { git diff --staged | grep "^+$1" | sed 's/.*="\?//;s/"$//';}
printf 'testing/%s: new aport\n\n%s\n%s\n' "$(meta pkgname)" \
"$(meta url)" "$(meta pkgdesc)" "$(cat $1)" > "$1"
else
printf '%s\n\n%s' `git diff-index --name-only --cached HEAD \
| sed -n 's/\/APKBUILD$//p;q'` "$(cat $1)" > "$1"
fi;;
esac</nowiki>}}

Now your changes are only available locally in your repository.

Because you do not have push rights to the Alpine aports repository you need to create a merge request to [https://gitlab.alpinelinux.org/alpine/aports Alpine's GitLab instance].

Alternatively you can also create a diff (patch) of the changes you made and send this patch to the
[https://lists.alpinelinux.org/~alpine/aports alpine-aports mailinglist].

To create a diff patch:

{{Cmd|git format-patch HEAD^}}

or if you have sprunge, you can create a link to your patch for convenience

{{Cmd|git format-patch HEAD^ --stdout <nowiki>|</nowiki> sprunge}}

== Automated flagging of outdated ports ==
Consider adding your port to [https://release-monitoring.org/ Anitya], so it will be flagged as outdated
as soon as a new stable version is released by upstream.

== See Also ==
* [[APKBUILD Reference]]
* [[APKBUILD examples]]
* [[Development using git]]
* [[Development using git:Quality assurance]]

[[category: Package Manager]]

APKBUILD Reference

2023-11-08T22:31:40Z

Papiris: fix formatting of maintainer snippet

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 <code>like this</code>.

= 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'').}}

These variables are all well documented in <code>man 5 APKBUILD</code>.

== 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 [https://en.wikipedia.org/wiki/GNU_Autotools autotools] package would have <code>make DESTDIR="$pkgdir" install</code> 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:
==== Maintainer ====
: Name and email address of the maintainer of the project (not your package).
: A well-formatted example is <code># Maintainer: John Snow <john_snow@thewall.net></code>

==== arch ====
: Package architecture(s) to build for. Can be one or several seperated by whitespace of: '''[[x86]], [[x86_64]], [[armv7]], [[armhf]], [[aarch64]], [[ppc64le]], [[s390x]], [[riscv64]], all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package). Architectures can be negated using the ! character to exclude them from the list of supported architectures. E.g. '''arch="all !ppc64le"''' means that the package is allowed to be built on all architectures but the ppc64le architecture.
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing <code>abuild -r</code>. 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. To specify a conflicting package, add the package name prefixed with a '!'.

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

==== depends_doc ====
: Run-time dependency package(s) for the '''$pkgname-doc''' subpackage.

==== depends_openrc ====
: Run-time dependency package(s) for the '''$pkgname-openrc''' subpackage.

==== depends_libs ====
: Run-time dependency package(s) for the '''$pkgname-libs''' subpackage.

==== depends_static ====
: Run-time dependency package(s) for the '''$pkgname-static''' subpackage.

==== checkdepends ====
: Dependencies that are only required during the check phase, they are only installed if the check option is enabled

==== giturl ====
:Git repository from which <code>abuild checkout</code> checks out. You can checkout a specific branch in git by adding <code>-b $branch</code>.
==== 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.
<blockquote>{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [https://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

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:
<blockquote><pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /sbin/nologin -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the <code>exit 0</code> at the end.}}</blockquote>

===== $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, <code>apk</code> 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.

: Typically this is used in a subpackage that should provide files which make sense with another package. For example:
<blockquote><pre>
...
subpackages="$pkgname-bash-completion:bashcomp:noarch"
...
bashcomp() {
pkgdesc="Bash completions for $pkgname"
install_if="$pkgname=$pkgver-r$pkgrel bash-completion"

install -Dm644 "$builddir"/doc/bash_completion/aria2c \
"$subpkgdir"/usr/share/bash-completion/completions/_aria2c
}
</pre>
From the aria2c APKBUILD. Note that the custom bashcomp() function is only necessary, because the files are not in /usr/share/bash-completion.
</blockquote>

:In general, install_if should only be used with '''at least one versioned constraint'''. Otherwise, a package that was implicitly installed by install_if and then removed from the binary repositories, will not get purged with <code>apk upgrade</code>. [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10720#note_121298]

==== license ====
: License(s) for the package, for example <code>GPL-3.0-or-later</code>, <code>BSD-2-Clause</code> or <code>MIT</code> [[Creating_an_Alpine_package#license|(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 <code>abuild checksum</code> and should be the last item in the APKBUILD.

New packages should use only sha512sums.

==== options ====
: Build-time options for the package.

: {| class="wikitable"
! Option
! Description
|-
| <code>!archcheck</code>
| 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).
|-
| <code>!check</code>
| Do not try to run the <code>check()</code> function. Please always add a short comment after the <code>!check</code> about why it's disabled. [https://github.com/alpinelinux/aports/pull/2322#discussion_r142545300] Creating a very simple check function, that calls <code>program --version</code> is worse than disabling tests completely because it gives the false impression that the package is thoroughly tested with the testsuite from upstream. [https://github.com/alpinelinux/aports/pull/7326#discussion_r278797457]
|-
| <code>checkroot</code>
| Specifies that the package's test suite will be run in ''fakeroot''. This is necessary for some test suites which fail when run as non-root.
|-
| <code>net</code>
| Allows network access when run in ''rootbld''.
|-
| <code>!strip</code>
| Avoid stripping symbols from binaries.
|-
| <code>suid</code>
| Allow [https://en.wikipedia.org/wiki/Setuid setuid] binaries.
|-
| <code>!tracedeps</code>
| Do not automatically find dependencies (e.g. by using <code>ldd</code> to find dynamic libraries, which the resulting binary links against).
|-
| <code>chmod-clean</code>
| Make all files writable in the src/ directory. Useful for packages that make files read-only in the process of building packages (go modules).
|-
| <code>toolchain</code>
| Don't warn when g++ is in makedepends
|-
| <code>!dbg</code>
| Don't create debugging subpackage
|-
| <code>ldpath-recursive</code>
| Scan directories recursively when creating .so providers
|-
| <code>!spdx</code>
| Do not check if the license= field has a SPDX compliant license
|-
| <code>textrels</code>
| Don't error out when text relocations are found
|-
| <code>charset.alias</code>
| Don't error out if /usr/lib/charset.alias is found
|-
| <code>libtool</code>
| Don't delete libtool .la files
|-
| <code>!fhs</code>
| Don't enforce checks on path that follow the FHS
|}

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

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$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 ''py3-''. 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 '''[[APKBUILD Reference#.24pkgname.pre-install|$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: <code>{digit}{.digit}...{letter}{_suf{#}}...{-r#}</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n17]
: A Suffix <code>suf</code> in the above format can be one of the following to indicate that the release is ''less recent'' than the version without the suffix: <code>alpha</code>, <code>beta</code>, <code>pre</code>, <code>rc</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n75]
: These are for indicating ''more recent'' releases: <code>cvs</code>, <code>svn</code>, <code>git</code>, <code>hg</code>, <code>p</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n76]
: All other suffices are invalid. To package a specific git commit, the date of the commit gets appended to the latest release, e.g. <code>1.0.0_git20180204</code>.

==== 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 ====
: Allow this package to be installed at the same time as the listed packages, even if they have conflicting files. The files from this package will override ("take over") the conflicting files.

: This can be used to override config files with "policy packages" [https://gitlab.alpinelinux.org/alpine/apk-tools/-/commit/89d003f8c2e5a92655ee778f7bfa5c0e85ddbed4].

: Another use case is renaming packages (or moving files from one package to another): "replaces" will avoid the file conflict error that apk reports if it happens to install the new package before uninstalling the old package [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10724#note_132872].

: A common misconception is that "replaces" is used to replace packages (like in [https://wiki.archlinux.org/index.php/PKGBUILD#replaces PKGBUILD]). This is not the case, it is only for solving file conflicts. To let apk consider installing one package instead of another one, refer to [[#provides|provides]] (with the version).

==== replaces_priority ====
: The priority of the replaces. If multiple packages replace files of each other, then the package with the highest ''replaces_priority'' will 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/software/software-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: or when the filename is braindead, like githubs' download tags:
:: <pre>https://github.com/software/software/archive/v$pkgver.tar.gz</pre>
:: The above two examples needs a target filename prefix:
:: <pre>$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver</pre>
:: and:
:: <pre>$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz</pre>

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

:* abuild currently supports the following archive types/archive file extensions:
:** .tar (only in Alpine >= 2.5)
:** .tar.gz / .tgz
:** .tar.bz2
:** .tar.lz (only in Alpine >=3.7)
:** .tar.lzma
:** .tar.xz
:** .zip

:* <code>source</code> should only include variables that change often like <code>pkgver</code> or a commit ID. CI will warn you if you include <code>pkgname</code> in source. Other variables like for example <code>_pkgname</code> or <code>_pyname</code> do not belong in <code>source</code> either.

==== 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:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''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 <code>subpkg-name</code> is the name of the '''subpackage''' and <code>subpkg_name</code> is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|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 executed 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.

==== langdir ====
: Path to where the language files are located for the '''-lang''' subpackage, defaults to '''/usr/share/locale'''

==== pcprefix ====
: Prefix all provides derived from parsing pkg-config Requires: with the value in this variable, example: ''''pcprefix="foo:"''' will produce '''pc:foo:bar'''

==== sonameprefix ====
: Prefix all provides derived from parsing shared objects with the value in this variable, example: '''sonameprefix="foo"''' will produce '''so:foo:bar.so.X'''

= Functions =
{{Note|All functions that are not ''prepare()'', ''build()'', ''check()'' and ''package()'' should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

sanitycheck() -> clean()-> fetch() -> verify() -> unpack() -> prepare() -> mkusers() -> 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().

: [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L403 default_unpack()] unpacks .tar, .tgz, .tar.gz, .tar.lz (only available in Alpine >=3.7), .tar.bz2, .tar.lzma, .tar.xz, and .zip archives from a symlink in ''$srcdir'' associated with ''$SRCDEST'' (or distfiles folder) resulting in an unpacked folder in ''$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 its internal ''dev()'' function, which in turn calls default_dev().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1605 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}}'' developer only folders in ''$pkgdir'' and transfer them to ''$subpkgdir''.

: In general, default_dev() will support packages that share pkg-config, C programming language API, shared and static libraries, Autotools, gettext, Vala programming language bindings, Python GObject introspection, a provided custom pkg-config like command (*-config), Qt, and CMake. If you have packages that have C++, other languages, other build system, etc; you need to manually move those developer files only if they are to be used in other packages.

: '''Important''': For default_dev() to be called as in no dev(), you need to explicitly add subpackages="$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 its internal ''doc()'' function, which in turn calls default_doc().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1519 default_doc()]'' will move ''"$pkgdir"/usr/share/{doc,man,info,html,sgml,licenses,gtk-doc,ri,help}'' 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.

: '''Important''': For default_doc() to be called as in no doc(), you need to explicitly add subpackages="$pkgname-doc".

==== openrc() ====
: Subpackage function for the '''$pkgname-openrc''' package whose job is to collect OpenRC service files that are in /etc/init.d and /etc/conf.d.

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1661 default_openrc()]'' will move ''"$pkgdir"/etc/{conf,init}.d'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging OpenRC service definitions should be in the package() function while letting abuild automatically collect the openrc folders.

: '''Important''': for default_openrc() to be called as in no openrc(), you need to explicitly add subpackages="$pkgname-openrc".

==== static() ====
: Subpackage function for the '''$pkgname-static''' package whose job is to collect static libraries that are stored in /lib and /usr/lib.

: ''[https://github.com/alpinelinux/abuild/blob/v3.4.0_rc4/abuild.in#L1748 default_static()]'' will move all static libraries (files ending with .a) from ''"$pkgdir"/lib'' and ''"$pkgdir"/usr/lib'' to their equivalents in ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging static libraries should be done in the package() function while letting abuild automatically collect the static libraries.

: '''Important''': for default_static() to be called as in no static(), you need to explicitly add subpackages="$pkgname-static".

==== snapshot() ====
: '''Optional'''. For live APKBUILDs or those with a _cvs, _svn, _git, _hg in their version number, you should create a snapshot function only if there is no download link to an archive file (.zip, .tar.gz, ...) to the commit/hash/tag. 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.

: The default [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L2310 snapshot()] function has variables associated with it:
:* $disturl - the base-url of the place to autoupload the snapshot
:* $svnurl - Subversion repository
:* $giturl - Git repository

: The default snapshot() can only support one repository. It is better to override it if there are multiple repositories involved in your package. CVS, Mercurial (hg), and alternative version control systems must override the default snapshot().

: 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 <code>abuild snapshot</code> to run it.

: The archives produced by the snapshot will be saved in ''/var/cache/distfiles'' or whatever you set for ''$SRCDEST''. 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 <code>abuild checksum</code> to use it in the APKBUILD creation process.

: This feature is available since Alpine >=2.6.

==== default_prepare() ====

: Before build preparation it handles set of patches inside <code>$srcdir</code> and prints failed ones.

== 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 <code>-p1</code> 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:

: Before default_prepare gets called, you can define ''patch_args'' to supply the argument to the patch command in global scope then throw away prepare() so it is unnecessary to use the old template code floating around to patch. patch_args and autopatching is only available in Alpine >=3.4. See [[Creating_an_Alpine_package#Patches]] to fix the patch that uses a different patch level (-pX).

<pre>
prepare() {
default_prepare
# your custom code here
}
</pre>

==== 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: <code>return 0</code>

: To enable or disable CFLAGS, CXXFLAGS, CMake with option, or configure option per arch, use the CARCH variable:
<pre>
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
</pre>
: The block can be used in other parts of the APKBUILD even in global.

==== check() ====
: '''Required if functionality exists.''' 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 (<code>options="!check"</code>).

: default_check() does nothing. You need to manually explicitly call the unit tests or test suite yourself. When you run the test, the program should return with an exit code of 0, indicating the tests were a success. Unit tests or test suites will do feature tests, per function correctness check, fuzz testing, benchmarks.

: A package may also require additional testing frameworks packages that are external dependencies. You should add those to the ''checkdepends='' in Alpine >=3.6 or ''makedepends='' for older for backporters. If the testing framework is not available, you need to create a package for it. If it requires a specific version of a testing framework, consider making it an internal dependency or a new package with a package name containing the major and minor version number like the python packages.

: Generally speaking, you should define the check functions for libraries, large programs like web browsers, or compilers and interpreters, cryptographic/security/anonymity stuff, mission critical stuff, PCI compliance/money/accounting software, server software with a lot of stakeholders or consumers. Soon for the new policy change will have virtually '''all packages with testing capabilities be required to have a working and defined check() function'''.

: There are times when the unit tests do not work, just because the test itself is broken, new unimplemented feature, external factors not taken into consideration, unbundling path differences, breakage caused by ccache, missing test dependency or version mismatch dependency as in python2 vs python3, test scripts only work for particular language implementation like only supporting python2 but not python3 having used the 2to3 conversion script. If a unit test is known not to work, you may need to patch it to omit that test or fix it; but, certain tests should not be disabled if it is important. You may need to alter the references to uncompiled internal dependencies to work with the external dependencies instead. For ccache, you can either disable it or remove it from the PATH environmental variable before running tests.

{{Note|Tests for graphical applications and toolkits might work on a X11 user setup but will fail on the server unless run with xvfb-run.}}

: If you don't add the ''check()'' and the ''options='', this is what you will see:

>>> WARNING: py-webtest*: APKBUILD does not run any tests!
Alpine policy will soon require that packages have any relevant testsuites run during the build process.
To fix, either define a check() function, or declare !check in $options to indicate the package does not have a testsuite.

: If you do not do a check or disable it, you must state there is no testsuite in comment form (#) next to options="!check" for the code reviewers.

: To run test suite with autotools do:

make check

: To run the test suite with python setuptools:

python2 setup.py test
python3 setup.py test

: For python it should be '''test''' not check. Check for python setuptools will check the packaging metadata fields[https://docs.python.org/3/distutils/examples.html#checking-a-package] only but not run the unit tests. There should be verbose output also. The dependencies for the tests are found in test_require in the setup.py.

: If it says <code>Ran 0 tests in 0.000s</code> that is not acceptable. check() will say it was good but it is not actually correct. It needs to run the test suite with an alternative method like <code>tox -e py27,py36</code> if you see a tox.ini file.

: You want to do it for each implementation to ensure that the API calls are correct per implementation but ncopa said it was just fine with python3.

: If there is a circular dependency for the checkdepends=, you need to disable the check and put the reason next to <code>options="!check"</code> that there is a circular dependency. You should disable it for the package that package that is least important or least security risk. The other solution is to make the conflicting dependency an internal dependency but making sure that it doesn't pull it at check time. This way they can both preform tests properly.

==== 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: <code>mkdir -p "$pkgdir"</code>

{{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.}}

= Special Operators =

== $pkgname~$pkgver ==

Specifies a required <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement. <code>~</code> ignores revisions of the package version. For example <code>superd~0.6</code> in <code>$depends</code> will ensure superd with package version 0.6 is installed as a run-time dependency for the package.

== $pkgname>=$pkgver ==

Specifies the installed package version must be greater than or equal to <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement.

= Examples =
The [[APKBUILD examples]] page will assist you in understanding how to create an APKBUILD.

= Version =

This document assumes abuild for Alpine Edge. For older releases of abuild, some of these features may not be available if you are using an older release. A link to the implementation is linked for researchers and backporters.

For more information see [[APKBUILD_versions]].

[[Category:Development]]

APKBUILD Reference

2023-11-08T22:28:03Z

Papiris: fix indent

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 <code>like this</code>.

= 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'').}}

These variables are all well documented in <code>man 5 APKBUILD</code>.

== 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 [https://en.wikipedia.org/wiki/GNU_Autotools autotools] package would have <code>make DESTDIR="$pkgdir" install</code> 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:
==== Maintainer ====
: Name and email address of the maintainer of the project (not your package).
: A well-formatted example is '''# Maintainer: John Snow <john_snow@thewall.net>'''

==== arch ====
: Package architecture(s) to build for. Can be one or several seperated by whitespace of: '''[[x86]], [[x86_64]], [[armv7]], [[armhf]], [[aarch64]], [[ppc64le]], [[s390x]], [[riscv64]], all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package). Architectures can be negated using the ! character to exclude them from the list of supported architectures. E.g. '''arch="all !ppc64le"''' means that the package is allowed to be built on all architectures but the ppc64le architecture.
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing <code>abuild -r</code>. 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. To specify a conflicting package, add the package name prefixed with a '!'.

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

==== depends_doc ====
: Run-time dependency package(s) for the '''$pkgname-doc''' subpackage.

==== depends_openrc ====
: Run-time dependency package(s) for the '''$pkgname-openrc''' subpackage.

==== depends_libs ====
: Run-time dependency package(s) for the '''$pkgname-libs''' subpackage.

==== depends_static ====
: Run-time dependency package(s) for the '''$pkgname-static''' subpackage.

==== checkdepends ====
: Dependencies that are only required during the check phase, they are only installed if the check option is enabled

==== giturl ====
:Git repository from which <code>abuild checkout</code> checks out. You can checkout a specific branch in git by adding <code>-b $branch</code>.
==== 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.
<blockquote>{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [https://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

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:
<blockquote><pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /sbin/nologin -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the <code>exit 0</code> at the end.}}</blockquote>

===== $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, <code>apk</code> 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.

: Typically this is used in a subpackage that should provide files which make sense with another package. For example:
<blockquote><pre>
...
subpackages="$pkgname-bash-completion:bashcomp:noarch"
...
bashcomp() {
pkgdesc="Bash completions for $pkgname"
install_if="$pkgname=$pkgver-r$pkgrel bash-completion"

install -Dm644 "$builddir"/doc/bash_completion/aria2c \
"$subpkgdir"/usr/share/bash-completion/completions/_aria2c
}
</pre>
From the aria2c APKBUILD. Note that the custom bashcomp() function is only necessary, because the files are not in /usr/share/bash-completion.
</blockquote>

:In general, install_if should only be used with '''at least one versioned constraint'''. Otherwise, a package that was implicitly installed by install_if and then removed from the binary repositories, will not get purged with <code>apk upgrade</code>. [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10720#note_121298]

==== license ====
: License(s) for the package, for example <code>GPL-3.0-or-later</code>, <code>BSD-2-Clause</code> or <code>MIT</code> [[Creating_an_Alpine_package#license|(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 <code>abuild checksum</code> and should be the last item in the APKBUILD.

New packages should use only sha512sums.

==== options ====
: Build-time options for the package.

: {| class="wikitable"
! Option
! Description
|-
| <code>!archcheck</code>
| 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).
|-
| <code>!check</code>
| Do not try to run the <code>check()</code> function. Please always add a short comment after the <code>!check</code> about why it's disabled. [https://github.com/alpinelinux/aports/pull/2322#discussion_r142545300] Creating a very simple check function, that calls <code>program --version</code> is worse than disabling tests completely because it gives the false impression that the package is thoroughly tested with the testsuite from upstream. [https://github.com/alpinelinux/aports/pull/7326#discussion_r278797457]
|-
| <code>checkroot</code>
| Specifies that the package's test suite will be run in ''fakeroot''. This is necessary for some test suites which fail when run as non-root.
|-
| <code>net</code>
| Allows network access when run in ''rootbld''.
|-
| <code>!strip</code>
| Avoid stripping symbols from binaries.
|-
| <code>suid</code>
| Allow [https://en.wikipedia.org/wiki/Setuid setuid] binaries.
|-
| <code>!tracedeps</code>
| Do not automatically find dependencies (e.g. by using <code>ldd</code> to find dynamic libraries, which the resulting binary links against).
|-
| <code>chmod-clean</code>
| Make all files writable in the src/ directory. Useful for packages that make files read-only in the process of building packages (go modules).
|-
| <code>toolchain</code>
| Don't warn when g++ is in makedepends
|-
| <code>!dbg</code>
| Don't create debugging subpackage
|-
| <code>ldpath-recursive</code>
| Scan directories recursively when creating .so providers
|-
| <code>!spdx</code>
| Do not check if the license= field has a SPDX compliant license
|-
| <code>textrels</code>
| Don't error out when text relocations are found
|-
| <code>charset.alias</code>
| Don't error out if /usr/lib/charset.alias is found
|-
| <code>libtool</code>
| Don't delete libtool .la files
|-
| <code>!fhs</code>
| Don't enforce checks on path that follow the FHS
|}

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

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$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 ''py3-''. 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 '''[[APKBUILD Reference#.24pkgname.pre-install|$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: <code>{digit}{.digit}...{letter}{_suf{#}}...{-r#}</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n17]
: A Suffix <code>suf</code> in the above format can be one of the following to indicate that the release is ''less recent'' than the version without the suffix: <code>alpha</code>, <code>beta</code>, <code>pre</code>, <code>rc</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n75]
: These are for indicating ''more recent'' releases: <code>cvs</code>, <code>svn</code>, <code>git</code>, <code>hg</code>, <code>p</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n76]
: All other suffices are invalid. To package a specific git commit, the date of the commit gets appended to the latest release, e.g. <code>1.0.0_git20180204</code>.

==== 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 ====
: Allow this package to be installed at the same time as the listed packages, even if they have conflicting files. The files from this package will override ("take over") the conflicting files.

: This can be used to override config files with "policy packages" [https://gitlab.alpinelinux.org/alpine/apk-tools/-/commit/89d003f8c2e5a92655ee778f7bfa5c0e85ddbed4].

: Another use case is renaming packages (or moving files from one package to another): "replaces" will avoid the file conflict error that apk reports if it happens to install the new package before uninstalling the old package [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10724#note_132872].

: A common misconception is that "replaces" is used to replace packages (like in [https://wiki.archlinux.org/index.php/PKGBUILD#replaces PKGBUILD]). This is not the case, it is only for solving file conflicts. To let apk consider installing one package instead of another one, refer to [[#provides|provides]] (with the version).

==== replaces_priority ====
: The priority of the replaces. If multiple packages replace files of each other, then the package with the highest ''replaces_priority'' will 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/software/software-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: or when the filename is braindead, like githubs' download tags:
:: <pre>https://github.com/software/software/archive/v$pkgver.tar.gz</pre>
:: The above two examples needs a target filename prefix:
:: <pre>$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver</pre>
:: and:
:: <pre>$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz</pre>

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

:* abuild currently supports the following archive types/archive file extensions:
:** .tar (only in Alpine >= 2.5)
:** .tar.gz / .tgz
:** .tar.bz2
:** .tar.lz (only in Alpine >=3.7)
:** .tar.lzma
:** .tar.xz
:** .zip

:* <code>source</code> should only include variables that change often like <code>pkgver</code> or a commit ID. CI will warn you if you include <code>pkgname</code> in source. Other variables like for example <code>_pkgname</code> or <code>_pyname</code> do not belong in <code>source</code> either.

==== 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:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''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 <code>subpkg-name</code> is the name of the '''subpackage''' and <code>subpkg_name</code> is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|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 executed 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.

==== langdir ====
: Path to where the language files are located for the '''-lang''' subpackage, defaults to '''/usr/share/locale'''

==== pcprefix ====
: Prefix all provides derived from parsing pkg-config Requires: with the value in this variable, example: ''''pcprefix="foo:"''' will produce '''pc:foo:bar'''

==== sonameprefix ====
: Prefix all provides derived from parsing shared objects with the value in this variable, example: '''sonameprefix="foo"''' will produce '''so:foo:bar.so.X'''

= Functions =
{{Note|All functions that are not ''prepare()'', ''build()'', ''check()'' and ''package()'' should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

sanitycheck() -> clean()-> fetch() -> verify() -> unpack() -> prepare() -> mkusers() -> 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().

: [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L403 default_unpack()] unpacks .tar, .tgz, .tar.gz, .tar.lz (only available in Alpine >=3.7), .tar.bz2, .tar.lzma, .tar.xz, and .zip archives from a symlink in ''$srcdir'' associated with ''$SRCDEST'' (or distfiles folder) resulting in an unpacked folder in ''$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 its internal ''dev()'' function, which in turn calls default_dev().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1605 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}}'' developer only folders in ''$pkgdir'' and transfer them to ''$subpkgdir''.

: In general, default_dev() will support packages that share pkg-config, C programming language API, shared and static libraries, Autotools, gettext, Vala programming language bindings, Python GObject introspection, a provided custom pkg-config like command (*-config), Qt, and CMake. If you have packages that have C++, other languages, other build system, etc; you need to manually move those developer files only if they are to be used in other packages.

: '''Important''': For default_dev() to be called as in no dev(), you need to explicitly add subpackages="$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 its internal ''doc()'' function, which in turn calls default_doc().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1519 default_doc()]'' will move ''"$pkgdir"/usr/share/{doc,man,info,html,sgml,licenses,gtk-doc,ri,help}'' 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.

: '''Important''': For default_doc() to be called as in no doc(), you need to explicitly add subpackages="$pkgname-doc".

==== openrc() ====
: Subpackage function for the '''$pkgname-openrc''' package whose job is to collect OpenRC service files that are in /etc/init.d and /etc/conf.d.

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1661 default_openrc()]'' will move ''"$pkgdir"/etc/{conf,init}.d'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging OpenRC service definitions should be in the package() function while letting abuild automatically collect the openrc folders.

: '''Important''': for default_openrc() to be called as in no openrc(), you need to explicitly add subpackages="$pkgname-openrc".

==== static() ====
: Subpackage function for the '''$pkgname-static''' package whose job is to collect static libraries that are stored in /lib and /usr/lib.

: ''[https://github.com/alpinelinux/abuild/blob/v3.4.0_rc4/abuild.in#L1748 default_static()]'' will move all static libraries (files ending with .a) from ''"$pkgdir"/lib'' and ''"$pkgdir"/usr/lib'' to their equivalents in ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging static libraries should be done in the package() function while letting abuild automatically collect the static libraries.

: '''Important''': for default_static() to be called as in no static(), you need to explicitly add subpackages="$pkgname-static".

==== snapshot() ====
: '''Optional'''. For live APKBUILDs or those with a _cvs, _svn, _git, _hg in their version number, you should create a snapshot function only if there is no download link to an archive file (.zip, .tar.gz, ...) to the commit/hash/tag. 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.

: The default [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L2310 snapshot()] function has variables associated with it:
:* $disturl - the base-url of the place to autoupload the snapshot
:* $svnurl - Subversion repository
:* $giturl - Git repository

: The default snapshot() can only support one repository. It is better to override it if there are multiple repositories involved in your package. CVS, Mercurial (hg), and alternative version control systems must override the default snapshot().

: 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 <code>abuild snapshot</code> to run it.

: The archives produced by the snapshot will be saved in ''/var/cache/distfiles'' or whatever you set for ''$SRCDEST''. 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 <code>abuild checksum</code> to use it in the APKBUILD creation process.

: This feature is available since Alpine >=2.6.

==== default_prepare() ====

: Before build preparation it handles set of patches inside <code>$srcdir</code> and prints failed ones.

== 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 <code>-p1</code> 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:

: Before default_prepare gets called, you can define ''patch_args'' to supply the argument to the patch command in global scope then throw away prepare() so it is unnecessary to use the old template code floating around to patch. patch_args and autopatching is only available in Alpine >=3.4. See [[Creating_an_Alpine_package#Patches]] to fix the patch that uses a different patch level (-pX).

<pre>
prepare() {
default_prepare
# your custom code here
}
</pre>

==== 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: <code>return 0</code>

: To enable or disable CFLAGS, CXXFLAGS, CMake with option, or configure option per arch, use the CARCH variable:
<pre>
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
</pre>
: The block can be used in other parts of the APKBUILD even in global.

==== check() ====
: '''Required if functionality exists.''' 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 (<code>options="!check"</code>).

: default_check() does nothing. You need to manually explicitly call the unit tests or test suite yourself. When you run the test, the program should return with an exit code of 0, indicating the tests were a success. Unit tests or test suites will do feature tests, per function correctness check, fuzz testing, benchmarks.

: A package may also require additional testing frameworks packages that are external dependencies. You should add those to the ''checkdepends='' in Alpine >=3.6 or ''makedepends='' for older for backporters. If the testing framework is not available, you need to create a package for it. If it requires a specific version of a testing framework, consider making it an internal dependency or a new package with a package name containing the major and minor version number like the python packages.

: Generally speaking, you should define the check functions for libraries, large programs like web browsers, or compilers and interpreters, cryptographic/security/anonymity stuff, mission critical stuff, PCI compliance/money/accounting software, server software with a lot of stakeholders or consumers. Soon for the new policy change will have virtually '''all packages with testing capabilities be required to have a working and defined check() function'''.

: There are times when the unit tests do not work, just because the test itself is broken, new unimplemented feature, external factors not taken into consideration, unbundling path differences, breakage caused by ccache, missing test dependency or version mismatch dependency as in python2 vs python3, test scripts only work for particular language implementation like only supporting python2 but not python3 having used the 2to3 conversion script. If a unit test is known not to work, you may need to patch it to omit that test or fix it; but, certain tests should not be disabled if it is important. You may need to alter the references to uncompiled internal dependencies to work with the external dependencies instead. For ccache, you can either disable it or remove it from the PATH environmental variable before running tests.

{{Note|Tests for graphical applications and toolkits might work on a X11 user setup but will fail on the server unless run with xvfb-run.}}

: If you don't add the ''check()'' and the ''options='', this is what you will see:

>>> WARNING: py-webtest*: APKBUILD does not run any tests!
Alpine policy will soon require that packages have any relevant testsuites run during the build process.
To fix, either define a check() function, or declare !check in $options to indicate the package does not have a testsuite.

: If you do not do a check or disable it, you must state there is no testsuite in comment form (#) next to options="!check" for the code reviewers.

: To run test suite with autotools do:

make check

: To run the test suite with python setuptools:

python2 setup.py test
python3 setup.py test

: For python it should be '''test''' not check. Check for python setuptools will check the packaging metadata fields[https://docs.python.org/3/distutils/examples.html#checking-a-package] only but not run the unit tests. There should be verbose output also. The dependencies for the tests are found in test_require in the setup.py.

: If it says <code>Ran 0 tests in 0.000s</code> that is not acceptable. check() will say it was good but it is not actually correct. It needs to run the test suite with an alternative method like <code>tox -e py27,py36</code> if you see a tox.ini file.

: You want to do it for each implementation to ensure that the API calls are correct per implementation but ncopa said it was just fine with python3.

: If there is a circular dependency for the checkdepends=, you need to disable the check and put the reason next to <code>options="!check"</code> that there is a circular dependency. You should disable it for the package that package that is least important or least security risk. The other solution is to make the conflicting dependency an internal dependency but making sure that it doesn't pull it at check time. This way they can both preform tests properly.

==== 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: <code>mkdir -p "$pkgdir"</code>

{{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.}}

= Special Operators =

== $pkgname~$pkgver ==

Specifies a required <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement. <code>~</code> ignores revisions of the package version. For example <code>superd~0.6</code> in <code>$depends</code> will ensure superd with package version 0.6 is installed as a run-time dependency for the package.

== $pkgname>=$pkgver ==

Specifies the installed package version must be greater than or equal to <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement.

= Examples =
The [[APKBUILD examples]] page will assist you in understanding how to create an APKBUILD.

= Version =

This document assumes abuild for Alpine Edge. For older releases of abuild, some of these features may not be available if you are using an older release. A link to the implementation is linked for researchers and backporters.

For more information see [[APKBUILD_versions]].

[[Category:Development]]

APKBUILD Reference

2023-11-08T22:26:17Z

Papiris: Add explanation of Maintainer, user defined variable

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 <code>like this</code>.

= 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'').}}

These variables are all well documented in <code>man 5 APKBUILD</code>.

== 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 [https://en.wikipedia.org/wiki/GNU_Autotools autotools] package would have <code>make DESTDIR="$pkgdir" install</code> 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:
==== Maintainer ====
: Name and email address of the maintainer of the project (not your package).
A well-formatted example is '''# Maintainer: John Snow <john_snow@thewall.net>'''

==== arch ====
: Package architecture(s) to build for. Can be one or several seperated by whitespace of: '''[[x86]], [[x86_64]], [[armv7]], [[armhf]], [[aarch64]], [[ppc64le]], [[s390x]], [[riscv64]], all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package). Architectures can be negated using the ! character to exclude them from the list of supported architectures. E.g. '''arch="all !ppc64le"''' means that the package is allowed to be built on all architectures but the ppc64le architecture.
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing <code>abuild -r</code>. 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. To specify a conflicting package, add the package name prefixed with a '!'.

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

==== depends_doc ====
: Run-time dependency package(s) for the '''$pkgname-doc''' subpackage.

==== depends_openrc ====
: Run-time dependency package(s) for the '''$pkgname-openrc''' subpackage.

==== depends_libs ====
: Run-time dependency package(s) for the '''$pkgname-libs''' subpackage.

==== depends_static ====
: Run-time dependency package(s) for the '''$pkgname-static''' subpackage.

==== checkdepends ====
: Dependencies that are only required during the check phase, they are only installed if the check option is enabled

==== giturl ====
:Git repository from which <code>abuild checkout</code> checks out. You can checkout a specific branch in git by adding <code>-b $branch</code>.
==== 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.
<blockquote>{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [https://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

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:
<blockquote><pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /sbin/nologin -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the <code>exit 0</code> at the end.}}</blockquote>

===== $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, <code>apk</code> 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.

: Typically this is used in a subpackage that should provide files which make sense with another package. For example:
<blockquote><pre>
...
subpackages="$pkgname-bash-completion:bashcomp:noarch"
...
bashcomp() {
pkgdesc="Bash completions for $pkgname"
install_if="$pkgname=$pkgver-r$pkgrel bash-completion"

install -Dm644 "$builddir"/doc/bash_completion/aria2c \
"$subpkgdir"/usr/share/bash-completion/completions/_aria2c
}
</pre>
From the aria2c APKBUILD. Note that the custom bashcomp() function is only necessary, because the files are not in /usr/share/bash-completion.
</blockquote>

:In general, install_if should only be used with '''at least one versioned constraint'''. Otherwise, a package that was implicitly installed by install_if and then removed from the binary repositories, will not get purged with <code>apk upgrade</code>. [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10720#note_121298]

==== license ====
: License(s) for the package, for example <code>GPL-3.0-or-later</code>, <code>BSD-2-Clause</code> or <code>MIT</code> [[Creating_an_Alpine_package#license|(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 <code>abuild checksum</code> and should be the last item in the APKBUILD.

New packages should use only sha512sums.

==== options ====
: Build-time options for the package.

: {| class="wikitable"
! Option
! Description
|-
| <code>!archcheck</code>
| 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).
|-
| <code>!check</code>
| Do not try to run the <code>check()</code> function. Please always add a short comment after the <code>!check</code> about why it's disabled. [https://github.com/alpinelinux/aports/pull/2322#discussion_r142545300] Creating a very simple check function, that calls <code>program --version</code> is worse than disabling tests completely because it gives the false impression that the package is thoroughly tested with the testsuite from upstream. [https://github.com/alpinelinux/aports/pull/7326#discussion_r278797457]
|-
| <code>checkroot</code>
| Specifies that the package's test suite will be run in ''fakeroot''. This is necessary for some test suites which fail when run as non-root.
|-
| <code>net</code>
| Allows network access when run in ''rootbld''.
|-
| <code>!strip</code>
| Avoid stripping symbols from binaries.
|-
| <code>suid</code>
| Allow [https://en.wikipedia.org/wiki/Setuid setuid] binaries.
|-
| <code>!tracedeps</code>
| Do not automatically find dependencies (e.g. by using <code>ldd</code> to find dynamic libraries, which the resulting binary links against).
|-
| <code>chmod-clean</code>
| Make all files writable in the src/ directory. Useful for packages that make files read-only in the process of building packages (go modules).
|-
| <code>toolchain</code>
| Don't warn when g++ is in makedepends
|-
| <code>!dbg</code>
| Don't create debugging subpackage
|-
| <code>ldpath-recursive</code>
| Scan directories recursively when creating .so providers
|-
| <code>!spdx</code>
| Do not check if the license= field has a SPDX compliant license
|-
| <code>textrels</code>
| Don't error out when text relocations are found
|-
| <code>charset.alias</code>
| Don't error out if /usr/lib/charset.alias is found
|-
| <code>libtool</code>
| Don't delete libtool .la files
|-
| <code>!fhs</code>
| Don't enforce checks on path that follow the FHS
|}

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

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$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 ''py3-''. 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 '''[[APKBUILD Reference#.24pkgname.pre-install|$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: <code>{digit}{.digit}...{letter}{_suf{#}}...{-r#}</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n17]
: A Suffix <code>suf</code> in the above format can be one of the following to indicate that the release is ''less recent'' than the version without the suffix: <code>alpha</code>, <code>beta</code>, <code>pre</code>, <code>rc</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n75]
: These are for indicating ''more recent'' releases: <code>cvs</code>, <code>svn</code>, <code>git</code>, <code>hg</code>, <code>p</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n76]
: All other suffices are invalid. To package a specific git commit, the date of the commit gets appended to the latest release, e.g. <code>1.0.0_git20180204</code>.

==== 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 ====
: Allow this package to be installed at the same time as the listed packages, even if they have conflicting files. The files from this package will override ("take over") the conflicting files.

: This can be used to override config files with "policy packages" [https://gitlab.alpinelinux.org/alpine/apk-tools/-/commit/89d003f8c2e5a92655ee778f7bfa5c0e85ddbed4].

: Another use case is renaming packages (or moving files from one package to another): "replaces" will avoid the file conflict error that apk reports if it happens to install the new package before uninstalling the old package [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10724#note_132872].

: A common misconception is that "replaces" is used to replace packages (like in [https://wiki.archlinux.org/index.php/PKGBUILD#replaces PKGBUILD]). This is not the case, it is only for solving file conflicts. To let apk consider installing one package instead of another one, refer to [[#provides|provides]] (with the version).

==== replaces_priority ====
: The priority of the replaces. If multiple packages replace files of each other, then the package with the highest ''replaces_priority'' will 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/software/software-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: or when the filename is braindead, like githubs' download tags:
:: <pre>https://github.com/software/software/archive/v$pkgver.tar.gz</pre>
:: The above two examples needs a target filename prefix:
:: <pre>$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver</pre>
:: and:
:: <pre>$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz</pre>

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

:* abuild currently supports the following archive types/archive file extensions:
:** .tar (only in Alpine >= 2.5)
:** .tar.gz / .tgz
:** .tar.bz2
:** .tar.lz (only in Alpine >=3.7)
:** .tar.lzma
:** .tar.xz
:** .zip

:* <code>source</code> should only include variables that change often like <code>pkgver</code> or a commit ID. CI will warn you if you include <code>pkgname</code> in source. Other variables like for example <code>_pkgname</code> or <code>_pyname</code> do not belong in <code>source</code> either.

==== 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:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''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 <code>subpkg-name</code> is the name of the '''subpackage''' and <code>subpkg_name</code> is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|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 executed 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.

==== langdir ====
: Path to where the language files are located for the '''-lang''' subpackage, defaults to '''/usr/share/locale'''

==== pcprefix ====
: Prefix all provides derived from parsing pkg-config Requires: with the value in this variable, example: ''''pcprefix="foo:"''' will produce '''pc:foo:bar'''

==== sonameprefix ====
: Prefix all provides derived from parsing shared objects with the value in this variable, example: '''sonameprefix="foo"''' will produce '''so:foo:bar.so.X'''

= Functions =
{{Note|All functions that are not ''prepare()'', ''build()'', ''check()'' and ''package()'' should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

sanitycheck() -> clean()-> fetch() -> verify() -> unpack() -> prepare() -> mkusers() -> 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().

: [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L403 default_unpack()] unpacks .tar, .tgz, .tar.gz, .tar.lz (only available in Alpine >=3.7), .tar.bz2, .tar.lzma, .tar.xz, and .zip archives from a symlink in ''$srcdir'' associated with ''$SRCDEST'' (or distfiles folder) resulting in an unpacked folder in ''$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 its internal ''dev()'' function, which in turn calls default_dev().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1605 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}}'' developer only folders in ''$pkgdir'' and transfer them to ''$subpkgdir''.

: In general, default_dev() will support packages that share pkg-config, C programming language API, shared and static libraries, Autotools, gettext, Vala programming language bindings, Python GObject introspection, a provided custom pkg-config like command (*-config), Qt, and CMake. If you have packages that have C++, other languages, other build system, etc; you need to manually move those developer files only if they are to be used in other packages.

: '''Important''': For default_dev() to be called as in no dev(), you need to explicitly add subpackages="$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 its internal ''doc()'' function, which in turn calls default_doc().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1519 default_doc()]'' will move ''"$pkgdir"/usr/share/{doc,man,info,html,sgml,licenses,gtk-doc,ri,help}'' 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.

: '''Important''': For default_doc() to be called as in no doc(), you need to explicitly add subpackages="$pkgname-doc".

==== openrc() ====
: Subpackage function for the '''$pkgname-openrc''' package whose job is to collect OpenRC service files that are in /etc/init.d and /etc/conf.d.

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1661 default_openrc()]'' will move ''"$pkgdir"/etc/{conf,init}.d'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging OpenRC service definitions should be in the package() function while letting abuild automatically collect the openrc folders.

: '''Important''': for default_openrc() to be called as in no openrc(), you need to explicitly add subpackages="$pkgname-openrc".

==== static() ====
: Subpackage function for the '''$pkgname-static''' package whose job is to collect static libraries that are stored in /lib and /usr/lib.

: ''[https://github.com/alpinelinux/abuild/blob/v3.4.0_rc4/abuild.in#L1748 default_static()]'' will move all static libraries (files ending with .a) from ''"$pkgdir"/lib'' and ''"$pkgdir"/usr/lib'' to their equivalents in ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging static libraries should be done in the package() function while letting abuild automatically collect the static libraries.

: '''Important''': for default_static() to be called as in no static(), you need to explicitly add subpackages="$pkgname-static".

==== snapshot() ====
: '''Optional'''. For live APKBUILDs or those with a _cvs, _svn, _git, _hg in their version number, you should create a snapshot function only if there is no download link to an archive file (.zip, .tar.gz, ...) to the commit/hash/tag. 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.

: The default [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L2310 snapshot()] function has variables associated with it:
:* $disturl - the base-url of the place to autoupload the snapshot
:* $svnurl - Subversion repository
:* $giturl - Git repository

: The default snapshot() can only support one repository. It is better to override it if there are multiple repositories involved in your package. CVS, Mercurial (hg), and alternative version control systems must override the default snapshot().

: 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 <code>abuild snapshot</code> to run it.

: The archives produced by the snapshot will be saved in ''/var/cache/distfiles'' or whatever you set for ''$SRCDEST''. 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 <code>abuild checksum</code> to use it in the APKBUILD creation process.

: This feature is available since Alpine >=2.6.

==== default_prepare() ====

: Before build preparation it handles set of patches inside <code>$srcdir</code> and prints failed ones.

== 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 <code>-p1</code> 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:

: Before default_prepare gets called, you can define ''patch_args'' to supply the argument to the patch command in global scope then throw away prepare() so it is unnecessary to use the old template code floating around to patch. patch_args and autopatching is only available in Alpine >=3.4. See [[Creating_an_Alpine_package#Patches]] to fix the patch that uses a different patch level (-pX).

<pre>
prepare() {
default_prepare
# your custom code here
}
</pre>

==== 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: <code>return 0</code>

: To enable or disable CFLAGS, CXXFLAGS, CMake with option, or configure option per arch, use the CARCH variable:
<pre>
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
</pre>
: The block can be used in other parts of the APKBUILD even in global.

==== check() ====
: '''Required if functionality exists.''' 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 (<code>options="!check"</code>).

: default_check() does nothing. You need to manually explicitly call the unit tests or test suite yourself. When you run the test, the program should return with an exit code of 0, indicating the tests were a success. Unit tests or test suites will do feature tests, per function correctness check, fuzz testing, benchmarks.

: A package may also require additional testing frameworks packages that are external dependencies. You should add those to the ''checkdepends='' in Alpine >=3.6 or ''makedepends='' for older for backporters. If the testing framework is not available, you need to create a package for it. If it requires a specific version of a testing framework, consider making it an internal dependency or a new package with a package name containing the major and minor version number like the python packages.

: Generally speaking, you should define the check functions for libraries, large programs like web browsers, or compilers and interpreters, cryptographic/security/anonymity stuff, mission critical stuff, PCI compliance/money/accounting software, server software with a lot of stakeholders or consumers. Soon for the new policy change will have virtually '''all packages with testing capabilities be required to have a working and defined check() function'''.

: There are times when the unit tests do not work, just because the test itself is broken, new unimplemented feature, external factors not taken into consideration, unbundling path differences, breakage caused by ccache, missing test dependency or version mismatch dependency as in python2 vs python3, test scripts only work for particular language implementation like only supporting python2 but not python3 having used the 2to3 conversion script. If a unit test is known not to work, you may need to patch it to omit that test or fix it; but, certain tests should not be disabled if it is important. You may need to alter the references to uncompiled internal dependencies to work with the external dependencies instead. For ccache, you can either disable it or remove it from the PATH environmental variable before running tests.

{{Note|Tests for graphical applications and toolkits might work on a X11 user setup but will fail on the server unless run with xvfb-run.}}

: If you don't add the ''check()'' and the ''options='', this is what you will see:

>>> WARNING: py-webtest*: APKBUILD does not run any tests!
Alpine policy will soon require that packages have any relevant testsuites run during the build process.
To fix, either define a check() function, or declare !check in $options to indicate the package does not have a testsuite.

: If you do not do a check or disable it, you must state there is no testsuite in comment form (#) next to options="!check" for the code reviewers.

: To run test suite with autotools do:

make check

: To run the test suite with python setuptools:

python2 setup.py test
python3 setup.py test

: For python it should be '''test''' not check. Check for python setuptools will check the packaging metadata fields[https://docs.python.org/3/distutils/examples.html#checking-a-package] only but not run the unit tests. There should be verbose output also. The dependencies for the tests are found in test_require in the setup.py.

: If it says <code>Ran 0 tests in 0.000s</code> that is not acceptable. check() will say it was good but it is not actually correct. It needs to run the test suite with an alternative method like <code>tox -e py27,py36</code> if you see a tox.ini file.

: You want to do it for each implementation to ensure that the API calls are correct per implementation but ncopa said it was just fine with python3.

: If there is a circular dependency for the checkdepends=, you need to disable the check and put the reason next to <code>options="!check"</code> that there is a circular dependency. You should disable it for the package that package that is least important or least security risk. The other solution is to make the conflicting dependency an internal dependency but making sure that it doesn't pull it at check time. This way they can both preform tests properly.

==== 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: <code>mkdir -p "$pkgdir"</code>

{{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.}}

= Special Operators =

== $pkgname~$pkgver ==

Specifies a required <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement. <code>~</code> ignores revisions of the package version. For example <code>superd~0.6</code> in <code>$depends</code> will ensure superd with package version 0.6 is installed as a run-time dependency for the package.

== $pkgname>=$pkgver ==

Specifies the installed package version must be greater than or equal to <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement.

= Examples =
The [[APKBUILD examples]] page will assist you in understanding how to create an APKBUILD.

= Version =

This document assumes abuild for Alpine Edge. For older releases of abuild, some of these features may not be available if you are using an older release. A link to the implementation is linked for researchers and backporters.

For more information see [[APKBUILD_versions]].

[[Category:Development]]

Talk:APKBUILD examples:Simple

2023-11-08T22:15:48Z

Papiris: Avoid empty MAINTAINER field in APKBUILD examples

I find many examples of APKBUILDs with an empty MAINTAINER field, including this one.
I suggest we add an example person and email address to the maintainer field in this example, to show that it isn't supposed to be empty