1<html><body><pre> 2C++ support with the Android NDK 3================================ 4 5 6The Android platform provides a very minimal C++ runtime support library 7(/system/lib/libstdc++) and corresponding headers for it in the NDK. 8 9By default, this 'system' runtime does *not* provide the following: 10 11 - Standard C++ Library support (except a few trivial headers). 12 - C++ exceptions support 13 - RTTI support 14 15However, the NDK provides various "helper C++ runtimes" which can provide them, 16or a subset of these features. 17 18To select the runtime you want to use, define APP_STL inside your 19Application.mk to one of the following values: 20 21 system -> Use the default minimal system C++ runtime library. 22 gabi++_static -> Use the GAbi++ runtime as a static library. 23 gabi++_shared -> Use the GAbi++ runtime as a shared library. 24 stlport_static -> Use the STLport runtime as a static library. 25 stlport_shared -> Use the STLport runtime as a shared library. 26 gnustl_static -> Use the GNU STL as a static library. 27 gnustl_shared -> Use the GNU STL as a shared library. 28 29The 'system' runtime is the default if there is no APP_STL definition in 30your Application.mk. As an example, to use the static GNU STL, add a line like: 31 32 APP_STL := gnustl_static 33 34To your Application.mk. You can only select a single C++ runtime that all 35your code will depend on. It is not possible to mix shared libraries compiled 36against different C++ runtimes. 37 38IMPORTANT: Defining APP_STL in Android.mk has no effect! 39 40If you are not using the NDK build system, you can still use the GNU STL, 41see docs/STANDALONE-TOOLCHAIN.html for more details. 42 43The capabilities of the various runtimes vary. See this table: 44 45 C++ C++ Standard 46 Exceptions RTTI Library 47 48 system no no no 49 gabi++ no yes no 50 stlport no yes yes 51 gnustl yes yes yes 52 53 54I. Runtimes overview: 55--------------------- 56 57I.1. System runtime: 58- - - - - - - - - - - 59 60The system runtime only provides a very small number of C++ standard headers. 61 62This corresponds to the actual C++ runtime provided by the Android platform. 63If you use it, your C++ binaries will automatically be linked against the 64system libstdc++. 65 66The only headers provided here are the following: 67 68 cassert cctype cerrno cfloat climits cmath csetjmp csignal cstddef 69 cstdint cstdio cstdlib cstring ctime cwchar new stl_pair.h typeinfo 70 utility 71 72Anything else is _not_ supported, including std::string or std::vector. 73 74 75I.2. GAbi++ runtime: 76- - - - - - - - - - - 77 78This is a new minimalistic runtime that provides the same headers than 79the system one, with the addition of RTTI (RunTime Type Information) support. 80 81There is very little reason to use it right now, but it is planned to become 82the basis for STLport's exceptions+RTTI support in the future. 83 84If you insist on using it, read the "RTTI Support" and 85"Static runtime considerations" sections below. 86 87 88I.3. STLport runtime: 89- - - - - - - - - - - 90 91This is a port of STLport (http://www.stlport.org) that can be used on 92Android. It will provide you with a complete set of C++ standard library 93headers, however it ONLY SUPPORTS RTTI, AND NO EXCEPTIONS! 94 95That's because the library embeds its own copy of GAbi++. 96 97Available as both both static and shared libraries. To use it, use either 98one of these two lines in your Application.mk: 99 100 APP_STL := stlport_shared 101 APP_STL := stlport_static 102 103Note that 'stlport_shared' is preferred, for reasons explained in 104"Static runtime considerations". 105 106 107I.4. GNU STL runtime: 108- - - - - - - - - - - 109 110This is the GNU Standard C++ Library (a.k.a. libstdc++-v3), providing the 111more features. Note that the shared library file is named "libgnustl_shared.so" 112instead of "libstdc++.so" as on other platforms. 113 114If you want to use it, please read the "C++ Exceptions support", 115"RTTI Support" and "Static runtime considerations" sections below. 116 117 118 119II. Important Considerations: 120----------------------------- 121 122 123II.1. C++ Exceptions support: 124- - - - - - - - - - - - - - - 125 126The NDK toolchain supports C++ exceptions, since NDK r5, however all C++ 127sources are compiled with -fno-exceptions support by default, for 128compatibility reasons with previous releases. 129 130To enable it, use the new LOCAL_CPP_FEATURES variable in your Android.mk, 131as in: 132 133 LOCAL_CPP_FEATURES += exceptions 134 135See docs/ANDROID-MK.html for more details about this varibale. 136 137Another way to do the same is to define it in your LOCAL_CPPFLAGS definition 138(but using LOCAL_CPP_FEATURES is preferred), as in: 139 140 LOCAL_CPPFLAGS += -fexceptions 141 142More simply, add a single line to your Application.mk, the setting will 143automatically apply to all your project's NDK modules: 144 145 APP_CPPFLAGS += -fexceptions 146 147IMPORTANT: You *will* have to select a C++ runtime that supports 148 exceptions to be able to link / run your code. At this point 149 this means only 'gnustl_static' or "gnustl_shared'! 150 151 152II.2. RTTI support: 153- - - - - - - - - - 154 155Similarly, the NDK toolchain supports C++ RTTI (RunTime Type Information) 156since NDK r5, but all C++ sources are built with -fno-rtti by default for 157compatibility reasons. To enable it, add the following to your module 158declarations: 159 160 LOCAL_CPP_FEATURES += rtti 161 162This will be equivalent to: 163 164 LOCAL_CPPFLAGS += -frtti 165 166Or more simply to your Application.mk: 167 168 APP_CPPFLAGS += -frtti 169 170 171II.3. Static runtimes: 172- - - - - - - - - - - - 173 174Please keep in mind that the static library variant of a given C++ runtime 175SHALL ONLY BE LINKED INTO A SINGLE BINARY for optimal conditions. 176 177What this means is that if your project consists of a single shared 178library, you can link against, e.g., stlport_static, and everything will 179work correctly. 180 181On the other hand, if you have two shared libraries in your project 182(e.g. libfoo.so and libbar.so) which both link against the same static 183runtime, each one of them will include a copy of the runtime's code in 184its final binary image. This is problematic because certain global 185variables used/provided internally by the runtime are duplicated. 186 187This is likely to result in code that doesn't work correctly, for example: 188 189 - memory allocated in one library, and freed in the other would leak 190 or even corrupt the heap. 191 192 - exceptions raised in libfoo.so cannot be caught in libbar.so (and may 193 simply crash the program). 194 195 - the buffering of std::cout not working properly 196 197This problem also happens if you want to link an executable and a shared 198library to the same static library. 199 200In other words, if your project requires several shared library modules, 201then use the shared library variant of your C++ runtime. 202 203 204II.4. Shared runtimes: 205- - - - - - - - - - - - 206 207If you use the shared library variant of a given C++ runtime, keep in mind 208that you must load it before any library that depends on it when your 209application starts. 210 211As an example, let's consider the case where we have the following modules 212 213 libfoo.so 214 libbar.so which is used by libfoo.so 215 libstlport_shared.so, used by both libfoo and libbar 216 217You will need to load the libraries in reverse dependency order, as in: 218 219 static { 220 System.loadLibrary("libstlport_shared"); 221 System.loadLibrary("libbar"); 222 System.loadLibrary("libfoo"); 223 } 224 225 226III. EXTRAS: 227 228III.1. STLport-specific issues: 229------------------------------- 230 231This NDK provides prebuilt static and shared libraries for STLport, 232but you can force it to be rebuilt from sources by defining the following 233in your environment or your Application.mk before building: 234 235 STLPORT_FORCE_REBUILD := true 236 237STLport is licensed under a BSD-style open-source license. See 238sources/cxx-stl/stlport/README for more details about the library. 239 240 241III.2. GNU libstdc++ license is GPLv3 + linking exception! 242---------------------------------------------------------- 243 244Be aware that the GNU libstdc++ is covered by the GPLv3 license (and *not* 245the LGPLv2 or LGPLv3 as some assume), full details available here: 246 247 http://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html 248 249Be sure that you comply with all clauses of this license. 250 251 252IV. Future Plans: 253----------------- 254 255 - Add exceptions support to GAbi++ 256 - Add exceptions support to STLport (once it is in GAbi++) 257 - uSTL support? 258 259</pre></body></html> 260