aboutsummaryrefslogtreecommitdiffstats
path: root/CODINGSTYLE.md
blob: 1064177643247a17fd0817da4cfe68749eb26281 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
# 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][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

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][POSIX.1-2017 definition 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

<!--
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 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>`.
* 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`.

[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