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