Improve Android doc (triplets, usage with cmake and prefab)

[pthom]

Describe your PR

Improve Android prefab and triplet doc

• Add a very minimal example showcasing the use of vcpkg + cmake + android

• Add docs/users/android.md. This file provides:

  • A script to populate (and adjust) the android triplets
  • details about the matching "android abi" / "vcpkg triplet"
  • An example showcasing how to consume libraries using vpckg, cmake and the android toolchain

• Improve the android prefab doc

• provides links to android.md inside docs/triplet.md

• provides link to android.md inside docs/index.md

What does your PR fix?

This PR can may be considered as a fix for two issues that arise because of incomplete doc

• Fix Eliminate bad error reporting "Value was null" #11052
• Fix android support #5717

Which triplets are supported/not supported? Have you updated the CI baseline?

Not applicable, this is doc only

Does your PR follow the maintainer guide?

Yes

[atkawa7]

@pthom @strega-nil looks good to me

[pthom]

@atkawa7 : if you have a few minutes, would you mind giving me some help on this pr: #11269

My issue is that I now can built a prefab package, but I do not know how to consume it (and thus test it). As a newbie to android development, the prefab doc was not that helpful for this.

[atkawa7]

@pthom I forgot another option which shows examples on how to consume it. Add this option --prefab-debug

./vcpkg export --triplet arm64-android jsoncpp --prefab --prefab-maven --prefab-debug

Output

[DEBUG] Configuration properties in Android Studio
In app/build.gradle

	com.vcpkg.ndk.support:jsoncpp:1.9.2

And cmake flags

    externalNativeBuild {
                cmake {
                    arguments '-DANDROID_STL=c++_shared'
                    cppFlags "-std=c++17"
                }
            }

In gradle.properties

    android.enablePrefab=true
    android.enableParallelJsonGen=false
    android.prefabVersion=${prefab.version}

Note: prefab packages are supported on Android Studio 4+

If you have Android 3.6 you might need to install android 4.1 Preview

[atkawa7]

@pthom checkout the following project that I created to consume the packages created

https://github.com/atkawa7/prefab-vpkg-integration-sample

[pthom]

I made some changes, and added an example + android.md file.

@atkawa7 could you please have a look at
https://github.com/pthom/vcpkg/blob/fix_prefab_doc/docs/users/android.md
and
https://github.com/pthom/vcpkg/blob/fix_prefab_doc/docs/specifications/prefab.md

[atkawa7]

@pthom looks good to me

[strega-nil]

Please poke me when you think the documentation is ready to merge; I don't know anything about android, and so I'm just going to trust your judgement :)

[atkawa7]

@strega-nil I think the documentation in its current form is good. I think @pthom addressed issues that new users might come across when consuming android archive packages. I don't know if there is still anything to be added @pthom. I am sure as more issues related to android come up we will continue to improve the docs and address concerns users might have

[pthom]

I added a second example

It provides a script vcpkg_android.cmake

The usage is even simpler:

1. Main CMakeList, before calling project()

if (VCPKG_TARGET_ANDROID)
    include("cmake/vcpkg_android.cmake")
endif()

2. cmake invocation:

cmake .. -DVCPKG_TARGET_ANDROID=ON -DANDROID_ABI=armeabi-v7a

I have successfuly tested on two vanillla installations of vcpkg under linux and MacOS.

@atkawa7 @strega-nil : if this looks good to you, the PR is ok on my side too

[strega-nil]

Alright, awesome! Thanks everyone, and @pthom especially. Y'all make this project so good!