Adicionar código C e C++ ao seu projeto

Adicione código C e C++ ao seu projeto do Android inserindo o código em um diretório cpp no módulo do projeto. Quando você cria o projeto, esse código é compilado em uma biblioteca nativa que o Gradle pode empacotar com seu app. Depois disso, seu código Java ou Kotlin pode chamar funções na sua biblioteca nativa pela Java Native Interface (JNI). Para saber mais sobre como usar o framework da JNI, leia Dicas de JNI para Android.

O Android Studio oferece suporte ao CMake, que é útil para projetos multiplataforma. O Android Studio também oferece suporte a ndk-build, que pode ser mais rápido que o CMake, mas só pode ser usado com o Android. No momento, não é possível usar o CMake e o ndk-build no mesmo módulo.

Para importar uma biblioteca ndk-build já existente para o projeto do Android Studio, aprenda a vincular o Gradle ao seu projeto de biblioteca nativa.

Esta página mostra como configurar o Android Studio com as ferramentas de build necessárias, criar um novo projeto com suporte a C/C++ e adicionar novos arquivos C/C++ ao seu projeto.

Se você quiser adicionar código nativo a um projeto existente, siga estas etapas:

  1. Crie novos arquivos de origem nativos e adicione os arquivos ao projeto do Android Studio.
    • Pule esta etapa se você já tiver o código nativo ou quiser importar uma biblioteca nativa pré-criada.
  2. Configure o CMake para criar seu código-fonte nativo em uma biblioteca. Esse script de build será necessário se você importar e vincular usando bibliotecas pré-criadas ou da plataforma.
    • Se você tiver uma biblioteca nativa que já tem um script de build CMakeLists.txt ou usa ndk-build e inclui um script de build Android.mk, pule esta etapa.
  3. Configure o Gradle fornecendo um caminho para seu arquivo de script CMake ou ndk-build. O Gradle usa o script de build para importar código-fonte para o projeto do Android Studio e empacotar sua biblioteca nativa no app.

Após configurar o projeto, acesse as funções nativas no código Java ou Kotlin usando o framework JNI. Para criar e executar seu app, clique em Run executar e depois executar aplicativo da barra de menus.

Observação: se o projeto existente usar a ferramenta descontinuada ndkCompile, migre para o CMake ou o ndk-build.

Fazer o download do NDK e das ferramentas de build

Para compilar e depurar código nativo para um app, os seguintes componentes são necessários:

  • Kit de desenvolvimento nativo do Android (NDK, na sigla em inglês): um conjunto de ferramentas que permite usar código C e C++ com o Android. O NDK fornece bibliotecas de plataforma que permitem gerenciar atividades nativas e acessar componentes físicos do dispositivo, como sensores e entrada por toque.
  • CMake: uma ferramenta de build externa que funciona com o Gradle para criar bibliotecas nativas. Esse componente não é necessário se você pretende usar apenas ndk-build.
  • LLDB: o depurador no Android Studio que depura código nativo.

Para saber mais sobre como instalar esses componentes, consulte Instalar e configurar o NDK e o CMake.

Criar um novo projeto com suporte a C/C++

Para criar um novo projeto que ofereça suporte a código nativo, o processo é parecido com a criação de qualquer outro projeto do Android Studio, mas com uma etapa a mais:

  1. Na seção Choose your project do assistente, selecione o tipo de projeto Native C++.
  2. Clique em Próxima.
  3. Preencha todos os campos na seção seguinte do assistente.
  4. Clique em Próxima.
  5. Na seção Customize C++ Support do assistente, você pode personalizar o projeto com o campo C++ Standard.
    • Use a lista suspensa para selecionar qual padronização do C++ você quer usar. Quando Toolchain Default é selecionado, a configuração padrão do CMake é utilizada.
  6. Clique em Finish.

Depois que o Android Studio terminar de criar o novo projeto, abra o painel Project à esquerda do ambiente de desenvolvimento integrado e selecione a visualização Android no menu. Conforme mostrado na Figura 1, o Android Studio adiciona o grupo cpp:

Figura 1. Grupos de visualização do Android para códigos nativos e scripts de build externos.

