| 1 | # Policy for APKBUILDs
|
| 2 |
|
| 3 | This documents defines a policy for writing APKBUILDs.
|
| 4 |
|
| 5 | # Standard Selection
|
| 6 |
|
| 7 | APKBUILDs are POSIX shell scripts as defined in
|
| 8 | [POSIX.1-2017 Volume 3][POSIX.1-2017 volume 3]. Additionally, the following
|
| 9 | extensions are supported:
|
| 10 |
|
| 11 | 1. The `local` keyword for introducing variables local to a function is
|
| 12 | supported, it is briefly documented in the [bash manual][bash functions].
|
| 13 | 2. Non-POSIX [parameter extensions][POSIX.1-2017 parameter expansion]
|
| 14 | are supported. This includes: Substring expansions (e.g.
|
| 15 | `${var:offset:length}`) and Replacement expansions (e.g.
|
| 16 | `${var/pattern/string}`). The [bash manual][bash expansion]
|
| 17 | contains further information on these two expansions.
|
| 18 |
|
| 19 | **NOTE:** `busybox ash` is currently used to evaluate APKBUILDs - since it
|
| 20 | supports additional POSIX shell extensions, your APKBUILD might be
|
| 21 | evaluated correctly, even if it is not confirming to this policy
|
| 22 | document.
|
| 23 |
|
| 24 | # Shell Style Considerations
|
| 25 |
|
| 26 | |
| 27 | This should be in conformance with most existing APKBUILDs
|
| 28 | Structure and content inspired by Google Shell Style Guide.
|
| 29 |
|
| 30 |
|
| 31 | ## Formatting
|
| 32 |
|
| 33 | ### Indention
|
| 34 |
|
| 35 | Indent with tabs, don't use spaces. Avoid whitespaces.
|
| 36 |
|
| 37 | ### Line Length
|
| 38 |
|
| 39 | Maximum line length is 80 characters, this should be considered a
|
| 40 | recommendation and not a strict requirement which must be followed at
|
| 41 | all costs. Most notably, automatically generated parts (e.g. by `abuild
|
| 42 | checksum`) are exempt from this rule.
|
| 43 |
|
| 44 | ### Compound Statements
|
| 45 |
|
| 46 | Put `; do` and `; then` on the same line as the `while`, `for` or `if`.
|
| 47 |
|
| 48 | ### Function Declarations
|
| 49 |
|
| 50 | * Always put the function name, the parenthesis and the curly brackets
|
| 51 | on the same line.
|
| 52 | * Don't use spacing between function name and parenthesis.
|
| 53 | * Do use spacing between function parenthesis and curly brackets.
|
| 54 |
|
| 55 | ### Case Statement
|
| 56 |
|
| 57 | * Don't indent alternatives.
|
| 58 | * A one-line alternative needs a space after the close parenthesis of the pattern and before the `;;`.
|
| 59 | * End the last case with `;;`.
|
| 60 |
|
| 61 | ### Variable Expansion
|
| 62 |
|
| 63 | * Use `${var}` over `$var` only when it is strictly necessary. Meaning:
|
| 64 | Only if the character following the [variable name][POSIX.1-2017 definition name]
|
| 65 | is an underscore or an alphanumeric character.
|
| 66 |
|
| 67 | ### Quoting
|
| 68 |
|
| 69 | * Always quote string literals (exceptions are assigning `pkgname` and
|
| 70 | `pkgver`, which must not be quoted).
|
| 71 | * Always quote variables, command substitutions or shell meta characters
|
| 72 | when used in strings. Prefer `"$var"/foo/bar` over `"$var/foo/bar"`.
|
| 73 | * Never quote literal integers.
|
| 74 | * Double quotes should be used, unless preventing variable interpolation
|
| 75 | is necessary.
|
| 76 |
|
| 77 | ## Features
|
| 78 |
|
| 79 | ### Command Substitution
|
| 80 |
|
| 81 | * Always use `$()` instead of backticks.
|
| 82 |
|
| 83 | ### Test and [
|
| 84 |
|
| 85 | * Prefer `[` over `test(1)`.
|
| 86 |
|
| 87 | ### amove
|
| 88 |
|
| 89 | * Always use `amove` to move files to subpackages in custom split functions
|
| 90 | unless the specific usecase is not supported by `amove`.
|
| 91 |
|
| 92 | ## Naming Conventions
|
| 93 |
|
| 94 | ### Function Names
|
| 95 |
|
| 96 | * Lower-case, with underscores to separate words. Prefix all helper
|
| 97 | functions with an underscore character.
|
| 98 |
|
| 99 | ### Variable Names
|
| 100 |
|
| 101 | * Lower-case, with underscores to separate words. Prefix all
|
| 102 | non-metadata non-local variables with an underscore character.
|
| 103 |
|
| 104 | ### Use Local Variables
|
| 105 |
|
| 106 | * Declare function-specific variables with the `local` keyword.
|
| 107 |
|
| 108 | ## Calling Commands
|
| 109 |
|
| 110 | ### Top-level Scope
|
| 111 |
|
| 112 | * External commands should not be called outside of functions;
|
| 113 | in variables, use parameter expansions instead
|
| 114 | (e.g. `${pkgver/-/.}` instead of `$(echo $pkgver | tr '-' '.')`).
|
| 115 |
|
| 116 | ### Return Values
|
| 117 |
|
| 118 | * APKBUILDs are executed with `set -e`, explicit `|| return 1`
|
| 119 | statements must not be used.
|
| 120 |
|
| 121 | ## Comments
|
| 122 |
|
| 123 | ### Spacing
|
| 124 |
|
| 125 | * All comments begin with an ASCII space character, e.g. `# foo`.
|
| 126 |
|
| 127 | ### TODO Comments
|
| 128 |
|
| 129 | * Use TODO comments for code that is temporary, a short-term solution,
|
| 130 | or good-enough but not perfect.
|
| 131 |
|
| 132 | # APKBUILD Style Considerations
|
| 133 |
|
| 134 | |
| 135 | This section attempts to document policies enforced by the linter from
|
| 136 | atools-go <https://gitlab.alpinelinux.org/alpine/infra/atools-go>,
|
| 137 | newapkbuild and existing APKBUILDs.
|
| 138 |
|
| 139 |
|
| 140 | ## Comments
|
| 141 |
|
| 142 | ### Contributor Comment
|
| 143 |
|
| 144 | * All APKBUILDs may begin with one or more contributor comments (one per
|
| 145 | line) containing a valid [RFC 5322][RFC 5322] address. For example,
|
| 146 | `# Contributor: Max Mustermann <[email protected]>`.
|
| 147 |
|
| 148 | ### Maintainer Comment
|
| 149 |
|
| 150 | * All APKBUILDs contain exactly one maintainer comment containing a
|
| 151 | valid RFC 5322 address. For example, `# Maintainer: Max Mustermann
|
| 152 | <[email protected]>`.
|
| 153 | * The Maintainer comment should immediately follow the Contributor comment(s).
|
| 154 | * In the case of package being abandoned, the comment should still be present,
|
| 155 | but left empty: `# Maintainer:`.
|
| 156 |
|
| 157 | ## Metadata Variables
|
| 158 |
|
| 159 | Metadata Variables are variables used directly by abuild itself, e.g. `pkgname` or `depends`.
|
| 160 |
|
| 161 | ### Metadata Values
|
| 162 |
|
| 163 | * `pkgname` must only contain lowercase characters.
|
| 164 | * `pkgname` must match the name of the directory the `APKBUILD` file is located in.
|
| 165 |
|
| 166 | ### Maintainer Variable
|
| 167 |
|
| 168 | * **NOTE:** There is a ongoing discussion wheather to use the Maintainer
|
| 169 | Variable, see https://gitlab.alpinelinux.org/alpine/tsc/-/issues/88.
|
| 170 | * All APKBUILDs should contain exactly one variable named `maintainer`,
|
| 171 | containing a valid RFC 5322 address. For example,
|
| 172 | `maintainer="Max Mustermann <[email protected]>"`.
|
| 173 | * `maintainer` should immediately follow the Contributor comment(s), above `pkgname`.
|
| 174 | * In the case of package being abandoned, the variable should still be present,
|
| 175 | but left empty: `maintainer=""`.
|
| 176 |
|
| 177 | ### Metadata Order
|
| 178 |
|
| 179 | The maintainer variable should be immediately followed by `pkgname`, `pkgver`
|
| 180 | and `pkgrel`, in that order. This is to ease review and assignment as the
|
| 181 | maintainer will be visible in the three lines of context, in the diff, when
|
| 182 | `pkgver` or `pkgrel` is changed.
|
| 183 |
|
| 184 | If a package uses a commit hash or other similar string instead of a release
|
| 185 | or tag, the hash should be put in the variable `_commit` directly under
|
| 186 | `pkgrel`.
|
| 187 |
|
| 188 | ### Variable Assignments
|
| 189 |
|
| 190 | * Empty Metadata Variable assignments, e.g. `install=""` must be removed.
|
| 191 | * The Metadata Variable `builddir` defaults to `$srcdir/$pkgname-$pkgver`
|
| 192 | and should only be assigned if the default values is not appropriate.
|
| 193 |
|
| 194 | ### Assignment Order
|
| 195 |
|
| 196 | * All Metadata Variables (except checksums) must be declared before the
|
| 197 | first function declaration.
|
| 198 | * Checksum Metadata Variables must be declared after the last function
|
| 199 | declaration, `abuild checksum` will automatically take care of this.
|
| 200 |
|
| 201 | ### Comments
|
| 202 |
|
| 203 | * For Metadata Variables such as `options` or `arch`,
|
| 204 | comments are encouraged to help other contributors understand the choices;
|
| 205 | in those cases, they should be put either on the same line after the variable,
|
| 206 | or above it, on a separate line, with an appropriate prefix
|
| 207 | (e.g. `# check: no test suite` or `# armhf: blocked by qt6-qtwebengine`).
|
| 208 |
|
| 209 | ## Build Functions
|
| 210 |
|
| 211 | ### Function Declaration
|
| 212 |
|
| 213 | * Functions should be declared in the order they are called by abuild.
|
| 214 | * All functions are executed in `"$builddir"` explicit directory changes
|
| 215 | to `$builddir` must be avoided (if possible).
|
| 216 | * Variables local to functions must always be declared with the `local`
|
| 217 | keyword.
|
| 218 | * If a function body is empty, contains only the default comment from `newapkbuild`,
|
| 219 | or only calls `default_*`, it should be completely omitted from the file.
|
| 220 |
|
| 221 | ### Function Overwriting
|
| 222 |
|
| 223 | * If the `prepare` function is overwritten it should always call
|
| 224 | `default_prepare`.
|
| 225 |
|
| 226 | [POSIX.1-2017 volume 3]: https://pubs.opengroup.org/onlinepubs/9699919799/idx/xcu.html
|
| 227 | [POSIX.1-2017 parameter expansion]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_02
|
| 228 | [POSIX.1-2017 definition name]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_235
|
| 229 | [bash functions]: https://www.gnu.org/software/bash/manual/bash.html#Shell-Functions
|
| 230 | [bash expansion]: https://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion
|
| 231 | [RFC 5322]: https://tools.ietf.org/html/rfc5322
|