[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

2 files changed, 171 insertions, 0 deletions

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)