Merge staging-next into staging

1 files changed, 132 insertions, 27 deletions

diff --git a/doc/languages-frameworks/android.section.md b/doc/languages-frameworks/android.section.md
index cfbacf1bccdc..62e544cd48b6 100644
--- a/doc/languages-frameworks/android.section.md
+++ b/doc/languages-frameworks/android.section.md
@@ -13,21 +13,19 @@ with import <nixpkgs> {};
 
 let
   androidComposition = androidenv.composeAndroidPackages {
-    toolsVersion = "25.2.5";
-    platformToolsVersion = "27.0.1";
-    buildToolsVersions = [ "27.0.3" ];
+    toolsVersion = "26.1.1";
+    platformToolsVersion = "30.0.5";
+    buildToolsVersions = [ "30.0.3" ];
     includeEmulator = false;
-    emulatorVersion = "27.2.0";
-    platformVersions = [ "24" ];
+    emulatorVersion = "30.3.4";
+    platformVersions = [ "28" "29" "30" ];
     includeSources = false;
-    includeDocs = false;
     includeSystemImages = false;
-    systemImageTypes = [ "default" ];
-    abiVersions = [ "armeabi-v7a" ];
-    lldbVersions = [ "2.0.2558144" ];
-    cmakeVersions = [ "3.6.4111459" ];
-    includeNDK = false;
-    ndkVersion = "16.1.4479499";
+    systemImageTypes = [ "google_apis_playstore" ];
+    abiVersions = [ "armeabi-v7a" "arm64-v8a" ];
+    cmakeVersions = [ "3.10.2" ];
+    includeNDK = true;
+    ndkVersion = "22.0.7026061";
     useGoogleAPIs = false;
     useGoogleTVAddOns = false;
     includeExtras = [
@@ -46,13 +44,11 @@ The following parameters are supported:
 
 * `toolsVersion`, specifies the version of the tools package to use
 * `platformsToolsVersion` specifies the version of the `platform-tools` plugin
-* `buildToolsVersion` specifies the versions of the `build-tools` plugins to
+* `buildToolsVersions` specifies the versions of the `build-tools` plugins to
   use.
 * `includeEmulator` specifies whether to deploy the emulator package (`false`
   by default). When enabled, the version of the emulator to deploy can be
   specified by setting the `emulatorVersion` parameter.
-* `includeDocs` specifies whether the documentation catalog should be included.
-* `lldbVersions` specifies what LLDB versions should be deployed.
 * `cmakeVersions` specifies which CMake versions should be deployed.
 * `includeNDK` specifies that the Android NDK bundle should be included.
   Defaults to: `false`.
@@ -82,6 +78,38 @@ For each requested system image we can specify the following options:
 
 Most of the function arguments have reasonable default settings.
 
+You can specify license names:
+
+* `extraLicenses` is a list of of license names.
+  You can get these names from repo.json or `querypackages.sh licenses`. The SDK
+  license (`android-sdk-license`) is accepted for you if you set accept_license
+  to true. If you are doing something like working with preview SDKs, you will
+  want to add `android-sdk-preview-license` or whichever license applies here.
+
+Additionally, you can override the repositories that composeAndroidPackages will
+pull from:
+
+* `repoJson` specifies a path to a generated repo.json file. You can generate this
+  by running `generate.sh`, which in turn will call into `mkrepo.rb`.
+* `repoXmls` is an attribute set containing paths to repo XML files. If specified,
+  it takes priority over `repoJson`, and will trigger a local build writing out a
+  repo.json to the Nix store based on the given repository XMLs.
+
+```nix
+repoXmls = {
+  packages = [ ./xml/repository2-1.xml ];
+  images = [
+    ./xml/android-sys-img2-1.xml
+    ./xml/android-tv-sys-img2-1.xml
+    ./xml/android-wear-sys-img2-1.xml
+    ./xml/android-wear-cn-sys-img2-1.xml
+    ./xml/google_apis-sys-img2-1.xml
+    ./xml/google_apis_playstore-sys-img2-1.xml
+  ];
+  addons = [ ./xml/addon2-1.xml ];
+};
+```
+
 When building the above expression with:
 
 ```bash
@@ -104,8 +132,8 @@ in
 androidComposition.platform-tools
 ```
 
-Using predefine Android package compositions
---------------------------------------------
+Using predefined Android package compositions
+---------------------------------------------
 In addition to composing an Android package set manually, it is also possible
 to use a predefined composition that contains all basic packages for a specific
 Android version, such as version 9.0 (API-level 28).
@@ -209,27 +237,104 @@ androidenv.emulateApp {
 In addition to prebuilt APKs, you can also bind the APK parameter to a
 `buildApp {}` function invocation shown in the previous example.
 
+Notes on environment variables in Android projects
+--------------------------------------------------
+* `ANDROID_SDK_ROOT` should point to the Android SDK. In your Nix expressions, this should be
+  `${androidComposition.androidsdk}/libexec/android-sdk`. Note that `ANDROID_HOME` is deprecated,
+  but if you rely on tools that need it, you can export it too.
+* `ANDROID_NDK_ROOT` should point to the Android NDK, if you're doing NDK development.
+  In your Nix expressions, this should be `${ANDROID_SDK_ROOT}/ndk-bundle`.
+
+If you are running the Android Gradle plugin, you need to export GRADLE_OPTS to override aapt2
+to point to the aapt2 binary in the Nix store as well, or use a FHS environment so the packaged
+aapt2 can run. If you don't want to use a FHS environment, something like this should work:
+
+```nix
+let
+  buildToolsVersion = "30.0.3";
+
+  # Use buildToolsVersion when you define androidComposition
+  androidComposition = <...>;
+in
+pkgs.mkShell rec {
+  ANDROID_SDK_ROOT = "${androidComposition.androidsdk}/libexec/android-sdk";
+  ANDROID_NDK_ROOT = "${ANDROID_SDK_ROOT}/ndk-bundle";
+
+  # Use the same buildToolsVersion here
+  GRADLE_OPTS = "-Dorg.gradle.project.android.aapt2FromMavenOverride=${ANDROID_SDK_ROOT}/build-tools/${buildToolsVersion}/aapt2";
+}
+```
+
+If you are using cmake, you need to add it to PATH in a shell hook or FHS env profile.
+The path is suffixed with a build number, but properly prefixed with the version.
+So, something like this should suffice:
+
+```nix
+let
+  cmakeVersion = "3.10.2";
+
+  # Use cmakeVersion when you define androidComposition
+  androidComposition = <...>;
+in
+pkgs.mkShell rec {
+  ANDROID_SDK_ROOT = "${androidComposition.androidsdk}/libexec/android-sdk";
+  ANDROID_NDK_ROOT = "${ANDROID_SDK_ROOT}/ndk-bundle";
+
+  # Use the same cmakeVersion here
+  shellHook = ''
+    export PATH="$(echo "$ANDROID_SDK_ROOT/cmake/${cmakeVersion}".*/bin):$PATH"
+  '';
+}
+```
+
+Note that running Android Studio with ANDROID_SDK_ROOT set will automatically write a
+`local.properties` file with `sdk.dir` set to $ANDROID_SDK_ROOT if one does not already
+exist. If you are using the NDK as well, you may have to add `ndk.dir` to this file.
+
+An example shell.nix that does all this for you is provided in examples/shell.nix.
+This shell.nix includes a shell hook that overwrites local.properties with the correct
+sdk.dir and ndk.dir values. This will ensure that the SDK and NDK directories will
+both be correct when you run Android Studio inside nix-shell.
+
+Notes on improving build.gradle compatibility
+---------------------------------------------
+Ensure that your buildToolsVersion and ndkVersion match what is declared in androidenv.
+If you are using cmake, make sure its declared version is correct too.
+
+Otherwise, you may get cryptic errors from aapt2 and the Android Gradle plugin warning
+that it cannot install the build tools because the SDK directory is not writeable.
+
+```gradle
+android {
+    buildToolsVersion "30.0.3"
+    ndkVersion = "22.0.7026061"
+    externalNativeBuild {
+        cmake {
+            version "3.10.2"
+        }
+    }
+}
+
+```
+
 Querying the available versions of each plugin
 ----------------------------------------------
-When using any of the previously shown functions, it may be a bit inconvenient
-to find out what options are supported, since the Android SDK provides many
-plugins.
+repo.json provides all the options in one file now.
 
-A shell script in the `pkgs/development/mobile/androidenv/` sub directory can be used to retrieve all
+A shell script in the `pkgs/development/mobile/androidenv/` subdirectory can be used to retrieve all
 possible options:
 
 ```bash
-sh ./querypackages.sh packages build-tools
+./querypackages.sh packages
 ```
 
-The above command-line instruction queries all build-tools versions in the
-generated `packages.nix` expression.
+The above command-line instruction queries all package versions in repo.json.
 
 Updating the generated expressions
 ----------------------------------
-Most of the Nix expressions are generated from XML files that the Android
-package manager uses. To update the expressions run the `generate.sh` script
-that is stored in the `pkgs/development/mobile/androidenv/` sub directory:
+repo.json is generated from XML files that the Android Studio package manager uses.
+To update the expressions run the `generate.sh` script that is stored in the
+`pkgs/development/mobile/androidenv/` subdirectory:
 
 ```bash
 ./generate.sh