Cómo agregar código C y C++ a un proyecto

Para agregar código C y C++ a tu proyecto de Android, coloca el código en un directorio cpp en el módulo del proyecto. Cuando creas el proyecto, este código se compila en una biblioteca nativa que Gradle puede empaquetar con la app. El código Java o Kotlin puede llamar a funciones de la biblioteca nativa a través de la Interfaz nativa de Java (JNI). Para obtener más información sobre el uso del framework de JNI, consulta las sugerencias de JNI para Android.

Android Studio es compatible con CMake, que es útil para proyectos multiplataforma. Android Studio también admite ndk-build, que puede ser más rápido que CMake, pero solo es compatible con Android. Por el momento, no se admite el uso de CMake y ndk-build en el mismo módulo.

Si deseas importar una biblioteca ndk-build existente a tu proyecto de Android Studio, obtén información para vincular Gradle a tu proyecto de biblioteca nativa.

En esta página, se muestra cómo configurar Android Studio con las herramientas de compilación necesarias, crear un proyecto nuevo compatible con C y C++, y agregar archivos C y C++ nuevos al proyecto.

Si, en cambio, deseas agregar código nativo a un proyecto existente, sigue estos pasos:

  1. Crea nuevos archivos fuente nativos y agrégalos a tu proyecto de Android Studio.
    • Omite este paso si ya tienes código nativo o si deseas importar una biblioteca nativa ya compilada.
  2. Configura CMake para compilar tu código fuente nativo en una biblioteca. Esta secuencia de comandos de compilación es obligatoria si realizas importaciones y vinculaciones en bibliotecas de plataforma o compiladas previamente.
    • Si ya tienes una biblioteca nativa con una secuencia de comandos de compilación CMakeLists.txt o que usa ndk-build y, además, incluye una secuencia de comandos de compilación Android.mk, omite este paso.
  3. Configura Gradle proporcionando una ruta de acceso al archivo de secuencia de comandos de CMake o ndk-build. Gradle usa la secuencia de comandos de compilación para importar código fuente a tu proyecto de Android Studio y empaquetar tu biblioteca nativa en la app.

Una vez que hayas configurado el proyecto, accede a las funciones nativas desde el código Java o Kotlin usando el framework de JNI. Para compilar y ejecutar tu app, haz clic en Run ejecutar y luego ejecutar la app desde la barra de menú.

Nota: Si tu proyecto existente usa la herramienta obsoleta ndkCompile, migra a CMake o ndk-build.

Cómo descargar el NDK y las herramientas de compilación

Para compilar y depurar el código nativo de tu app, necesitas los siguientes componentes:

  • El kit de desarrollo nativo (NDK) de Android: Es un conjunto de herramientas que te permite usar código C y C++ con Android. El NDK proporciona bibliotecas de plataforma que te permiten administrar actividades nativas y acceder a componentes de dispositivos físicos, como sensores y entradas táctiles.
  • CMake: Es una herramienta de compilación externa que funciona junto con Gradle para compilar tu biblioteca nativa. No necesitas este componente si solo planeas usar ndk-build.
  • LLDB: Es el depurador en Android Studio que depura código nativo.

Si deseas obtener información para instalar estos componentes, consulta Cómo instalar y configurar el NDK y CMake.

Cómo crear un nuevo proyecto compatible con C y C++

Para crear un proyecto nuevo que admita código nativo, el proceso es similar a crear cualquier otro proyecto de Android Studio, pero tiene un paso adicional:

  1. En la sección Choose your project del asistente, selecciona el tipo de proyecto Native C++.
  2. Haz clic en Next.
  3. Completa todos los demás campos en la siguiente sección del asistente.
  4. Haz clic en Next.
  5. En la sección Customize C++ Support del asistente, puedes personalizar el proyecto en el campo C++ Standard.
    • Usa la lista desplegable para seleccionar qué estandarización de C++ deseas usar. Si seleccionas Toolchain Default, se usará la configuración predeterminada de CMake.
  6. Haz clic en Finish.

Después de que Android Studio termine de crear el proyecto nuevo, abre el panel Project del lado izquierdo del IDE y selecciona la vista Android del menú. Como se muestra en la Figura 1, Android Studio agrega el grupo cpp:

Figura 1: Grupos de vistas de Android para fuentes nativas y secuencias de comandos de compilación externa

Nota: Esta vista no refleja la jerarquía real del archivo en el disco, sino que agrupa archivos similares para simplificar la navegación por el proyecto.

