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 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 except 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, more on this below).
• 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.

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 variables with an underscore character.

Use Local Variables

• Declare function-specific variables with the local keyword.

Calling Commands

Command Substitutions and Global Variables

• Avoid command Substitutions in global variables, use parameter expansions instead.

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 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]>.
• In addition to a Maintainer Comment a Contributor Comment must be present for said 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.

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.

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.

Function Overwriting

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