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. Ao criar seu projeto, esse código é compilado em uma biblioteca nativa que o Gradle pode empacotar com seu APK. O código Java ou Kotlin pode chamar funções na biblioteca nativa por meio da Java Native Interface (JNI, na sigla em inglês). 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:

Crie novos arquivos de origem nativos e adicione-os ao projeto do Android Studio.
- Você pode pular esta etapa se já tem o código nativo ou se quer importar uma biblioteca nativa pré-compilada.
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ê estiver importando e vinculado usando bibliotecas pré-compiladas 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.
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 .

Observação: se seu 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 posterior do plug-in e usar o CMake ou o ndk-build para compilar suas bibliotecas nativas poderá ser uma boa alternativa se seu projeto nativo já usa 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. 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, são necessários os seguintes componentes:

Android Native Development Kit (NDK, na sigla em inglês): 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 (link em inglês): 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 (link em inglês): 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.

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 criados com o CMake 3.10.2. Para usar a versão antiga incluída, especifique o CMake versão 3.6.0 no arquivo build.gradle do seu módulo:

    android {
        ...
        externalNativeBuild {
            cmake {
                ...
                version "3.6.0"
            }
        }
    }

Embora essa não seja uma prática recomendada, é possível especificar a versão do CMake como a versão mínima, adicionando um + ao final da entrada build.gradle, por exemplo, 3.10.2+.

Usar uma versão personalizada do CMake

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

Faça o download do CMake 3.7 ou mais recente no site oficial do CMake e instale-o.

Especifique a versão do CMake que você quer que o Gradle use no arquivo build.gradle do módulo:

    android {
        ...
        externalNativeBuild {
            cmake {
                ...
                version "cmake-version"
            }
        }
    }

Adicione o caminho para a instalação do CMake na variável de ambiente PATH ou inclua-o no arquivo local.properties do projeto, conforme mostrado abaixo. Se o Gradle não encontrar a versão do CMake especificada no 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"
    
```
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 (link em inglês), 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 ambiente PATH.

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:

Na seção Choose your project do assistente, selecione o tipo de projeto Native C++.
Clique em Next.
Preencha todos os campos na seção seguinte do assistente.
Clique em Next.
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.
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 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 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 amostra 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 compilar o 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 o coloca 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 , 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:

O Gradle chama o script de compilação externa, CMakeLists.txt.
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 APK.
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.
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 APK, você pode usar o APK Analyzer:

Selecione Build > Build Bundles(s) / APK(s) > Build APK(s).
Selecione Build > Analyze APK.
Selecione o APK no diretório app/build/outputs/apk/ e clique em OK.
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 C/C++ a um projeto existente, faça o seguinte:

Caso ainda não tenha um diretório cpp/ no conjunto de origem principal do app, crie um da seguinte maneira:

Abra o painel Project à esquerda do ambiente de desenvolvimento integrado e selecione a visualização Project no menu suspenso.
Navegue até your-module > src, clique com o botão direito do mouse no diretório main e selecione New > Directory.
Nomeie o diretório como cpp e clique em OK.

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

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

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.

Se você também quiser criar um arquivo principal, marque a caixa de seleção Create an associated header.

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

Create Hello-CMake with Android Studio, um codelab que mostra como usar o modelo do CMake do Android Studio para iniciar o desenvolvimento de projetos do Android NDK (em inglês).