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 APK. Depois disso, seu código Java ou Kotlin pode chamar funções na sua biblioteca nativa através da Java Native Interface (JNI). Para saber mais sobre como usar o framework da JNI, leia Dicas da JNI no 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 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, você precisará seguir estas etapas:

  1. Crie novos arquivos de origem nativos e adicione-os ao projeto do Android Studio.
    • Você pode pular esta etapa se já tiver o código nativo ou se quiser importar uma biblioteca nativa pré-compilada.
  2. Configure o CMake para compilar 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é-compiladas ou da plataforma.
    • Se você tiver uma biblioteca nativa que já tem um script de compilação CMakeLists.txt ou usar o ndk-build e incluir um script de compilação Android.mk, você poderá ignorar esta etapa.
  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 APK.

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

Observação: se seu projeto existente usa a ferramenta obsoleta ndkCompile, faça a migração para o uso de CMake ou ndk-build. Para saber mais, acesse a seção sobre como Migrar do ndkCompile.

Atenção, usuários experimentais do Gradle: migrar para a versão 2.2.0 ou posterior do plug-in e usar o CMake ou o ndk-build para compilar suas bibliotecas nativas poderá ser uma boa alternativa se qualquer uma destas situações se aplicar a você: seu projeto nativo já usa o CMake ou o ndk-build; você prefere uma versão estável do sistema de compilação Gradle; ou você quer compatibilidade para ferramentas complementares, como o CCache. Caso contrário, você pode continuar usando a versão experimental do Gradle e o plug-in do Android.

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 compilar bibliotecas nativas. 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.

É possível instalar esses componentes usando o SDK Manager:

  1. Em um projeto aberto, selecione Tools > SDK Manager na barra de menus.
  2. Clique na guia SDK Tools.
  3. Marque as caixas ao lado de LLDB, CMake e NDK, conforme mostrado na figura 1.

    Figura 1. Instalação do LLDB, CMake e NDK a partir do SDK Manager.

  4. Clique em Apply e em seguida em OK na caixa de diálogo pop-up.
  5. Após a instalação, clique em Finish e em OK.

Usar o CMake 3.6.0 ou 3.10.2

O SDK Manager inclui a versão bifurcada 3.6.0 do CMake, além da versão 3.10.2. Os projetos que não definem uma versão específica do CMake no build.gradle são compilados com o CMake 3.6.0. Para usar a versão mais recente, especifique a versão 3.10.2 do CMake no arquivo build.gradle do seu módulo:

    android {
        ...
        externalNativeBuild {
            cmake {
                ...
                version "3.10.2"
            }
        }
    }
    
Embora não seja uma prática recomendada, você pode especificar a versão do CMake como a versão mínima adicionando um + ao final da entrada no build.gradle, como 3.10+ ou 3+.

Usar uma versão personalizada do CMake

Se você quiser usar o CMake em versão 3.7 ou posterior não incluída pelo SDK Manager, siga estas etapas:

  1. Faça o download do CMake 3.7 ou posterior no site oficial do CMake e instale-o.
  2. Especifique a versão que você quer que o Gradle use no arquivo build.gradle do seu módulo:
        android {
            ...
            externalNativeBuild {
                cmake {
                    ...
                    version "cmake-version"
                }
            }
        }
        
  3. Adicione o caminho para a instalação do CMake na variável de ambientes PATH ou inclua-o no arquivo local.properties do projeto, conforme mostrado abaixo. Se o Gradle não encontrar seu arquivo build.gradle, você receberá um erro de compilação.
        # If you set this property, Gradle no longer uses PATH to find CMake.
        cmake.dir="path-to-cmake"
        
  4. Se você ainda não tem o sistema de compilação Ninja instalado na sua estação de trabalho, acesse o site oficial do Ninja, faça o download da versão mais recente disponível para seu sistema operacional e instale-a. Não se esqueça de adicionar o caminho para a instalação do Ninja na sua variável de ambientes PATH.

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

Criar um novo projeto compatível com código nativo é parecido com 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 Next.
  3. Preencha todos os campos na seção seguinte do assistente.
  4. Clique em Next.
  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. A seleção de Toolchain Default usa a configuração padrão do CMake.
  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. Como 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 compilação 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 nd-kbuild e bibliotecas pré-compiladas que fazem parte do projeto. Para novos projetos, o Android Studio cria um arquivo de origem C++ de amostra, native-lib.cpp, e o coloca no diretório src/main/cpp/ do módulo do app. Esse código de exemplo oferece uma função C++ simples, stringFromJNI(), que retorna a string "Hello from C++". Você pode aprender 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 informam ao Gradle como compilar um app, o CMake e o ndk-build precisam de um script de compilação para saber como compilar a biblioteca nativa. Para novos projetos, o Android Studio cria um script de compilação do CMake, CMakeLists.txt, e coloca-o no diretório raiz do módulo. Para saber mais sobre o conteúdo desse script de compilação, leia Configurar o CMake.

Criar e executar o aplicativo de amostra

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 compilação externa CMakeLists.txt.
  2. O CMake segue os comandos no script de compilação para compilar um arquivo de origem C++, native-lib.cpp, para uma biblioteca de objetos compartilhada com o nome libnative-lib.so, que o Gradle empacota no APK.
  3. Durante o tempo de execução, o MainActivity do app carrega a biblioteca nativa usando System.loadLibrary(). Depois disso, a função nativa da biblioteca stringFromJNI() estará disponível para o app.
  4. MainActivity.onCreate() chama stringFromJNI(), que retorna "Hello from C++" e o usa para atualizar TextView.

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

Se você quiser verificar se o Gradle empacota a biblioteca nativa no APK, 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 no diretório app/build/outputs/apk/ e clique em OK.
  4. Como mostrado na figura 3, você poderá 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. Se você ainda não tiver um diretório cpp/ no conjunto principal de origem do seu app, crie um da seguinte maneira:
    1. Abra o painel Project à esquerda do ambiente de desenvolvimento integrado e selecione a visualização Project no menu suspenso.
    2. Navegue até seu-módulo > src, clique com o botão direito no diretório main e selecione New > Directory.
    3. Insira cpp como nome do diretório e clique em OK.

  2. Clique com o botão direito no diretório cpp/ e selecione New > C/C++ Source File.
  3. Insira 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++ do pop-up, selecione outra extensão de arquivo dos menus suspensos Source Extension e Header Extension e clique em OK.
  5. Se você também quiser criar um arquivo de cabeçalho, 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 inclui-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