Quick start guide

This tutorial guides you through creating your first Android application with native C++ code. You’ll build a simple “Hello from C++” app that demonstrates how Java/Kotlin code interacts with native code through JNI (Java Native Interface).

Prerequisites

Before starting, ensure you have:

Android Studio installed with NDK and CMake
Basic knowledge of Android app development
Basic C++ knowledge (helpful but not required)

If you haven’t installed the NDK yet, see the installation guide.

Create your first native app

Create a new project with native support

Open Android Studio and create a new project:

Click File > New > New Project
Select Native C++ template
Click Next
Configure your project:
- Name: HelloNDK
- Package name: com.example.hellondk
- Language: Kotlin (or Java)
- Minimum SDK: API 21 or higher
Click Next
Choose C++ Standard: C++14 or higher
Click Finish

Android Studio creates a project with native code support pre-configured.

Explore the project structure

Your project now contains both Java/Kotlin and C++ code:

app/
├── src/
│   ├── main/
│   │   ├── java/          # Java/Kotlin code
│   │   ├── cpp/           # C++ native code
│   │   │   ├── native-lib.cpp
│   │   │   └── CMakeLists.txt
│   │   └── AndroidManifest.xml
└── build.gradle

Key files:

native-lib.cpp: Your C++ source code
CMakeLists.txt: CMake build configuration
MainActivity.kt/java: Loads and calls native code

Examine the native code

Open app/src/main/cpp/native-lib.cpp. You’ll see a JNI function:

#include <jni.h>
#include <string>

extern "C" JNIEXPORT jstring JNICALL
Java_com_example_hellondk_MainActivity_stringFromJNI(
        JNIEnv* env,
        jobject /* this */) {
    std::string hello = "Hello from C++";
    return env->NewStringUTF(hello.c_str());
}

This function:

Is called from Java/Kotlin code
Returns a string created in C++
Uses JNI to convert C++ string to Java string

The function name follows JNI naming convention: Java_<package>_<class>_<method>

Examine the CMake configuration

Open app/src/main/cpp/CMakeLists.txt:

cmake_minimum_required(VERSION 3.18.1)

project("hellondk")

add_library(
    native-lib
    SHARED
    native-lib.cpp
)

find_library(
    log-lib
    log
)

target_link_libraries(
    native-lib
    ${log-lib}
)

This configuration:

Creates a shared library named native-lib
Compiles native-lib.cpp
Links the Android log library

Examine the Kotlin/Java code

Open MainActivity.kt (or MainActivity.java):

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        // Load the native library
        System.loadLibrary("native-lib")
        
        // Call the native method
        val textView: TextView = findViewById(R.id.sample_text)
        textView.text = stringFromJNI()
    }
    
    // Declare the native method
    external fun stringFromJNI(): String
}

The code:

Loads the native library with System.loadLibrary()
Declares the native method with external (Kotlin) or native (Java)
Calls the C++ function like any other method

Build and run the app

Connect an Android device or start an emulator
Click Run (green play button) or press Shift+F10
Wait for the build to complete
The app displays “Hello from C++” on the screen

The first build may take longer as CMake compiles the native code for multiple architectures (armeabi-v7a, arm64-v8a, x86, x86_64).

Customize your native code

Now let’s modify the native code to perform a simple calculation.

Add a new native function

In native-lib.cpp, add a new function that adds two numbers:

extern "C" JNIEXPORT jint JNICALL
Java_com_example_hellondk_MainActivity_addNumbers(
        JNIEnv* env,
        jobject /* this */,
        jint a,
        jint b) {
    return a + b;
}

This function:

Takes two integers as parameters
Returns their sum
Uses jint (JNI integer type)

Declare the method in Kotlin/Java

In MainActivity.kt, add the method declaration:

external fun addNumbers(a: Int, b: Int): Int

Call the native function

Update onCreate to call the new function:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    
    val textView: TextView = findViewById(R.id.sample_text)
    val greeting = stringFromJNI()
    val sum = addNumbers(15, 27)
    textView.text = "$greeting\nSum: $sum"
}

Build and run again

Run the app again. You should now see:

Hello from C++
Sum: 42

Add logging from native code

Logging is essential for debugging native code. Let’s add Android logging support.

Include the log header

In native-lib.cpp, add the Android log header:

#include <jni.h>
#include <string>
#include <android/log.h>

