From 931974b4e371571a6a62aaa738658bd3c59958a2 Mon Sep 17 00:00:00 2001 From: Adarsh Fernando Date: Mon, 13 Jun 2016 20:33:27 -0700 Subject: [PATCH] Docs: Updated 'NDK Apps Linking to Platform Libraries' - updated compatibility with future platform releases - expanded on ways to dignose and debug Bug: 29215157 Change-Id: Ie63d024eac9914d4553419c734132696fb94d7e5 --- docs/html/preview/behavior-changes.jd | 356 +++++++++++++++++++++----- 1 file changed, 291 insertions(+), 65 deletions(-) diff --git a/docs/html/preview/behavior-changes.jd b/docs/html/preview/behavior-changes.jd index 66dce7a5d0bee..acdc490120b5d 100644 --- a/docs/html/preview/behavior-changes.jd +++ b/docs/html/preview/behavior-changes.jd @@ -370,70 +370,290 @@ see Sharing FilesNDK Apps Linking to Platform Libraries

- Android N includes namespace changes to prevent loading of non-public APIs. - If you use the NDK, you should only be using public APIs from the Android - platform. Using non-public APIs in the next official release of Android - can cause your app to crash. + Starting in Android N, the system prevents apps from dynamically linking + against non-NDK libraries, which may cause your app to crash. This change in + behavior aims to create a consistent app experience across platform updates + and different devices. Even though your code might not be linking against + private libraries, it's possible that a third-party static library in your + app could be doing so. Therefore, all developers should check to make sure + that their apps do not crash on devices running Android N. If your app uses + native code, you should only be using public NDK APIs.

- In order to alert you to use of non-public APIs, apps running on an Android N - device generate an error in logcat output when an app calls a non-public API. - This error is also displayed on the device screen as a message to help - raise awareness of this situation. You should review your app code to - remove use of non-public platform APIs and thoroughly test your apps using - a preview device or emulator. -

- -

- If your app depends on platform libraries, see the NDK documentation for - typical fixes for replacing common private APIs with public API equivalents. - You may also be linking to platform libraries without realizing it, - especially if your app uses a library that is part of the platform (such as - libpng), but is not part of the NDK. In that case, ensure that - your APK contains all the .so files you intended to link against. -

- -

- Caution: Some third-party libraries may link to non-public - APIs. If your app uses these libraries, your app may crash when running - on the next official release of Android. -

- -

- Apps should not depend on or use native libraries that are not included in - the NDK, because they may change, or be removed from one Android release to - another. The switch from OpenSSL to BoringSSL is an example of such a change. - Also, different devices may offer different levels of compatibility, because - there are no compatibility requirements for platform libraries not included - in the NDK. If you must access non-NDK libraries on older devices, make the - loading dependent on the Android API level. -

- -

- To help you diagnose these types problems here are some example Java and NDK - errors you might encounter when attempting to build your app with Android N: -

- -

Example Java error:

-
-java.lang.UnsatisfiedLinkError: dlopen failed: library "/system/lib/libcutils.so"
-    is not accessible for the namespace "classloader-namespace"
-
- -

Example NDK error:

-
-dlopen failed: cannot locate symbol "__system_property_get" referenced by ...
-
- - -

- Here are some typical fixes for apps encountering these types of errors: + There are three ways your app might be trying to access private platform + APIs:

+ +

+ Apps should not use native libraries that are not included in the NDK because + they may change or be removed between different versions of Android. The + switch from OpenSSL to BoringSSL is an example of such a change. Also, + because there are no compatibility requirements for platform libraries not + included in the NDK, different devices may offer different levels of + compatibility. +

+ +

+ In order to reduce the impact that this restriction may have on currently + released apps, a set of libraries that see significant use—such as + libandroid_runtime.so, libcutils.so, + libcrypto.so, and libssl.so—are temporarily + accessible on N for apps targeting API level 23 or lower. If your app loads + one of these libraries, logcat generates a warning and a toast appears on the + target device to notify you. If you see these warnings, you should update + your app to either include its own copy of those libraries or only use the + public NDK APIs. Future releases of the Android platform may restrict the use + of private libraries altogether and cause your app to crash. +

+ +

+ All apps generate a runtime error when they call an API that is neither + public nor temporarily accessible. The result is that + System.loadLibrary and dlopen(3) both return + NULL, and may cause your app to crash. You should review your + app code to remove use of private platform APIs and thoroughly test your apps + using a preview device or emulator. If you are unsure whether your app uses + private libraries, you can check logcat to identify + the runtime error. +

+ +

+ The following table describes the behavior you should expect to see from an + app depending on its use of private native libraries and its target API + level (android:targetSdkVersion). +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Libraries + + Target API level + + Runtime access via dynamic linker + + N Developer Preview behavior + + Final N Release behavior + + Future Android platform behavior +
+ NDK Public + + Any + + Accessible + + Works as expected + + Works as expected + + Works as expected +
+ Private (temporarily accessible private libraries) + + 23 or lower + + Temporarily accessible + + Works as expected, but you receive a logcat warning and a message on the + target device. + + Works as expected, but you receive a logcat warning. + + Runtime error +
+ Private (temporarily accessible private libraries) + + 24 or higher + + Restricted + + Runtime error + + Runtime error + + Runtime error +
+ Private (other) + + Any + + Restricted + + Runtime error + + Runtime error + + Runtime error +
+ +

+ Check if your app uses private libraries +

+ +

+ To help you identify issues loading private libraries, logcat may generate a + warning or runtime error. For example, if your app targets API level 23 or + lower, and tries to access a private library on a device running Android N, + you may see a warning similar to the following: +

+ +
+03-21 17:07:51.502 31234 31234 W linker  : library "libandroid_runtime.so"
+("/system/lib/libandroid_runtime.so") needed or dlopened by
+"/data/app/com.popular-app.android-2/lib/arm/libapplib.so" is not accessible
+for the namespace "classloader-namespace" - the access is temporarily granted
+as a workaround for http://b/26394120
+
+ +

+ These logcat warnings tell you which which library is trying to access a + private platform API, but will not cause your app to crash. If the app + targets API level 24 or higher, however, logcat generates the following + runtime error and your app may crash: +

+ +
+java.lang.UnsatisfiedLinkError: dlopen failed: library "libcutils.so"
+("/system/lib/libcutils.so") needed or dlopened by
+"/system/lib/libnativeloader.so" is not accessible for the namespace
+"classloader-namespace"
+  at java.lang.Runtime.loadLibrary0(Runtime.java:977)
+  at java.lang.System.loadLibrary(System.java:1602)
+
+ +

+ You may also see these logcat outputs if your app uses third-party libraries + that dynamically link to private platform APIs. The readelf tool in the + Android NDK allows you to generate a list of all dynamically linked shared + libraries of a given .so file by running the following command: +

+ +
+aarch64-linux-android-readelf -dW libMyLibrary.so
+
+ +

+ Update your app +

+ +

+ Here are some steps you can take to fix these types of errors and make + sure your app doesn't crash on future platform updates: +

+ +