Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

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

Puedes agregar código C y C ++ a tu proyecto de Android si colocas 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 el APK. 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 marco de trabajo de JNI, consulta las sugerencias de JNI para Android.

Android Studio es compatible con CMake, que es muy útil para proyectos multiplataforma, y con ndk-build, que puede ser más rápido que CMake, aunque solo es compatible con Android. Actualmente, no es posible usar CMake y ndk-build en el mismo módulo.

Si deseas importar una biblioteca ndk-build existente al proyecto de Android Studio, obtén información sobre cómo vincular Gradle al 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/C++ y agregar archivos C/C++ nuevos al proyecto.

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

  1. Crea archivos de origen nativos nuevos y agrégalos al proyecto de Android Studio.
    • Puedes omitir 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. También necesitas esta secuencia de comandos de compilación si realizas importaciones y vinculaciones en bibliotecas de plataforma o ya compiladas.
    • Si dispones de una biblioteca nativa existente que ya tiene una secuencia de comandos de compilación CMakeLists.txt o usa ndk-build e incluye una secuencia de comandos de compilación Android.mk, puedes omitir este paso.
  3. Configura Gradle proporcionando una ruta de acceso al archivo de secuencia de comandos CMake o ndk-build. Gradle usa la secuencia de comandos de compilación para importar el código fuente en el proyecto de Android Studio y para empaquetar la biblioteca nativa (el archivo del SO) en el APK.

Una vez que hayas configurado el proyecto, podrás acceder a las funciones nativas desde el código Java o Kotlin usando el marco de trabajo de JNI. Para crear y ejecutar la app, simplemente haz clic en Run ejecutar y luego ejecutar la app desde la barra de menú.

Nota: Si el proyecto existente utiliza la herramienta obsoleta ndkCompile, debes migrar a CMake o ndk-build. Para obtener más información, accede a la sección correspondiente en Cómo migrar desde ndkCompile.

Atención si eres usuario experimental de Gradle: Considera realizar la migración a la versión 2.2.0 del complemento o a una versión posterior, y usar CMake o ndk-build para compilar las bibliotecas nativas si se cumple alguna de las siguientes declaraciones: el proyecto nativo ya usa CMake o ndk-build; prefieres usar una versión estable del sistema de compilación de Gradle; o deseas tener compatibilidad con herramientas del complemento, como CCache. De lo contrario, puedes seguir usando la versión experimental de Gradle y el complemento de Android.

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

Si quieres compilar y depurar el código nativo de tu app, necesitarás 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, y que 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 que usa Android Studio para depurar código nativo.

Puedes instalar estos componentes con SDK Manager:

  1. En un proyecto abierto, selecciona Tools > SDK Manager de la barra de menú.
  2. Haz clic en la pestaña SDK Tools.
  3. Selecciona las casillas de verificación junto a LLDB, CMake y NDK, como se muestra en la figura 1.

    Figura 1: Instalación de LLDB, CMake y NDK desde SDK Manager

  4. Haz clic en Apply y, luego, en OK en el cuadro de diálogo emergente.
  5. Cuando finalice la instalación, haz clic en Finish y, luego, en OK.

Cómo usar CMake 3.6.0 o 3.10.2

SDK Manager incluye la versión bifurcada de CMake 3.6.0 y 3.10.2. Los proyectos en los que no se configura una versión específica de CMake en build.gradle se compilan con CMake 3.6.0. Para usar la versión que se incluye más adelante, especifica la versión 3.10.2 de CMake en el archivo build.gradle del módulo:

    android {
        ...
        externalNativeBuild {
            cmake {
                ...
                version "3.10.2"
            }
        }
    }
    
Si bien no es una práctica recomendada, puedes especificar la versión de CMake como la versión mínima si agregas el símbolo + al final de la entrada build.gradle, como 3.10+ o 3+.

Cómo usar una versión de CMake personalizada

