diff options
Diffstat (limited to 'CODINGSTYLE.md')
| -rw-r--r-- | CODINGSTYLE.md | 270 |
1 files changed, 175 insertions, 95 deletions
diff --git a/CODINGSTYLE.md b/CODINGSTYLE.md index 74dfcd154ea..505634d7c4a 100644 --- a/CODINGSTYLE.md +++ b/CODINGSTYLE.md @@ -1,111 +1,191 @@ -# Alpine Linux coding style - -Thank you for taking interest in contributing to our aports repository. -As consistency and readability are so important for the quality of our APKBUILD -and thus the quality of Alpine Linux, we kindly ask to follow these -recommendations. - -## Language -Alpine Linux APKBUILD files are inherently just POSIX shell scripts. Please avoid -extensions, even if they work or are accepted by busybox ash. (using keyword -`local` is an exception) - -## Naming convention -Use snake_case. Functions, variables etc. should be lower-cased with -underscores to separate words. - -Local 'private' variables and functions in global scope should be prefixed -with a single underscore to avoid name collisions with internal variables in -`abuild`. - -Double underscores are reserved and should not be used. -```sh -_my_variable="data" -``` - -### Bracing -Curly braces for functions should be on the same line. - -```sh -prepare() { - ... -} -``` - -Markers to indicate a compound statement should be on the same line. - - -#### if ...; then -```sh - if [ true ]; then - echo "It is so" - fi -} -``` - -#### while ...; do -```sh - while ...; do - ... - done -``` - -#### for ...; do -```sh - for x in foo bar baz; do - ... - done -``` +# Policy for APKBUILDs -### Spacing -All keywords and operators are separated by a space. +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][bash functions]. +2. Non-POSIX [parameter extensions][POSIX.1-2017 parameter expansion] + are supported. This includes: Substring expansions (e.g. + `${var:offset:length}`) and Replacement expansions (e.g. + `${var/pattern/string}`). The [bash manual][bash expansion] + 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 + +<!-- +This should be in conformance with most existing APKBUILDs +Structure and content inspired by Google Shell Style Guide. +--> + +## 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 -For cleanliness sake, ensure there is no trailing whitespace. +Put `; do` and `; then` on the same line as the `while`, `for` or `if`. -## Identation -Indentation is one tab character per level, alignment is done using spaces. -For example (using the >------- characters to indicate a tab): -```sh -build() -{ ->-------make DESTDIR="${pkgdir}" \ ->------- PREFIX="/usr" -} -``` +### Function Declarations -This ensures code is always neatly aligned and properly indented. +* 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. -Space before tab should be avoided. +### Case statement -## Line length -A line should not be longer than 80 characters. While this is not a hard limit, it -is strongly recommended to avoid having longer lines, as long lines reduce -readability and invite deep nesting. +* 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 `;;`. -## Variables +### Variable expansion + +* Use `${var}` over `$var` only when it is strictly necessary. Meaning: + Only if the character following the [variable name][POSIX.1-2017 definition name] + is an underscore or an alphanumeric character. ### Quoting -Quote strings containing variables, command substitutions, spaces or shell meta -characters, unless careful unquoted expansion is required. -Don't quote _literal_ integers. +* 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 + +<!-- +This section attempts to document policies enforced by the linter from +atools <https://github.com/maxice8/atools>, newapkbuild and existing +APKBUILDs. +--> + +## Comments + +### Contributor Comment + +* All APKBUILDs may begin with one or more contributor comments (one per + line) containing a valid [RFC 5322][RFC 5322] address. For example, + `# Contributor: Max Mustermann <max@example.org>`. + +### Maintainer Comment + +* All APKBUILDs contain exactly one maintainer comment containing a + valid RFC 5322 address. For example, `# Maintainer: Max Mustermann + <max@example.org>`. +* 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. + +### 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. -### Bracing -Only use curly braces around variables when needed. +## Build Functions -```sh -foo="${foo}_bar" -foo_bar="$foo" -``` +### Function Declaration -## Subshell usage -Use `$()` syntax, not backticks. +* 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. -## Sorting -Some items tend to benefit from being sorted. A list of sources, dependencies -etc. Always try to find a reasonable sort order, where alphabetically tends to -be the most useful one. +### Function Overwriting -## Eval -`eval` is evil and should be avoided. +* If the `prepare` function is overwritten it should always call + `default_prepare`. +[POSIX.1-2017 volume 3]: https://pubs.opengroup.org/onlinepubs/9699919799/idx/xcu.html +[POSIX.1-2017 parameter expansion]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_02 +[POSIX.1-2017 definition name]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_235 +[bash functions]: https://www.gnu.org/software/bash/manual/bash.html#Shell-Functions +[bash expansion]: https://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion +[RFC 5322]: https://tools.ietf.org/html/rfc5322 |