alint.5.scd 16.1 KB
Newer Older
Leo's avatar
Leo committed
1 2 3 4
alint(5)

# NAME

Leo's avatar
Leo committed
5
alint - linting labels and tags
Leo's avatar
Leo committed
6 7 8

# DESCRIPTION

Leo's avatar
Leo committed
9 10 11 12
A label and a tag are 2 attributes given to each test in alint, a label is composed
by a collection of words separated by dashes and it is meant to convey the general
idea of what the test does. A tag is a string with AL followed by an integer, those
being assigned in increasing order as new tests are made but never re-using old ones.
Leo's avatar
Leo committed
13

Leo's avatar
Leo committed
14 15 16
tests can be skipped by setting an environment variable composed of SKIP_ + the label
in uppercase with the dashes replaced by underscore or by setting an environment variable
composed of SKIP_ + the tag.
Leo's avatar
Leo committed
17

Leo's avatar
Leo committed
18
# Severity
Leo's avatar
Leo committed
19

Leo's avatar
Leo committed
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
Severity is assigned to each tag and indicates how serious the violation found is:

## Serious (S)

Will cause problems during build or when package is delivered to users. Should be fixed
immediately.

## Important (I)

Might cause problems during build or when the package is delivered to users in certain
situations. Should be fixed soon.

## Minor (M)

Won't directly cause issues during build or when the package is delivered to users.
Leo's avatar
Leo committed
35 36 37
Should be fixed when convenient.

This also holds style issues that are dictated on the CODINGSTYLE.md file.
Leo's avatar
Leo committed
38

Leo's avatar
Leo committed
39 40 41 42 43 44
## STYLE (T)

Won't cause any issues, are specific style issues pertinent to a concerned developer
or contributor. the _APKBUILD\_STYLE_ variable can be set to a specific value to enable
a subset of checks that the specific developer or user uses.

45 46 47 48
When a check belongs to this category this manual page also provides information on which
developers use a specific style check as developers can sometimes both want to have the
same check done on their own style.

Leo's avatar
Leo committed
49 50 51 52
Current valid values are:

- leo (style linting for leo)

Leo's avatar
Leo committed
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
# Certainty

Certainty is assigned to each tag and indicates how certain a test is that the violation
found is not a false positive

## Certain (C)

The test is certain that this is not a false positive

## Possible (P)

The test is not certain that this is a false positive, but there is a high chance it isn't

# LABELS TAGS (aports-lint)

The following labels and tags are used by the *aports-lint* program.

## duplicate-package [AL22]
Leo's avatar
Leo committed
71

Leo's avatar
Leo committed
72 73
The Package being introduced is already present in another repo. Solve the
conflict by:
Leo's avatar
Leo committed
74

Leo's avatar
Leo committed
75 76
- If the package in the uppermost repo has more recent changes, merge them.
- Then delete the package in the upper repo.
Leo's avatar
Leo committed
77

Leo's avatar
Leo committed
78
Duplicate packages will shadow each other in the repo and the one with the
Leo's avatar
Leo committed
79 80 81 82
higher version will win, it can also cause programs to compile against
the wrong version of a package. E.g: if *main/foo-1-r0* and *testing/foo-2-r0* exist
and *main/bar* is updated to version 2 which requires *foo>=2-r0* then it will
fail because it will only find *main/foo-1-r0* and not *testing/foo-2-r0*.
Leo's avatar
Leo committed
83

Leo's avatar
Leo committed
84 85 86
Severity: Serious, Certainty: Certain

## upper-repo-depends [AL16]
Leo's avatar
Leo committed
87 88 89 90 91 92 93 94 95

The package depends on a package in a upper repo. The package must be moved to 
the upper repo or the dependency moved to the repo the package is.

Packages cannot depend on a package on an upper repo. Packages in main cannot
depend on packages in other repos. Packages in community can depend on main
and itself only. Packages in testing can depend on main, community and itself
only. Packages in unmaintained can depend on package on any repo but non-free.

Leo's avatar
Leo committed
96 97 98
Severity: Serious, Certainty: Certain

## duplicate-depends [AL17]
Leo's avatar
Leo committed
99 100 101 102 103

The APKBUILD has duplicate depends. One of them must be removed.

Declaring duplicate dependencies is superfluous.

Leo's avatar
Leo committed
104 105 106
Severity: Minor, Certainty: Certain

## upper-repo-makedepends [AL18]
Leo's avatar
Leo committed
107 108 109 110 111 112 113