Si deseas usar CMake 3.7 o una versión posterior que no se incluye en SDK Manager, sigue estos pasos:

  1. Descarga e instala CMake 3.7 o una versión posterior desde el sitio web oficial de CMake.
  2. Especifica la versión de CMake que desees que use Gradle en el archivo build.gradle del módulo:
        android {
            ...
            externalNativeBuild {
                cmake {
                    ...
                    version "cmake-version"
                }
            }
        }
        
  3. Agrega la ruta de acceso a la instalación de CMake de la variable de entorno PATH o inclúyela en el archivo local.properties del proyecto, como se muestra a continuación. Si Gradle no puede encontrar la versión de CMake que especificaste en el archivo build.gradle, se mostrará un error de compilación.
        # If you set this property, Gradle no longer uses PATH to find CMake.
        cmake.dir="path-to-cmake"
        
  4. Si aún no tienes instalado el sistema de compilación Ninja en la estación de trabajo, accede al sitio web oficial de Ninja y descarga e instala la versión más reciente de Ninja disponible para tu SO. Asegúrate de agregar también la ruta de instalación de Ninja a la variable de entorno PATH.

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

Crear un nuevo proyecto compatible para código nativo es similar s crear cualquier otro proyecto de Android Studio, aunque hay 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 de CMake predeterminada.
  6. Haz clic en Finish.

Después de que Android Studio haya terminado de crear el proyecto nuevo, abre el panel Project del lateral izquierdo del IDE y selecciona la vista Android. Como se muestra en la figura 2, Android Studio agrega el grupo cpp:

Figura 2: 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, pero agrupa archivos similares para simplificar la navegación por el proyecto.

El grupo cpp es el lugar donde puedes encontrar todos los archivos de fuente nativos, los encabezados, las secuencias de comandos de compilación para CMake o ndk-build y las bibliotecas ya compiladas que son parte del proyecto. Para proyectos nuevos, Android Studio crea un archivo de fuente de muestra C++, native-lib.cpp, y lo coloca en el directorio src/main/cpp/ del módulo de la app. Este código de muestra proporciona una función C++ simple, stringFromJNI(), que muestra la string "Hello from C++". Para obtener información sobre cómo 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 indican a Gradle cómo compilar la app, CMake y ndk-build requieren una secuencia de comandos de compilación para 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 coloca en el directorio raíz del módulo. Para 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 describen los eventos que tienen lugar para compilar y ejecutar la app de muestra:

  1. Gradle llama a la secuencia de compilación externa CMakeLists.txt.
  2. CMake sigue los comandos de la secuencia de comandos de compilación para compilar un archivo fuente C++, native-lib.cpp, en una biblioteca de objeto compartida y le asigna el nombre libnative-lib.so, que Gradle luego empaquetará en el APK.
  3. Durante el tiempo de ejecución, el objeto MainActivity de la app carga la biblioteca nativa 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.

Nota: Instant Run no es compatible con los componentes del proyecto escrito en el código nativo.

Para verificar si Gradle empaqueta la biblioteca nativa en el APK, puedes usar el Analizador de APK:

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

    Figura 3: Ubicación de una biblioteca nativa con el Analizador de APK

Sugerencia: Si quieres experimentar con otras apps de 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, haz lo siguiente:

  1. Si aún no tienes un directorio cpp/ en el conjunto principal de fuentes de la app, crea uno de la siguiente manera:
    1. Abre el panel Project en el lateral izquierdo del IDE y selecciona la vista Project del menú desplegable.
    2. Navega hasta your-module > src, haz clic con el botón derecho en el directorio main y selecciona New > Directory.
    3. 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 de origen, como native-lib.
  4. En el menú desplegable Type, selecciona la extensión de archivo del archivo fuente, como .cpp.
    • Puedes agregar otros tipos de archivos al menú desplegable, como .cxx o .hxx. Para ello, haz clic en Edit File Types. En el cuadro de diálogo C/C++ que aparece, selecciona otra extensión de archivo de los menús desplegables Source Extension y Header Extension, y haz clic en OK.
  5. Si también deseas crear un encabezado de archivo, selecciona la casilla de verificación Create an associated header.
  6. Haz clic en OK.

Después de agregar archivos C/C++ nuevos al proyecto, deberás configurar CMake para 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