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.

ndk/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.

ndk/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

ndk/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 <foo.h> 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 (<stdlib.h>, <stdio.h>, 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 (<pthread.h>),
+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 <linux/...> and <asm/...> 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:
+-----------------
+
+<math.h> 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:
+
+   <cstddef>
+   <new>
+   <utility>
+   <stl_pair.h>
+
+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:
+-----------------------------
+
+<android/log.h> 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:
+-------------------------
+
+<zlib.h> and <zconf.h> 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
+