1# API Lint 2 3Metalava can optionally run warn about various API problems based on the Android 4API Council's guidelines, described in go/android-api-guidelines. 5 6These rules are not always exact. For example, you should avoid using acronyms 7in names; e.g. a method should be named handleUri, not handleURI. But what about 8getZOrder? This is probably better than getZorder, but metalava can't tell 9without consulting a dictionary. 10 11Therefore, there are cases where you want to say "ok, that's good advice in 12general, but wrong here". In order to avoid having this warningshow up again 13and again, there are two ways to mark an issue such that it is no longer 14flagged. 15 16(Note that metalava will not report issues on classes, methods and fields that 17are deprecated since these are presumably already known to be bad and are already 18discouraged.) 19 20## Suppressing with @Suppress 21 22Next to an error message, metalava will include the issue id. For example, 23here's a sample error message: 24 25 src/android/pkg/MyStringImpl.java:3: error: Don't expose your implementation details: MyStringImpl ends with Impl [EndsWithImpl] 26 27Here the id is "EndsWithImpl". You can suppress this with the @SuppressLint 28annotation: 29 30 ... 31 import android.annotation.SuppressLint; 32 ... 33 34 @SuppressLint("EndsWithImpl") 35 public class MyStringImpl { 36 ... 37 38## Suppressing with baselines 39 40Metalava also has support for "baselines", which are files which record all the 41current warnings and errors in the codebase. When metalava runs, it looks up the 42baseline to see if a given issue is already listed in the baseline, and if so, 43it is silently ignored. 44 45You can pass a flag to metalava ("--update-baseline") to tell it to update the 46baseline files with any new errors it comes across instead of reporting 47them. With soong, if you specify the baseline explicitly, like this: 48 49 --- a/Android.bp 50 +++ b/Android.bp 51 @@ -1678,6 +1678,7 @@ droidstubs { 52 }, 53 api_lint: { 54 enabled: true, 55 ==> baseline_filename: "api/baseline.txt", <== 56 } 57 jdiff_enabled: true, 58 } 59 60then the build system will automatically supply `--update-baseline` on your 61behalf to a generated file in the out/ folder, and if there's a failure metalava 62will tell you where to find the updated baseline which you can then copy into 63place: 64 65 ... 66 93 new API lint issues were found. See tools/metalava/API-LINT.md for how to handle these. 67 ************************************************************ 68 Your API changes are triggering API Lint warnings or errors. 69 To make these errors go away, you have two choices: 70 71 1. You can suppress the errors with @SuppressLint("<id>") 72 2. You can update the baseline by executing the following 73 command: 74 cp \ 75 out/soong/.intermediates/frameworks/base/system-api-stubs-docs/android_common/api/system-baseline.txt \ 76 frameworks/base/api/system-baseline.txt 77 To submit the revised baseline.txt to the main Android 78 repository, you will need approval. 79 ************************************************************ 80 81 82 83Then re-run the build and you should now see diffs to the baseline file; git 84diff to make sure you're really only marking the issues you intended to include. 85 86 $ git status 87 ... 88 Untracked files: 89 (use "git add <file>..." to include in what will be committed) 90 91 baseline.txt 92 93## Copying File Manually 94 95In the near future the build system will not allow source files to be modified 96by the build. At that point you'll need to manually copy in the file instead. 97During the build, before failing, metalava will emit a message like this: 98 99 ... 100 metalava wrote updated baseline to out/something/baseline.txt 101 ... 102 103At that point you can copy the file to where you need: 104 105```sh 106$ cp out/something/baseline.txt frameworks/base/api/baseline.txt 107``` 108 109## Existing Issues 110 111You can view the exact set of existing issues (current APIs that get flagged by 112API lint) by inspecting the baseline files in the source tree, but to get a 113sense of the types of issues that are more likely to have a false positive, 114here's the existing distribution as of early 2019: 115 116 Count Issue Id Rule Severity 117 -------------------------------------------------- 118 119 932 ProtectedMember M7 error 120 321 OnNameExpected warning 121 288 ArrayReturn warning 122 269 ActionValue C4 error 123 266 NoByteOrShort FW12 warning 124 221 ExecutorRegistration L1 warning 125 211 AllUpper C2 error 126 206 GetterSetterNames M6 error 127 185 BannedThrow error 128 172 SamShouldBeLast warning 129 159 NoClone error 130 159 ParcelNotFinal FW8 error 131 119 NotCloseable warning 132 105 ListenerLast M3 warning 133 81 ConcreteCollection CL2 error 134 78 StaticUtils error 135 76 IntentName C3 error 136 74 VisiblySynchronized M5 error 137 72 GenericException S1 error 138 65 KotlinOperator warning 139 57 AcronymName S1 warning 140 55 ParcelCreator FW3 error 141 54 ParcelConstructor FW3 error 142 53 UseIcu warning 143 48 Enum F5 error 144 41 RethrowRemoteException FW9 error 145 37 AutoBoxing M11 error 146 35 StreamFiles M10 warning 147 28 IntentBuilderName FW1 warning 148 27 ServiceName C4 error 149 26 ListenerInterface L1 error 150 25 ContextFirst M3 error 151 25 InterfaceConstant C4 error 152 24 CallbackInterface CL3 error 153 24 RegistrationName L3 error 154 23 IllegalStateException S1 warning 155 22 EqualsAndHashCode M8 error 156 22 PackageLayering FW6 warning 157 18 MinMaxConstant C8 warning 158 18 SingletonConstructor error 159 17 MethodNameUnits error 160 15 MissingBuildMethod warning 161 15 UserHandleName warning 162 14 UserHandle warning 163 13 ResourceFieldName error 164 12 ManagerLookup error 165 11 ManagerConstructor error 166 9 CallbackMethodName L1 error 167 9 ParcelableList warning 168 8 CallbackName L1 warning 169 7 HeavyBitSet error 170 7 ResourceValueFieldName C7 error 171 6 CompileTimeConstant error 172 6 SetterReturnsThis M4 warning 173 4 EndsWithImpl error 174 4 TopLevelBuilder warning 175 4 UseParcelFileDescriptor FW11 error 176 3 MentionsGoogle error 177 3 StartWithLower S1 error 178 2 AbstractInner warning 179 2 BuilderSetStyle warning 180 2 OverlappingConstants C1 warning 181 2 PairedRegistration L2 error 182 2 SingularCallback L1 error 183 2 StartWithUpper S1 error 184 1 ContextNameSuffix C4 error 185 1 KotlinKeyword error 186 -------------------------------------------------- 187 4902 188 189(This is generated when metalava is invoked with both --verbose and --update-baseline.) 190