Introduction to Android NDK Development and CMake Usage

Hello World

We will understand CMake through a Hello World project.

First, create a new project that includes native code. When creating a New Project, check the Include C++ support option.

New Project

Once the project is created, we can see that there are four differences compared to a regular Android project.

1. A cpp directory has been added under main, which is where the C/C++ code is placed.

2. The module-level build.gradle file has been modified.

3. A CMakeLists.txt file has been added.

4. There is an additional .externalNativeBuild directory.

5. 

Difference

• build.gradle

Since CMake’s commands are integrated into gradle – externalNativeBuild, there are two places to configure CMake in gradle.

The externalNativeBuild – cmake outside of defaultConfig specifies the path to CMakeLists.txt; the externalNativeBuild – cmake inside defaultConfig mainly fills in the command parameters for CMake. The parameters in arguments are ultimately transformed into an executable CMake command, which can be found in .externalNativeBuild/cmake/debug/{abi}/cmake_build_command.txt. As follows:

cmake command

For more command parameters and their meanings, you can refer to the Android NDK-CMake documentation:

https://developer.android.com/ndk/guides/cmake.html

• CMakeLists.txt

CMakeLists.txt mainly defines which files need to be compiled and the relationships with other libraries.

Let’s take a look at the CMakeLists.txt in the new project.

This is actually a very basic CMakeLists.txt. CMakeLists.txt can be very powerful, allowing for custom commands, file searches, header file inclusion, variable settings, etc. It is recommended to use it in conjunction with the official CMake documentation.

https://cmake.org/documentation/

At the same time, I recommend a simplified Chinese translation of the CMake manual:

https://www.zybuluo.com/khan-lau/note/254724

Using CMake with Your Own and Other Pre-built Libraries

When you need to incorporate existing static/dynamic libraries (like FFMpeg) or compile core parts yourself and provide them, you need to consider how to use your own and other pre-built libraries in CMake.

The documentation on using existing libraries on the Android NDK official website still explains the combination of ndk-build + Android.mk + Application.mk (in fact, most of the official documentation does not use CMake).

https://developer.android.com/ndk/guides/libs.html

Fortunately, there is an official example project on GitHub called hello-libs that demonstrates how to create static/dynamic libraries and reference them. Now let’s pull down the code and see how it is implemented.

https://github.com/googlesamples/android-ndk/tree/master/hello-libs

hello-libs

Let’s first look at the README introduction on GitHub:

1. app – Uses a static library and a dynamic library from $project/distribution/.

2. gen-libs – Generates a dynamic library and a static library and copies them to the $project/distribution/ directory. You do not need to compile this library again; the binary files are already stored in the project. Of course, if needed, you can compile your own source code by uncommenting the settings.gradle and app/build.gradle files, then executing once, and commenting them back to prevent any impact during the build.

We will analyze the module from the bottom up, starting with the gen-libs module.

• gen-libs/build.gradle

Consulting the documentation, we can see that the arguments -DANDROID_PLATFORM represents the compiled Android platform. The documentation suggests setting minSdkVersion directly, so this parameter can be ignored. Another parameter -DANDROID_TOOLCHAIN=clang indicates that CMake has two compilation toolchains – clang and gcc, with gcc deprecated and clang being the default. Documentation address:

https://developer.android.com/ndk/guides/cmake.html

targets ‘gmath’, ‘gperf’ indicate which projects to compile. (If not filled in, it will compile all.)

• cpp/CMakeLists.txt

The outer CMakeLists mainly uses add_subdirectory. Consulting the CMake official documentation, we can see that this command adds a sub-path for building. The CMakeLists.txt in the sub-path will also be executed, meaning it will execute the CMakeLists.txt in gmath and gperf.

CMake official documentation:

• cpp/gmath/CMakeLists.txt

This is one of the static library’s CMakeLists.txt, while the other is quite similar, only changing STATIC to SHARED (dynamic library).

add_library(gmath STATIC src/gmath.c) was previously used to compile a static library, with the source file being src/gmath.c.

set_target_properties command is used to set some properties of the target to change how they are built. In this command, the ARCHIVE_OUTPUT_DIRECTORY property of gmath is set, which changes the output path.

add_custom_command is a custom command. This command also copies the header files to the distribution_DIR.

The above explains the process of compiling static/dynamic libraries. To summarize, here are three points:

1. Compile static/dynamic libraries

2. Modify output paths

3. Copy exposed header files

Next, let’s see how the app module uses the pre-built static/dynamic libraries.

• app/src/main/cpp/CMakeLists.txt

I have placed my explanations in comments. You can see that it is roughly divided into four steps:

1. Individually create static/dynamic libraries, directly referencing existing .a files or .so files.

2. Create your application’s library hello-libs.

3. Include previously exposed header files.

4. Link the static/dynamic libraries.

This is quite understandable. After editing and syncing, you will find that the C/C++ code in hello-libs can reference the exposed header files to call internal methods..

References

First and foremost, the official Android NDK documentation is essential to read, even though it may not be complete.

https://developer.android.com/ndk/guides/index.html

When you first encounter NDK development and find the new Hello World project too simple, I recommend pulling down the googlesamples – android-ndk project.

https://github.com/googlesamples/android-ndk

There are multiple examples available that are much more comprehensive than the official documentation.

Google Samples

When you find that some NDK configurations in the examples do not meet your needs, you will need to consult the CMake official documentation for a complete list of supported functions. Additionally, here is a simplified Chinese translation of the CMake manual.

https://www.zybuluo.com/khan-lau/note/254724

The above documentation is solely to address compilation configuration issues encountered during NDK development. The specifics of C/C++ logic writing and JNI are not covered here.