[vcpkg] Improve Android doc (triplets, usage with cmake and prefab) (#11264)

* Android: add docs/examples/vcpkg_android_example_cmake/

* Add docs/users/android.md

* Improve Android prefab doc

Following additional informations given by @atkawa7 at
https://github.com/microsoft/vcpkg/pull/11264

* Link to android.md
* Update the prefab usage instructions: "vcpkg install"
    the 4 archs before exporting a prefab
* added --prefab-debug flag
* added gradle integration info
* reviewed the prefab output directory structure
  (from a dump of an actual export)

* docs/users/triplets.md: link to android.md

* docs/index.md: link to android.md

* android.md: specify 2 possibiities for android_ndk_home

* Added examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake

Usage:

1. Main CMakeLists:
  if (VCPKG_TARGET_ANDROID)
      include("cmake/vcpkg_android.cmake")
  endif()

2. cmake invocation:
  cmake .. -DVCPKG_TARGET_ANDROID=ON -DANDROID_ABI=armeabi-v7a

* trigger pipeline build

* trigger pipelines

13 files changed, 502 insertions, 70 deletions

diff --git a/docs/examples/vcpkg_android_example_cmake/.gitignore b/docs/examples/vcpkg_android_example_cmake/.gitignore
new file mode 100644
index 000000000..378eac25d
--- /dev/null
+++ b/docs/examples/vcpkg_android_example_cmake/.gitignore
@@ -0,0 +1 @@
+build
diff --git a/docs/examples/vcpkg_android_example_cmake/CMakeLists.txt b/docs/examples/vcpkg_android_example_cmake/CMakeLists.txt
new file mode 100644
index 000000000..7572bbbc8
--- /dev/null
+++ b/docs/examples/vcpkg_android_example_cmake/CMakeLists.txt
@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.0)
+project(test)
+find_package(jsoncpp CONFIG REQUIRED)
+add_library(my_lib my_lib.cpp)
+target_link_libraries(my_lib jsoncpp_lib)
diff --git a/docs/examples/vcpkg_android_example_cmake/compile.sh b/docs/examples/vcpkg_android_example_cmake/compile.sh
new file mode 100755
index 000000000..1d1aa60a9
--- /dev/null
+++ b/docs/examples/vcpkg_android_example_cmake/compile.sh
@@ -0,0 +1,54 @@
+#
+# 1. Check the presence of required environment variables
+#
+if [ -z ${ANDROID_NDK_HOME+x} ]; then
+  echo "Please set ANDROID_NDK_HOME"
+  exit 1
+fi
+if [ -z ${VCPKG_ROOT+x} ]; then
+  echo "Please set VCPKG_ROOT"
+  exit 1
+fi
+
+#
+# 2. Set the path to the toolchains
+#
+vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
+android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
+
+
+#
+# 3. Select a pair "Android abi" / "vcpkg triplet"
+# Uncomment one of the four possibilities below
+#
+
+android_abi=armeabi-v7a
+vcpkg_target_triplet=arm-android
+
+# android_abi=x86
+# vcpkg_target_triplet=x86-android
+
+# android_abi=arm64-v8a
+# vcpkg_target_triplet=arm64-android
+
+# android_abi=x86_64
+# vcpkg_target_triplet=x64-android
+
+
+#
+# 4. Install the library via vcpkg
+#
+$VCPKG_ROOT/vcpkg install jsoncpp:$vcpkg_target_triplet
+
+#
+# 5. Test the build
+#
+rm -rf build
+mkdir build
+cd build 
+cmake .. \
+  -DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \
+  -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \
+  -DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \
+  -DANDROID_ABI=$android_abi
+make
diff --git a/docs/examples/vcpkg_android_example_cmake/my_lib.cpp b/docs/examples/vcpkg_android_example_cmake/my_lib.cpp
new file mode 100644
index 000000000..f0165d72d
--- /dev/null
+++ b/docs/examples/vcpkg_android_example_cmake/my_lib.cpp
@@ -0,0 +1,8 @@
+#include <json/json.h>
+
+int answer()
+{
+  Json::Value meaning_of;
+  meaning_of["everything"] = 42;
+  return meaning_of["everything"].asInt();
+}
diff --git a/docs/examples/vcpkg_android_example_cmake_script/.gitignore b/docs/examples/vcpkg_android_example_cmake_script/.gitignore
new file mode 100644
index 000000000..378eac25d
--- /dev/null
+++ b/docs/examples/vcpkg_android_example_cmake_script/.gitignore
@@ -0,0 +1 @@
+build
diff --git a/docs/examples/vcpkg_android_example_cmake_script/CMakeLists.txt b/docs/examples/vcpkg_android_example_cmake_script/CMakeLists.txt
new file mode 100644
index 000000000..d3218866f
--- /dev/null
+++ b/docs/examples/vcpkg_android_example_cmake_script/CMakeLists.txt
@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.0)
+
+# if -DVCPKG_TARGET_ANDROID=ON is specified when invoking cmake, load cmake/vcpkg_android.cmake
+# !!! Important: place this line before calling project() !!!
+if (VCPKG_TARGET_ANDROID)
+    include("cmake/vcpkg_android.cmake")
+endif()
+
+project(test)
+
+find_package(jsoncpp CONFIG REQUIRED)
+add_library(my_lib my_lib.cpp)
+target_link_libraries(my_lib jsoncpp_lib)
diff --git a/docs/examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake b/docs/examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake
new file mode 100644
index 000000000..ce6cc4a61
--- /dev/null
+++ b/docs/examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake
@@ -0,0 +1,99 @@
+#
+# vcpkg_android.cmake 
+#
+# Helper script when using vcpkg with cmake. It should be triggered via the variable VCPKG_TARGET_ANDROID
+#
+# For example:
+# if (VCPKG_TARGET_ANDROID)
+#     include("cmake/vcpkg_android.cmake")
+# endif()
+# 
+# This script will:
+# 1 & 2. check the presence of needed env variables: ANDROID_NDK_HOME and VCPKG_ROOT
+# 3. set VCPKG_TARGET_TRIPLET according to ANDROID_ABI
+# 4. Combine vcpkg and Android toolchains by setting CMAKE_TOOLCHAIN_FILE 
+#    and VCPKG_CHAINLOAD_TOOLCHAIN_FILE
+
+# Note: VCPKG_TARGET_ANDROID is not an official Vcpkg variable. 
+# it is introduced for the need of this script
+
+if (VCPKG_TARGET_ANDROID)
+
+    #
+    # 1. Check the presence of environment variable ANDROID_NDK_HOME
+    #
+    if (NOT DEFINED ENV{ANDROID_NDK_HOME})
+        message(FATAL_ERROR "
+        Please set an environment variable ANDROID_NDK_HOME
+        For example:
+        export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
+        Or:
+        export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b
+        ")
+    endif()
+
+    #
+    # 2. Check the presence of environment variable VCPKG_ROOT
+    #
+    if (NOT DEFINED ENV{VCPKG_ROOT})
+        message(FATAL_ERROR "
+        Please set an environment variable VCPKG_ROOT
+        For example:
+        export VCPKG_ROOT=/path/to/vcpkg
+        ")
+    endif()
+
+
+    #
+    # 3. Set VCPKG_TARGET_TRIPLET according to ANDROID_ABI
+    # 
+    # There are four different Android ABI, each of which maps to 
+    # a vcpkg triplet. The following table outlines the mapping from vcpkg architectures to android architectures
+    #
+    # |VCPKG_TARGET_TRIPLET       | ANDROID_ABI          |
+    # |---------------------------|----------------------|
+    # |arm64-android              | arm64-v8a            |
+    # |arm-android                | armeabi-v7a          |
+    # |x64-android                | x86_64               |
+    # |x86-android                | x86                  |
+    #
+    # The variable must be stored in the cache in order to successfuly the two toolchains. 
+    #
+    if (ANDROID_ABI MATCHES "arm64-v8a")
+        set(VCPKG_TARGET_TRIPLET "arm64-android" CACHE STRING "" FORCE)
+    elseif(ANDROID_ABI MATCHES "armeabi-v7a")
+        set(VCPKG_TARGET_TRIPLET "arm-android" CACHE STRING "" FORCE)
+    elseif(ANDROID_ABI MATCHES "x86_64")
+        set(VCPKG_TARGET_TRIPLET "x64-android" CACHE STRING "" FORCE)
+    elseif(ANDROID_ABI MATCHES "x86")
+        set(VCPKG_TARGET_TRIPLET "x86-android" CACHE STRING "" FORCE)
+    else()
+        message(FATAL_ERROR "
+        Please specify ANDROID_ABI
+        For example
+        cmake ... -DANDROID_ABI=armeabi-v7a
+
+        Possible ABIs are: arm64-v8a, armeabi-v7a, x64-android, x86-android
+        ")
+    endif()
+    message("vcpkg_android.cmake: VCPKG_TARGET_TRIPLET was set to ${VCPKG_TARGET_TRIPLET}")
+
+
+    #
+    # 4. Combine vcpkg and Android toolchains
+    #
+
+    # vcpkg and android both provide dedicated toolchains:
+    #
+    # vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
+    # android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
+    #
+    # When using vcpkg, the vcpkg toolchain shall be specified first. 
+    # However, vcpkg provides a way to preload and additional toolchain, 
+    # with the VCPKG_CHAINLOAD_TOOLCHAIN_FILE option.
+    set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE $ENV{ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake)
+    set(CMAKE_TOOLCHAIN_FILE $ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake)
+    message("vcpkg_android.cmake: CMAKE_TOOLCHAIN_FILE was set to ${CMAKE_TOOLCHAIN_FILE}")
+    message("vcpkg_android.cmake: VCPKG_CHAINLOAD_TOOLCHAIN_FILE was set to ${VCPKG_CHAINLOAD_TOOLCHAIN_FILE}")
+
+endif(VCPKG_TARGET_ANDROID)
diff --git a/docs/examples/vcpkg_android_example_cmake_script/compile.sh b/docs/examples/vcpkg_android_example_cmake_script/compile.sh
new file mode 100755
index 000000000..abd981a6a
--- /dev/null
+++ b/docs/examples/vcpkg_android_example_cmake_script/compile.sh
@@ -0,0 +1,37 @@
+# 1. Install the library via vcpkg
+# This install jsoncpp for the 4 android target ABIs and for the host computer.
+# see the correspondence between ABIs and vcpkg triplets in the table below: 
+#
+# |VCPKG_TARGET_TRIPLET       | ANDROID_ABI          |
+# |---------------------------|----------------------|
+# |arm64-android              | arm64-v8a            |
+# |arm-android                | armeabi-v7a          |
+# |x64-android                | x86_64               |
+# |x86-android                | x86                  |
+$VCPKG_ROOT/vcpkg install \
+  jsoncpp \
+  jsoncpp:arm-android \
+  jsoncpp:arm64-android \
+  jsoncpp:x86-android \
+  jsoncpp:x64-android
+
+
+# 2. Test the build
+#
+# First, select an android ABI
+# Uncomment one of the four possibilities below
+#
+android_abi=armeabi-v7a
+# android_abi=x86
+# android_abi=arm64-v8a
+# android_abi=x86_64
+
+rm -rf build 
+mkdir build && cd build 
+
+# DVCPKG_TARGET_ANDROID will load vcpkg_android.cmake,
+# which will then load the android + vcpkg toolchains.
+cmake .. \
+  -DVCPKG_TARGET_ANDROID=ON \
+  -DANDROID_ABI=$android_abi
+make
diff --git a/docs/examples/vcpkg_android_example_cmake_script/my_lib.cpp b/docs/examples/vcpkg_android_example_cmake_script/my_lib.cpp
new file mode 100644
index 000000000..f0165d72d
--- /dev/null
+++ b/docs/examples/vcpkg_android_example_cmake_script/my_lib.cpp
@@ -0,0 +1,8 @@
+#include <json/json.h>
+
+int answer()
+{
+  Json::Value meaning_of;
+  meaning_of["everything"] = 42;
+  return meaning_of["everything"].asInt();
+}
diff --git a/docs/index.md b/docs/index.md
index 579b0e4c8..af1b966a0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -14,6 +14,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 - [Integration with build systems](users/integration.md)
 - [Triplet files](users/triplets.md)
 - [Configuration and Environment](users/config-environment.md)
+- [Usage with Android](users/android.md)
 
 ### Maintainer help
 
diff --git a/docs/specifications/prefab.md b/docs/specifications/prefab.md
index bb0479c4c..4574e01ee 100644
--- a/docs/specifications/prefab.md
+++ b/docs/specifications/prefab.md
@@ -1,64 +1,89 @@
-## Exporting to Android Archives (AAR files)
+# Vcpkg: export Android prefab Archives (AAR files)
 
-Vcpkg current supports exporting to android archive files([AAR files](https://developer.android.com/studio/projects/android-library)). Once the archive is created it can imported in Android Studio as a native dependent.  The archive is automatically consumed using [android studio's prefab tool](https://github.com/google/prefab). For more information on Prefab checkout the following article ["Native Dependencies in Android Studio 4.0"](https://android-developers.googleblog.com/2020/02/native-dependencies-in-android-studio-40.html) and the documentation on how to use prefab on [https://google.github.io/prefab/](https://google.github.io/prefab).
+Vcpkg can export android archives ([AAR files](https://developer.android.com/studio/projects/android-library)). Once an archive is created, it can imported in Android Studio as a native dependent.  The archive is automatically consumed using [android studio's prefab tool](https://github.com/google/prefab). 
 
-#### To support export to android the following tools should be available;
+For more information on Prefab, refer to:
+* The [official prefab documentation](https://google.github.io/prefab).
+* a blog post from Android developers blog: [Native Dependencies in Android Studio 4.0](https://android-developers.googleblog.com/2020/02/native-dependencies-in-android-studio-40.html) 
 
-- `maven <optional>`
-- `ndk <required>`
-- `7zip <required on windows>` or `zip <required on linux>`
+_Note for Android Studio users: prefab packages are supported on Android Studio 4+_
 
-**Android triplets that support the following architectures arm64-v8a, armeabi-v7a, x86_64 x86 must be present**
+## Requirements
 
-#### An example of a triplet configuration targeting android would be
+1. `ndk <required>`
 
-```cmake
-set(VCPKG_TARGET_ARCHITECTURE arm64)
-set(VCPKG_CRT_LINKAGE dynamic)
-set(VCPKG_LIBRARY_LINKAGE dynamic)
-set(VCPKG_CMAKE_SYSTEM_NAME Android)
-```
+Set environment variable `ANDROID_NDK_HOME` to your android ndk installation. For example:
+
+````
+export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
+````
+
+2. `7zip <required on windows>` or `zip <required on linux>`
+
+3. `maven <optional>`
+
+4. Android triplets
+
+See [android.md](../users/android.md) for instructions on how to install the triplets.
+
+*Please note that in order to use "prefab" (see below), the four architectures are required. If any is missing the export will fail*
 
-The following table outlines the mapping from vcpkg architectures to android architectures
 
-|vcpkg architecture | android architecture |
-|-------------------|----------------------|
-|arm64              | arm64-v8a            |
-|arm                | armeabi-v7a          |
-|x64                | x86_64               |
-|x86                | x86                  |
+## Example exporting [jsoncpp]
 
-**Please note the four architectures are required. If any is missing the export will fail**
-**To export the following environment `ANDROID_NDK_HOME` variable is required for exporting**
+First "vcpkg install" the 4 android architectures (it is mandatory to export all 4 of them)
+
+````
+./vcpkg install jsoncpp:arm-android  jsoncpp:arm64-android  jsoncpp:x64-android  jsoncpp:x86-android
+````
+
+
+Then, export the prefab:
+
+Note:
+* The `--prefab-maven` flag is optional. Call it if you maven is installed.
+* The `--prefab-debug` flag will output instructions on how to use the prefab archive via gradle.
 
-#### Example exporting [jsoncpp]
-The `--prefab-maven` flag is option. Only call it when you have maven installed
 ```
-./vcpkg export --triplet x64-android jsoncpp --prefab --prefab-maven
+./vcpkg export --triplet x64-android jsoncpp --prefab --prefab-maven --prefab-debug
 ```
 
+You will see an ouput like this:
 ```
 The following packages are already built and will be exported:
-    jsoncpp:x86-android
+    jsoncpp:arm64-android
+
 Exporting package jsoncpp...
+[DEBUG] Found 4 triplets
+	arm64-android
+	x64-android
+	x86-android
+	arm-android
+
+...
+... Lots of output...
+...
+
 [INFO] Scanning for projects...
-[INFO]
-[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
-[INFO] Building Maven Stub Project (No POM) 1
-[INFO] --------------------------------[ pom ]---------------------------------
-[INFO]
-[INFO] --- maven-install-plugin:2.4:install-file (default-cli) @ standalone-pom ---
-[INFO] Installing<root>/prefab/jsoncpp/jsoncpp-1.9.2.aar to /.m2/repository/com/vcpkg/ndk/support/jsoncpp/1.9.2/jsoncpp-1.9.2.aar
-[INFO] Installing <vcpkg_root>/prefab/jsoncpp/pom.xml to /.m2/repository/com/vcpkg/ndk/support/jsoncpp/1.9.2/jsoncpp-1.9.2.pom
-[INFO] ------------------------------------------------------------------------
+Downloading from central: https://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-clean-plugin/2.5/maven-clean-plugin-2.5.pom
+
+...
+... Lots of output...
+...
+
 [INFO] BUILD SUCCESS
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time:  0.301 s
-[INFO] Finished at: 2020-03-01T10:18:15Z
-[INFO] ------------------------------------------------------------------------
+[INFO] Total time:  2.207 s
+[INFO] Finished at: 2020-05-10T14:42:28+02:00
+
+
+...
+... Lots of output...
+...
+
+[DEBUG] Configuration properties in Android Studio
 In app/build.gradle
 
-    com.vcpkg.ndk.support:jsoncpp:1.9.2
+	com.vcpkg.ndk.support:jsoncpp:1.9.2
 
 And cmake flags
 
@@ -75,50 +100,59 @@ In gradle.properties
     android.enableParallelJsonGen=false
     android.prefabVersion=${prefab.version}
 
-Successfuly exported jsoncpp. Checkout <vcpkg_root>/prefab/jsoncpp/aar
+Successfuly exported jsoncpp. Checkout .../vcpkg/prefab 
+
 ```
 
 #### The output directory after export
-```
+
+````
 prefab
-└── jsoncpp
-    ├── aar
+└── jsoncpp/
+    ├── aar/
     │   ├── AndroidManifest.xml
-    │   ├── META-INF
-    │   │   └── LICENCE
-    │   └── prefab
-    │       ├── modules
-    │       │   └── jsoncpp
-    │       │       ├── include
-    │       │       │   └── json
-    │       │       │       ├── allocator.h
-    │       │       │       ├── assertions.h
-    │       │       │       ├── autolink.h
-    │       │       │       ├── config.h
-    │       │       │       ├── forwards.h
-    │       │       │       ├── json.h
-    │       │       │       ├── json_features.h
-    │       │       │       ├── reader.h
-    │       │       │       ├── value.h
-    │       │       │       ├── version.h
-    │       │       │       └── writer.h
-    │       │       ├── libs
-    │       │       │   ├── android.arm64-v8a
+    │   ├── META-INF/
+    │   │   └── LICENSE
+    │   └── prefab/
+    │       ├── modules/
+    │       │   └── jsoncpp/
+    │       │       ├── libs/
+    │       │       │   ├── android.arm64-v8a/
     │       │       │   │   ├── abi.json
+    │       │       │   │   ├── include/
+    │       │       │   │   │   └── json/
+    │       │       │   │   │       ├── json.h
+    │       │       │   │   │       └── ....
     │       │       │   │   └── libjsoncpp.so
-    │       │       │   ├── android.armeabi-v7a
+    │       │       │   ├── android.armeabi-v7a/
     │       │       │   │   ├── abi.json
+    │       │       │   │   ├── include/
+    │       │       │   │   │   └── json/
+    │       │       │   │   │       ├── json.h
+    │       │       │   │   │       └── ....
     │       │       │   │   └── libjsoncpp.so
-    │       │       │   ├── android.x86
+    │       │       │   ├── android.x86/
     │       │       │   │   ├── abi.json
+    │       │       │   │   ├── include/
+    │       │       │   │   │   └── json/
+    │       │       │   │   │       ├── json.h
+    │       │       │   │   │       └── ....
     │       │       │   │   └── libjsoncpp.so
-    │       │       │   └── android.x86_64
+    │       │       │   └── android.x86_64/
     │       │       │       ├── abi.json
+    │       │       │       ├── include/
+    │       │       │       │   └── json/
+    │       │       │   │   │       ├── json.h
+    │       │       │   │   │       └── ....
     │       │       │       └── libjsoncpp.so
     │       │       └── module.json
     │       └── prefab.json
     ├── jsoncpp-1.9.2.aar
     └── pom.xml
+````
 
-13 directories, 25 files
-```
+## Example consuming [jsoncpp] via vcpkg and prefab
+
+See the example repo here:
+
+https://github.com/atkawa7/prefab-vpkg-integration-sample
diff --git a/docs/users/android.md b/docs/users/android.md
new file mode 100644
index 000000000..6ff1d05d1
--- /dev/null
+++ b/docs/users/android.md
@@ -0,0 +1,168 @@
+# Vcpkg and Android
+
+Android is not officialy supported, and there are no official android triplets at the moment.
+
+However, some packages can compile to Android, and the situation is improving: see the list of [PR related to Android](https://github.com/Microsoft/vcpkg/pulls?q=+android+).
+
+
+## Android build requirements
+
+1. Download the [android ndk](https://developer.android.com/ndk/downloads/)
+
+2. Set environment variable `ANDROID_NDK_HOME` to your android ndk installation. 
+   For example:
+
+````bash
+export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
+````
+
+Or:
+````bash
+export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b
+````
+
+3. Install [vcpkg](https://github.com/microsoft/vcpkg)
+
+4. Set environment variable `VCPKG_ROOT` to your vcpkg installation.
+````bash
+export VCPKG_ROOT=/path/to/vcpkg
+````
+
+## Create the android triplets
+
+
+### Android ABI and corresponding vcpkg triplets
+
+There are four different Android ABI, each of which maps to 
+a vcpkg triplet. The following table outlines the mapping from vcpkg architectures to android architectures
+
+|VCPKG_TARGET_TRIPLET       | ANDROID_ABI          |
+|---------------------------|----------------------|
+|arm64-android              | arm64-v8a            |
+|arm-android                | armeabi-v7a          |
+|x64-android                | x86_64               |
+|x86-android                | x86                  |
+
+### Create the android triplets
+You can copy-paste the script below to populate them, and adjust them to your needs if required.
+
+````bash
+cd $VCPKG_ROOT
+
+echo "
+set(VCPKG_TARGET_ARCHITECTURE arm)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE dynamic)
+set(VCPKG_CMAKE_SYSTEM_NAME Android)
+" > triplets/community/arm-android.cmake
+
+echo "
+set(VCPKG_TARGET_ARCHITECTURE arm64)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE dynamic)
+set(VCPKG_CMAKE_SYSTEM_NAME Android)
+" > triplets/community/arm64-android.cmake
+ 
+echo "
+set(VCPKG_TARGET_ARCHITECTURE x86)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE dynamic)
+set(VCPKG_CMAKE_SYSTEM_NAME Android)
+" > triplets/community/x86-android.cmake
+
+echo "
+set(VCPKG_TARGET_ARCHITECTURE x64)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE dynamic)
+set(VCPKG_CMAKE_SYSTEM_NAME Android)
+" > triplets/community/x64-android.cmake
+````
+
+## Install libraries for Android using vcpkg
+
+Example for jsoncpp:
+
+````bash
+cd $VCPKG_ROOT
+
+# specify the triplet like this
+./vcpkg install jsoncpp --triplet arm-android   
+# or like this
+./vcpkg install jsoncpp:arm64-android           
+./vcpkg install jsoncpp:x86-android
+./vcpkg install jsoncpp:x64-android
+````
+
+## Consume libraries using vpckg, cmake and the android toolchain
+
+1. Combine vcpkg and Android toolchains
+
+vcpkg and android both provide dedicated toolchains:
+````bash
+vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
+android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
+````
+
+When using vcpkg, the vcpkg toolchain shall be specified first. 
+
+However, vcpkg provides a way to preload and additional toolchain, with the VCPKG_CHAINLOAD_TOOLCHAIN_FILE option. 
+
+````bash
+cmake \
+  -DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \
+  -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \
+  ...
+````
+
+2. Specifiy the android abi and vcpkg triplet
+
+When compiling for android, you need to select a matching "android abi" / "vcpkg triplet" pair.
+
+For example:
+
+````bash
+android_abi=armeabi-v7a
+vcpkg_target_triplet=arm-android
+
+cmake 
+  ...
+  -DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \
+  -DANDROID_ABI=$android_abi
+````
+
+### Test on an example
+
+The folder [docs/examples/vcpkg_android_example_cmake](../examples/vcpkg_android_example_cmake) provides a working example, with an android library that consumes the jsoncpp library:
+
+*Details*
+
+* The [CMakeLists](../examples/vcpkg_android_example_cmake/CMakeLists.txt) simply uses `find_package` and `target_link_library`
+
+* The [compile.sh](../examples/vcpkg_android_example_cmake/compile.sh) script enables you to select any matching pair of "android abi" /  "vcpkg triplet" and to test the compilation
+
+* The dummy [my_lib.cpp](../examples/vcpkg_android_example_cmake/my_lib.cpp) file uses the jsoncpp library
+
+*Note*: this example only compiles an Android library, as the compilation of a full fledged Android App is beyond the scope of this document.
+
+### Test on an example, using [vcpkg_android.cmake](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake)
+
+The folder [docs/examples/vcpkg_android_example_cmake_script](../examples/vcpkg_android_example_cmake_script) provides the same example, and uses a cmake script in order to simplify the usage.
+
+*Details*
+
+* The main [CMakeLists](../examples/vcpkg_android_example_cmake_script/CMakeLists.txt) loads [vcpkg_android.cmake](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake) if the flag `VCPKG_TARGET_ANDROID` is set:
+````cmake
+if (VCPKG_TARGET_ANDROID)
+    include("cmake/vcpkg_android.cmake")
+endif()
+````
+*Important: place these lines before calling project() !*
+
+* The [compile.sh](../examples/vcpkg_android_example_cmake_script/compile.sh) script shows that it is then possible to compile for android using a simple cmake invocation, for example:
+````bash
+cmake .. -DVCPKG_TARGET_ANDROID=ON -DANDROID_ABI=armeabi-v7a
+````
+
+## Consume libraries using vpckg, and Android prefab Archives (AAR files)
+
+See [prefab.md](../specifications/prefab.md)
\ No newline at end of file
diff --git a/docs/users/triplets.md b/docs/users/triplets.md
index 30fd66eea..aafae0920 100644
--- a/docs/users/triplets.md
+++ b/docs/users/triplets.md
@@ -166,3 +166,6 @@ The default triplet when running any vcpkg command is `%VCPKG_DEFAULT_TRIPLET%`
 - OSX: `x64-osx`
 
 We recommend using a systematic naming scheme when creating new triplets. The Android toolchain naming scheme is a good source of inspiration: https://developer.android.com/ndk/guides/standalone_toolchain.html.
+
+## Android triplets
+See [android.md](android.md)