| # API Lint |
| |
| Metalava can optionally run warn about various API problems based on the Android |
| API Council's guidelines, described in go/android-api-guidelines. |
| |
| These rules are not always exact. For example, you should avoid using acronyms |
| in names; e.g. a method should be named handleUri, not handleURI. But what about |
| getZOrder? This is probably better than getZorder, but metalava can't tell |
| without consulting a dictionary. |
| |
| Therefore, there are cases where you want to say "ok, that's good advice in |
| general, but wrong here". In order to avoid having this warningshow up again |
| and again, there are two ways to mark an issue such that it is no longer |
| flagged. |
| |
| (Note that metalava will not report issues on classes, methods and fields that |
| are deprecated since these are presumably already known to be bad and are already |
| discouraged.) |
| |
| ## Suppressing with @Suppress |
| |
| Next to an error message, metalava will include the issue id. For example, |
| here's a sample error message: |
| |
| src/android/pkg/MyStringImpl.java:3: error: Don't expose your implementation details: MyStringImpl ends with Impl [EndsWithImpl] |
| |
| Here the id is "EndsWithImpl". You can suppress this with the @SuppressLint |
| annotation: |
| |
| ... |
| import android.annotation.SuppressLint; |
| ... |
| |
| @SuppressLint("EndsWithImpl") |
| public class MyStringImpl { |
| ... |
| |
| ## Suppressing with baselines |
| |
| Metalava also has support for "baselines", which are files which record all the |
| current warnings and errors in the codebase. When metalava runs, it looks up the |
| baseline to see if a given issue is already listed in the baseline, and if so, |
| it is silently ignored. |
| |
| You can pass a flag to metalava ("--update-baseline") to tell it to update the |
| baseline files with any new errors it comes across instead of reporting |
| them. With soong, if you specify the baseline explicitly, like this: |
| |
| --- a/Android.bp |
| +++ b/Android.bp |
| @@ -1678,6 +1678,7 @@ droidstubs { |
| }, |
| api_lint: { |
| enabled: true, |
| ==> baseline_filename: "api/baseline.txt", <== |
| } |
| jdiff_enabled: true, |
| } |
| |
| then the build system will automatically supply `--update-baseline` on your |
| behalf to a generated file in the out/ folder, and if there's a failure metalava |
| will tell you where to find the updated baseline which you can then copy into |
| place: |
| |
| ... |
| 93 new API lint issues were found. See tools/metalava/API-LINT.md for how to handle these. |
| ************************************************************ |
| Your API changes are triggering API Lint warnings or errors. |
| To make these errors go away, you have two choices: |
| |
| 1. You can suppress the errors with @SuppressLint("<id>") |
| 2. You can update the baseline by executing the following |
| command: |
| cp \ |
| out/soong/.intermediates/frameworks/base/system-api-stubs-docs/android_common/api/system-baseline.txt \ |
| frameworks/base/api/system-baseline.txt |
| To submit the revised baseline.txt to the main Android |
| repository, you will need approval. |
| ************************************************************ |
| |
| |
| |
| Then re-run the build and you should now see diffs to the baseline file; git |
| diff to make sure you're really only marking the issues you intended to include. |
| |
| $ git status |
| ... |
| Untracked files: |
| (use "git add <file>..." to include in what will be committed) |
| |
| baseline.txt |
| |
| ## Copying File Manually |
| |
| In the near future the build system will not allow source files to be modified |
| by the build. At that point you'll need to manually copy in the file instead. |
| During the build, before failing, metalava will emit a message like this: |
| |
| ... |
| metalava wrote updated baseline to out/something/baseline.txt |
| ... |
| |
| At that point you can copy the file to where you need: |
| |
| ```sh |
| $ cp out/something/baseline.txt frameworks/base/api/baseline.txt |
| ``` |
| |
| ## Existing Issues |
| |
| You can view the exact set of existing issues (current APIs that get flagged by |
| API lint) by inspecting the baseline files in the source tree, but to get a |
| sense of the types of issues that are more likely to have a false positive, |
| here's the existing distribution as of early 2019: |
| |
| Count Issue Id Rule Severity |
| -------------------------------------------------- |
| |
| 932 ProtectedMember M7 error |
| 321 OnNameExpected warning |
| 288 ArrayReturn warning |
| 269 ActionValue C4 error |
| 266 NoByteOrShort FW12 warning |
| 221 ExecutorRegistration L1 warning |
| 211 AllUpper C2 error |
| 206 GetterSetterNames M6 error |
| 185 BannedThrow error |
| 172 SamShouldBeLast warning |
| 159 NoClone error |
| 159 ParcelNotFinal FW8 error |
| 119 NotCloseable warning |
| 105 ListenerLast M3 warning |
| 81 ConcreteCollection CL2 error |
| 78 StaticUtils error |
| 76 IntentName C3 error |
| 74 VisiblySynchronized M5 error |
| 72 GenericException S1 error |
| 65 KotlinOperator warning |
| 57 AcronymName S1 warning |
| 55 ParcelCreator FW3 error |
| 54 ParcelConstructor FW3 error |
| 53 UseIcu warning |
| 48 Enum F5 error |
| 41 RethrowRemoteException FW9 error |
| 37 AutoBoxing M11 error |
| 35 StreamFiles M10 warning |
| 28 IntentBuilderName FW1 warning |
| 27 ServiceName C4 error |
| 26 ListenerInterface L1 error |
| 25 ContextFirst M3 error |
| 25 InterfaceConstant C4 error |
| 24 CallbackInterface CL3 error |
| 24 RegistrationName L3 error |
| 23 IllegalStateException S1 warning |
| 22 EqualsAndHashCode M8 error |
| 22 PackageLayering FW6 warning |
| 18 MinMaxConstant C8 warning |
| 18 SingletonConstructor error |
| 17 MethodNameUnits error |
| 15 MissingBuildMethod warning |
| 15 UserHandleName warning |
| 14 UserHandle warning |
| 13 ResourceFieldName error |
| 12 ManagerLookup error |
| 11 ManagerConstructor error |
| 9 CallbackMethodName L1 error |
| 9 ParcelableList warning |
| 8 CallbackName L1 warning |
| 7 HeavyBitSet error |
| 7 ResourceValueFieldName C7 error |
| 6 CompileTimeConstant error |
| 6 SetterReturnsThis M4 warning |
| 4 EndsWithImpl error |
| 4 TopLevelBuilder warning |
| 4 UseParcelFileDescriptor FW11 error |
| 3 MentionsGoogle error |
| 3 StartWithLower S1 error |
| 2 AbstractInner warning |
| 2 BuilderSetStyle warning |
| 2 OverlappingConstants C1 warning |
| 2 PairedRegistration L2 error |
| 2 SingularCallback L1 error |
| 2 StartWithUpper S1 error |
| 1 ContextNameSuffix C4 error |
| 1 KotlinKeyword error |
| -------------------------------------------------- |
| 4902 |
| |
| (This is generated when metalava is invoked with both --verbose and --update-baseline.) |
