From d1841595e13482e78c8e6e458926ce0ca0387504 Mon Sep 17 00:00:00 2001 From: David 'Digit' Turner Date: Mon, 1 Jun 2009 20:38:19 +0200 Subject: [PATCH] Add docs/STABLE-APIS.TXT which contains the list of exposed frozen APIs in the NDK. Also update README.TXT and docs/ANDROID-MK.TXT accordingly, to document the use of LOCAL_LDLIBS. --- README.TXT | 4 ++ docs/ANDROID-MK.TXT | 11 +++++ docs/STABLE-APIS.TXT | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 128 insertions(+) create mode 100644 docs/STABLE-APIS.TXT diff --git a/README.TXT b/README.TXT index 56299c6..fc4cdad 100644 --- a/README.TXT +++ b/README.TXT @@ -9,6 +9,10 @@ A high-level overview of the NDK's features and limitations can be found in docs/OVERVIEW.TXT. Please read this document as it contains crucial information for correct usage. +See docs/STABLE-APIS.TXT for the list of frozen binary APIs exposed by +this NDK, as well as the corresponding system image versions that support +them. + Before using the NDK, you will need to follow the steps described by docs/INSTALL.TXT which lists the NDK pre-requisites and the steps needed to set it up properly on your machine. diff --git a/docs/ANDROID-MK.TXT b/docs/ANDROID-MK.TXT index fb6bc8e..9ba5388 100644 --- a/docs/ANDROID-MK.TXT +++ b/docs/ANDROID-MK.TXT @@ -353,6 +353,17 @@ LOCAL_SHARED_LIBRARIES i.e. you should still add them to your application's required modules in your Application.mk +LOCAL_LDLIBS + The list of additional linker flags to be used when building your + module. This is useful to pass the name of specific system libraries + with the "-l" prefix. For example, the following will tell the linker + to generate a module that links to /system/lib/libz.so at load time: + + LOCAL_LDLIBS := -lz + + See docs/STABLE-APIS.TXT for the list of exposed system libraries you + can linked against with this NDK release. + LOCAL_ALLOW_UNDEFINED_SYMBOLS By default, any undefined reference encountered when trying to build a shared library will result in an "undefined symbol" error. This is a diff --git a/docs/STABLE-APIS.TXT b/docs/STABLE-APIS.TXT new file mode 100644 index 0000000..743d657 --- /dev/null +++ b/docs/STABLE-APIS.TXT @@ -0,0 +1,113 @@ +Android NDK Stable APIs: +======================== + +This is the list of stable APIs/ABIs exposed by the Android NDK. + +I. Purpose: +----------- + +Each API corresponds to a set of headers files, and a shared library file +that contains the corresponding implementation, and which must be linked +against by your native code. + +For example, to use system library "Foo", you would include a header +like in your code, then tell the build system that your native +module needs to link to /system/lib/libfoo.so at load-time by adding +the following line to your Android.mk file: + + LOCAL_LDLIBS := -lfoo + +Note that the build system automatically links the C library, the Math +library and the C++ support library to your native code, there is no +need to list them in a LOCAL_LDLIBS line. + + + +II. Android 1.5 Stable Native APIs: +----------------------------------- + +All the APIs listed below are available for developing native code that +runs on Android 1.5 system images and above. + +The C Library: +-------------- + +The C library headers, as they are defined on Android 1.5 are available +through their standard names (, , etc...). If one header +is not there at build time, it's because its implementation is not available +on a 1.5 system image. + +The build system automatically links your native modules to the C library, +you don't need to add it to LOCAL_LDLIBS. + +Note that the Android C library includes support for pthread (), +so "LOCAL_LIBS := -lpthread" is not needed. The same is true for real-time +extensions (-lrt on typical Linux distributions). + + +** VERY IMPORTANT NOTE: ****************************************************** +* +* The kernel-specific headers in and are not considered +* stable at this point. Avoid including them directly because some of them +* are likely to change in future releases of the platform. This is especially +* true for anything related to specific hardware definitions. +* +****************************************************************************** + + +The Math Library: +----------------- + + is available, and the math library is automatically linked to your +native modules at build time, so there is no need to list "-lm" through +LOCAL_LDLIBS. + + + +C++ Library: +------------ + +An *extremely* minimal C++ support API is available. For Android 1.5, this is +currently limited to the following headers: + + + + + + +They may not contain all definitions required by the standard. Notably, support +for C++ exceptions and RTTI is not available with Android 1.5 system images. + +The C++ support library (-lstdc++) is automatically linked to your native +modules too, so there is no need to list it through LOCAL_LDLIBS + + + +Android-specific Log Support: +----------------------------- + + contains various definitions that can be used to send log messages +to the kernel from your native code. Please have a look at its content in +(build/platforms/android-1.5/common/include/android/log.h), which contain many +informative comments on how to use it. + +You should be able to write helpful wrapper macros for your own usage to +access this facility. + +If you use it, your native module should link to /system/lib/liblog.so with: + + LOCAL_LDLIBS := -llog + + + +ZLib Compression Library: +------------------------- + + and are available and can be used to use the ZLib compression +library available on Android 1.5 system images. Documentation for it is available +on the ZLib page: http://www.zlib.net/manual.html + +If you use it, your native module should link to /system/lib/libz.so with: + + LOCAL_LDLIBS := -lz + -- 2.11.0