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 -> Official Android 1.6 system images 30 android-5 -> Experimental Eclair system images 31 32II. Android-3 Stable Native APIs: 33--------------------------------- 34 35All the APIs listed below are available for developing native code that 36runs on Android 1.5 system images and above. 37 38The C Library: 39-------------- 40 41The C library headers, as they are defined on Android 1.5 are available 42through their standard names (<stdlib.h>, <stdio.h>, etc...). If one header 43is not there at build time, it's because its implementation is not available 44on a 1.5 system image. 45 46The build system automatically links your native modules to the C library, 47you don't need to add it to LOCAL_LDLIBS. 48 49Note that the Android C library includes support for pthread (<pthread.h>), 50so "LOCAL_LIBS := -lpthread" is not needed. The same is true for real-time 51extensions (-lrt on typical Linux distributions). 52 53 54** VERY IMPORTANT NOTE: ****************************************************** 55* 56* The kernel-specific headers in <linux/...> and <asm/...> are not considered 57* stable at this point. Avoid including them directly because some of them 58* are likely to change in future releases of the platform. This is especially 59* true for anything related to specific hardware definitions. 60* 61****************************************************************************** 62 63 64The Math Library: 65----------------- 66 67<math.h> is available, and the math library is automatically linked to your 68native modules at build time, so there is no need to list "-lm" through 69LOCAL_LDLIBS. 70 71 72 73C++ Library: 74------------ 75 76An *extremely* minimal C++ support API is available. For Android 1.5, this is 77currently limited to the following headers: 78 79 <cstddef> 80 <new> 81 <utility> 82 <stl_pair.h> 83 84They may not contain all definitions required by the standard. Notably, 85support for C++ exceptions and RTTI is not available with Android 1.5 system 86images. 87 88The C++ support library (-lstdc++) is automatically linked to your native 89modules too, so there is no need to list it through LOCAL_LDLIBS 90 91 92 93Android-specific Log Support: 94----------------------------- 95 96<android/log.h> contains various definitions that can be used to send log 97messages to the kernel from your native code. Please have a look at its 98content in (build/platforms/android-3/common/include/android/log.h), which 99contain many informative comments on how to use it. 100 101You should be able to write helpful wrapper macros for your own usage to 102access this facility. 103 104If you use it, your native module should link to /system/lib/liblog.so with: 105 106 LOCAL_LDLIBS := -llog 107 108 109ZLib Compression Library: 110------------------------- 111 112<zlib.h> and <zconf.h> are available and can be used to use the ZLib 113compression library. Documentation for it is at the ZLib page: 114 115 http://www.zlib.net/manual.html 116 117If you use it, your native module should link to /system/lib/libz.so with: 118 119 LOCAL_LDLIBS := -lz 120 121 122III. Android-4 Stable Native APIs: 123---------------------------------- 124 125All the APIs listed below are available for developing native code that runs 126on Android 1.6 system images and above, 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 155 156IV. Android-5 Stable Native APIs: 157---------------------------------- 158 159All the APIs listed below are available for developing native code that runs 160on the Eclair experimental branch, which will be used to make the next official 161platform system images. 162 163 164The OpenGL ES 2.0 Library: 165-------------------------- 166 167The standard OpenGL ES 2.0 headers <GLES2/gl2.h> and <GLES2/gl2ext.h> contain the 168declarations needed to perform OpenGL ES 2.0 rendering calls from native code. 169This includes the ability to define and use vertex and fragment shaders using the 170GLSL language. 171 172If you use them, your native module should link to /system/lib/libGLESv2.so 173as in: 174 175 LOCAL_LDLIBS := -lGLESv2.so 176 177Please note that, at the moment, native headers and libraries for the EGL APIs 178are *not* available. EGL is used to perform surface creation and flipping 179(instead of rendering). The corresponding operations must be performed in your 180VM application instead, for example with a GLSurfaceView, as described here: 181 182http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html 183 184The "hello-gl2" sample application demonstrate this. It is used to draw a very 185simple triangle with the help of a vertex and fragment shaders. 186