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: true, 54 ==> baseline_filename: "api/baseline.txt", <== 55 jdiff_enabled: true, 56 } 57 58then the build system will automatically supply `--update-baseline` on your 59behalf to a generated file in the out/ folder, and if there's a failure metalava 60will tell you where to find the updated baseline which you can then copy into 61place: 62 63 ... 64 93 new API lint issues were found. See tools/metalava/API-LINT.md for how to handle these. 65 ************************************************************ 66 Your API changes are triggering API Lint warnings or errors. 67 To make these errors go away, you have two choices: 68 69 1. You can suppress the errors with @SuppressLint("<id>") 70 2. You can update the baseline by executing the following 71 command: 72 cp \ 73 out/soong/.intermediates/frameworks/base/system-api-stubs-docs/android_common/api/system-baseline.txt \ 74 frameworks/base/api/system-baseline.txt 75 To submit the revised baseline.txt to the main Android 76 repository, you will need approval. 77 ************************************************************ 78 79 80 81Then re-run the build and you should now see diffs to the baseline file; git 82diff to make sure you're really only marking the issues you intended to include. 83 84 $ git status 85 ... 86 Untracked files: 87 (use "git add <file>..." to include in what will be committed) 88 89 baseline.txt 90 91## Copying File Manually 92 93In the near future the build system will not allow source files to be modified 94by the build. At that point you'll need to manually copy in the file instead. 95During the build, before failing, metalava will emit a message like this: 96 97 ... 98 metalava wrote updated baseline to out/something/baseline.txt 99 ... 100 101At that point you can copy the file to where you need: 102 103```sh 104$ cp out/something/baseline.txt frameworks/base/api/baseline.txt 105``` 106 107## Existing Issues 108 109You can view the exact set of existing issues (current APIs that get flagged by 110API lint) by inspecting the baseline files in the source tree, but to get a 111sense of the types of issues that are more likely to have a false positive, 112here's the existing distribution as of early 2019: 113 114 Count Issue Id Rule Severity 115 -------------------------------------------------- 116 117 932 ProtectedMember M7 error 118 321 OnNameExpected warning 119 288 ArrayReturn warning 120 269 ActionValue C4 error 121 266 NoByteOrShort FW12 warning 122 221 ExecutorRegistration L1 warning 123 211 AllUpper C2 error 124 206 GetterSetterNames M6 error 125 185 BannedThrow error 126 172 SamShouldBeLast warning 127 159 NoClone error 128 159 ParcelNotFinal FW8 error 129 119 NotCloseable warning 130 105 ListenerLast M3 warning 131 81 ConcreteCollection CL2 error 132 78 StaticUtils error 133 76 IntentName C3 error 134 74 VisiblySynchronized M5 error 135 72 GenericException S1 error 136 65 KotlinOperator warning 137 57 AcronymName S1 warning 138 55 ParcelCreator FW3 error 139 54 ParcelConstructor FW3 error 140 53 UseIcu warning 141 48 Enum F5 error 142 41 RethrowRemoteException FW9 error 143 37 AutoBoxing M11 error 144 35 StreamFiles M10 warning 145 28 IntentBuilderName FW1 warning 146 27 ServiceName C4 error 147 26 ListenerInterface L1 error 148 25 ContextFirst M3 error 149 25 InterfaceConstant C4 error 150 24 CallbackInterface CL3 error 151 24 RegistrationName L3 error 152 23 IllegalStateException S1 warning 153 22 EqualsAndHashCode M8 error 154 22 PackageLayering FW6 warning 155 18 MinMaxConstant C8 warning 156 18 SingletonConstructor error 157 17 MethodNameUnits error 158 15 MissingBuildMethod warning 159 15 UserHandleName warning 160 14 UserHandle warning 161 13 ResourceFieldName error 162 12 ManagerLookup error 163 11 ManagerConstructor error 164 9 CallbackMethodName L1 error 165 9 ParcelableList warning 166 8 CallbackName L1 warning 167 7 HeavyBitSet error 168 7 ResourceValueFieldName C7 error 169 6 CompileTimeConstant error 170 6 SetterReturnsThis M4 warning 171 4 EndsWithImpl error 172 4 TopLevelBuilder warning 173 4 UseParcelFileDescriptor FW11 error 174 3 MentionsGoogle error 175 3 StartWithLower S1 error 176 2 AbstractInner warning 177 2 BuilderSetStyle warning 178 2 OverlappingConstants C1 warning 179 2 PairedRegistration L2 error 180 2 SingularCallback L1 error 181 2 StartWithUpper S1 error 182 1 ContextNameSuffix C4 error 183 1 KotlinKeyword error 184 -------------------------------------------------- 185 4902 186 187(This is generated when metalava is invoked with both --verbose and --update-baseline.) 188