ndk-samples README

The project's README from github.com/android/ndk-samples. As one markdown file: README.md.

Android NDK Samples

This repository contains sample apps that use the Android NDK.

For an explanation of the layout of this repository, see ARCHITECTURE.md.

Build and run

build

  1. Clone the repository
  2. Open the whole project in Android Studio
  3. Install CMake 4.1.0 via the SDK Manager (must be done manually until https://issuetracker.google.com/443137057 is fixed).
  4. Select the sample you want to run in the top bar (you may need to sync gradle first)
  5. Click the play button to run the sample

You can also build the samples from the command line if you prefer. Use ./gradlew build to build everything (if you're on Windows, use .\gradlew.bat instead of ./gradlew). For individual tasks, see ./gradlew tasks. To see the tasks for an individual sample, run the tasks task for that directory. For example, ./gradlew :camera:basic:tasks will show the tasks for the camera/basic app.

I just want something to copy from as a starting point

The samples in this repository are generally not a good starting point for a production quality app. They aim to demonstrate individual NDK APIs, but often make sacrifices to be succinct that make them unsuitable for a production app. This is gradually changing, but for now you should not do this.

Now in Android is an excellent resource for production quality apps in general, but does not touch on NDK- specific issues. https://github.com/DanAlbert/ndk-app-template can help some with that until this repository is able to.

You're most likely best served by using the New Project wizard in Android Studio to create a new app, then using those resources and the samples here as a reference. Android Studio's "Native C++" template is a good starting point for typical applications that need to use some C++ via JNI. The "Game Activity" template is a good starting point for game-like apps (that is, apps that do not use the Android UI, but instead render their own UI using OpenGL or Vulkan).

Best practices shown here

There are a few best practices shown throughout this repository that should be explained, but there's no central place to discuss those in the code, so we'll discuss those here.

RegisterNatives

We prefer using RegisterNatives() via JNI_OnLoad() over the name-based matching that Studio's New Project Wizard will typically create, e.g. JNI functions that follow the pattern JNIEXPORT void JNICALL Java_com_etc_ClassName_methodName(). That approach to matching C/C++ functions to their Java native function (or Kotlin external fun) makes for a shorter demo when there are only a small number of functions, but it has a number of disadvantages. See the JNI tips guide for details.

Version scripts

All of the app libraries shown here are built using a version script. This is a file that explicitly lists which symbols should be exported from the library, and hides all the others. Version scripts function similarly to -fvisibility=hidden, but can go a step further and are capable of hiding symbols in static libraries that are used by your app. Hiding as many symbols as possible results in smaller binaries that load faster, as there are fewer relocations required and LTO can do a better job. They also run faster as same-library function calls do not need to be made through the PLT. There are no good reasons to not use a version script for your NDK code. See the NDK documentation on controlling symbol visibility for more information.

You can find these in each sample as the lib<name>.map.txt file (where <name> is the name of the library passed to add_app_library() in the CMakeLists.txt file). The build plumbing that uses the version scripts is in the definition of add_app_library() in cmake/AppLibrary.cmake.

Additional documentation

Support

If you've found an issue with a sample and you know how to fix it, please send us a PR!.

If you need to report a bug, where it needs to be filed depends on the type of issue:

For questions about using the NDK or the platform APIs, you can ask on:

Additional NDK samples:

License

Copyright 2015 The Android Open Source Project, Inc.

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

LICENSE

ndk-samples (android/ndk-samples)

Searching Database…

10.5K ·GitHub
Ndk-samples
这是什么？这是一组 Android NDK 官方示例应用，每个示例都演示了如何在 Android Studio 项目中使用某个特定的原生（C++/JNI）API。
这是一个应用，还是一堆独立的示例项目？这是一个单一代码仓库，包含许多相互独立的示例应用（如相机、音频、游戏渲染等），每个示例都作为独立的 Gradle 模块/任务进行构建和运行。
怎样构建和运行示例？克隆代码仓库，在 Android Studio 中打开整个项目，通过 SDK Manager 安装 CMake 4.1.0，然后在顶部栏中选择一个示例，点击运行即可。你也可以使用 ./gradlew build 从命令行进行构建。
我需要安装特定版本的 CMake 吗？需要。在示例能够构建之前，必须先通过 Android Studio 的 SDK Manager 手动安装 CMake 4.1.0。
我能直接复制其中一个示例，作为自己应用的起点吗？不建议直接这样做：这些示例为了演示单一的 NDK API 而做了简化，省掉了生产环境所需的一些处理，因此并不适合用于正式产品。Android Studio 中的 'Native C++' 或 'Game Activity' 模板是更好的起点。
这些示例面向哪些人？需要通过 JNI 编写原生 C++ 代码的 Android 开发者（例如用于相机、音频，或基于 OpenGL/Vulkan 的游戏渲染），并且希望获得某个特定 NDK API 的参考实现。
什么是 RegisterNatives，为什么这些示例要使用它？RegisterNatives() 通过 JNIOnLoad() 调用，是将原生函数绑定到 Java/Kotlin 方法的首选方式，而不是依赖 Android Studio 基于名称的 JNI 匹配机制；后者在实际项目中存在多项弊端。
为什么每个示例都使用版本脚本？每个原生库都附带一个 .map.txt 版本脚本，明确列出导出的符号并隐藏其他所有符号，从而生成体积更小、加载更快、重定位更少的二进制文件。
除了这个仓库，还有其他 NDK 示例仓库吗？有。README 中链接了 Google Play Game Samples、Android Vulkan Tutorials、Android Vulkan API Basic Samples 和 Android High Performance Audio，它们同样是官方的 NDK 示例集。
What are similar projects?f8app, sunflower, Material-Animations, 3d-game-shaders-for-beginners, compose-samples, dolphin, Android-CleanArchitecture, imgui
Which topics is it in?sample-app, opengl, cmake, examples, vulkan, native, android-app, game-development, mobile-app, beginner-friendly, c++, java
Creator
android
Size
54 MB
Stars
10.5K
Updated
CommitSep 25
Age
11y
Commits · 90 Days