The package makedepends on a package in a upper repo. The package must be moved
to the upper repo or the dependency moved to the repo the package is.

Packages cannot makedepend on a package on an upper repo. Packages in main cannot
makedepend on packages in other repos. Packages in community can depend on main
and itself only. Packages in testing can makedepend on main, community and itself
Leo's avatar
Leo committed
114
only. Packages in unmaintained can makedepend on packages of any repo but non-free.
Leo's avatar
Leo committed
115

Leo's avatar
Leo committed
116 117 118
Severity: Serious, Certainty: Certain

## duplicate-makedepends [AL19]
Leo's avatar
Leo committed
119 120 121 122 123

The APKBUILD has duplicate makedepends. One of them must be removed.

Declaring duplicate dependencies is superfluous.

Leo's avatar
Leo committed
124 125 126
Severity: Minor, Certainty: Certain

## upper-repo-checkdepends [AL20]
Leo's avatar
Leo committed
127 128 129 130 131 132 133 134 135

The package checkdepends on a package in a upper repo. The package must be moved
to the upper repo or the dependency moved to the repo the package is.

Packages cannot checkdepend on a package on an upper repo. Packages in main cannot
checkdepend on packages in other repos. Packages in community can checkdepend on main
and itself only. Packages in testing can checkdepend on main, community and itself
only. Packages in unmaintained can checkdepend on package on any repo but non-free.

Leo's avatar
Leo committed
136 137 138
Severity: Serious, Certainty: Certain

## duplicate-checkdepends [AL21]
Leo's avatar
Leo committed
139 140 141 142 143

The APKBUILD has duplicate checkdepends. One of them must be removed.

Declaring duplicate dependencies is superfluous.

Leo's avatar
Leo committed
144 145 146
Severity: Minor, Certainty: Certain

## pkgname-dirname-mismatch [AL23]
Leo's avatar
Leo committed
147 148 149 150

The pkgname variable of the APKBUILD has value *foo* but the directory in which the
APKBUILD is found is not named *foo*

Leo's avatar
Leo committed
151 152 153
Severity: Important, Certainty: Certain

## depends-makedepends-checkdepends-overlap [AL24]
Leo's avatar
Leo committed
154

155 156 157 158
A package is present in 2 to 3 of the 3 types of following dependencies: depends,
makedepends and checkdepends. All of them are installed during creation of the package,
please specify only once in the lowest common denominator location.

Leo's avatar
Leo committed
159 160
Severity: Important, Certainty: Certain

161 162 163 164 165 166 167 168 169 170
## deprecated-packages [AL58]

A package is present in depends, makedepends or checkdepends that is considered deprecated.

The deprecated packages are hard-coded into aports-lint with the option of adding custom ones
via CUSTOM_DEPRECATED_PACKAGES variable. They are considered no longer fit for usage in Alpine
Linux and should be removed IMMEDIATELY.

Severity: Serious, Certainty: Certain

171 172 173 174 175 176 177 178 179
## remote-patch-from-live-source [AL60]

The remote patch is from a live source, like a GitHub Pull Request or a GitLab Merge
Request, those are subjected to cause checksum mismatches if the source changes.

Please import the commits of the source locally.

Severity: Important, Certainty: Certain

Leo's avatar
Leo committed
180
# LABELS TAGS (apkbuild-lint)
Leo's avatar
Leo committed
181

Leo's avatar
Leo committed
182
The following labels and tags are used by the *apkbuild-lint* program
Leo's avatar
Leo committed
183

Leo's avatar
Leo committed
184
## default-builddir-value [AL1]
Leo's avatar
Leo committed
185

186
The value of builddir matches the default of *$srcdir/$pkgname-$pkgver*.
Leo's avatar
Leo committed
187 188
The *builddir* declaration can be removed.

189
Starting with v2.29.0 (Alpine version 3.3) of *abuild* the value is set automatically.
Leo's avatar
Leo committed
190

Leo's avatar
Leo committed
191 192 193 194 195 196
Some packages are excluded from this as they are built by abuild during
bootstrap and as such are built with the pkgname plus the -bootstrap suffix.

More packages can be added to the exceptions by passing a whitespace-separated
list in the variable CUSTOM_BOOTSTRAP_PACKAGES.

197
Severity: Minor, Certainty: Certain
Leo's avatar
Leo committed
198 199

## unnecessary-return-1 [AL2]
Leo's avatar
Leo committed
200 201 202 203 204 205

The APKBUILD has *|| return 1* statements. They can be safely removed.

