Add documentation section for Android

2 files changed, 241 insertions, 0 deletions

diff --git a/doc/languages-frameworks/android.section.md b/doc/languages-frameworks/android.section.md
new file mode 100644
index 00000000000..237f3441874
--- /dev/null
+++ b/doc/languages-frameworks/android.section.md
@@ -0,0 +1,240 @@
+---
+title: Android
+author: Sander van der Burg
+date: 2018-11-18
+---
+# Android
+
+The Android build environment provides three major features and a number of
+supporting features.
+
+Deploying an Android SDK installation with plugins
+--------------------------------------------------
+The first use case is deploying the SDK with a desired set of plugins or subsets
+of an SDK.
+
+```nix
+with import <nixpkgs> {};
+
+let
+  androidComposition = androidenv.composeAndroidPackages {
+    toolsVersion = "25.2.5";
+    platformToolsVersion = "27.0.1";
+    buildToolsVersions = [ "27.0.3" ];
+    includeEmulator = false;
+    emulatorVersion = "27.2.0";
+    platformVersions = [ "24" ];
+    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";
+    useGoogleAPIs = false;
+    useGoogleTVAddOns = false;
+    includeExtras = [
+      "extras;google;gcm"
+    ];
+  };
+in
+androidComposition.androidsdk
+```
+
+The above function invocation states that we want an Android SDK with the above
+specified plugin versions. By default, most plugins are disabled. Notable
+exceptions are the tools, platform-tools and build-tools sub packages.
+
+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
+  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`.
+* `ndkVersion` specifies the NDK version that we want to use.
+* `includeExtras` is an array of identifier strings referring to arbitrary
+  add-on packages that should be installed.
+* `platformVersions` specifies which platform SDK versions should be included.
+
+For each platform version that has been specified, we can apply the following
+options:
+
+* `includeSystemImages` specifies whether a system image for each platform SDK
+  should be included.
+* `includeSources` specifies whether the sources for each SDK version should be
+  included.
+* `useGoogleAPIs` specifies that for each selected platform version the
+  Google API should be included.
+* `useGoogleTVAddOns` specifies that for each selected platform version the
+  Google TV add-on should be included.
+
+For each requested system image we can specify the following options:
+
+* `systemImageTypes` specifies what kind of system images should be included.
+  Defaults to: `default`.
+* `abiVersions` specifies what kind of ABI version of each system image should
+  be included. Defaults to: `armeabi-v7a`.
+
+Most of the function arguments have reasonable default settings.
+
+When building the above expression with:
+
+```bash
+$ nix-build
+```
+
+The Android SDK gets deployed with all desired plugin versions.
+
+We can also deploy subsets of the Android SDK. For example, to only the the
+`platform-tools` package, you can evaluate the following expression:
+
+```nix
+with import <nixpkgs> {};
+
+let
+  androidComposition = androidenv.composeAndroidPackages {
+    # ...
+  };
+in
+androidComposition.platform-tools
+```
+
+Using predefine 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).
+
+The following Nix expression can be used to deploy the entire SDK with all basic
+plugins:
+
+```nix
+with import <nixpkgs> {};
+
+androidenv.androidPkgs_9_0.androidsdk
+```
+
+It is also possible to use one plugin only:
+
+```nix
+with import <nixpkgs> {};
+
+androidenv.androidPkgs_9_0.platform-tools
+```
+
+Building an Android application
+-------------------------------
+In addition to the SDK, it is also possible to build an Ant-based Android
+project and automatically deploy all the Android plugins that a project
+requires.
+
+```nix
+with import <nixpkgs> {};
+
+androidenv.buildApp {
+  name = "MyAndroidApp";
+  src = ./myappsources;
+  release = true;
+
+  # If release is set to true, you need to specify the following parameters
+  keyStore = ./keystore;
+  keyAlias = "myfirstapp";
+  keyStorePassword = "mykeystore";
+  keyAliasPassword = "myfirstapp";
+
+  # Any Android SDK parameters that install all the relevant plugins that a
+  # build requires
+  platformVersions = [ "24" ];
+
+  # When we include the NDK, then ndk-build is invoked before Ant gets invoked
+  includeNDK = true;
+}
+```
+
+Aside from the app-specific build parameters (`name`, `src`, `release` and
+keystore parameters), the `buildApp {}` function supports all the function
+parameters that the SDK composition function (the function shown in the
+previous section) supports.
+
+This build function is particularly useful when it is desired to use
+[Hydra](http://nixos.org/hydra): the Nix-based continuous integration solution
+to build Android apps. An Android APK gets exposed as a build product and can be
+installed on any Android device with a web browser by navigating to the build
+result page.
+
+Spawning emulator instances
+---------------------------
+For testing purposes, it can also be quite convenient to automatically generate
+scripts that spawn emulator instances with all desired configuration settings.
+
+An emulator spawn script can be configured by invoking the `emulateApp {}`
+function:
+
+```nix
+with import <nixpkgs> {};
+
+androidenv.emulateApp {
+  name = "emulate-MyAndroidApp";
+  platformVersion = "24";
+  abiVersion = "armeabi-v7a"; # mips, x86 or x86_64
+  systemImageType = "default";
+  useGoogleAPIs = false;
+}
+```
+
+It is also possible to specify an APK to deploy inside the emulator
+and the package and activity names to launch it:
+
+```nix
+with import <nixpkgs> {};
+
+androidenv.emulateApp {
+  name = "emulate-MyAndroidApp";
+  platformVersion = "24";
+  abiVersion = "armeabi-v7a"; # mips, x86 or x86_64
+  systemImageType = "default";
+  useGoogleAPIs = false;
+  app = ./MyApp.apk;
+  package = "MyApp";
+  activity = "MainActivity";
+}
+```
+
+In addition to prebuilt APKs, you can also bind the APK parameter to a
+`buildApp {}` function invocation shown in the previous example.
+
+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.
+
+A shell script in the `pkgs/development/mobile/androidenv/` sub directory can be used to retrieve all
+possible options:
+
+```bash
+sh ./querypackages.sh packages build-tools
+```
+
+The above command-line instruction queries all build-tools versions in the
+generated `packages.nix` expression.
+
+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:
+
+```bash
+sh ./generate.sh
+```
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index ac0ad712532..a67c6bbc8bd 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -10,6 +10,7 @@
   Nixpkgs to easily build packages for other programming languages, such as
   Perl or Haskell. These are described in this chapter.
  </para>
+ <xi:include href="android.section.xml" />
  <xi:include href="beam.xml" />
  <xi:include href="bower.xml" />
  <xi:include href="coq.xml" />