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

Você pode adicionar códigos 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 é compatível com o CMake, que é bom para projetos multiplataforma, e com o ndk-build, que pode ser mais rápido do que o CMake, mas é compatível apenas com o Android. No momento, não é possível usar o CMake e o ndk-build no mesmo módulo.

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

Esta página mostra como configurar o Android Studio com as ferramentas de compilação necessárias, criar um novo projeto compatível com C/C++ e adicionar novos arquivos C/C++ ao seu projeto.

Se, em vez disso, você quiser adicionar código nativo a um projeto existente, será necessário seguir estas etapas:

  1. Crie novos arquivos de origem nativos e adicione-os ao projeto do Android Studio.
    • Você poderá pular essa etapa se já tiver o código nativo ou se quiser importar uma biblioteca nativa pré-criada.
  2. Configure o CMake para criar seu código-fonte nativo em uma biblioteca. Esse script de compilação também será necessário se você importar e vincular usando bibliotecas pré-criadas ou da plataforma.
    • Você pode pular essa etapa caso tenha uma biblioteca nativa existente que já tenha um script de compilação CMakeLists.txt ou que use o ndk-build e inclua um script de compilação Android.mk.
  3. Configure o Gradle fornecendo um caminho para seu arquivo de script CMake ou ndk-build. O Gradle usa o script de compilação para importar código-fonte para o projeto do Android Studio e empacotar sua biblioteca nativa (o arquivo de SO) no app.

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

Observação: se o projeto existente usar a ferramenta obsoleta ndkCompile, será necessário fazer a migração usando o CMake ou o ndk-build. Para saber mais, vá para a seção sobre como Migrar do ndkCompile.

Atenção, usuário experimental do Gradle: migrar para a versão 2.2.0 ou mais recente do plug-in e usar o CMake ou o ndk-build para criar suas bibliotecas nativas pode ser uma boa alternativa caso seu projeto nativo já use o CMake ou o ndk-build, se você prefere uma versão estável do sistema de compilação Gradle ou se quer compatibilidade para ferramentas complementares, como o CCache (links em inglês). Caso contrário, você pode continuar usando a versão experimental do Gradle e o plug-in do Android (link em inglês).

Fazer o download do NDK e das ferramentas de compilação

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

  • Android Native Development Kit (NDK): um conjunto de ferramentas que permite usar código C e C++ com o Android, além de oferecer bibliotecas da plataforma para gerenciar atividades nativas e acessar componentes de dispositivos físicos, como sensores e entrada por toque.
  • CMake: uma ferramenta de compilação externa que funciona com o Gradle para criar sua biblioteca nativa. Esse componente não é necessário se você pretende usar apenas o ndk-build.
  • LLDB: o depurador usado pelo Android Studio para depurar códigos nativos.

Para ver informações sobre como instalar esses componentes, consulte Instalar e configurar o NDK, o CMake e o LLDB.

Criar um novo projeto compatível com C/C++

Criar um novo projeto compatível com código nativo é semelhante a criar qualquer outro projeto do Android Studio, mas há 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 concluir a criação do novo projeto, abra o painel Project à esquerda do ambiente de desenvolvimento integrado e selecione a visualização Android. Conforme mostrado na figura 2, o Android Studio adiciona o grupo cpp:

Figura 2. 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 compilação 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 amostra, native-lib.cpp, e coloca esse arquivo no diretório src/main/cpp/ do módulo do app. Esse código de exemplo fornece uma função C++ simples, stringFromJNI(), que retorna a string "Hello from C++". Você pode aprender a adicionar outros arquivos de origem ao projeto na seção sobre como Criar novos arquivos de origem nativos.

Da mesma forma que os arquivos build.gradle informam ao Gradle como criar o app, o CMake e o ndk-build precisam de um build script para saber como criar a 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 compila 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 compilação e execução do app de amostra:

  1. O Gradle chama o script de build externo, CMakeLists.txt.
  2. O CMake segue os comandos no script de compilação 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. Durante o tempo 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 usa para atualizar TextView.

Observação: o Instant Run não é compatível com componentes de projeto programados em código nativo.

Para confirmar se o Gradle empacota a biblioteca nativa no app, você pode usar 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 3, é possível ver libnative-lib.so na janela do APK Analyzer em lib/<ABI>/.

    Figura 3. Localização de 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 projeto de amostra 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, crie um da seguinte maneira:
    1. Abra o painel Project no lado esquerdo do ambiente de desenvolvimento integrado e selecione a visualização Project no menu suspenso.
    2. Navegue até your-module > src, clique com o botão direito do mouse no diretório main e selecione New > Directory.
    3. 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 suspenso Type, selecione a extensão de arquivo do arquivo de origem, como .cpp.
    • Para adicionar outros tipos de arquivo ao menu suspenso, como .cxx ou .hxx, clique em Edit File Types . Na caixa de diálogo C/C++ que é exibida, selecione outra extensão de arquivo nos menus suspensos Source Extension e Header Extension e clique em OK.

  5. Se você também quiser 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 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