#define TAG "NativeLib"
#define LOGD(...) __android_log_print(ANDROID_LOG_DEBUG, TAG, __VA_ARGS__)
#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, TAG, __VA_ARGS__)

Add logging to your function

Update the addNumbers function:

extern "C" JNIEXPORT jint JNICALL
Java_com_example_hellondk_MainActivity_addNumbers(
        JNIEnv* env,
        jobject /* this */,
        jint a,
        jint b) {
    LOGI("Adding %d + %d", a, b);
    jint result = a + b;
    LOGI("Result: %d", result);
    return result;
}

View logs

Run the app and check Logcat in Android Studio:

Open Logcat tab at the bottom
Filter by “NativeLib”
You’ll see the log messages from C++:

I/NativeLib: Adding 15 + 27
I/NativeLib: Result: 42

Understanding JNI types

When working with JNI, you need to understand type mappings between Java and C++:

Java Type	JNI Type	C++ Type
boolean	jboolean	uint8_t
byte	jbyte	int8_t
char	jchar	uint16_t
short	jshort	int16_t
int	jint	int32_t
long	jlong	int64_t
float	jfloat	float
double	jdouble	double
Object	jobject	-
String	jstring	-

Always use JNI types in your native function signatures. Using regular C++ types will cause runtime errors.

Build system configuration

The build.gradle file contains NDK configuration:

android {
    defaultConfig {
        // Specify which ABIs to build
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
        }
    }
    
    // Link CMake build script
    externalNativeBuild {
        cmake {
            path "src/main/cpp/CMakeLists.txt"
            version "3.18.1"
        }
    }
}

Building for fewer ABIs reduces APK size but limits device compatibility. Most production apps target armeabi-v7a and arm64-v8a.

Debugging native code

Android Studio provides full debugging support for native code:

Set breakpoints

Open native-lib.cpp and click in the left gutter to set a breakpoint.

Debug the app

Click Debug (bug icon) instead of Run. The debugger will pause at your breakpoint.

Inspect variables

Use the Variables pane to inspect values, step through code, and evaluate expressions.

Common issues and solutions

UnsatisfiedLinkError

If you see UnsatisfiedLinkError: No implementation found:

Verify the native function name matches the JNI naming convention
Ensure System.loadLibrary() is called before the native method
Check that CMakeLists.txt includes your .cpp file

Build errors

If the native build fails:

Check Build tab for CMake error messages
Ensure NDK and CMake are installed via SDK Manager
Verify CMake version in CMakeLists.txt matches installed version

Missing symbols

If you get linker errors about missing symbols:

Add required libraries to target_link_libraries in CMakeLists.txt
For Android APIs, use find_library() to locate system libraries

Next steps

Congratulations! You’ve built your first native Android application. Here’s what to explore next:

Build systems

Learn advanced CMake and ndk-build configurations

JNI guide

Deep dive into Java Native Interface programming

Performance

Optimize your native code for maximum performance

Debugging

Master native debugging and crash analysis

Additional resources

NDK API Reference - Complete native API documentation
NDK Guides - Comprehensive development guides
Android NDK Google Group - Community support
GitHub Issues - Report bugs and request features

Get Started

Core Concepts

Build Systems

Guides

Advanced Topics

Quick start guide

Quick start guide

Prerequisites

Create your first native app

Customize your native code

Add logging from native code

Understanding JNI types

Build system configuration

Debugging native code

Common issues and solutions

UnsatisfiedLinkError

Build errors

Missing symbols

Next steps

Build systems

JNI guide

Performance

Debugging

Additional resources

Build docs developers (and LLMs) love

Get Started

Core Concepts

Build Systems

Guides

Advanced Topics

​Quick start guide

​Prerequisites

​Create your first native app

​Customize your native code

​Add logging from native code

​Understanding JNI types

​Build system configuration

​Debugging native code

​Common issues and solutions

​UnsatisfiedLinkError

​Build errors

​Missing symbols

​Next steps

Build systems

JNI guide

Performance

Debugging

​Additional resources

Build docs developers (and LLMs) love

Quick start guide

Prerequisites

Create your first native app

Customize your native code

Add logging from native code

Understanding JNI types

Build system configuration

Debugging native code

Common issues and solutions

UnsatisfiedLinkError

Build errors

Missing symbols

Next steps

Additional resources