Starting with version v2.15.0 of *abuild* the building process is executed
with *set -e* effectively adding a *|| return 1* to every command.

Leo's avatar
Leo committed
206
Severity: Minor, Certainty: Certain
Leo's avatar
Leo committed
207 208

## pkgname-quoted [AL3]
Leo's avatar
Leo committed
209 210 211

The APKBUILD's *pkgname* variable is quoted. It must not be quoted.

Leo's avatar
Leo committed
212
Severity: Minor, Certainty: Certain
213

Leo's avatar
Leo committed
214 215 216
## pkgver-quoted [AL4]

The APKBUILD's *pkgver* variable is quoted. It must not be quoted.
Leo's avatar
Leo committed
217

Leo's avatar
Leo committed
218
Severity: Minor, Certainty: Certain
219

Leo's avatar
Leo committed
220
## empty-variable [AL5]
Leo's avatar
Leo committed
221 222 223 224 225 226

The APKBUILD has variables that are empty values, they can safely be removed.

Empty variables can be removed to make the APKBUILD smaller and more
concise.

Leo's avatar
Leo committed
227 228 229
Severity: Minor, Certainty: Certain

## custom-variable [AL6]
Leo's avatar
Leo committed
230 231 232 233

The APKBUILD has custom variables that are not prefixed with an underscore.
prefix the variables with underscore.

Leo's avatar
Leo committed
234
Variables that do no affect behavior of *abuild* should be prefixed with an
Leo's avatar
Leo committed
235 236 237
underscore so maintainers and contributors can easily distinguish their
importance.

Leo's avatar
Leo committed
238 239 240
Severity: Important, Certainty: Certain

## indent-tabs [AL7]
Leo's avatar
Leo committed
241 242 243 244 245 246

The APKBUILD is using spaces instead of tabs for indenting. Replace the
spaces with tabs.

APKBUILDs use tab characters (\t) not spaces for indentation.

Leo's avatar
Leo committed
247 248 249
Severity: Important, Certainty: Certain

## trailing-whitespace [AL8]
Leo's avatar
Leo committed
250 251 252 253 254

The APKBUILD has trailing whitespace characters. Remove them.

Trailing whitespace is superfluous.

Leo's avatar
Leo committed
255 256
Severity: Important, Certainty: Certain

Leo's avatar
Leo committed
257
## backticks-usage [AL25]
Leo's avatar
Leo committed
258 259 260 261 262 263

The APKBUILD uses backticks for running a shell command, use `$()` instead.

Severity: Serious, Certainty: Possible

## function-keyword [AL9]
Leo's avatar
Leo committed
264 265 266 267 268 269 270

The APKBUILD uses the function keyword to declare a function. Use
*function()* instead.

the function keyword is a bashism. *abuild* uses Posix-compliant
shell with the *local* keyword.

Leo's avatar
Leo committed
271 272 273
Severity: Serious, Certainty: Certain

## space-before-function-parenthesis [AL10]
Leo's avatar
Leo committed
274 275

The APKBUILD has a space character between the name of a function
Leo's avatar
Leo committed
276
and the parenthesis that denote it is a function. Remove the superfluous
Leo's avatar
Leo committed
277 278
space.

Leo's avatar
Leo committed
279
Severity: MInor, Certainty: Certain
280

Leo's avatar
Leo committed
281
## space-after-function-parenthesis [AL11]
Leo's avatar
Leo committed
282 283 284 285

The APKBUILD doesn't have a space after the function parenthesis or has more
than one space. Use only one space after the function parenthesis.

Leo's avatar
Leo committed
286
Severity: Minor, Certainty: Certain
287

Leo's avatar
Leo committed
288
## newline-opening-brace [AL12]
Leo's avatar
Leo committed
289 290 291 292 293

The APKBUILD has a newline before the opening brace of a function. Put the
opening brace in the same line as the declaration with one space after the
function parenthesis.

Leo's avatar
Leo committed
294
Severity: Minor, Certainty: Certain
295

Leo's avatar
Leo committed
296
## superfluous-cd-builddir [AL13]
Leo's avatar
Leo committed
297 298 299 300 301

The APKBUILD has *cd "$builddir"* statements that are superfluous. Remove them.

Staring with v3.3.0 of *abuild* the *prepare*, *build*, *check* and *package*
functions automatically have their working directory set to the value of
Leo's avatar
Leo committed
302 303
*builddir*. It is also possible that there are 2 *cd "$builddir"* statements
one after the other.
304

