1## Correctness checks {#checks}
2
3### Android lint {#checks-lint}
4
5Android lint runs correctness checks on all library source code, with a limited
6subset of checks run on test sources.
7
8Lint sometimes flags false positives, even though it is safe to ignore these
9errors (for example `WeakerAccess` warnings when you are avoiding synthetic
10access). There may also be lint failures when your library is in the middle of a
11beta / rc / stable release, and cannot make the breaking changes needed to fix
12the root cause. There are two ways of ignoring lint errors:
13
141.  Suppression - using `@SuppressLint` (for Java) or `@Suppress` annotations to
15    ignore the warning per call site, per method, or per file.
16
17    Note: `@SuppressLint` requires Android dependency
18
192.  Baselines - allowlisting errors in a `lint-baseline.xml` file at the root of
20    the project directory.
21
22Where possible, you should use a **suppression annotation at the call site**.
23This helps ensure that you are only suppressing the *exact* failure, and this
24also keeps the failure visible so it can be fixed later on. Only use a baseline
25if you are in a Java library without Android dependencies, or when enabling a
26new lint check, and it is prohibitively expensive / not possible to fix the
27errors generated by enabling this lint check.
28
29To update a lint baseline after you have fixed issues, run the
30`updateLintBaseline` task.
31
32```shell
33./gradlew :core:core:updateLintBaseline
34```
35
36### Metalava API lint {#checks-metalava}
37
38As well as Android lint, which runs on all source code, Metalava will also run
39checks on the public API surface of each library. Similar to with Android Lint,
40there can sometimes be false positives / intended deviations from the API
41guidelines that Metalava will lint your API surface against. When this happens,
42you can suppress Metalava API lint issues using `@SuppressLint` (for Java) or
43`@Suppress` annotations. In cases where it is not possible, update Metalava's
44baseline with the `updateApiLintBaseline` task.
45
46```shell
47./gradlew :core:core:updateApiLintBaseline
48```
49
50This will create/amend the `api_lint.ignore` file that lives in a library's
51`api` directory.
52
53### Build output {#checks-build}
54
55In order to more easily identify the root cause of build failures, we want to
56keep the amount of output generated by a successful build to a minimum.
57Consequently, we track build output similarly to the way in which we track lint
58warnings.
59
60#### Invoking build output validation {#checks-build-invoke}
61
62You can add `-Pandroidx.validateNoUnrecognizedMessages` to any other `gradlew`
63command to enable validation of build output. For example:
64
65```shell
66./gradlew -Pandroidx.validateNoUnrecognizedMessages :help
67```
68
69#### Exempting new build output messages {#checks-build-suppress}
70
71Please avoid exempting new build output and instead fix or suppress the warnings
72themselves, because that will take effect not only on the build server but also
73in Android Studio, and will also run more quickly.
74
75If you cannot prevent the message from being generating and must exempt the
76message anyway, follow the instructions in the error:
77
78```shell
79$ ./gradlew -Pandroidx.validateNoUnrecognizedMessages :help
80
81Error: build_log_simplifier.py found 15 new messages found in /usr/local/google/workspace/aosp-androidx-git/out/dist/gradle.log.
82
83Please fix or suppress these new messages in the tool that generates them.
84If you cannot, then you can exempt them by doing:
85
86  1. cp /usr/local/google/workspace/aosp-androidx-git/out/dist/gradle.log.ignore /usr/local/google/workspace/aosp-androidx-git/frameworks/support/development/build_log_simplifier/messages.ignore
87  2. modify the new lines to be appropriately generalized
88```
89
90Each line in this exemptions file is a regular expression matching one or more
91lines of output to be exempted. You may want to make these expressions as
92specific as possible to ensure that the addition of new, similar messages will
93also be detected (for example, discovering an existing warning in a new source
94file).
95