Incorporating native code in C and C++ into projects for mobile devices is becoming an increasingly popular practice among developers. This allows you to achieve significant performance gains in computationally complex tasks such as graphics processing, game physics, or working with audio streams. However, the very process of connecting tools to compile such code often causes difficulties for beginners, especially at the stage of initial environment configuration.
To get started, you will need not just to download the archive, but also to correctly enter the paths to the tools in system variables so that the assembly scripts can find the compiler. Android Native Development Kit (NDK) is a set of tools that allows you to implement parts of your application in native code, using C and C++ languages. Without proper installation, the project build will fail with an error indicating that the required toolchain is missing.
There are several ways to integrate this package into your workflow: from using the built-in manager in Android Studio to manually downloading binaries from the official developer portal. The choice of method depends on your specific tasks and requirements for library versions. Below we will go through each of the steps in detail so that you can create a stable environment for cross-compilation.
Selecting a download method and package version
The first step is to determine which version of the toolkit your project needs. Modern versions of Android Studio offer a built-in SDK manager that greatly simplifies the process of downloading and updating components. This is the most preferred option for most developers, as it guarantees version compatibility and automatic path configuration.
However, in some cases, it is necessary to use a specific, often older or, conversely, experimental version of the NDK, which cannot be obtained through the standard IDE interface. Then the only option is to manually download the archive from the developers’ website. Google provides packages for various operating systems, including Windows, macOS and Linux.
When choosing a version, pay attention to the release number. Newer versions contain security fixes and support for the latest C++ language standards, but may require updating the minimum version of your application's API. Old versions may be necessary to support legacy code, but their use carries the risk of not being compatible with newer versions of the operating system Android.
Always check your project's build.gradle file to see what the minimum NDK version is specified in the ndkVersion parameter. Using an incompatible version may lead to strange linking errors.
- 📦 Android Studio SDK Manager — automatic installation and update via a graphical interface.
- 💻 Command Line Tools — download via the sdkmanager utility for servers or CI/CD pipelines.
- 🌐 Direct Download — manual download of a ZIP archive from the official website for specific versions.
- ⚙️ Custom Path —use a local copy located outside the standard SDK directory.
Manual installation and unpacking of the archive
If you decide to go the manual installation route, you need to download the appropriate archive for your operating system. After the download is complete, the file should be unpacked into a directory whose path does not contain spaces or Cyrillic characters. This is a critical requirement, as many of the command line tools included in the suite may not handle such paths correctly.
The standard location is a folder inside the SDK directory, usually Android/Sdk/ndk. However, you are free to choose any other convenient location on the disk, for example C:\Dev\Android\ndk or /opt/android-ndk in Linux systems. The main thing is to remember the full path, as it will be required for further setting of environment variables.
After unpacking, inside the folder you will see a directory with the name of the version, for example, 25.2.9519653. Inside it are all the necessary binaries, scripts and header files. The folder structure is strictly defined, and changing its internal contents manually is not recommended so as not to disrupt the operation of the build scripts.
NDK folder structure
Inside the root folder of the version there are subdirectories toolchains (compilers), platforms (header files for different versions of Android), sources (source code of system libraries) and prebuilt (ready-made binaries for the host system).
| Component | Description | Location |
|---|---|---|
toolchains |
A set of Clang and GCC compilers for various architectures | Root version folder |
platforms |
Header files and libraries for different API levels | Version root folder |
sources |
Source code of system libraries (libc, libm, libstdc++) | Version root folder |
build |
Scripts and configuration files for the system build | Version root folder |
Setting environment variables in the system
In order for the system and build tools to find NDK executable files from any directory, you need to add the path to them to the environment variable. In the operating system Windows this is done through the system properties, and in Linux and macOS through shell configuration files such as .bashrc or .zshrc.
In Windows, open the Control Panel, find the "System" section and go to advanced settings. In the window that opens, click the "Environment Variables" button. You need to create a new system variable named ANDROID_NDK_HOME and specify as the value the full path to the folder with the installed toolset.
export ANDROID_NDK_HOME=/opt/android-ndk-r25b
export PATH=$PATH:$ANDROID_NDK_HOME
After adding the variable in Linux or macOS, do not forget to apply the changes by running the command source ~/.bashrc or restarting the terminal. You can verify the success of the setup by trying to run the version check command from any folder. If the system responds with the version number, then the path is entered correctly.
⚠️ Attention: If you use several versions of the NDK simultaneously for different projects, the global environment variable may cause conflicts. In this case, it is better to set the path locally in the configuration file of a specific project or pass it as an argument when starting Gradle.
Integration with Android Studio and Gradle
Modern build system Gradle can automatically find the installed NDK, if it located in the standard SDK directory. However, to explicitly indicate the version in the module configuration file build.gradle the block androidis used. This allows you to fix the version of the toolkit for the entire project, which is especially useful during team development.
In the file local.properties, which is located in the project root, you can also explicitly specify the path to the NDK. This takes precedence over system variables and IDE settings. The line looks like ndk.dir=C\:\\Android\\ndk\\25.2.9519653 for Windows or a similar path for Unix systems.
When synchronizing the project, Android Studio will check for the specified version. If it is missing, the IDE will offer to download it automatically. This is a convenient mechanism that eliminates the need for manual configuration, but requires a stable Internet connection at the time of the first build.
Explicitly specifying the ndkVersion in build.gradle ensures that all developers on the team and the build server will use identical tools, eliminating errors of "works on my machine."
CMake and ndk-build configuration
To compile native code in the project, you need to configure the build system. At the moment CMake as a more modern and flexible tool compared to the outdated one ndk-build. In the file CMakeLists.txt you describe the dependencies, source files and target libraries that should be compiled.
In order for Gradle to know to run CMake, in the file build.gradle application module block externalNativeBuild specifies the path to the configuration file. You can also pass additional compiler flags, such as level optimization -O2 or enabling debugging information.
externalNativeBuild {
cmake {
path"src/main/cpp/CMakeLists.txt"
version"3.22.1"
}
}
If you still use the old method ndk-buildthe file structure Android.mk will be different. Here you need to explicitly specify modules, sources and flags. Although this method is considered obsolete, it is still found in older projects and some specific cases.
⚠️ Attention: The CMake interfaces and capabilities included in the NDK may change from version to version. Always check the official documentation for the specific version you are using, especially when using new features of the C++ language.
Verifying the installation and resolving problems
After completing all the settings, you need to ensure that the environment works correctly. Try building the project ("Rebuild Project"). If the process went through without errors, it means that the paths were entered correctly and the compiler was found. If errors occur, carefully study the build log (Build Output).
A common problem is an error NDK not configured or a message that the file cmake not found. This usually means that the environment variable was not picked up by the IDE or the path to local.properties is incorrect. It's also worth checking the permissions on the tools folder, especially on Linux and macOS.
Another common situation is mismatched architectures. Make sure your build configuration is set to the processor architectures (ABIs) that your device or emulator supports. For example, an attempt to run a library compiled only for armeabi-v7aon a device with architecture x86_64 without appropriate emulation will lead to a crash.
☑️ Diagnosing problems with NDK
Frequently asked questions (FAQ)
Is it possible to use several versions of the NDK at the same time?
Yes, it is possible. You can install multiple versions in different folders. For each project in the file local.properties or build.gradle you can specify the path to the specific required version. In this case, the system environment variable may point to the default version.
What version of NDK is needed to support Android 14?
For development for new versions of Android, it is recommended to use the current stable NDK releases. Typically these are versions numbered 25 and higher. Specific requirements depend on the APIs and libraries used, so it is better to focus on the recommendations in the documentation of the corresponding API level.
Why does the assembly fail with the error "no rule to make target"?
This error often occurs when using ndk-build and indicates a problem in the file Android.mk. Check that the paths to the source files are correct and make sure that the file names are specified with the correct case, as Linux and Windows file systems are sensitive to this differently.
Do I need to install a separate GCC for the NDK to work?
No, it is not necessary. Modern versions of Android NDK include their own toolchain based on Clang and LLVM, which is completely self-sufficient. Installing a separate GCC can even lead to conflicts if the paths are configured incorrectly.