• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Lint
2
3[Android Lint] is [one of the static analysis tools] that Chromium uses to catch
4possible issues in Java code.
5
6This is a [list of checks] that you might encounter.
7
8[Android Lint]: https://googlesamples.github.io/android-custom-lint-rules/book.md.html
9[one of the static analysis tools]: static_analysis.md
10[list of checks]: https://googlesamples.github.io/android-custom-lint-rules/checks/index.md.html
11
12[TOC]
13
14## How Chromium uses lint
15
16Chromium only runs lint on apk or bundle targets that explicitly set
17`enable_lint = true`. Some example targets that have this set are:
18
19 - `//chrome/android:monochrome_public_bundle`
20 - `//android_webview/support_library/boundary_interfaces:boundary_interface_example_apk`
21 - `//remoting/android:remoting_apk`
22
23## My code has a lint error
24
25If lint reports an issue in your code, there are several possible remedies.
26In descending order of preference:
27
28### Fix it
29
30While this isn't always the right response, fixing the lint error or warning
31should be the default.
32
33### Suppress it locally
34
35Java provides an annotation,
36[`@SuppressWarnings`](https://developer.android.com/reference/java/lang/SuppressWarnings),
37that tells lint to ignore the annotated element. It can be used on classes,
38constructors, methods, parameters, fields, or local variables, though usage in
39Chromium is typically limited to the first three. You do not need to import it
40since it is in the `java.lang` package.
41
42Like many suppression annotations, `@SuppressWarnings` takes a value that tells
43**lint** what to ignore. It can be a single `String`:
44
45```java
46@SuppressWarnings("NewApi")
47public void foo() {
48    a.methodThatRequiresHighSdkLevel();
49}
50```
51
52It can also be a list of `String`s:
53
54```java
55@SuppressWarnings({
56        "NewApi",
57        "UseSparseArrays"
58        })
59public Map<Integer, FakeObject> bar() {
60    Map<Integer, FakeObject> shouldBeASparseArray = new HashMap<Integer, FakeObject>();
61    another.methodThatRequiresHighSdkLevel(shouldBeASparseArray);
62    return shouldBeASparseArray;
63}
64```
65
66For resource xml files you can use `tools:ignore`:
67
68```xml
69<?xml version="1.0" encoding="utf-8"?>
70<resources xmlns:tools="http://schemas.android.com/tools">
71    <!-- TODO(crbug/###): remove tools:ignore once these colors are used -->
72    <color name="hi" tools:ignore="NewApi,UnusedResources">@color/unused</color>
73</resources>
74```
75
76The examples above are the recommended ways of suppressing lint warnings.
77
78### Suppress it in a `lint-suppressions.xml` file
79
80**lint** can be given a per-target XML configuration file containing warnings or
81errors that should be ignored. Each target defines its own configuration file
82via the `lint_suppressions_file` gn variable. It is usually defined near its
83`enable_lint` gn variable.
84
85These suppressions files should only be used for temporarily ignoring warnings
86that are too hard (or not possible) to suppress locally, and permanently
87ignoring warnings only for this target. To permanently ignore a warning for all
88targets, add the warning to the `_DISABLED_ALWAYS` list in
89[build/android/gyp/lint.py](https://source.chromium.org/chromium/chromium/src/+/main:build/android/gyp/lint.py).
90Disabling globally makes lint a bit faster.
91
92The exception to the above rule is for warnings that affect multiple languages.
93Feel free to suppress those in lint-suppressions.xml files since it is not
94practical to suppress them in each language file and it is a lot of extra bloat
95to list out every language for every violation in lint-baseline.xml files.
96
97Here is an example of how to structure a suppressions XML file:
98
99```xml
100<?xml version="1.0" encoding="utf-8" ?>
101<lint>
102  <!-- Chrome is a system app. -->
103  <issue id="ProtectedPermissions" severity="ignore"/>
104  <issue id="UnusedResources">
105    <!-- 1 raw resources are accessed by URL in various places. -->
106    <ignore regexp="gen/remoting/android/.*/res/raw/credits.*"/>
107    <!-- TODO(crbug.com/###): Remove the following line.  -->
108    <ignore regexp="The resource `R.string.soon_to_be_used` appears to be unused"/>
109  </issue>
110</lint>
111```
112
113## What are `lint-baseline.xml` files for?
114
115Baseline files are to help us introduce new lint warnings and errors without
116blocking on fixing all our existing code that violate these new errors. Since
117they are generated files, they should **not** be used to suppress lint warnings.
118One of the approaches above should be used instead. Eventually all the errors in
119baseline files should be either fixed or ignored permanently.
120
121Most devs do not need to update baseline files and should not need the script
122below. Occasionally when making large build configuration changes it may be
123necessary to update baseline files (e.g. increasing the min_sdk_version).
124
125Baseline files are defined via the `lint_baseline_file` gn variable. It is
126usually defined near a target's `enable_lint` gn variable. To regenerate all
127baseline files, run:
128
129```
130$ third_party/android_build_tools/lint/rebuild_baselines.py
131```
132
133This script will also update baseline files in downstream //clank if needed.
134Since downstream and upstream use separate lint binaries, it is usually safe
135to simply land the update CLs in any order.
136