base/android/README.md

   1 # //base/android
   2
   3 This directory contains:
   4
   5 * C++ APIs that are broadly useful and are unique to `target_os="android"`, and
   6 * Java APIs that are broadly useful, along C++ bindings when necessary.
   7
   8 This directory does not contain Android-specific implementations / extensions
   9 to APIs declared directly in `//base`. Those live in `//base/*_android.cc`, or
  10 behind `#ifdef`s.
  11
  12 ## Adding New APIs
  13
  14 The advice laid out in [//base/README.md] applies to this directory as well.
  15 The bars for what APIs should exist and for code quality are generally higher
  16 than for other directories. If you find yourself wanting to add a new API, you
  17 should expect that code reviews take multiple revisions and that they be met
  18 with (respectful) scrutiny.
  19
  20 If you are not sure whether an API would make sense to add, you can ask via
  21 java@chromium.org.
  22 It is common to add APIs to `//chrome` (or elsewhere) first, and move them into
  23 `//base` after their usefulness has been proven.
  24
  25 [//base/README.md]: /base/README.md
  26
  27 ### What Uses //base/android?
  28
  29 The main two clients are Chrome and WebView, but it is also used by other
  30 Chromium-based apps, such as Chromecast and Chrome Remote desktop. Some
  31 `//base/android` classes are used by `//build` (this is a layering violation,
  32 tracked in [crbug/1364192] and [crbug/1377351]).
  33
  34 Two considerations for WebView:
  35
  36 1. The application Context is that of the host app's.
  37 2. The UI thread might be different from the main thread.
  38
  39 [crbug/1364192]: https://crbug.com/1364192
  40 [crbug/1377351]: https://crbug.com/1377351
  41
  42
  43 ### New API Checklist
  44
  45 Here is a list of checks you should go through when adding a new API:
  46
  47 1. The functionality does not already exist in system libraries (Java APIs,
  48    Android SDK) or in already adopted `third_party` libraries, such as AndroidX.
  49 2. Reasonable effort has been made to ensure the new API is discoverable. E.g.:
  50    Coordinate refactorings of existing patterns to it, add a [presubmit check],
  51    to recommend it, etc.
  52 3. Tests (ideally Robolectric) are added.
  53 4. Thought has been put into API design.
  54    * E.g. adding `@Nullable`, or `@DoNotMock`
  55    * E.g. adding test helpers, such as `ForTesting()` methods or `TestRule`s
  56    * E.g. adding asserts or comments about thread-safety
  57    * E.g. could usage of the API be made harder to get wrong?
  58
  59 [presumbit check]: https://chromium.googlesource.com/chromium/src/+/main/build/android/docs/java_toolchain.md#Static-Analysis-Code-Checks
  60
  61 ### Choosing a Reviewer
  62
  63 All members of [`//base/android/OWNERS`] will be CC'ed on reviews through a
  64 [`//WATCHLIST`] entry. For new APIs, feel free to pick a reviewer at random.
  65 For modifying existing files, it is best to use a reviewer from prior changes to
  66 the file.
  67
  68 [`//base/android/OWNERS`]: /base/android/OWNERS
  69 [`//WATCHLIST`]: /WATCHLIST