1# Android Lint Checks for AOSP
2
3Custom Android Lint checks are written here to be executed against java modules
4in AOSP. These checks are broken down into two subdirectories:
5
61. [Global Checks](#android-global-lint-checker)
72. [Framework Checks](#android-framework-lint-checker)
8
9# [Android Global Lint Checker](/global)
10Checks written here are executed for the entire tree. The `AndroidGlobalLintChecker`
11build target produces a jar file that is included in the overall build output
12(`AndroidGlobalLintChecker.jar`).  This file is then downloaded as a prebuilt under the
13`prebuilts/cmdline-tools` subproject, and included by soong with all invocations of lint.
14
15## How to add new global lint checks
161. Write your detector with its issues and put it into
17   `global/checks/src/main/java/com/google/android/lint`.
182. Add your detector's issues into `AndroidGlobalIssueRegistry`'s `issues`
19   field.
203. Write unit tests for your detector in one file and put it into
21   `global/checks/test/java/com/google/android/lint`.
224. Have your change reviewed and merged.  Once your change is merged,
23   obtain a build number from a successful build that includes your change.
245. Run `prebuilts/cmdline-tools/update-android-global-lint-checker.sh
25   <build_number>`. The script will create a commit that you can upload for
26   approval to the `prebuilts/cmdline-tools` subproject.
276. Done! Your lint check should be applied in lint report builds across the
28   entire tree!
29
30# [Android Framework Lint Checker](/framework)
31
32Checks written here are going to be executed for modules that opt in to those (e.g. any
33`services.XXX` module) and results will be automatically reported on CLs on gerrit.
34
35## How to add new framework lint checks
36
371. Write your detector with its issues and put it into
38   `framework/checks/src/main/java/com/google/android/lint`.
392. Add your detector's issues into `AndroidFrameworkIssueRegistry`'s `issues` field.
403. Write unit tests for your detector in one file and put it into
41   `framework/checks/test/java/com/google/android/lint`.
424. Done! Your lint checks should be applied in lint report builds for modules that include
43   `AndroidFrameworkLintChecker`.
44
45## How to run lint against your module
46
471. Add the following `lint` attribute to the module definition, e.g. `services.autofill`:
48```
49java_library_static {
50    name: "services.autofill",
51    ...
52    lint: {
53        extra_check_modules: ["AndroidFrameworkLintChecker"],
54    },
55}
56```
572. Run the following command to verify that the report is being correctly built:
58```
59m out/soong/.intermediates/frameworks/base/services/autofill/services.autofill/android_common/lint/lint-report.html
60```
61   (Lint report can be found in the same path, i.e. `out/../lint-report.html`)
62
633. Now lint issues should appear on gerrit!
64
65**Notes:**
66
67- Lint report will not be produced if you just build the module, i.e. `m services.autofill` will not
68  build the lint report.
69- If you want to build lint reports for more than 1 module and they include a common module in their
70  `defaults` field, e.g. `platform_service_defaults`, you can add the `lint` property to that common
71  module instead of adding it in every module.
72- If you want to run a single lint type, use the `ANDROID_LINT_CHECK`
73  environment variable with the id of the lint. For example:
74  `ANDROID_LINT_CHECK=UnusedTokenOfOriginalCallingIdentity m out/[...]/lint-report.html`
75
76# How to apply automatic fixes suggested by lint
77
78See [lint_fix](fix/README.md)
79
80# Create or update a baseline
81
82Baseline files can be used to silence known errors (and warnings) that are deemed to be safe. When
83there is a lint-baseline.xml file in the root folder of the java library, soong will
84automatically use it. You can override the file using lint properties too.
85
86```
87java_library {
88    lint: {
89        baseline_filename: "my-baseline.xml", // default: lint-baseline.xml;
90    }
91}
92```
93
94When using soong to create a lint report (as described above), it also creates a reference
95baseline file. This contains all lint errors and warnings that were found. So the next time
96you run lint, if you use this baseline file, there should be 0 findings.
97
98After the previous invocation, you can find the baseline here:
99
100```
101out/soong/.intermediates/frameworks/base/services/autofill/services.autofill/android_common/lint/lint-baseline.xml
102```
103
104As noted above, this baseline file contains warnings too, which might be undesirable. For example,
105CI tools might surface these warnings in code reviews. In order to create this file without
106warnings, we need to pass another flag to lint: `--nowarn`. One option is to add the flag to your
107Android.bp file and then run lint again:
108
109```
110  lint: {
111    extra_check_modules: ["AndroidFrameworkLintChecker"],
112    flags: ["--nowarn"],
113  }
114```
115
116# Documentation
117
118- [Android Lint Docs](https://googlesamples.github.io/android-custom-lint-rules/)
119- [Lint Check Unit Testing](https://googlesamples.github.io/android-custom-lint-rules/api-guide/unit-testing.md.html)
120- [Android Lint source files](https://source.corp.google.com/studio-main/tools/base/lint/libs/lint-api/src/main/java/com/android/tools/lint/)
121- [PSI source files](https://github.com/JetBrains/intellij-community/tree/master/java/java-psi-api/src/com/intellij/psi)
122- [UAST source files](https://upsource.jetbrains.com/idea-ce/structure/idea-ce-7b9b8cc138bbd90aec26433f82cd2c6838694003/uast/uast-common/src/org/jetbrains/uast)
123- [IntelliJ plugin for viewing PSI tree of files](https://plugins.jetbrains.com/plugin/227-psiviewer)
124