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++ yes yes no 50 stlport yes 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) and 80exception handling support. 81 82If you insist on using it, read the "RTTI Support" and 83"Static runtime considerations" sections below. 84 85 86I.3. STLport runtime: 87- - - - - - - - - - - 88 89This is a port of STLport (http://www.stlport.org) that can be used on 90Android. It will provide you with a complete set of C++ standard library 91headers, with RTTI and exception handling support. 92 93That's because the library embeds its own copy of GAbi++. 94 95Available as both both static and shared libraries. To use it, use either 96one of these two lines in your Application.mk: 97 98 APP_STL := stlport_shared 99 APP_STL := stlport_static 100 101Note that 'stlport_shared' is preferred, for reasons explained in 102"Static runtime considerations". 103 104 105I.4. GNU STL runtime: 106- - - - - - - - - - - 107 108This is the GNU Standard C++ Library (a.k.a. libstdc++-v3), providing the 109more features. Note that the shared library file is named "libgnustl_shared.so" 110instead of "libstdc++.so" as on other platforms. 111 112If you want to use it, please read the "C++ Exceptions support", 113"RTTI Support" and "Static runtime considerations" sections below. 114 115 116 117II. Important Considerations: 118----------------------------- 119 120 121II.1. C++ Exceptions support: 122- - - - - - - - - - - - - - - 123 124The NDK toolchain supports C++ exceptions, since NDK r5, however all C++ 125sources are compiled with -fno-exceptions support by default, for 126compatibility reasons with previous releases. 127 128To enable it, use the new LOCAL_CPP_FEATURES variable in your Android.mk, 129as in: 130 131 LOCAL_CPP_FEATURES += exceptions 132 133See docs/ANDROID-MK.html for more details about this variable. 134 135Another way to do the same is to define it in your LOCAL_CPPFLAGS definition 136(but using LOCAL_CPP_FEATURES is preferred), as in: 137 138 LOCAL_CPPFLAGS += -fexceptions 139 140More simply, add a single line to your Application.mk, the setting will 141automatically apply to all your project's NDK modules: 142 143 APP_CPPFLAGS += -fexceptions 144 145IMPORTANT: You *will* have to select a C++ runtime that supports 146 exceptions to be able to link / run your code. 147 148 149II.2. RTTI support: 150- - - - - - - - - - 151 152Similarly, the NDK toolchain supports C++ RTTI (RunTime Type Information) 153since NDK r5, but all C++ sources are built with -fno-rtti by default for 154compatibility reasons. To enable it, add the following to your module 155declarations: 156 157 LOCAL_CPP_FEATURES += rtti 158 159This will be equivalent to: 160 161 LOCAL_CPPFLAGS += -frtti 162 163Or more simply to your Application.mk: 164 165 APP_CPPFLAGS += -frtti 166 167 168II.3. Static runtimes: 169- - - - - - - - - - - - 170 171Please keep in mind that the static library variant of a given C++ runtime 172SHALL ONLY BE LINKED INTO A SINGLE BINARY for optimal conditions. 173 174What this means is that if your project consists of a single shared 175library, you can link against, e.g., stlport_static, and everything will 176work correctly. 177 178On the other hand, if you have two shared libraries in your project 179(e.g. libfoo.so and libbar.so) which both link against the same static 180runtime, each one of them will include a copy of the runtime's code in 181its final binary image. This is problematic because certain global 182variables used/provided internally by the runtime are duplicated. 183 184This is likely to result in code that doesn't work correctly, for example: 185 186 - memory allocated in one library, and freed in the other would leak 187 or even corrupt the heap. 188 189 - exceptions raised in libfoo.so cannot be caught in libbar.so (and may 190 simply crash the program). 191 192 - the buffering of std::cout not working properly 193 194This problem also happens if you want to link an executable and a shared 195library to the same static library. 196 197In other words, if your project requires several shared library modules, 198then use the shared library variant of your C++ runtime. 199 200 201II.4. Shared runtimes: 202- - - - - - - - - - - - 203 204If you use the shared library variant of a given C++ runtime, keep in mind 205that you must load it before any library that depends on it when your 206application starts. 207 208As an example, let's consider the case where we have the following modules 209 210 libfoo.so 211 libbar.so which is used by libfoo.so 212 libstlport_shared.so, used by both libfoo and libbar 213 214You will need to load the libraries in reverse dependency order, as in: 215 216 static { 217 System.loadLibrary("stlport_shared"); 218 System.loadLibrary("bar"); 219 System.loadLibrary("foo"); 220 } 221 222Note that you shouldn't use the 'lib' prefix when calling 223System.loadLibrary(), unless you specify the full path as in: 224 225 System.loadLibrary("/path/to/libstlport_shared.so") 226 227Which is not recommended, since this hard-codes the path in your code. 228 229 230III. EXTRAS: 231 232III.1. STLport-specific issues: 233------------------------------- 234 235This NDK provides prebuilt static and shared libraries for STLport, 236but you can force it to be rebuilt from sources by defining the following 237in your environment or your Application.mk before building: 238 239 STLPORT_FORCE_REBUILD := true 240 241STLport is licensed under a BSD-style open-source license. See 242sources/cxx-stl/stlport/README for more details about the library. 243 244 245III.2. GNU libstdc++ license is GPLv3 + linking exception! 246---------------------------------------------------------- 247 248Be aware that the GNU libstdc++ is covered by the GPLv3 license (and *not* 249the LGPLv2 or LGPLv3 as some assume), full details available here: 250 251 http://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html 252 253Be sure that you comply with all clauses of this license. 254 255 256IV. Future Plans: 257----------------- 258 259 - uSTL support? 260 261</pre></body></html> 262