Android NDK Installation Guide

Introduction to Android NDK

What is the Android NDK?

The Android Native Development Kit (NDK) is a toolset that lets developers use C and C++ code in their Android apps. It’s handy for tasks that need high performance, like game development or real-time data processing. By using the NDK, you can squeeze out more speed and efficiency from your app because it allows you to run native code directly on the device.

Difference Between Android NDK and SDK

The Android Software Development Kit (SDK) is the standard toolkit for building Android apps using Java or Kotlin. It includes libraries, tools, and documentation for creating apps that run on the Android platform. On the flip side, the NDK lets you write parts of your app in native languages like C or C++. This is useful when you need to optimize performance or reuse existing code written in these languages. While the SDK is great for most app development tasks, the NDK is your go-to for performance-critical parts of your app.

Prerequisites

System Requirements

Before diving into the NDK, make sure your system meets the necessary requirements. You’ll need a computer with at least 8GB of RAM and a multi-core processor. The operating system should be Windows 10, macOS 10.14 or later, or a recent version of Linux. Additionally, ensure you have enough storage space, around 10GB, to accommodate the NDK and related tools.

Required Tools

To get started with the NDK, you’ll need a few essential tools. Android Studio is the primary Integrated Development Environment (IDE) for Android development. Within Android Studio, you’ll use CMake, a tool that helps manage the build process of your project. Another important tool is LLDB, which is used for debugging native code. Make sure to have these tools installed and ready to go before you start working with the NDK.

Installing the Android NDK

Install NDK via Android Studio

1. Open Android Studio: Launch Android Studio on your computer.
2. Navigate to SDK Manager: Click on "File" in the top menu, then select "Settings" (or "Preferences" on macOS). In the left pane, choose "Appearance & Behavior," then "System Settings," and finally "Android SDK."
3. SDK Tools Tab: Switch to the "SDK Tools" tab.
4. Select NDK: Check the box next to "NDK (Side by side)" and any other necessary tools like CMake or LLDB.
5. Apply Changes: Click "Apply" and then "OK" to start the installation process. Android Studio will download and install the selected components.
6. Verify Installation: Once the installation completes, you can verify it by going to the "SDK Tools" tab again and ensuring the NDK is listed as installed.

Manual Installation

1. Download NDK: Visit the Android NDK download page and download the version you need.
2. Extract Files: Unzip the downloaded file to a directory of your choice.
3. Set Environment Variables: Add the path to the NDK directory to your system's PATH environment variable. This makes it accessible from the command line.
   • Windows: Go to "System Properties," then "Environment Variables," and add the NDK path to the "Path" variable.
   • macOS/Linux: Open your terminal and edit your shell profile file (e.g., .bashrc, .zshrc). Add the line export PATH=$PATH:/path/to/ndk.
4. Verify Installation: Open a terminal or command prompt and type ndk-build --version. If the NDK is installed correctly, this command will display the version number.

Verify Installation

1. Check in Android Studio: Open Android Studio, go to "File" > "Project Structure" > "SDK Location." Ensure the "Android NDK location" field points to the correct directory.
2. Command Line Verification: Open a terminal or command prompt and type ndk-build --version. The output should show the NDK version installed.
3. Sample Project: Create a sample project in Android Studio that uses native code. Build the project to ensure everything is set up correctly.

Configuring the NDK

Set Up NDK in Android Studio

1. Open Project: Launch your project in Android Studio.
2. Project Structure: Go to "File" > "Project Structure."
3. SDK Location: In the "SDK Location" tab, ensure the "Android NDK location" is set to the correct path.
4. Sync Project: Click "OK" to save the settings and sync your project with the new NDK configuration.

Configure Specific Versions of the NDK

1. Edit Gradle File: Open your project's build.gradle file.

2. Specify NDK Version: Add the following lines to specify the NDK version:
   groovy
   android {
   ndkVersion "21.3.6528147"
   }

3. Sync Project: Save the file and sync your project to apply the changes.

