[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

9 files changed, 226 insertions, 0 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();
+}