Observação: essa visualização não reflete a hierarquia de arquivos real no disco, mas agrupa arquivos semelhantes para simplificar a navegação no projeto.

O grupo cpp é onde você pode encontrar todos os arquivos de origem nativos, cabeçalhos, scripts de build do CMake ou ndk-build e bibliotecas pré-criadas que fazem parte do projeto. Para projetos novos, o Android Studio cria um arquivo de origem C++ de exemplo, native-lib.cpp, e coloca esse arquivo no diretório src/main/cpp/ do módulo do app. Este exemplo de código fornece uma função C++ simples, stringFromJNI(), que retorna a string "Hello from C++". Aprenda a adicionar mais arquivos de origem ao projeto na seção sobre como Criar novos arquivos de origem nativos.

Da mesma forma que os arquivos build.gradle instruem o Gradle a criar seu app, o CMake e o ndk-build exigem um script de build para saber como criar sua biblioteca nativa. Para novos projetos, o Android Studio cria um script de build do CMake, CMakeLists.txt, e o coloca no diretório raiz do módulo. Para saber mais sobre o conteúdo desse script de build, leia Configurar o CMake.

Criar e executar o aplicativo de exemplo

Ao clicar em Run executar e depois executar aplicativo da barra de menus, o Android Studio cria e inicia um app que exibe o texto "Hello from C++" no dispositivo ou emulador Android. A visão geral a seguir descreve os eventos que podem ocorrer na criação e execução do app de exemplo:

  1. O Gradle chama o script de build externo, CMakeLists.txt.
  2. O CMake segue os comandos no script de build para criar um arquivo de origem C++, native-lib.cpp, em uma biblioteca de objetos compartilhada com o nome libnative-lib.so, que o Gradle empacota no app.
  3. No momento de execução, a MainActivity do app carrega a biblioteca nativa usando System.loadLibrary(). A função nativa da biblioteca, stringFromJNI(), agora está disponível para o app.
  4. MainActivity.onCreate() chama stringFromJNI(), que retorna "Hello from C++" e o usa para atualizar o TextView.

Para confirmar se o Gradle empacota a biblioteca nativa no app, use o APK Analyzer:

  1. Selecione Build > Build Bundles(s)/APK(s) > Build APK(s).
  2. Selecione Build > Analyze APK.
  3. Selecione o APK ou o AAB no diretório app/build/outputs/ e clique em OK.
  4. Conforme mostrado na Figura 2, é possível observar libnative-lib.so na janela do APK Analyzer em lib/<ABI>/.

    Figura 2. Localizar uma biblioteca nativa usando o APK Analyzer.

Dica: se você quiser fazer experimentos com outros apps Android que usam código nativo, clique em File > New > Import Sample e selecione um exemplo de projeto na lista Ndk.

Criar novos arquivos de origem C/C++

Para adicionar novos arquivos de origem a um projeto existente, faça o seguinte:

  1. Caso ainda não tenha um diretório cpp/ no conjunto de origem principal do app, siga estas etapas para criar um:
    1. Abra o painel Project à esquerda do ambiente de desenvolvimento integrado e selecione a visualização Project no menu.
    2. Acesse your-module > src.
    3. Clique com o botão direito do mouse no diretório main e selecione New > Directory.
    4. Nomeie o diretório como cpp e clique em OK.

  2. Clique com o botão direito do mouse no diretório cpp/ e selecione New > C/C++ Source File.

  3. Digite um nome para o arquivo de origem, como native-lib.

  4. No menu Type, selecione a extensão do arquivo de origem, como .cpp.
    • Clique em Edit File Types para adicionar outros tipos de arquivos ao menu, como .cxx ou .hxx. Na caixa de diálogo New File Extensions, selecione outra extensão de arquivo nos menus Source Extension e Header Extension e clique em OK.

  5. Para criar um arquivo principal, marque a caixa de seleção Create an associated header.

  6. Clique em OK.

Depois de adicionar novos arquivos C/C++ ao projeto, você ainda vai precisar configurar o CMake para incluí-los na biblioteca nativa.

Outros recursos

Para saber mais sobre compatibilidade com o código C/C++ no seu app, experimente o recurso a seguir.

Codelabs