Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Antes de começar
Este guia presume que você já conheça bem os conceitos inerentes à programação nativa e
ao desenvolvimento para Android.
Introdução
Esta seção traz uma explicação de nível avançado sobre como o NDK funciona. O Android NDK é um conjunto de ferramentas que permitem incorporar C ou C++ (“código nativo”) em apps para Android. A capacidade de usar código nativo em apps para Android pode ser muito útil para desenvolvedores que querem:
portar apps entre plataformas;
reutilizar bibliotecas existentes ou fornecer as próprias para reutilização;
melhorar o desempenho em determinados casos, em especial nos de computação intensa,
como jogos.
Como funciona
Esta seção apresenta os principais componentes usados na criação de um app nativo para Android
e descreve o processo de compilação e
empacotamento.
Principais componentes
É necessário compreender os seguintes componentes durante a criação do seu
app:
Bibliotecas compartilhadas nativas: o NDK cria essas bibliotecas, ou arquivos .so, a
partir do código-fonte C/C++.
Bibliotecas estáticas nativas: o NDK também pode criar bibliotecas estáticas ou arquivos .a
que podem ser vinculados a outras bibliotecas.
Java Native Interface (JNI): a JNI é a interface de comunicação entre
os componentes Java e C++. Este guia requer conhecimentos sobre JNI.
Para mais informações sobre esse recurso, consulte a Especificação da Java Native Interface (link em inglês).
Interface Binária de App (ABI): a ABI define exatamente como deverá ser a
interação entre o código de máquina do app e o sistema no momento da execução. O NDK
compila arquivos .so de acordo com essas definições. Diferentes ABIs correspondem a
diferentes arquiteturas: o NDK é compatível com ABI para ARM de 32 bits, AArch64,
x86 e x86-64. Para mais informações, consulte ABIs
do Android.
O fluxo geral para desenvolver um app nativo para Android é o seguinte:
Projete o app e decida quais partes serão implementadas em Java e quais
em código nativo.
Crie um projeto de app Android normalmente.
Se você estiver criando um app sem componente Java, precisará declarar a classe NativeActivity no
AndroidManifest.xml. Para mais informações, consulte Atividades e apps
nativos.
Crie um arquivo Android.mk que descreva a biblioteca nativa, incluindo nome, sinalizações, bibliotecas
vinculadas e arquivos de origem a serem compilados no diretório
“JNI”.
Você também pode criar um arquivo Application.mk configurando as ABIs
de destino, conjuntos de ferramentas, modo de liberação/depuração e STL. Para qualquer um desses itens que você não
especificar, os valores padrão a seguir serão usados, respectivamente:
ABI: todas as ABIs não obsoletas
Modo: liberação
STL: system
Coloque o código-fonte nativo no diretório jni do projeto.
Use o ndk-build para compilar as bibliotecas nativas (.so, .a).
Crie o componente Java, produzindo o arquivo executável .dex.
Agrupe tudo em um arquivo APK, contendo .so, .dex e outros arquivos
necessários para a execução do app.
Atividades e aplicativos nativos
O Android SDK fornece uma classe auxiliar, NativeActivity, que permite
programar uma atividade completamente nativa. A NativeActivity lida com a comunicação
entre a estrutura do Android e seu código nativo para que você não precise criar uma
subclassificação nem chamar os métodos. Basta declarar o app como nativo no
arquivo AndroidManifest.xml e começar a
desenvolvê-lo.
Os apps Android que usam NativeActivity ainda podem ser executados na própria máquina
virtual, no sandbox de outros apps. Portanto, você ainda pode acessar
as APIs do framework do Android por meio do JNI. Porém, em certos casos, como para sensores,
eventos de entrada e recursos, o NDK fornece interfaces nativas que você pode usar
em vez de chamar o JNI. Para mais informações sobre essa compatibilidade, consulte
APIs nativas.
Independentemente de estar desenvolvendo ou não uma atividade nativa, recomendamos que você crie
projetos com as ferramentas de compilação tradicionais do Android. Isso
ajuda a garantir a compilação e o empacotamento de apps Android com a estrutura
correta.
O Android NDK fornece duas possibilidades para implementar atividades nativas:
O cabeçalho native_activity.h
define a versão nativa da classe NativeActivity. Ele contém a
interface de callback e as estruturas de dados necessárias para criar a atividade
nativa. Como a linha de execução principal do app lida com os callbacks,
suas implementações não podem gerar bloqueios. Se isso acontecer, você poderá receber
erros do tipo ANR (O app não está respondendo), porque a linha de execução principal não responderá até o retorno
do callback.
O arquivo android_native_app_glue.h define uma biblioteca auxiliar estática compilada sobre
a interface native_activity.h. Ele gera outra linha de execução, que
gerencia elementos como callbacks ou eventos de entrada em um loop de evento. Mover
esses eventos para uma linha de execução separada impede que qualquer callback bloqueie sua linha de execução principal.
A fonte <ndk_root>/sources/android/native_app_glue/android_native_app_glue.c
também está disponível, permitindo que você modifique a implementação.
Para mais informações sobre como usar essa biblioteca estática, veja o exemplo de app de
atividade nativa e a documentação correspondente. Para mais informações,
leia também os comentários
no arquivo
<ndk_root>/sources/android/native_app_glue/android_native_app_glue.h.
Usar a interface native_activity.h
Para implementar uma atividade nativa com a interface native_activity.h:
Crie um diretório jni/ no diretório raiz do projeto. Ele
vai armazenar todos os códigos nativos.
Declare sua atividade nativa no arquivo AndroidManifest.xml.
Como seu app não tem código em Java, defina android:hasCode como false.
O atributo android:value da tag meta-data especifica o nome da biblioteca compartilhada
que contém o ponto de entrada para o app (como main em C/C++), omitindo o
prefixo lib e o sufixo .so do nome da
biblioteca.
Crie um arquivo para a atividade nativa e implemente a função nomeada na
variável ANativeActivity_onCreate. O app chama essa função quando a
atividade nativa é iniciada. Essa função, análoga a main em C/C++, recebe
um ponteiro para uma estrutura NativeActivity, que contém ponteiros
de função para as diferentes implementações de callback que você precisa escrever. Defina os
ponteiros aplicáveis da função de callback em ANativeActivity->callbacks para
as implementações dos callbacks.
Defina o campo ANativeActivity->instance como o endereço de qualquer instância de
dados específicos que você quer usar.
Implemente tudo o que a atividade fará depois de iniciada.
Implemente os demais callbacks definidos em
ANativeActivity->callbacks. Para saber mais sobre quando os callbacks
são chamados, consulte Gerenciamento do ciclo de vida da atividade.
Desenvolva o restante do app.
Crie um Android.mk file no diretório jni/ do projeto para descrever seu
módulo nativo para o sistema de compilação. Para mais informações, consulte
Android.mk.
Depois de criar um arquivo Android.mk, compile seu código nativo usando o
comando ndk-build.
cd<path>/<to>/<project>
$NDK/ndk-build
Compile e instale seu projeto para Android normalmente. Se o código nativo estiver no
diretório jni/, o script de compilação empacotará automaticamente os
arquivos .so compilados a partir dele no APK.
Outra amostra de código
Para fazer o download de amostras do NDK, consulte Amostras do NDK (link em inglês).
O conteúdo e os exemplos de código nesta página estão sujeitos às licenças descritas na Licença de conteúdo. Java e OpenJDK são marcas registradas da Oracle e/ou suas afiliadas.
Última atualização 2025-07-27 UTC.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-07-27 UTC."],[],[],null,["# Concepts\n\nBefore you begin\n----------------\n\nThis guide assumes that you are already familiar with concepts inherent in\nnative programming and in [Android development](/develop).\n\nIntroduction\n------------\n\nThis section provides a high-level explanation of how the NDK works. The Android NDK is a set of\ntools allowing you to embed C or C++ (\"native code\") into your Android apps. The ability to use\nnative code in Android apps can be particularly useful to developers who wish to do one or more of\nthe following:\n\n- Port their apps between platforms.\n- Reuse existing libraries, or provide their own libraries for reuse.\n- Increase performance in certain cases, particularly computationally intensive ones like games.\n\nHow it works\n------------\n\nThis section introduces the main components used in building a native\napplication for Android, and goes on to describe the process of building and\npackaging.\n\n### Main components\n\nYou should have an understanding of the following components as you build your\napp:\n\n- Native shared libraries: The NDK builds these libraries, or `.so` files, from\n your C/C++ source code.\n\n- Native static libraries: The NDK can also build static libraries, or `.a`\n files, which you can link into other libraries.\n\n- Java Native Interface (JNI): The JNI is the interface via which the Java and\n C++ components talk to one another. This guide assumes knowledge of the JNI;\n for information about it, consult the [Java Native Interface Specification](http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html).\n\n- Application Binary Interface (ABI): The ABI defines exactly how your app's\n machine code is expected to interact with the system at runtime. The NDK\n builds `.so` files against these definitions. Different ABIs correspond to\n different architectures: The NDK includes ABI support for 32-bit ARM, AArch64,\n x86, and x86-64. For more information, see [Android\n ABIs](/ndk/guides/abis).\n\n- Manifest: If you are writing an app with no Java component to it, you must\n declare the [NativeActivity](/reference/android/app/NativeActivity) class in the\n [manifest](/guide/topics/manifest/manifest-intro). See [Use the\n native_activity.h interface](#na) for more detail on how to do this.\n\n### Flow\n\nThe general flow for developing a native app for Android is as follows:\n\n1. Design your app, deciding which parts to implement in Java, and which parts\n to implement as native code.\n\n | **Note:** While it is possible to completely avoid Java, you are likely to find the Android Java framework useful for tasks including controlling the display and UI.\n2. Create an Android app Project as you would for any other Android project.\n\n3. If you are writing a native-only app, declare the [NativeActivity](/reference/android/app/NativeActivity) class in\n `AndroidManifest.xml`. For more information, see the [Native activities and\n applications](#naa).\n\n4. Create an `Android.mk` file describing the native library, including name,\n flags, linked libraries, and source files to be compiled in the \"JNI\"\n directory.\n\n5. Optionally, you can create an `Application.mk` file configuring the target\n ABIs, toolchain, release/debug mode, and STL. For any of these that you do\n not specify, the following default values are used, respectively:\n\n - ABI: all non-deprecated ABIs\n - Mode: Release\n - STL: system\n6. Place your native source under the project's `jni` directory.\n\n7. Use ndk-build to compile the native (`.so`, `.a`) libraries.\n\n8. Build the Java component, producing the executable `.dex` file.\n\n9. Package everything into an APK file, containing `.so`, `.dex`, and other\n files needed for your app to run.\n\nNative activities and applications\n----------------------------------\n\nThe Android SDK provides a helper class, [NativeActivity](/reference/android/app/NativeActivity), that allows you to\nwrite a completely native activity. [NativeActivity](/reference/android/app/NativeActivity) handles the communication\nbetween the Android framework and your native code, so you do not have to\nsubclass it or call its methods. All you need to do is declare your application\nto be native in your `AndroidManifest.xml` file, and begin creating your native\napplication.\n\nAn Android application using [NativeActivity](/reference/android/app/NativeActivity) still runs in its own virtual\nmachine, sandboxed from other applications. You can therefore still access\nAndroid framework APIs through the JNI. In certain cases, such as for sensors,\ninput events, and assets, the NDK provides native interfaces that you can use\ninstead of having to call across the JNI. For more information about such\nsupport, see [Native APIs](/ndk/guides/stable_apis).\n\nRegardless of whether or not you are developing a native activity, we recommend\nthat you create your projects with the traditional Android build tools. Doing so\nhelps ensure building and packaging of Android applications with the correct\nstructure.\n\nThe Android NDK provides you with two choices to implement your native activity:\n\n- The [native_activity.h](/ndk/reference/native__activity_8h) header defines the native version of the [NativeActivity](/reference/android/app/NativeActivity) class. It contains the callback interface and data structures that you need to create your native activity. Because the main thread of your application handles the callbacks, your callback implementations must not be blocking. If they block, you might receive ANR (Application Not Responding) errors because your main thread is unresponsive until the callback returns.\n- The `android_native_app_glue.h` file defines a static helper library built on top of the [native_activity.h](/ndk/reference/native__activity_8h) interface. It spawns another thread, which handles things such as callbacks or input events in an event loop. Moving these events to a separate thread prevents any callbacks from blocking your main thread.\n\nThe `\u003cndk_root\u003e/sources/android/native_app_glue/android_native_app_glue.c`\nsource is also available, allowing you to modify the implementation.\n\nFor more information on how to use this static library, examine the\nnative-activity sample application and its documentation. Further reading is\nalso available in the comments in the\n`\u003cndk_root\u003e/sources/android/native_app_glue/android_native_app_glue.h`\nfile.\n\n### Use the native_activity.h interface\n\nTo implement a native activity with the [native_activity.h](/ndk/reference/native__activity_8h) interface:\n\n1. Create a `jni/` directory in your project's root directory. This directory\n stores all of your native code.\n\n2. Declare your native activity in the `AndroidManifest.xml` file.\n\n Because your application has no Java code, set `android:hasCode` to `false`. \n\n \u003capplication android:label=\"@string/app_name\" android:hasCode=\"false\"\u003e\n\n You must set the `android:name` attribute of the activity tag to\n [NativeActivity](/reference/android/app/NativeActivity). \n\n \u003cactivity android:name=\"android.app.NativeActivity\"\n android:label=\"@string/app_name\"\u003e\n\n | **Note:** You can subclass [NativeActivity](/reference/android/app/NativeActivity). If you do, use the name of the subclass instead of [NativeActivity](/reference/android/app/NativeActivity).\n\n The `android:value` attribute of the `meta-data` tag specifies the name of\n the shared library containing the entry point to the application (such as\n C/C++ `main`), omitting the `lib` prefix and `.so` suffix from the library\n name. \n\n \u003cmanifest\u003e\n \u003capplication\u003e\n \u003cactivity\u003e\n \u003cmeta-data android:name=\"android.app.lib_name\"\n android:value=\"native-activity\" /\u003e\n \u003cintent-filter\u003e\n \u003caction android:name=\"android.intent.action.MAIN\" /\u003e\n \u003ccategory android:name=\"android.intent.category.LAUNCHER\" /\u003e\n \u003c/intent-filter\u003e\n \u003c/activity\u003e\n \u003c/application\u003e\n \u003c/manifest\u003e\n\n3. Create a file for your native activity, and implement the function named in\n the [ANativeActivity_onCreate](/ndk/reference/group___native_activity#ga02791d0d490839055169f39fdc905c5e) variable. The app calls this function when the\n native activity starts. This function, analogous to `main` in C/C++, receives\n a pointer to an [ANativeActivity](/ndk/reference/struct_a_native_activity) structure, which contains function pointers\n to the various callback implementations that you need to write. Set the\n applicable callback function pointers in `ANativeActivity-\u003ecallbacks` to\n the implementations of your callbacks.\n\n4. Set the `ANativeActivity-\u003einstance` field to the address of any instance of\n specific data that you want to use.\n\n5. Implement anything else that you want your activity to do upon starting.\n\n6. Implement the rest of the callbacks that you set in\n `ANativeActivity-\u003ecallbacks`. For more information on when the callbacks are\n called, see [Managing the Activity Lifecycle](/training/basics/activity-lifecycle).\n\n7. Develop the rest of your application.\n\n8. Create an `Android.mk file` in the `jni/` directory of your project to\n describe your native module to the build system. For more information, see\n [Android.mk](/ndk/guides/android_mk).\n\n9. Once you have an [Android.mk](/ndk/guides/android_mk) file, compile your native code using the\n `ndk-build` command.\n\n cd \u003cpath\u003e/\u003cto\u003e/\u003cproject\u003e\n $NDK/ndk-build\n\n10. Build and install your Android project as usual. If your native code is in\n the `jni/` directory, the build script automatically packages the `.so`\n file(s) built from it into the APK.\n\nAdditional sample code\n----------------------\n\nTo download NDK samples, see [NDK Samples](https://github.com/android/ndk-samples)."]]
