Skip to content

Build for Android

Jump to bottom
Angelo Theodorou edited this page Dec 12, 2021 · 1 revision

Note: You can also download binaries or automate the compilation with ncline.

Before starting download and install CMake. In order to build the nCine library for Android you need to clone or download some git repositories:

  • nCine, this is the main project
  • nCine-android-libraries, this project contains CMake scripts to build dependency libraries
  • nCine-data, the data files for the nCine tests (optional but recommended)
  • ncPong, a Pong game built with the nCine that is useful as an example project (optional)
  • ncPong-data, the data files for the Pong game (optional)

For the nCine project to automatically find the dependencies and the data it is important that all repositories are in the same directory.

For the nCine project to automatically find the dependencies and the data it is important that all repositories are in the same directory and that their name is the same as the repository name. This means that if you decide to download a ZIP file generated by GitHub from a branch, you need to remove the branch suffix so that the directory name is the same as the repository one.

For example, if you download nCine-master.zip and extract it, you should rename the nCine-master directory to nCine to better follow the rest of the istructions.

Note: Remember that for every project, depending on your needs, you can specify -D CMAKE_BUILD_TYPE=Debug or -D CMAKE_BUILD_TYPE=Release at the CMake generation phase.

Build the dependency libraries

As for the other projects, the Android dependencies are built using CMake.

You will also need the Android NDK, at least r19, in order to compile the code. You can set its path in the ANDROID_NDK_HOME, ANDROID_NDK_ROOT or ANDROID_NDK environment variables, or in the NDK_DIR CMake variable.

Two more variables need to be set before running CMake:

  • ARCH has to be set to one of the supported architectures: armeabi-v7a, arm64-v8a or x86_64
  • PLATFORM has to be set to a number specifying the Android API level

You can now invoke CMake to configure the libraries:

cmake -S nCine-android-libraries/ -B nCine-android-libraries-build -D ARCH=arm64-v8a -D PLATFORM=21 -D CMAKE_BUILD_TYPE=Release

Then invoke CMake again to compile them:

cmake --build nCine-android-libraries-build

Note: The CMake scripts use the ExternalProject module and sometimes they define a patch step. If you are on Windows you might need to install a patch command and either specify it modifying the scripts in question or make it available through the syetem path variable.

Build the nCine library

To enable the compilation of the Android version of the library you need to switch on the NCINE_BUILD_ANDROID CMake variable. Similar to the dependency libraries project, you can set the NDK path through an environment variable or via CMake.

cmake -S nCine -B nCine-build -D NCINE_BUILD_ANDROID=ON
cmake --build nCine-build

To assemble the APK you need to install Gradle and to setup two Gradle properties, cmakeCommand and ndkDir. The first one is the path to the CMake executable while the second is the NDK path. You can specify those properties using the gradle.properties file or on the command line, using -Pproperty=value. It is now possible to build the APKs of the default test.

cd nCine-build/android
gradle build -PcmakeCommand=<path/to/cmake> -PndkDir=<path/to/NDK>

Note: When invoking gradle on Windows the generator used by CMake to compile is NMake Makefiles. It would only work if you have nmake in your system path variable.

There is an additional CMake option that would carry on this step automatically, invoking Gradle and passing the two needed properties.

cmake -S nCine -B nCine-build -D NCINE_BUILD_ANDROID=ON -D NCINE_ASSEMBLE_APK=ON

Build the samples

If you have nCine built somewhere with Android support enabled you can invoke Gradle as follows.

gradle build -PcmakeCommand=<path/to/cmake> -PndkDir=<path/to/NDK> -p <path/to/built/android/dir> -PbuildDir=<builddir> --project-cache-dir=<builddir>/.gradle

Build the ncPong example

In order to build the Android version of ncPong you need to switch on the NCPROJECT_BUILD_ANDROID CMake variable and then run Gradle to build the APK.

You will also need to specify the nCine_DIR variable. It should point to the engine build directory or, if you are using an archive downloaded from the artifacts repository, to the directory inside the engine that contains the nCineConfig.cmake file.

cmake -S ncPong -B ncPong-build -D NCPROJECT_BUILD_ANDROID=ON -D nCine_DIR=<current directory>/nCine-build
cd ncPong-build/android
gradle build -PcmakeCommand=<path/to/cmake> -PndkDir=<path/to/NDK>

Note: Should you decide to build the ncPong example, remember that you will need the ncPong-data directory at the same level.

C.I. Scripts

For reference you can have a look at the continuous integration scripts:

nCine • Website • Twitter • YouTube • Discord

Clone this wiki locally