Create Hello-CMake with Android Studio

1. Overview

In this codelab, you'll learn how to use Android Studio CMake template to start Android C/C++ project development with a few clicks: 6f76687f3526b8ab.png

What you'll learn

  • How to use Android Studio's CMake support to create a C/C++ project.
  • How to explore and debug JNI code.

What you'll need

How will you use this tutorial?

Read it through only Read it and complete the exercises

How would you rate your experience with building Android apps?

Novice Intermediate Proficient

2. Create a Sample App with the C++ Template

  1. Find and start Android Studio on your development system: a) On Windows, Start > All apps > Android Studio b) On Mac OS X: Double-click on Android Studio in your Application folder c) On Linux: Run studio.sh from your installed location

If this is the first time you are running this version of Android Studio, Android Studio will prompt you to import settings from your previous installation, either import settings from a previous installation or accept default settings only. The "Welcome to Android Studio" screen would appear as:

64ed958c9eddadb4.png

  1. Select "Start a new Android Studio project".
  2. In the "Choose your project" dialog, choose "Native C++":

ce14403e1bd61918.png

  1. Click "Next" to set up your first C/C++ project.
  2. In the "Configure your project" dialog, change "Application Name" to Hello-cmake, and leave the rest to their default settings. Your project should look similar to the following:

cd1e2940876a094.png

  1. Click "Next".
  2. In the "Customize C++ Support" dialog, and select "C++17" for "C++ Standard", feel free to select different language standards for the project (This sample does not use any C++17/C++14 specific features). In the later section, you would discover that this configuration creates the "cppFlags" in the module's build.gradle file. bf7ace11a14d227d.png
  3. Click "Finish" to complete application creation! Wait for Android Studio to complete the new project creation, and it should look like the following:

ea7b289303c93d18.png

  1. Fix "NDK not configured" error. This is because Android does not find the required NDK version on your system. The backend of Android Studio is Android Gradle Plugin (AGP), AGP version 4.0 provides an option for you to configure the needed NDK with ndkVersion;If you do not configure NDK version, AGP 4.0 will use its default NDK version. In this project, you have not specified which NDK to use yet, and actually this project does not care about the version of NDK: any NDK version would work, so you could simply take the given default NDK. In this case, simply click "Install NDK ‘21.0.6113669'" and follow the prompt to fix the error! When it is done, your would see something like this: 7472e6ec7dd70f71.png Note that from AGP 4.1+, the default NDK version will be silently installed when needed.
  2. Your project is ready to run! If you have a physical Android device available, connect it to your workstation with a USB cable; otherwise, create an Emulator.
  3. Run 952c90b61c40a0b6.png the project, you should see the following when running on emulator: 8daca5a8d0ac570a.png

3. Browsing and Debugging JNI Code

  1. From the "Project" pane on the left side of the IDE, expand the "External Build Files" node and double-click "CMakeLists.txt". 4be0f1e82c462004.png This is the CMake build script that Android Studio generates for your Hello-cmake project; CMakelist.txt directs compiler and linker to produce libnative-lib.so from your C/C++ source code. libNatiove-lib.so is loaded by your project's Java code at run time. The CMakeLists.txt contains mostly comment, it should look similar to:
# Sets the minimum version of CMake required to build the native
# library.
cmake_minimum_required(VERSION 3.4.1)

# Creates the project's shared lib: libnative-lib.so.
# The lib is loaded by this project's Java code in MainActivity.java:
#     System.loadLibrary("native-lib");
# The lib name in both places must match.
add_library( native-lib
             SHARED
             src/main/cpp/native-lib.cpp )

find_library(log-lib
             log )

# Specifies libraries CMake should link to your target library. You
# can link multiple libraries, such as libraries you define in the
# build script, prebuilt third-party libraries, or system libraries.

target_link_libraries( # Specifies the target library.
                       native-lib

                       # Links the target library to the log library
                       # included in the NDK.
                       ${log-lib} )
  1. From the same "Project" pane, open "Gradle Scripts" > "build.gradle(Module:app)". In the android.externalNativeBuild.cmake{} block, you can see the bridging code from Gradle to CMake:
// Sets up parameters for both jni build and cmake.
// For a complete list of parameters, see
// developer.android.com/ndk/guides/cmake.html#variables
externalNativeBuild {
   cmake {
       // cppFlags are configured according to your selection
       // of "Customize C++ Support", in this codelab's
       //    "Create a Sample App with the C++ Template",
       //    step 6
       cppFlags "-std=c++17"
   }
......

// Specifies the location of the top level CMakeLists.txt
// The path is relative to the hosting directory
// of this build.gradle file
externalNativeBuild {
   cmake {
       path "src/main/cpp/CMakeLists.txt"
       version "3.10.2"

   }
}

The Android CMake toolchain provides a group of variables for your CMake scripts to configure build parameters, refer to Using CMake variables in Gradle for the complete list.

  1. Under app > cpp, open the file "native-lib.cpp".
  2. From here, you could navigate your C/C++ code. For example, to locate the prototype for C/C++ function "NewStringUTF()", simply right click on the "NewStringUTF" in env->NewStringUTF(hello.c_str()), and select "Go To" > "Implementation(s)". Android Studio will open jni.h inside IDE, and show you the function prototype right away. ddd19c24dadb075.png
  3. Close jni.h source window and go back to native-lib.cpp. Locate the following line of code: std::string hello = "Hello from C++". Set a breakpoint by clicking the left gutter along that line of code or place the caret on the line and press Control+F8 (or Command+F8 on Mac). 5922cb23d14c9147.png
  4. Make sure your Android device is enabled with USB debugging, then click the debug button d42ce5eea9eb453c.png to deploy your app. Your target device should prompt "Waiting For Debugger" message: 6846bccc5d73efa8.png

Do not tap "FORCE CLOSE". Note: Android Studio might prompt to install "Instant Run" before starting application; in that case, choosing either "Proceed without Instant Run" or "Install and Continue" is fine for this codelab.

  1. Wait until Android Studio connects to the debugger on your device (it might take a short time for the first time to connect debugger, depending on the device and Android platform version) and stops at the breakpoint: 6f76687f3526b8ab.png
  2. Select "5: Debug" b62a4a35dc68cdd.png tab, click "env" inside the "Variables" to observe the contents of env pointer. You can now step over code with the F8 key and perform other debugging activities. Press F9 to resume execution–you should see the application finish execution on the target device!

4. Congratulations!

With Android Studio 4.0.0, it is simple to create and manage a project that includes C/C++ code; begin your new C/C++ projects with Android Studio + CMake today!

What we've covered with Android Studio

  • Create a JNI project with Android Studio C/C++ template
  • Debug native code in JNI project

Next Steps

Learn More