Policy for APKBUILDs

This documents defines a policy for writing APKBUILDs.

Standard selection

APKBUILDs are POSIX shell scripts as defined in POSIX.1-2017 Volume 3. Additionally, the following extensions are supported:

1. The local keyword for introducing variables local to a function is supported, it is briefly documented in the bash manual.
2. Non-POSIX parameter extensions are supported. This includes: Substring expansions (e.g. ${var:offset:length}) and Replacement expansions (e.g. ${var/pattern/string}). The bash manual contains further information on these two expansions.

NOTE: busybox ash is currently used to evaluate APKBUILDs - since it supports additional POSIX shell extensions, your APKBUILD might be evaluated correctly, even if it is not confirming to this policy document.

Shell Style Considerations

Formatting

Indention

Indent with tabs, don’t use spaces. Avoid whitespaces.

Line Length

Maximum line length is 80 characters, this should be considered a recommendation and not a strict requirement which must be followed at all costs. Most notably, automatically generated parts (e.g. by abuild checksum) are exempt from this rule.

Compound Statements

Put ; do and ; then on the same line as the while, for or if.

Function Declarations

• Always put the function name, the parenthesis and the curly brackets on the same line.
• Don’t use spacing between function name and parenthesis.
• Do use spacing between function parenthesis and curly brackets.

Case statement

• Don’t indent alternatives.
• A one-line alternative needs a space after the close parenthesis of the pattern and before the ;;.
• End the last case with ;;.

Variable expansion

• Use ${var} over $var only when it is strictly necessary. Meaning: Only if the character following the variable name is an underscore or an alphanumeric character.

Quoting

• Always quote string literals (exceptions are assigning pkgname and pkgver, which must not be quoted).
• Always quote variables, command substitutions or shell meta characters when used in strings. Prefer "$var"/foo/bar over "$var/foo/bar".
• Never quote literal integers.
• Double quotes should be used, unless preventing variable interpolation is necessary.

Features

Command Substitution

• Always use $() instead of backticks.

Test and [

• Prefer [ over test(1).

Naming Conventions

Function Names

• Lower-case, with underscores to separate words. Prefix all helper functions with an underscore character.

Variable Names

• Lower-case, with underscores to separate words. Prefix all non-metadata non-local variables with an underscore character.

Use Local Variables

• Declare function-specific variables with the local keyword.

Calling Commands

Top-level Scope

• External commands should not be called outside of functions; in variables, use parameter expansions instead (e.g. ${pkgver/-/.} instead of $(echo $pkgver | tr '-' '.')).

Return Values

• APKBUILDs are executed with set -e, explicit || return 1 statements must not be used.

Comments

Spacing

• All comments begin with an ASCII space character, e.g. # foo.

TODO Comments

• Use TODO comments for code that is temporary, a short-term solution, or good-enough but not perfect.

APKBUILD style considerations

Comments

Contributor Comment

• All APKBUILDs may begin with one or more contributor comments (one per line) containing a valid RFC 5322 address. For example, # Contributor: Max Mustermann <[email protected]>.

Maintainer Comment

• All APKBUILDs contain exactly one maintainer comment containing a valid RFC 5322 address. For example, # Maintainer: Max Mustermann <[email protected]>.
• The Maintainer comment should immediately follow the Contributor comment(s).
• In the case of package being abandoned, the comment should still be present, but left empty: # Maintainer:.

Metadata Variables

Metadata Variables are variables used directly by abuild itself, e.g. pkgname or depends.

Metadata Values

• pkgname must only contain lowercase characters.
• pkgname must match the name of the directory the APKBUILD file is located in.

Maintainer Variable

• NOTE: There is a ongoing discussion wheather to use the Maintainer Variable, see https://gitlab.alpinelinux.org/alpine/tsc/-/issues/88.
• All APKBUILDs should contain exactly one variable named maintainer, containing a valid RFC 5322 address. For example, maintainer="Max Mustermann <[email protected]>".
• maintainer should immediately follow the Contributor comment(s), above pkgname.
• In the case of package being abandoned, the variable should still be present, but left empty: maintainer="".

Metadata order

The maintainer variable should be immediately followed by pkgname, pkgver and pkgrel, in that order. This is to ease review and assignment as the maintainer will be visible in the three lines of context, in the diff, when pkgver or pkgrel is changed.

Variable Assignments

• Empty Metadata Variable assignments, e.g. install="" must be removed.
• The Metadata Variable builddir defaults to $srcdir/$pkgname-$pkgver and should only be assigned if the default values is not appropriate.

Assignment Order

• All Metadata Variables (except checksums) must be declared before the first function declaration.
• Checksum Metadata Variables must be declared after the last function declaration, abuild checksum will automatically take care of this.

Comments

• For Metadata Variables such as options or arch, comments are encouraged to help other contributors understand the choices; in those cases, they should be put either on the same line after the variable, or above it, on a separate line, with an appropriate prefix (e.g. # check: no test suite or # armhf: blocked by qt6-qtwebengine).

Build Functions

Function Declaration

• Functions should be declared in the order they are called by abuild.
• All functions are executed in "$builddir" explicit directory changes to $builddir must be avoided (if possible).
• Variables local to functions must always be declared with the local keyword.
• If a function body is empty, contains only the default comment from newapkbuild, or only calls default_*, it should be completely omitted from the file.

Function Overwriting

• If the prepare function is overwritten it should always call default_prepare.