1Android NDK Stable APIs: 2======================== 3 4This is the list of stable APIs/ABIs exposed by the Android NDK. 5 6I. Purpose: 7----------- 8 9Each API corresponds to a set of headers files, and a shared library file 10that contains the corresponding implementation, and which must be linked 11against by your native code. 12 13For example, to use system library "Foo", you would include a header 14like <foo.h> in your code, then tell the build system that your native 15module needs to link to /system/lib/libfoo.so at load-time by adding 16the following line to your Android.mk file: 17 18 LOCAL_LDLIBS := -lfoo 19 20Note that the build system automatically links the C library, the Math 21library and the C++ support library to your native code, there is no 22need to list them in a LOCAL_LDLIBS line. 23 24There are several "API Levels" defined. Each API level corresponds to 25a given Android system platform release. The following levels are 26currently supported: 27 28 android-3 -> Official Android 1.5 system images 29 android-4 -> Experimental Donut system images 30 31II. Android-3 Stable Native APIs: 32--------------------------------- 33 34All the APIs listed below are available for developing native code that 35runs on Android 1.5 system images and above. 36 37The C Library: 38-------------- 39 40The C library headers, as they are defined on Android 1.5 are available 41through their standard names (<stdlib.h>, <stdio.h>, etc...). If one header 42is not there at build time, it's because its implementation is not available 43on a 1.5 system image. 44 45The build system automatically links your native modules to the C library, 46you don't need to add it to LOCAL_LDLIBS. 47 48Note that the Android C library includes support for pthread (<pthread.h>), 49so "LOCAL_LIBS := -lpthread" is not needed. The same is true for real-time 50extensions (-lrt on typical Linux distributions). 51 52 53** VERY IMPORTANT NOTE: ****************************************************** 54* 55* The kernel-specific headers in <linux/...> and <asm/...> are not considered 56* stable at this point. Avoid including them directly because some of them 57* are likely to change in future releases of the platform. This is especially 58* true for anything related to specific hardware definitions. 59* 60****************************************************************************** 61 62 63The Math Library: 64----------------- 65 66<math.h> is available, and the math library is automatically linked to your 67native modules at build time, so there is no need to list "-lm" through 68LOCAL_LDLIBS. 69 70 71 72C++ Library: 73------------ 74 75An *extremely* minimal C++ support API is available. For Android 1.5, this is 76currently limited to the following headers: 77 78 <cstddef> 79 <new> 80 <utility> 81 <stl_pair.h> 82 83They may not contain all definitions required by the standard. Notably, 84support for C++ exceptions and RTTI is not available with Android 1.5 system 85images. 86 87The C++ support library (-lstdc++) is automatically linked to your native 88modules too, so there is no need to list it through LOCAL_LDLIBS 89 90 91 92Android-specific Log Support: 93----------------------------- 94 95<android/log.h> contains various definitions that can be used to send log 96messages to the kernel from your native code. Please have a look at its 97content in (build/platforms/android-3/common/include/android/log.h), which 98contain many informative comments on how to use it. 99 100You should be able to write helpful wrapper macros for your own usage to 101access this facility. 102 103If you use it, your native module should link to /system/lib/liblog.so with: 104 105 LOCAL_LDLIBS := -llog 106 107 108ZLib Compression Library: 109------------------------- 110 111<zlib.h> and <zconf.h> are available and can be used to use the ZLib 112compression library. Documentation for it is at the ZLib page: 113 114 http://www.zlib.net/manual.html 115 116If you use it, your native module should link to /system/lib/libz.so with: 117 118 LOCAL_LDLIBS := -lz 119 120 121III. Android-4 Stable Native APIs: 122---------------------------------- 123 124All the APIs listed below are available for developing native code that runs 125on the Donut experimental branch, which will be used to make the next official 126platform system images. 127 128 129The OpenGL ES 1.x Library: 130-------------------------- 131 132The standard OpenGL ES headers <GLES/gl.h> and <GLES/glext.h> contain the 133declarations needed to perform OpenGL ES 1.x rendering calls from native 134code. 135 136If you use them, your native module should link to /system/lib/libGLESv1_CM.so 137as in: 138 139 LOCAL_LDLIBS := -lGLESv1_CM.so 140 141Please note that, at the moment, native headers and libraries for the EGL APIs 142are *not* available. EGL is used to perform surface creation and flipping 143(instead of rendering). The corresponding operations must be performed in your 144VM application instead, for example with a GLSurfaceView, as described here: 145 146http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html 147 148The "san-angeles" sample application shows how you can do that, while 149rendering each frame in native code. This is a small Android port of the 150excellent "San Angeles Observation" demo program. For more information about 151it, see: 152 153 http://jet.ro/visuals/san-angeles-observation/ 154