games/vcmi
1
0
Fork 0
mirror of https://github.com/vcmi/vcmi.git synced 2025-11-23 22:37:55 +02:00
Code Issues Releases Activity

[docs] update developer documentation for Conan v2

Browse Source
This commit is contained in:
Andrey Filipenkov
2025-08-26 21:31:37 +03:00
parent 6c697bb95b
commit 3ab8b449c7
4 changed files with 176 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/developers/Building_Android.md
View File

@@ -1,19 +1,19 @@
# Building Android
The following instructions apply to **v1.2 and later**. For earlier versions the best documentation is <https://github.com/vcmi/vcmi-android/blob/master/building.txt> (and reading scripts in that repo), however very limited to no support will be provided from our side if you wish to go down that rabbit hole.
The following instructions apply to **v1.7 and later**. For earlier versions see older Git revision, e.g. from [1.6.8 release](https://github.com/vcmi/vcmi/blob/1.6.8/docs/developers/Building_Android.md).
*Note*: building has been tested only on Linux and macOS. It may or may not work on Windows out of the box.
## Requirements
1. CMake 3.20+: download from your package manager or from <https://cmake.org/download/>
2. JDK 11, not necessarily from Oracle
1. CMake 3.26+: download from your package manager or from <https://cmake.org/download/>
2. JDK 17, not necessarily from Oracle
3. Android command line tools or Android Studio for your OS: <https://developer.android.com/studio/>
4. Android NDK version **r25c (25.2.9519653)**, there're multiple ways to obtain it:
4. Android NDK version **r25c (25.2.9519653)** (later version would also probably work), there're multiple ways to obtain it:
- recommended: download with Conan, especially if you're going to build VCMI dependencies from source, see [#NDK and Conan](#ndk-and-conan)
- install with Android Studio
- install with `sdkmanager` command line tool
- download from <https://developer.android.com/ndk/downloads>
- download with Conan, see [#NDK and Conan](#ndk-and-conan)
5. Optional:
- Ninja: download from your package manager or from <https://github.com/ninja-build/ninja/releases>
- Ccache: download from your package manager or from <https://github.com/ccache/ccache/releases>
@@ -32,15 +32,18 @@ We use Conan package manager to build/consume dependencies, find detailed usage
On the step where you need to replace **PROFILE**, choose:
- `android-32` to build for 32-bit architecture (armeabi-v7a)
- `android-64` to build for 64-bit architecture (aarch64-v8a)
- `android-32-ndk` to build for ARM 32-bit (armeabi-v7a)
- `android-64-ndk` to build for ARM 64-bit (aarch64-v8a)
- `android-x64-ndk` to build for Intel 64-bit (x86_64)
Advanced users may choose profile without `-ndk` suffix to use NDK that's already installed in their system.
### NDK and Conan
Conan must be aware of the NDK location when you execute `conan install`. There're multiple ways to achieve that as written in the [Conan docs](https://docs.conan.io/1/integrations/cross_platform/android.html):
Conan must be aware of the NDK location when you execute `conan install`. There're multiple ways to achieve that as written in the [Conan docs](https://docs.conan.io/2/examples/cross_build/android/ndk.html#examples-cross-build-android-ndk):
- the easiest is to download NDK from Conan (option 1 in the docs), then all the magic happens automatically. On the step where you need to replace **PROFILE**, choose *android-**X**-ndk* where ***X*** is either `32` or `64`.
- to use an already installed NDK, you can simply pass it on the command line to `conan install`: (note that this will work only when consuming the pre-built binaries)
- the easiest is to download NDK from Conan (option 1 in the docs), then all the magic happens automatically
- to use an already installed NDK, you can simply pass it on the command line to `conan install`: (note that this will likely work only when consuming the prebuilt binaries)
```sh
conan install -c tools.android:ndk_path=/path/to/ndk ...
@@ -48,37 +51,48 @@ conan install -c tools.android:ndk_path=/path/to/ndk ...
## Build process
Before starting the build, local Gradle configuration must be created (it's a requirement for Qt 5):
```sh
mkdir ~/.gradle
echo "android.bundle.enableUncompressedNativeLibs=true" > ~/.gradle/gradle.properties
```
Building for Android is a 2-step process. First, native C++ code is compiled to a shared library (unlike an executable on other platforms), then Java code is compiled to an actual executable which will be loading the native shared library at runtime.
This is a traditional CMake project, you can build it from command line or some IDE. You're not required to pass any custom options (except Conan toolchain file), defaults are already good. If you wish to use your own CMake presets, inherit them from our `build-with-conan` preset.
This is a traditional CMake project, you can build it from command line or some IDE. You're not required to pass any custom options (except Conan toolchain file), defaults are already good.
The Java code (located in the `android` directory of the repo) will be built automatically after the native code using the `androiddeployqt` tool. But you must set `JAVA_HOME` and `ANDROID_HOME` environment variables.
APK will appear in `<build dir>/android-build/vcmi-app/build/outputs/apk/debug` directory which you can then install to your device with `adb install -r /path/to/apk` (`adb` command is from Android command line tools).
APK will appear in `<build dir>/android-build/vcmi-app/build/outputs/apk/<build configuration>` directory which you can then install to your device with `adb install -r /path/to/apk` (`adb` command is from Android command line tools).
### Example
```sh
# the following environment variables must be set
export JAVA_HOME=/path/to/jdk11
export JAVA_HOME=/path/to/jdk17
export ANDROID_HOME=/path/to/android/sdk
cmake -S . -B ../build -G Ninja -D CMAKE_BUILD_TYPE=Debug -D ENABLE_CCACHE:BOOL=ON --toolchain ...
cmake --build ../build
```
You can also see a more detailed walkthrough on CMake configuration at [How to build VCMI (macOS)](./Building_macOS.md).
## Docker
For developing it's also possible to use Docker to build android APK. The only requirement is to have Docker installed. The container image contains all the other prerequisites.
To build using docker just open a terminal with `vcmi` as working directory.
To build using docker just open a terminal with `vcmi` repo root as working directory.
Build the image with (only needed once):
`docker build -f docker/BuildAndroid-aarch64.dockerfile -t vcmi-android-build .`
```sh
docker build -f docker/BuildAndroid-aarch64.dockerfile -t vcmi-android-build .
```
After building the image you can compile vcmi with:
`docker run -it --rm -v $PWD/:/vcmi vcmi-android-build`
The current dockerfile is aarch64 only but can adjusted manually for armv7.
```sh
docker run -it --rm -v $PWD/:/vcmi vcmi-android-build
```
The current dockerfile is aarch64 only but can be easily adjusted for other architectures.