El grupo cpp es el lugar en el que puedes encontrar todos los archivos fuente nativos, los encabezados, las secuencias de comandos de compilación para CMake o ndk-build, así como las bibliotecas ya compiladas que son parte del proyecto. Para proyectos nuevos, Android Studio crea un archivo fuente C++ de muestra, native-lib.cpp, y lo ubica en el directorio src/main/cpp/ del módulo de la app. Este código de muestra proporciona una función simple de C++, stringFromJNI(), que muestra la string "Hello from C++". Si deseas obtener información para agregar archivos fuente adicionales al proyecto, consulta la sección correspondiente de Cómo crear nuevos archivos fuente nativos.

Así como los archivos build.gradle le indican a Gradle el modo para compilar la app, CMake y ndk-build requieren una secuencia de comandos de compilación a fin de saber cómo compilar la biblioteca nativa. Para proyectos nuevos, Android Studio crea una secuencia de comandos de compilación de CMake, CMakeLists.txt, y la ubica en el directorio raíz del módulo. Si deseas obtener más información sobre el contenido de esta secuencia de comandos de compilación, consulta Cómo configurar CMake.

Cómo compilar y ejecutar la app de muestra

Cuando haces clic en Run ejecutar y luego ejecutar la app desde la barra de menú, Android Studio compila e inicia una app que muestra el texto "Hello from C++" en el dispositivo o emulador de Android. En la siguiente descripción general, se detallan los eventos que tienen lugar para compilar y ejecutar la app de muestra:

  1. Gradle llama a la secuencia de comandos de compilación externa CMakeLists.txt.
  2. CMake sigue los comandos de la secuencia de comandos de compilación a fin de compilar un archivo de origen C++, native-lib.cpp, en una biblioteca de objeto compartida y le asigna el nombre libnative-lib.so, que Gradle luego empaquetará en la app.
  3. Durante el tiempo de ejecución, el objeto MainActivity de la app carga la biblioteca nativa mediante System.loadLibrary(). La función nativa de la biblioteca, stringFromJNI(), ahora está disponible para la app.
  4. MainActivity.onCreate() llama a stringFromJNI(), que muestra "Hello from C++" y lo usa para actualizar TextView.

A fin de verificar que Gradle empaquete la biblioteca nativa en la app, usa el Analizador de APK:

  1. Selecciona Build > Build Bundles(s) / APK(s) > Build APK(s).
  2. Elige Build > Analyze APK.
  3. Selecciona el APK o el AAB del directorio app/build/outputs/ y haz clic en OK.
  4. Como se muestra en la Figura 2, puedes ver libnative-lib.so en la ventana del Analizador de APK, en lib/<ABI>/.

    Figura 2: Ubica una biblioteca nativa con el Analizador de APK.

Sugerencia: Si quieres experimentar con otras apps para Android que usan código nativo, haz clic en File > New > Import Sample y selecciona un proyecto de muestra de la lista Ndk.

Cómo crear archivos fuente C/C++ nuevos

Para agregar nuevos archivos fuente C/C++ a un proyecto existente, sigue estos pasos:

  1. Si aún no tienes un directorio cpp/ en el conjunto de fuentes principal de la app, crea uno de la siguiente manera:
    1. Abre el panel Project en el lado izquierdo del IDE y selecciona la vista Project del menú.
    2. Ve a your-module > src.
    3. Haz clic con el botón derecho en el directorio main y selecciona New > Directory.
    4. Ingresa cpp como nombre del directorio y haz clic en OK.

  2. Haz clic con el botón derecho en el directorio cpp/ y selecciona New > C/C++ Source File.

  3. Ingresa un nombre para el archivo fuente, como native-lib.

  4. En el menú Type, selecciona la extensión de archivo del archivo fuente, como .cpp.
    • Haz clic en Edit File Types para agregar otros tipos de archivos al menú, como .cxx o .hxx. En el cuadro de diálogo emergente New File Extensions, selecciona otra extensión de archivo de los menús Source Extension y Header Extension, y haz clic en OK.

  5. Para crear un archivo de encabezado, selecciona la casilla de verificación Create an associated header.

  6. Haz clic en OK.

Después de agregar archivos C y C++ nuevos al proyecto, deberás configurar CMake a fin de incluirlos en la biblioteca nativa.

Recursos adicionales

Para obtener más información sobre la compatibilidad con el código C/C++ en la app, prueba el siguiente recurso.

Codelabs

  • Crea Hello-CMake con Android Studio: En este codelab, se muestra cómo usar la plantilla de CMake de Android Studio para comenzar el desarrollo de proyectos con el NDK de Android.