Default NDK Version per AGP Version

1. Check AGP Version: Open your build.gradle file and find the classpath line under dependencies to see your AGP version.
2. Default NDK: Refer to the table above to know which NDK version is default for your AGP version.
3. Override if Needed: If you need a different NDK version, follow the steps in the "Configure Specific Versions of the NDK" section.

Creating and Importing Projects

Create a New Native Project

Starting a new project with the Android NDK is pretty straightforward. Open Android Studio and select "Start a new Android Studio project." Choose a template that fits your needs, but make sure to select one that supports C++ if you plan to use native code. After naming your project and setting up the initial configurations, you'll reach a screen where you can enable C++ support. Check the box for "Include C++ support," then click "Finish."

Once the project is created, Android Studio will generate the necessary files and folders for your native code. You'll see a cpp directory where your C++ files will reside. The IDE also creates a CMakeLists.txt file, which is crucial for building your native code. Now, you can start writing your C++ code in the cpp folder and configure your build settings in the CMakeLists.txt file.

Import an Existing Native Project

If you already have a project with native code, importing it into Android Studio is a breeze. Open Android Studio and select "Import project (Gradle, Eclipse ADT, etc.)." Navigate to the root directory of your existing project and click "OK." Android Studio will automatically detect the project's configuration and set up the necessary files.

After importing, make sure your CMakeLists.txt file and build.gradle files are correctly configured. Sometimes, paths to native libraries or source files might need adjustments. You can find these settings in the build.gradle file under the externalNativeBuild section. Once everything is set up, sync your project with Gradle to ensure all dependencies and configurations are correctly loaded.

Building and Running NDK Projects

Build Configuration

Configuring the build settings for your NDK project involves editing the CMakeLists.txt file and the build.gradle file. In CMakeLists.txt, you specify the source files, include directories, and libraries your project needs. For example, you might add lines like add_library(native-lib SHARED src/main/cpp/native-lib.cpp) to define a native library.

In the build.gradle file, you need to configure the externalNativeBuild block. This block tells Gradle how to build your native code using CMake or ndk-build. You can specify the path to your CMakeLists.txt file and any additional build arguments. Sync your project with Gradle after making these changes to ensure everything is correctly configured.

Running and Debugging

Running and debugging NDK projects in Android Studio is similar to regular Android projects. Click the "Run" button or select "Run" from the menu to build and deploy your app to a connected device or emulator. If you encounter any issues, check the "Build" tab for error messages and fix them accordingly.

For debugging, Android Studio provides a powerful debugger that supports both Java and native code. Set breakpoints in your C++ code by clicking in the left margin of the editor. When you run your app in debug mode, the debugger will stop at these breakpoints, allowing you to inspect variables, step through code, and evaluate expressions. This makes it easier to find and fix bugs in your native code.

Advanced Configuration

Using CMake with NDK

Integrating CMake with your NDK projects allows you to manage complex build configurations easily. In your CMakeLists.txt file, you can define multiple libraries, set compiler flags, and specify custom build steps. For instance, you might use target_link_libraries(native-lib log) to link your native library with the Android log library.

You can also create custom CMake modules to handle specific tasks, like finding third-party libraries or generating source files. These modules can be included in your CMakeLists.txt file using the include() command. This flexibility makes CMake a powerful tool for managing your NDK project's build process.

Managing Dependencies

Managing dependencies in NDK projects involves specifying the libraries and frameworks your native code relies on. In your CMakeLists.txt file, use commands like find_package() and target_link_libraries() to include these dependencies. For example, if your project uses OpenCV, you might add find_package(OpenCV REQUIRED) and target_link_libraries(native-lib ${OpenCV_LIBS}).

In the build.gradle file, you can also specify dependencies for your native code. Use the externalNativeBuild block to include prebuilt libraries or download dependencies from remote repositories. This ensures all necessary libraries are available during the build process, making it easier to manage complex projects with multiple dependencies.