jbudorick | 8d4d974 | 2016-04-26 04:47:10 | [diff] [blame] | 1 | # Lint |
| 2 | |
| 3 | Android's [**lint**](http://developer.android.com/tools/help/lint.html) is a static |
| 4 | analysis tool that Chromium uses to catch possible issues in Java code. |
| 5 | |
| 6 | [TOC] |
| 7 | |
| 8 | ## How Chromium uses lint |
| 9 | |
| 10 | Chromium runs lint on a per-target basis for all targets using any of the |
| 11 | following templates if they are marked as Chromium code (i.e., |
| 12 | `chromium_code = true`): |
| 13 | |
| 14 | - `android_apk` |
| 15 | - `android_library` |
| 16 | - `instrumentation_test_apk` |
| 17 | - `unittest_apk` |
| 18 | |
| 19 | Chromium also runs lint on a per-target basis for all targets using any of the |
| 20 | following templates if they are marked as Chromium code and they support |
| 21 | Android (i.e., `supports_android = true`): |
| 22 | |
| 23 | - `java_library` |
| 24 | |
| 25 | This is implemented in the |
| 26 | [`android_lint`](https://code.google.com/p/chromium/codesearch#chromium/src/build/config/android/internal_rules.gni&q=android_lint%20file:internal_rules%5C.gni) |
| 27 | gn template. |
| 28 | |
| 29 | ## My code has a lint error |
| 30 | |
| 31 | If lint reports an issue in your code, there are several possible remedies. |
| 32 | In descending order of preference: |
| 33 | |
| 34 | ### Fix it |
| 35 | |
| 36 | While this isn't always the right response, fixing the lint error or warning |
| 37 | should be the default. |
| 38 | |
| 39 | ### Suppress it in code |
| 40 | |
| 41 | Android provides an annotation, |
| 42 | [`@SuppressLint`](http://developer.android.com/reference/android/annotation/SuppressLint.html), |
| 43 | that tells lint to ignore the annotated element. It can be used on classes, |
| 44 | constructors, methods, parameters, fields, or local variables, though usage |
| 45 | in Chromium is typically limited to the first three. |
| 46 | |
| 47 | Like many suppression annotations, `@SuppressLint` takes a value that tells **lint** |
| 48 | what to ignore. It can be a single `String`: |
| 49 | |
| 50 | ```java |
| 51 | @SuppressLint("NewApi") |
| 52 | public void foo() { |
| 53 | a.methodThatRequiresHighSdkLevel(); |
| 54 | } |
| 55 | ``` |
| 56 | |
| 57 | It can also be a list of `String`s: |
| 58 | |
| 59 | ```java |
| 60 | @SuppressLint({ |
| 61 | "NewApi", |
| 62 | "UseSparseArrays" |
| 63 | }) |
| 64 | public Map<Integer, FakeObject> bar() { |
| 65 | Map<Integer, FakeObject> shouldBeASparseArray = new HashMap<Integer, FakeObject>(); |
| 66 | another.methodThatRequiresHighSdkLevel(shouldBeASparseArray); |
| 67 | return shouldBeASparseArray; |
| 68 | } |
| 69 | ``` |
| 70 | |
| 71 | This is the preferred way of suppressing warnings in a limited scope. |
| 72 | |
| 73 | ### Suppress it in the suppressions XML file |
| 74 | |
| 75 | **lint** can be given an XML configuration containing warnings or errors that |
| 76 | should be ignored. Chromium's lint suppression XML file can be found in |
| 77 | [`build/android/lint/suppressions.xml`](https://chromium.googlesource.com/chromium/src/+/master/build/android/lint/suppressions.xml). |
| 78 | It can be updated to suppress current warnings by running: |
| 79 | |
| 80 | ```bash |
| 81 | $ python build/android/lint/suppress.py <result.xml file> |
| 82 | ``` |
| 83 | |
| 84 | e.g., to suppress lint errors found in `media_java`: |
| 85 | |
| 86 | ```bash |
| 87 | $ python build/android/lint/suppress.py out/Debug/gen/media/base/android/media_java__lint/result.xml |
| 88 | ``` |
| 89 | |
| 90 | **This mechanism should only be used for disabling warnings across the entire code base; class-specific lint warnings should be disabled inline.** |
| 91 | |