1 <html><body><pre> 2 C++ support with the Android NDK 3 ================================ 4 5 6 The Android platform provides a very minimal C++ runtime support library 7 (/system/lib/libstdc++) and corresponding headers for it in the NDK. 8 9 By 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 15 However, the NDK provides various "helper C++ runtimes" which can provide them, 16 or a subset of these features. 17 18 To select the runtime you want to use, define APP_STL inside your 19 Application.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 29 The 'system' runtime is the default if there is no APP_STL definition in 30 your Application.mk. As an example, to use the static GNU STL, add a line like: 31 32 APP_STL := gnustl_static 33 34 To your Application.mk. You can only select a single C++ runtime that all 35 your code will depend on. It is not possible to mix shared libraries compiled 36 against different C++ runtimes. 37 38 IMPORTANT: Defining APP_STL in Android.mk has no effect! 39 40 If you are not using the NDK build system, you can still use the GNU STL, 41 see docs/STANDALONE-TOOLCHAIN.html for more details. 42 43 The 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 54 I. Runtimes overview: 55 --------------------- 56 57 I.1. System runtime: 58 - - - - - - - - - - - 59 60 The system runtime only provides a very small number of C++ standard headers. 61 62 This corresponds to the actual C++ runtime provided by the Android platform. 63 If you use it, your C++ binaries will automatically be linked against the 64 system libstdc++. 65 66 The 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 72 Anything else is _not_ supported, including std::string or std::vector. 73 74 75 I.2. GAbi++ runtime: 76 - - - - - - - - - - - 77 78 This is a new minimalistic runtime that provides the same headers than 79 the system one, with the addition of RTTI (RunTime Type Information) and 80 exception handling support. 81 82 If you insist on using it, read the "RTTI Support" and 83 "Static runtime considerations" sections below. 84 85 86 I.3. STLport runtime: 87 - - - - - - - - - - - 88 89 This is a port of STLport (http://www.stlport.org) that can be used on 90 Android. It will provide you with a complete set of C++ standard library 91 headers, with RTTI and exception handling support. 92 93 That's because the library embeds its own copy of GAbi++. 94 95 Available as both both static and shared libraries. To use it, use either 96 one of these two lines in your Application.mk: 97 98 APP_STL := stlport_shared 99 APP_STL := stlport_static 100 101 Note that 'stlport_shared' is preferred, for reasons explained in 102 "Static runtime considerations". 103 104 105 I.4. GNU STL runtime: 106 - - - - - - - - - - - 107 108 This is the GNU Standard C++ Library (a.k.a. libstdc++-v3), providing the 109 more features. Note that the shared library file is named "libgnustl_shared.so" 110 instead of "libstdc++.so" as on other platforms. 111 112 If you want to use it, please read the "C++ Exceptions support", 113 "RTTI Support" and "Static runtime considerations" sections below. 114 115 116 117 II. Important Considerations: 118 ----------------------------- 119 120 121 II.1. C++ Exceptions support: 122 - - - - - - - - - - - - - - - 123 124 The NDK toolchain supports C++ exceptions, since NDK r5, however all C++ 125 sources are compiled with -fno-exceptions support by default, for 126 compatibility reasons with previous releases. 127 128 To enable it, use the new LOCAL_CPP_FEATURES variable in your Android.mk, 129 as in: 130 131 LOCAL_CPP_FEATURES += exceptions 132 133 See docs/ANDROID-MK.html for more details about this variable. 134 135 Another 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 140 More simply, add a single line to your Application.mk, the setting will 141 automatically apply to all your project's NDK modules: 142 143 APP_CPPFLAGS += -fexceptions 144 145 IMPORTANT: You *will* have to select a C++ runtime that supports 146 exceptions to be able to link / run your code. 147 148 149 II.2. RTTI support: 150 - - - - - - - - - - 151 152 Similarly, the NDK toolchain supports C++ RTTI (RunTime Type Information) 153 since NDK r5, but all C++ sources are built with -fno-rtti by default for 154 compatibility reasons. To enable it, add the following to your module 155 declarations: 156 157 LOCAL_CPP_FEATURES += rtti 158 159 This will be equivalent to: 160 161 LOCAL_CPPFLAGS += -frtti 162 163 Or more simply to your Application.mk: 164 165 APP_CPPFLAGS += -frtti 166 167 168 II.3. Static runtimes: 169 - - - - - - - - - - - - 170 171 Please keep in mind that the static library variant of a given C++ runtime 172 SHALL ONLY BE LINKED INTO A SINGLE BINARY for optimal conditions. 173 174 What this means is that if your project consists of a single shared 175 library, you can link against, e.g., stlport_static, and everything will 176 work correctly. 177 178 On 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 180 runtime, each one of them will include a copy of the runtime's code in 181 its final binary image. This is problematic because certain global 182 variables used/provided internally by the runtime are duplicated. 183 184 This 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 194 This problem also happens if you want to link an executable and a shared 195 library to the same static library. 196 197 In other words, if your project requires several shared library modules, 198 then use the shared library variant of your C++ runtime. 199 200 201 II.4. Shared runtimes: 202 - - - - - - - - - - - - 203 204 If you use the shared library variant of a given C++ runtime, keep in mind 205 that you must load it before any library that depends on it when your 206 application starts. 207 208 As 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 214 You 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 222 Note that you shouldn't use the 'lib' prefix when calling 223 System.loadLibrary(), unless you specify the full path as in: 224 225 System.loadLibrary("/path/to/libstlport_shared.so") 226 227 Which is not recommended, since this hard-codes the path in your code. 228 229 230 III. EXTRAS: 231 232 III.1. STLport-specific issues: 233 ------------------------------- 234 235 This NDK provides prebuilt static and shared libraries for STLport, 236 but you can force it to be rebuilt from sources by defining the following 237 in your environment or your Application.mk before building: 238 239 STLPORT_FORCE_REBUILD := true 240 241 STLport is licensed under a BSD-style open-source license. See 242 sources/cxx-stl/stlport/README for more details about the library. 243 244 245 III.2. GNU libstdc++ license is GPLv3 + linking exception! 246 ---------------------------------------------------------- 247 248 Be aware that the GNU libstdc++ is covered by the GPLv3 license (and *not* 249 the LGPLv2 or LGPLv3 as some assume), full details available here: 250 251 http://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html 252 253 Be sure that you comply with all clauses of this license. 254 255 256 IV. Future Plans: 257 ----------------- 258 259 - uSTL support? 260 261 </pre></body></html> 262
