vcpkg/docs/users/android.md
ras0219 75522bb1f2
[docs] Improve inter-document linking; add 'latest' links (#16502)
* [docs] Improve inter-document linking; add 'latest' links

* [docs] Apply suggestions from code review

Co-authored-by: nicole mazzuca <mazzucan@outlook.com>

Co-authored-by: nicole mazzuca <mazzucan@outlook.com>
Co-authored-by: Robert Schumacher <roschuma@microsoft.com>
2021-03-11 16:37:49 -08:00

5.5 KiB

Vcpkg and Android

The latest version of this documentation is available on GitHub.

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.

Android build requirements

  1. Download the android ndk

  2. Set environment variable ANDROID_NDK_HOME to your android ndk installation. 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
  1. Install vcpkg

  2. Set environment variable VCPKG_ROOT to your vcpkg installation.

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.

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:

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:

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.

cmake \
  -DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \
  -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \
  ...
  1. Specifiy the android abi and vcpkg triplet

When compiling for android, you need to select a matching "android abi" / "vcpkg triplet" pair.

For example:

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 provides a working example, with an android library that consumes the jsoncpp library:

Details

  • The CMakeLists simply uses find_package and target_link_library

  • The 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 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

The folder docs/examples/vcpkg_android_example_cmake_script provides the same example, and uses a cmake script in order to simplify the usage.

Details

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

Important: place these lines before calling project() !

  • The compile.sh script shows that it is then possible to compile for android using a simple cmake invocation, for example:
cmake .. -DVCPKG_TARGET_ANDROID=ON -DANDROID_ABI=armeabi-v7a

Consume libraries using vpckg, and Android prefab Archives (AAR files)

See prefab.md