305
Severity: Minor, Certainty: Possible
Leo's avatar
Leo committed
306 307

## pkgname-has-uppercase [AL14]
308 309

pkgname has uppercase characters, pkgname must have only lowercase characters.
Leo's avatar
Leo committed
310

Leo's avatar
Leo committed
311 312 313
Severity: Serious, Certainty: Certain

## pkgver-has-pkgrel [AL15]
Leo's avatar
Leo committed
314 315 316

pkgver has *-r* followed by a number, that is reserved for the relaease of a package
as defined by the *pkgrel* variable.
Leo's avatar
Leo committed
317 318

Severity: Serious, Certainty: Certain
Leo's avatar
Leo committed
319 320 321

## _builddir-is-set [AL26]

Kevin Daudt's avatar
Kevin Daudt committed
322
\_builddir is set instead of builddir, which is an old variable from before builddir
Leo's avatar
Leo committed
323
existed as a concept understood by abuild.
Leo's avatar
Leo committed
324 325

Severity: Serious, Certainty: Certain
Leo's avatar
Leo committed
326 327 328 329 330 331

## literal-integer-is-quoted [AL28]

A variable declaration containing only integers should not be quoted.

Severity: Minor,  Certainty: Certain
Kevin Daudt's avatar
Kevin Daudt committed
332 333 334 335 336 337 338 339 340 341 342

## pkgname-used-in-source [AL29]

"$pkgname" is used in the source url. This tightly couples the pkgname to the
upstream name, which makes it harder to rename packages or create specialized /
variants of packages.

Instead, use the upstream name fully written out. This only counts for the url
itself, not the local archive name prefix.

Severity: Minor, Certainty: Certain
Leo's avatar
Leo committed
343 344 345 346 347 348 349

## double-underscore-in-variable [AL30]

Usage of double underscore in variables is forbidden, use always one underscore
for variables that are not used by abuild.

Severity: Minor, Certainty: Certain
Leo's avatar
Leo committed
350 351 352 353 354 355

## variable-capitalized [AL31]

Variables should have no capitalized letters

Severity: Minor, Certainty: Certain
Leo's avatar
Leo committed
356 357 358 359 360

## braced-variable [AL32]

Variable has braces around it while it is not required, remove the braces.

Leo's avatar
Leo committed
361
Severity: Minor, Certainty: Possible
Kevin Daudt's avatar
Kevin Daudt committed
362

363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382
## cpan-variable [AL35]

The variables `cpandepends`, `cpanmakedepends` and `cpancheckdepends` were created
by the apkbuild-cpan program but are now deprecated and their contents must be merged
into the contents of its respective variable.

Severity: Minor, Certainty: Certain

## overwrite-xflags [AL36]

Don't overwrite `CFLAGS`, `GOFLAGS`, `CPPFLAGS`, `CXXFLAGS` and `FFLAGS`. There
flags are generally defined outside the of the APKBUILD and should not be
overwritten because they contain important flags that should not be discarded.
Instead, expand the variable. For example: `CFLAGS="$CFLAGS .."`

This list might be expanded as more variables are found that should not be
overwritten.

Severity: Serious, Certainty: Certain

383 384 385 386 387 388
## invalid-option [AL49]

A option in the option= variable has a value that is not used by abuild,
while it most likely won't cause any problems it is considered good form
to remove it.

389 390 391
The variable VALID_CUSTOM_OPTIONS can be used to denote other options that
are acceptable, it takes a whitespace-separated list.

392 393
Severity: Minor, Certainty: Certain

Leo's avatar
Leo committed
394 395 396 397 398 399 400 401
## missing-default-prepare [AL54]

The prepare() function is defined but a call to default_prepare (which applies all
patches in source=) is missing. Please add default_prepare where appropriate in the
definition of prepare().

Severity: Serious, Certainty: Certain

Leo's avatar
Leo committed
402 403 404 405 406 407 408
## build-type-not-none [AL55]

The CMake option CMAKE_BUILD_TYPE must be set to None, otherwise the compiler flags
set by abuild won't be respected.

Severity: Serious, Certainty: Possible

409
## missing-patch-description [AL56]
410 411 412 413 414 415

A patch specified in `$sources` is missing a description. The
description should at the very least explain why the patch is necessary.

Severity: Minor, Certainty: Certain

Leo's avatar
Leo committed
416 417 418 419 420
## invalid-arch [AL57]

