[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

1 files changed, 104 insertions, 70 deletions

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