android/ndk-samples
1
0
Fork 0
mirror of https://github.com/android/ndk-samples synced 2025-11-05 23:20:53 +08:00
Code Issues Packages Projects Releases Wiki Activity

Point at DAC instead of duplicating docs.

Browse Source 
We have the more refined version of this information on DAC now.
This commit is contained in:
Dan Albert
2025-10-03 14:23:04 -07:00
committed by Dan Albert
parent 6906ad32da
commit 65e4ae2dae
1 changed files with 8 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
README.md
View File

@@ -51,40 +51,15 @@ discuss those here.
### `RegisterNatives` ### `RegisterNatives`
We prefer using `RegisterNatives` via `JNI_OnLoad` over the name-based matching We prefer using `RegisterNatives()` via `JNI_OnLoad()` over the name-based
that Studio's New Project Wizard will typically create, e.g. JNI functions that matching that Studio's New Project Wizard will typically create, e.g. JNI
follow the pattern `JNIEXPORT void JNICALL Java_com_etc_ClassName_methodName`. functions that follow the pattern `JNIEXPORT void JNICALL
That approach to matching C/C++ functions to their Java `native` function (or Java_com_etc_ClassName_methodName()`. That approach to matching C/C++ functions
Kotlin `external fun`) makes for a shorter demo when there are only a small to their Java `native` function (or Kotlin `external fun`) makes for a shorter
number of functions, but it has a number of disadvantages: demo when there are only a small number of functions, but it has a number of
disadvantages. See the [JNI tips] guide for details.
1. Mistakes are uncovered late. An incorrectly named function will not cause an [JNI tips]: https://developer.android.com/ndk/guides/jni-tips#native-libraries
error until called by Java, so it's easier to ship bugs if your testing does
not cover all JNI methods.
2. All JNI symbols must be exported, leading to more relocations, larger
binaries, and less effective link-time optimization (LTO).
3. The first call to a JNI function will be slower than subsequent calls, as the
Java call will first need to find a matching implementation.
4. If you want to rename the function in Java, you have to also rename the C/C++
function.
5. Android Studio cannot auto-fix typos in your native function names, although
it can auto-generate new ones.
Instead, most apps should use `RegisterNatives` via `JNI_OnLoad`. This performs
up-front registration of native methods with an explicit mapping. It takes a
little bit more up-front-work, but doing so counters all of the disadvantages
above:
1. Mistakes are caught early. An incorrectly named function will cause an error
during library load.
2. The only symbol that typically must be exported is `JNI_OnLoad`. Some use
cases may additionally need `ANativeActivty_OnCreate` or similar.
3. No lookup required for the first call to each native function, so performance
overhead is consistent.
4. The Java or C/C++ functions can be renamed at will, and only the map needs to
be updated to match.
5. Android Studio can warn you and auto-fix common mistakes in class names and
function signatures.
### Version scripts ### Version scripts