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