Configure CMake

    This section covers some basic commands you should include in your build script in order to tell CMake which sources to use when creating your native library. To learn more, read the official documentation about .

    After you configure a new CMake build script, you need toconfigure Gradleto include your CMake project as a build dependency, so that Gradle builds andpackages your native library with your app's APK.

    Note: If your project uses ndk-build, you don’t need to create a CMake build script. You can simply to include your existing native library project by providing a path to your Android.mk file.

    To create a plain text file that you can use as your CMake build script, proceed as follows:

    • Open the Project pane from the left side of the IDE and select the Project view from the drop-down menu.

    • Right-click on the root directory of your-module and select New > File.
      Note: You can create the build script in any location you want. However, when configuring the build script, paths to your native source files and libraries are relative to the location of the build script.

    • Enter "CMakeLists.txt" as the filename and click OK.
      You can now configure your build script by adding CMake commands. To instruct CMake to create a native library from native source code, add the and add_library() commands to your build script:

    Tip: Similar to how you can tell CMake to create a native library from source files, you can use the command to tell CMake to instead create an executable from those source files. However, building executables from your native sources is optional, and building native libraries to package into your APK satisfies most project requirements.

    When you add a source file or library to your CMake build script using add_library(), Android Studio also shows associated header files in the Project view after you sync your project. However, in order for CMake to locate your header files during compile time, you need to add the include_directories() command to your CMake build script and specify the path to your headers:

    1. add_library(...)
    2.  
    3. # Specifies a path to native header files.
    4. include_directories(src/main/cpp/include/)

    For example, if you specify "native-lib" as the name of your shared library in the build script, CMake creates a file named libnative-lib.so. However, when loading this library in your Java or Kotlin code, use the name you specified in the CMake build script:

    1. static {
    2.     System.loadLibrary("native-lib");
    3. }

    Note: If you rename or remove a library in your CMake build script, you need to clean your project before Gradle applies the changes or removes the older version of the library from your APK. To clean your project, select Build > Clean Project from the menu bar.

    Android Studio automatically adds the source files and headers to the cpp group in the Project pane. By using multiple add_library() commands, you can define additional libraries for CMake to build from other source files.

    The Android NDK provides a set of native APIs and libraries that you may find useful. You can use any of these APIs by including in your project’s script file.

    Prebuilt NDK libraries already exist on the Android platform, so you don’t need to build them or package them into your APK. Because the NDK libraries are already a part of CMake’s search path, you don’t even need to specify the location of the library in your local NDK installation—you only need to provide CMake with the name of the library you want to use and link it against your own native library.

    Add the find_library() command to your CMake build script to locate an NDK library and store its path as a variable. You use this variable to refer to the NDK library in other parts of the build script. The following sample locates the and stores its path in log-lib:

    In order for your native library to call functions in the log library, you need to link the libraries using the target_link_libraries() command in your CMake build script:

    1. find_library(...)
    2.  
    3. # Links your native library against one or more other native libraries.
    4. target_link_libraries( # Specifies the target library.
    5.                        native-lib
    6.  
    7.                        ${log-lib} )

    The NDK also includes some libraries as source code that you need to build and link to your native library. You can compile the source code into a native library by using the add_library() command in your CMake build script. To provide a path to your local NDK library, you can use the ANDROID_NDK path variable, which Android Studio automatically defines for you.

    1. add_library( app-glue
    2.              STATIC
    3.              ${ANDROID_NDK}/sources/android/native_app_glue/android_native_app_glue.c )
    4.  
    5. # You need to link static libraries against your shared native library.
    6. target_link_libraries( native-lib app-glue ${log-lib} )

    Adding a prebuilt library is similar to specifying another native library for CMake to build. However, because the library is already built, you need to use the flag to tell CMake that you only want to import the library into your project:

    You then need to specify the path to the library using the set_target_properties() command as shown below.

    Some libraries provide separate packages for specific CPU architectures, or , and organize them into separate directories. This approach helps libraries take advantage of certain CPU architectures while allowing you to use only the versions of the library you want. To add multiple ABI versions of a library to your CMake build script, without having to write multiple commands for each version of the library, you can use the ANDROID_ABI path variable. This variable uses a list of the default ABIs that the NDK supports, or a filtered list of ABIs you to use. For example:

    1. add_library(...)
    2. set_target_properties( # Specifies the target library.
    3.                        imported-lib
    4.  
    5.                        # Specifies the parameter you want to define.
    6.                        PROPERTIES IMPORTED_LOCATION
    7.  
    8.                        # Provides the path to the library you want to import.
    9.                        imported-lib/src/${ANDROID_ABI}/libimported-lib.so )

    For CMake to locate your header files during compile time, you need to use the include_directories() command and include the path to your header files:

    1. include_directories( imported-lib/include/ )

    Note: If you want to package a prebuilt library that is not a build-time dependency—for example, when adding a prebuilt library that is a dependency of imported-lib, you do not need perform the following instructions to link the library.

    To link the prebuilt library to your own native library, add it to the target_link_libraries() command in your CMake build script:

    To package the prebuilt library into your APK, you need to manually configure Gradle with the sourceSets block to include the path to your .so file. After building your APK, you can verify which libraries Gradle packages into your APK by using the .

    If you want to build multiple CMake projects and include their outputs in your Android project, you can use one CMakeLists.txt file as the top-level CMake build script (which is the one you link to Gradle) and add additional CMake projects as dependencies of that build script. The following top-level CMake build script uses the command to specify another file as a build dependency and then links against its output just as it would with any other prebuilt library.

    1. # Sets lib_src_DIR to the path of the target CMake project.
    2. set( lib_src_DIR ../gmath )
    3.  
    4. set( lib_build_DIR ../gmath/outputs )
    5. file(MAKE_DIRECTORY ${lib_build_DIR})
    6.  
    7. # Adds the CMakeLists.txt file located in the specified directory
    8. # as a build dependency.
    9. add_subdirectory( # Specifies the directory of the CMakeLists.txt file.
    10.                   ${lib_src_DIR}
    11.  
    12.                   # Specifies the directory for the build outputs.
    13.                   ${lib_build_DIR} )
    14.  
    15. # Adds the output of the additional CMake build as a prebuilt static
    16. # library and names it lib_gmath.
    17. add_library( lib_gmath STATIC IMPORTED )
    18. set_target_properties( lib_gmath PROPERTIES IMPORTED_LOCATION
    19.                        ${lib_build_DIR}/${ANDROID_ABI}/lib_gmath.a )
    20. include_directories( ${lib_src_DIR}/include )
    21.  
    22. # Links the top-level CMake build output against lib_gmath.
    23. target_link_libraries( native-lib ... lib_gmath )