The variable 'arch' in the APKBUILD has an invalid value in it, the only options
are the name of the arches used by Alpine Linux and the strings 'noarch' and 'all'.

421 422 423 424
The acceptable arches are taken from /usr/share/abuild/functions.sh as those are the
ones recognized by abuild and thus Alpine Linux as valid arches, if you have other
arches, read below.

Leo's avatar
Leo committed
425 426 427 428 429
The variable CUSTOM_VALID_ARCHES can be used to denote other arches that are to be
considered valid, it takes a whitespace-separated list.

Severity: Serious, Certainty: Certain

Kevin Daudt's avatar
Kevin Daudt committed
430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447
# LABELS TAGS (initd-lint)

## unexpected-shebang-line [AL33]

OpenRC service files need to use `#!/sbin/openrc-run` to properly work. See
https://github.com/OpenRC/openrc/blob/master/service-script-guide.md#syntax-of-service-scripts
for more details.

Severity: Important, Certainty: Certain

## custom-start-stop-function [AL34]

It's discouraged to write custom start / stop function for service files. In
most cases it suffices to define `command`, `command_args`, and `pidfile`.  See
https://github.com/OpenRC/openrc/blob/master/service-script-guide.md#dont-write-your-own-startstop-functions
for more information.

Severity: Important, Certainty: Certain
Leo's avatar
Leo committed
448

Leo's avatar
Leo committed
449
# LABEL TAGS (secfixes-check)
Leo's avatar
Leo committed
450

Leo's avatar
Leo committed
451
## secfixes-missing-colon [AL37]
Leo's avatar
Leo committed
452

Leo's avatar
Leo committed
453
The secfixes header is missing a colon at the end.
454

Leo's avatar
Leo committed
455
Severity: Serious, Certainty: Certain
456

Leo's avatar
Leo committed
457
## pkgver-pkgrel-missing-colon [AL38]
458

Leo's avatar
Leo committed
459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474
The pkgver-pkgrel header is colon at the end.

Severity: Serious, Certainty: Certain

## pkgver-pkgrel-invalid-pkgver [AL39]

The pkgver-pkgrel header has an invalid pkgver.

Severity: Serious, Certainty: Certain

## pkgver-pkgrel-invalid-pkgrel [AL40]

The pkgver-pkgrel header has an invalid pkgrel.

Severity: Serious, Certainty: Certain

475
## security-identifier-missing-hyphen [AL41]
Leo's avatar
Leo committed
476

477
The security identifier is missing a leading hyphen.
Leo's avatar
Leo committed
478 479 480

Severity: Serious, Certainty: Certain

481
## security-identifier-wrong-indent [AL47]
Leo's avatar
Leo committed
482 483 484 485 486 487

The CVE identifier has too many or too few leading whitespaces,
it must have exactly 5 whitespaces between the comment marker and
the mapping hyphen.

Severity: Serious, Certainty: Certain
Leo's avatar
Leo committed
488 489 490 491 492

## pkgver-pkgrel-wrong-indent [AL48]

The pkgver-pkgrel header has too many or too few leading whitespaces,
it must have exactly 3 whitespaces between the comment marker and the
Leo's avatar
Leo committed
493
mapping hyphen.
Leo's avatar
Leo committed
494 495

Severity: Serious, Certainty: Certain
Leo's avatar
Leo committed
496

497 498 499
## cve-identifier-formatted-incorrectly [AL50]

The CVE identifier is not formatted correctly, please check the output
Leo's avatar
Leo committed
500
string for the reason why.
501 502

Severity: Minor, Certainty: Certain
503 504 505 506 507 508 509

## gnutls-sa-identifier-formatted-incorrectly [AL51]

The GNUTLS-SA identifier is not formatted correctly, please check the output
string for the reason why.

Severity: Minor, Certainty: Certain
510 511 512 513 514 515 516

## unknown-security-identifier [AL52]

An unknown identifier was passed, if it is a legitimate identifier then please
contact the authors to add support for it.

Severity: Minor, Certainty: Certain
517 518 519 520 521 522 523

## xsa-identifier-formatted-incorrectly [AL53]

The XSA identifier is not formatted correctly, please check the output string
for the reason why.

Severity: Minor, Certainty: Certain
Leo's avatar
Leo committed
524 525 526 527 528 529 530 531

## duplicate-identifier-value [AL59]

There are duplicate values of known identifiers. While this doesn't cause problems
while building it may cause false positives for users that rely on our secdb to
know if something is fixed.

Severity: Serious, Certainty: Certain