vcpkg/docs/users/android.md

Vcpkg and Android

The latest version of this documentation is available on GitHub.

Android is not tested as part of vcpkg repository's CI process, so regressions can occur as part of library updates. PRs improving support are welcome!

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

3. Install vcpkg

4. Set environment variable VCPKG_ROOT to your vcpkg installation.

export VCPKG_ROOT=/path/to/vcpkg

vcpkg triplets and their corresponding 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

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

Using Vulkan SDK

Vcpkg has a vulkan package which allows you to find_package(Vulkan). To use it you have to provide VULKAN_SDK environment variable.

export VULKAN_SDK=/usr/local
./vcpkg install vulkan

NDK already contains Vulkan headers and libvulkan.so binaries for each of its architecture.
To expose them to VcPkg, you can consider export VULKAN_SDK=... for each installation.
But by placing set(ENV{VULKAN_SDK} ...) in the triplet files, you can skip the tedious work.

If you are using NDK 21.3.6528147 or earlier version, it will be like the following.

# In android triplets... (e.g. arm64-android.cmake)
set(VCPKG_CMAKE_SYSTEM_NAME Android)
# ...
# If your API level is 30, libvulkan.so is at $ENV{ANDROID_NDK_HOME}/platforms/android-30/arch-arm64/usr/lib
set(ENV{VULKAN_SDK} $ENV{ANDROID_NDK_HOME}/sysroot/usr)

Notice that the location of the sysroot has changed since NDK 22. (see https://github.com/android/ndk/issues/1407)
If you prefer using the latest version, check the BuildSystemMaintainers.md of the NDK document and then put appropriate path for your system.

For example, Mac OS users will use the path like this.

# In android triplets... (e.g. arm64-android.cmake)
set(VCPKG_CMAKE_SYSTEM_NAME Android)
# ...
# If your API level is 30, libvulkan.so is at $ENV{ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr/lib/aarch64-linux-android/30
set(ENV{VULKAN_SDK} $ENV{ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr)

By doing this for all android triplets, you can install vulkan and the packages that require it. (e.g. vulkan-hpp)

`vcpkg install vulkan-hpp:arm64-android`

user@host$ ./vcpkg install vulkan-hpp:arm64-android
Computing installation plan...
The following packages will be built and installed:
  * vulkan[core]:arm64-android -> 1.1.82.1-1
    vulkan-hpp[core]:arm64-android -> 2019-05-11-1
Additional packages (*) will be modified to complete this operation.
Detecting compiler hash for triplet arm64-android...
...
Starting package 1/2: vulkan:arm64-android
Building package vulkan[core]:arm64-android...
-- Using community triplet arm64-android. This triplet configuration is not guaranteed to succeed.
-- [COMMUNITY] Loading triplet configuration from: /.../vcpkg/triplets/community/arm64-android.cmake
-- Querying VULKAN_SDK Environment variable
-- Searching /.../Library/Android/sdk/ndk/22.1.7171670/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr/include/vulkan/ for vulkan.h
-- Found vulkan.h
-- Performing post-build validation
-- Performing post-build validation done
...
Building package vulkan[core]:arm64-android... done
Installing package vulkan[core]:arm64-android...
Installing package vulkan[core]:arm64-android... done
Elapsed time for package vulkan:arm64-android: 35.9 ms
Starting package 2/2: vulkan-hpp:arm64-android
Building package vulkan-hpp[core]:arm64-android...
-- Using community triplet arm64-android. This triplet configuration is not guaranteed to succeed.
-- [COMMUNITY] Loading triplet configuration from: /.../vcpkg/triplets/community/arm64-android.cmake
-- Using cached /.../vcpkg/downloads/KhronosGroup-Vulkan-Hpp-5ce8ae7fd0d9c0543d02f33cfa8a66e6a43e2150.tar.gz
-- Cleaning sources at /.../vcpkg/buildtrees/vulkan-hpp/src/e6a43e2150-4f344cd911.clean. Use --editable to skip cleaning for the packages you specify.
-- Extracting source /.../vcpkg/downloads/KhronosGroup-Vulkan-Hpp-5ce8ae7fd0d9c0543d02f33cfa8a66e6a43e2150.tar.gz
-- Using source at /.../vcpkg/buildtrees/vulkan-hpp/src/e6a43e2150-4f344cd911.clean
-- Performing post-build validation
-- Performing post-build validation done
...
Building package vulkan-hpp[core]:arm64-android... done
Installing package vulkan-hpp[core]:arm64-android...
Installing package vulkan-hpp[core]:arm64-android... done
Elapsed time for package vulkan-hpp:arm64-android: 144.5 ms

Total elapsed time: 1.013 s

The package vulkan-hpp:arm64-android is header only and can be used from CMake via:

    find_path(VULKAN_HPP_INCLUDE_DIRS "vulkan/vulkan.hpp")
    target_include_directories(main PRIVATE ${VULKAN_HPP_INCLUDE_DIRS})

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 \
  ...

2. Specify 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

• The main CMakeLists loads vcpkg_android.cmake if the flag VCPKG_TARGET_ANDROID is set:

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 vcpkg, and Android prefab Archives (AAR files)

See prefab.md