diff options
author | Dan Albert <danalbert@google.com> | 2019-05-14 11:03:17 -0700 |
---|---|---|
committer | Dan Albert <danalbert@google.com> | 2019-06-13 13:25:45 -0700 |
commit | a259034ada218f1abb0f1dc5da85a4dce5b9b76b (patch) | |
tree | d5bfe037d132d9f7d5f8ec1e97e556664304c91f /docs | |
parent | b949e2ac60619bf7d2a37f3d2c2a5f9ab679a05e (diff) | |
download | ndk-a259034ada218f1abb0f1dc5da85a4dce5b9b76b.tar.gz |
Document advice for middleware vendors.
Test: None
Bug: None
Change-Id: Ib00e73692ef57c6f0c23a2094f0cc28800c4b16a
Diffstat (limited to 'docs')
-rw-r--r-- | docs/user/middleware_vendors.md | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/docs/user/middleware_vendors.md b/docs/user/middleware_vendors.md new file mode 100644 index 000000000..e7ebcd952 --- /dev/null +++ b/docs/user/middleware_vendors.md @@ -0,0 +1,56 @@ +# Advice for Middleware Vendors + +Distributing middleware built with the NDK imposes some additional problems that +app developers do not need to worry about. Prebuilt libraries impose some of +their implementation choices on their users. + +## Choosing API levels and NDK versions + +Your users cannot use a `minSdkVersion` lower than yours. If your users' apps +need to run on Android 16, you cannot build for Android 21. + +NDK versions are largely compatible with each other, but occasionally there are +changes that break compatibility. If you know that all of your users are using +the same version of the NDK, it's best to use the same version that they do. +Otherwise, use the newest version. + +## Using the STL + +If you're writing C++ and using the STL, your choice between libc++_shared and +libc++_static affects your users if you distribute a shared library. If you +distribute a shared library, you must either use libc++_shared or ensure that +libc++'s symbols are not exposed by your library. The best way to do this is to +explicitly declare your ABI surface with a version script (this also helps keep +your implementation details private). For example, a simple arithmetic library +might have the following version script: + +Note: If you distribute a static library, it does not matter whether you choose +a static or shared STL because nothing is linked in a static library. The user +can link whichever they choose in their application. They must link *something*, +even for C-only consumers, so be sure to document that it is required and which +version of the NDK was used to build in case of incompatibility in STL versions. + +``` +LIBMYMATH { +global: + add; + sub; + mul; + div; + # C++ symbols in an extern block will be mangled automatically. See + # https://stackoverflow.com/a/21845178/632035 for more examples. + extern "C++" { + "pow(int, int)"; + } +local: + *; +}; +``` + +A version script should be the preferred option because it is the most robust +way to control symbol visibility. Another, less robust option is to use +`-Wl,--exclude-libs,libc++_static.a -Wl,--exclude-libs,libc++abi.a` when +linking. This is less robust because it will only hide the symbols in the +libraries that are explicitly named, and no diagnostics are reported for +libraries that are not used (a typo in the library name is not an error, and the +burden is on the user to keep the library list up to date). |