mirror/vcpkg
1
0
Fork 0
mirror of https://github.com/microsoft/vcpkg.git synced 2024-12-19 11:00:25 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity
97298f2ede
vcpkg/docs/users/android.md
Dean 97298f2ede
[vcpkg] Update android usage documentation (#23690) 
* [doc] triplet creation is not needed any more for android.

The metioned triplets are already commited on master branch. There is no need to create triplet files for android. This doc is kind of outdated. I tried without the triplet creation stelp and jsoncpp installation is successful.

* [doc] keep android triplet to ABI mapping table

Co-authored-by: Jonliu1993 <13720414433@163.com>
2022-04-11 09:05:48 -07:00

225 lines
9.0 KiB
Markdown
Raw Blame History

# Vcpkg and Android
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/android.md).**
Android is not officially 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](https://github.com/Microsoft/vcpkg/pulls?q=+android+).
## Android build requirements
1. Download the [android ndk](https://developer.android.com/ndk/downloads/)
2. Set environment variable `ANDROID_NDK_HOME` to your android ndk installation.
For example:
````bash
export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
````
Or:
````bash
export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b
````
3. Install [vcpkg](https://github.com/microsoft/vcpkg)
4. Set environment variable `VCPKG_ROOT` to your vcpkg installation.
````bash
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:
````bash
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](https://github.com/microsoft/vcpkg/blob/master/ports/vulkan/portfile.cmake) which allows you to `find_package(Vulkan)`. To use it you have to provide `VULKAN_SDK` environment variable.
```bash
export VULKAN_SDK=/usr/local
./vcpkg install vulkan
```
NDK already contains [Vulkan](https://developer.android.com/ndk/guides/graphics/getting-started) 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.
```cmake
# 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](https://developer.android.com/studio/projects/install-ndk#default-ndk-per-agp), check the [BuildSystemMaintainers.md of the NDK document](https://android.googlesource.com/platform/ndk/+/master/docs/BuildSystemMaintainers.md#sysroot) and then put appropriate path for your system.
For example, Mac OS users will use the path like this.
```cmake
# 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`)
<details>
<summary markdown="span">`vcpkg install vulkan-hpp:arm64-android`</summary>
```console
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})
```
</details>
## Consume libraries using vpckg, cmake and the android toolchain
1. Combine vcpkg and Android toolchains
vcpkg and android both provide dedicated toolchains:
````bash
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.
````bash
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:
````bash
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](../examples/vcpkg_android_example_cmake) provides a working example, with an android library that consumes the jsoncpp library:
*Details*
* The [CMakeLists](../examples/vcpkg_android_example_cmake/CMakeLists.txt) simply uses `find_package` and `target_link_library`
* The [compile.sh](../examples/vcpkg_android_example_cmake/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](../examples/vcpkg_android_example_cmake/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](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake)
The folder [docs/examples/vcpkg_android_example_cmake_script](../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](../examples/vcpkg_android_example_cmake_script/CMakeLists.txt) loads [vcpkg_android.cmake](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake) if the flag `VCPKG_TARGET_ANDROID` is set:
````cmake
if (VCPKG_TARGET_ANDROID)
include("cmake/vcpkg_android.cmake")
endif()
````
*Important: place these lines before calling project() !*
* The [compile.sh](../examples/vcpkg_android_example_cmake_script/compile.sh) script shows that it is then possible to compile for android using a simple cmake invocation, for example:
````bash
cmake .. -DVCPKG_TARGET_ANDROID=ON -DANDROID_ABI=armeabi-v7a
````
## Consume libraries using vpckg, and Android prefab Archives (AAR files)
See [prefab.md](../specifications/prefab.md)
Reference in New Issue View Git Blame Copy Permalink