David Friedman | e23031c | 2015-05-22 03:20:03 -0700 | [diff] [blame] | 1 | page.title=C++ Library Support |
| 2 | @jd:body |
| 3 | |
| 4 | <div id="qv-wrapper"> |
| 5 | <div id="qv"> |
| 6 | <h2>On this page</h2> |
| 7 | |
| 8 | <ol> |
| 9 | <li><a href="#hr">Helper Runtimes</a></li> |
| 10 | <li><a href="#rc">Runtime Characteristics</a></li> |
| 11 | <li><a href="#ic">Important Considerations</a></li> |
| 12 | <li><a href="#li">Licensing</a></li> |
| 13 | </ol> |
| 14 | </div> |
| 15 | </div> |
| 16 | |
| 17 | <p>The Android platform provides a very minimal C++ runtime support library ({@code libstdc++}). |
| 18 | This minimal support does not include, for example:</p> |
| 19 | |
| 20 | <ul> |
| 21 | <li>Standard C++ Library support (except a few trivial headers).</li> |
| 22 | <li>C++ exceptions support</li> |
| 23 | <li>RTTI support</li> |
| 24 | </ul> |
| 25 | |
| 26 | <p>The NDK provides headers for use with this default library. In addition, the NDK provides a |
| 27 | number of helper runtimes that provide additional features. This page provides information about |
| 28 | these helper runtimes, their characteristics, and how to use them. |
| 29 | </p> |
| 30 | |
| 31 | <h2 id="hr">Helper Runtimes</h2> |
| 32 | |
| 33 | <p>Table 1 provides names, brief explanations, and features of runtimes available inthe NDK.</p> |
| 34 | |
David Friedman | a766e68 | 2015-05-26 17:41:42 -0700 | [diff] [blame] | 35 | <p class="table-caption" id="runtimes"> |
David Friedman | e23031c | 2015-05-22 03:20:03 -0700 | [diff] [blame] | 36 | <strong>Table 1.</strong> NDK Runtimes and Features.</p> |
| 37 | |
| 38 | <table> |
| 39 | <tr> |
| 40 | <th>Name</th> |
| 41 | <th>Explanation> |
| 42 | <th>Features |
| 43 | </tr> |
| 44 | |
| 45 | <tr> |
| 46 | <td><a href="#system">{@code libstdc++} (default)</a> </td> |
| 47 | <td>The default minimal system C++ runtime library.</td> |
| 48 | <td>N/A</td> |
| 49 | </tr> |
| 50 | |
| 51 | <tr> |
| 52 | <td><a href="#ga">{@code gabi++_static}</a> </td> |
| 53 | <td>The GAbi++ runtime (static).</td> |
| 54 | <td>C++ Exceptions and RTTI</td> |
| 55 | </tr> |
| 56 | |
| 57 | <tr> |
| 58 | <td><a href="#ga">{@code gabi++_shared}</a> </td> |
| 59 | <td>The GAbi++ runtime (shared).</td> |
| 60 | <td>C++ Exceptions and RTTI</td> |
| 61 | </tr> |
| 62 | |
| 63 | <tr> |
| 64 | <td><a href="#stl">{@code stlport_static}</a> </td> |
| 65 | <td>The STLport runtime (static).</td> |
| 66 | <td> C++ Exceptions and RTTI; Standard Library</td> |
| 67 | </tr> |
| 68 | |
| 69 | <tr> |
| 70 | <td><a href="#stl">{@code stlport_shared}</a> </td> |
| 71 | <td>The STLport runtime (shared).</td> |
| 72 | <td> C++ Exceptions and RTTI; Standard Library</td> |
| 73 | </tr> |
| 74 | |
| 75 | <tr> |
| 76 | <td><a href="#gn">{@code gnustl_static}</a> </td> |
| 77 | <td>The GNU STL (static).</td> |
| 78 | <td> C++ Exceptions and RTTI; Standard Library</td> |
| 79 | </tr> |
| 80 | |
| 81 | <tr> |
| 82 | <td><a href="#gn">{@code gnustl_shared}</a> </td> |
| 83 | <td>The GNU STL (shared).</td> |
| 84 | <td> C++ Exceptions and RTTI; Standard Library</td> |
| 85 | </tr> |
| 86 | |
| 87 | <tr> |
| 88 | <td><a href="#cs">{@code c++_static}</a> </td> |
| 89 | <td>The LLVM libc++ runtime (static).</td> |
| 90 | <td> C++ Exceptions and RTTI; Standard Library</td> |
| 91 | </tr> |
| 92 | |
| 93 | <tr> |
| 94 | <td><a href="#cs">{@code c++_shared}</a> </td> |
| 95 | <td>The LLVM libc++ runtime (shared).</td> |
| 96 | <td> C++ Exceptions and RTTI; Standard Library</td> |
| 97 | </tr> |
| 98 | </table> |
| 99 | |
| 100 | <h3>How to set your runtime</h3> |
| 101 | |
| 102 | <p>Use the {@code APP_STL} variable in your <a href="{@docRoot}ndk/guides/application_mk.html"> |
| 103 | {@code Application.mk}</a> file to specify the runtime you wish to use. Use the values in |
| 104 | the "Name" column in Table 1 as your setting. For example:</p> |
| 105 | |
| 106 | <pre> |
| 107 | APP_STL := gnustl_static |
| 108 | </pre> |
| 109 | |
| 110 | <p>You may only select one runtime for your app, and can only do in |
| 111 | <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a>.</p> |
| 112 | |
| 113 | <p>Even if you do not use the NDK build system, you can still use STLport, libc++ or GNU STL. |
| 114 | For more information on how to use these runtimes with your own toolchain, see <a href="{@docRoot}ndk/guides/standalone_toolchain.html">Standalone Toolchain</a>.</p> |
| 115 | |
| 116 | <h2 id="rc">Runtime Characteristics</h2> |
David Friedman | 14d1777 | 2015-05-26 13:21:24 -0700 | [diff] [blame] | 117 | <h3 id="system">libstdc++ (default system runtime)</h3> |
David Friedman | e23031c | 2015-05-22 03:20:03 -0700 | [diff] [blame] | 118 | |
| 119 | <p>This runtime only provides the following headers, with no support beyond them:</p> |
| 120 | <ul> |
| 121 | <li>{@code cassert}</li> |
| 122 | <li>{@code cctype}</li> |
| 123 | <li>{@code cerrno}</li> |
| 124 | <li>{@code cfloat}</li> |
| 125 | <li>{@code climits}</li> |
| 126 | <li>{@code cmath}</li> |
| 127 | <li>{@code csetjmp}</li> |
| 128 | <li>{@code csignal}</li> |
| 129 | <li>{@code cstddef}</li> |
| 130 | <li>{@code cstdint}</li> |
| 131 | <li>{@code cstdio}</li> |
| 132 | <li>{@code cstdlib}</li> |
| 133 | <li>{@code cstring}</li> |
| 134 | <li>{@code ctime}</li> |
| 135 | <li>{@code cwchar}</li> |
| 136 | <li>{@code new}</li> |
| 137 | <li>{@code stl_pair.h}</li> |
| 138 | <li>{@code typeinfo}</li> |
| 139 | <li>{@code utility}</li> |
| 140 | </ul> |
| 141 | |
| 142 | <h3 id="ga">GAbi++ runtime</h3> |
| 143 | <p>This runtime provides the same headers as the default runtime, but adds support for RTTI |
| 144 | (RunTime Type Information) and exception handling.</p> |
| 145 | |
| 146 | |
| 147 | <h3 id="stl">STLport runtime</h3> |
| 148 | <p>This runtime is an Android port of STLport |
| 149 | (<a href="http://www.stlport.org">http://www.stlport.org</a>). It provides a complete set of C++ |
| 150 | standard library headers. It also, by embedding its own instance of GAbi++, provides support for |
| 151 | RTTI and exception handling.</p> |
| 152 | |
| 153 | <p>While shared and static versions of this runtime are avilable, we recommend using the shared |
| 154 | version. For more information, see <a href="#sr">Static runtimes</a>.</p> |
| 155 | |
| 156 | <p>The shared library file is named {@code libstlport_shared.so} instead of {@code libstdc++.so} |
| 157 | as is common on other platforms.</p> |
| 158 | |
| 159 | <p>In addition to the static- and shared-library options, you can also force the NDK to |
| 160 | build the library from sources by adding the following line to your {@code Application.mk} |
| 161 | file, or setting it in your environment prior to building: </p> |
| 162 | |
| 163 | <pre> |
| 164 | STLPORT_FORCE_REBUILD := true |
| 165 | </pre> |
| 166 | |
| 167 | |
| 168 | <h3 id="gn">GNU STL runtime</h3> |
| 169 | <p>This runtime is the GNU Standard C++ Library, ({@code libstdc++-v3}). Its shared library file is |
| 170 | named {@code libgnustl_shared.so}.</p> |
| 171 | |
| 172 | |
| 173 | <h3 id="cs">libC++ runtime:</h3> |
| 174 | <p>This runtime is an Android port of <a href="http://libcxx.llvm.org/">LLVM libc++</a>. Its |
| 175 | shared library file is named {@code libc++_shared.so}.</p> |
| 176 | |
| 177 | <p>By default, this runtime compiles with {@code -std=c++11}. As with GNU {@code libstdc++}, you |
David Friedman | 14d1777 | 2015-05-26 13:21:24 -0700 | [diff] [blame] | 178 | need to explicitly turns on exceptions or RTTI support. For information on how to do this, see |
David Friedman | e23031c | 2015-05-22 03:20:03 -0700 | [diff] [blame] | 179 | <a href="#xp">C++ Exceptions</a> and <a href="#rt">RTTI</a>.</p> |
| 180 | |
| 181 | <p>The NDK provides prebuilt static and shared libraries for {@code libc++} compiled by Clang 3.4, |
| 182 | but you can force the NDK to rebuild {@code libc++} from sources by adding the following line to |
| 183 | your {@code Application.mk} file, or setting it in your environment prior to building: </p> |
| 184 | |
| 185 | <pre> |
| 186 | LIBCXX_FORCE_REBUILD := true |
| 187 | </pre> |
| 188 | |
| 189 | <h4>atomic support</h4> |
| 190 | |
Neil Fuller | 71fbb81 | 2015-11-30 09:51:33 +0000 | [diff] [blame] | 191 | <p>If you include {@code <atomic>}, it's likely that you also need {@code libatomic}. |
David Friedman | e23031c | 2015-05-22 03:20:03 -0700 | [diff] [blame] | 192 | If you are using {@code ndk-build}, add the following line:</p> |
| 193 | |
| 194 | <pre> |
| 195 | LOCAL_LDLIBS += -latomic |
| 196 | </pre> |
| 197 | |
| 198 | <p>If you are using your own toolchain, use:</p> |
| 199 | |
| 200 | <pre> |
| 201 | -latomic |
| 202 | </pre> |
| 203 | |
| 204 | <p class="note"><strong>Note: </strong>{@code -latomic} is only available for GCC 4.8. |
| 205 | Because Clang 3.5 and Clang 3.6 use GCC 4.8's headers and libraries, as well as its |
| 206 | {@code as} and {@code ld} options, those versions of Clang also get {@code -latomic}.</p> |
| 207 | |
| 208 | |
| 209 | <h4>Compatibility</h4> |
| 210 | |
| 211 | <p>Around 99% of tests pass when compiling {@code libc++} with Clang 3.4 for all supported ABIs. |
| 212 | The failures are mostly in the areas of {@code wchar_t} and locales that Android bionic |
| 213 | doesn't support. Switching locale from the default produces the following warning in |
| 214 | {@code logcat}:</p> |
| 215 | |
| 216 | <pre> |
| 217 | newlocale() WARNING: Trying to set locale to en_US.UTF-8 other than "", "C" or "POSIX" |
| 218 | </pre> |
| 219 | |
| 220 | <p>We do not recommend using {@code libc++} with GCC 4.6 because of GCC 4.6's limited c++11 |
| 221 | support.</p> |
| 222 | |
| 223 | <p>For information on {@code libc++} tests that fail to compile, {@code black_list*} in |
| 224 | {@code $NDK/tests/device/test-libc++-shared-full/jni/Android.mk}. For information about tests |
| 225 | that fail to run correctly, see {@code $NDK/tests/device/test-libc++-shared-full/BROKEN_RUN}. |
| 226 | {@code $NDK}, here, is the your NDK installation's root directory.</p> |
| 227 | |
| 228 | |
| 229 | <h2 id="ic">Important Considerations</h2> |
| 230 | |
| 231 | <h3 id="xp">C++ Exceptions</h3> |
| 232 | <p>In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimes |
| 233 | that support exception handling. However, to ensure compatibility with earlier releases, it |
| 234 | compiles all C++ sources with {@code -fno-exceptions} support by default. You can enable C++ |
| 235 | exceptions either for your entire app, or for individual modules. |
| 236 | |
| 237 | <p>To enable exception-handling support for your entire app, add the following line to |
David Friedman | 14d1777 | 2015-05-26 13:21:24 -0700 | [diff] [blame] | 238 | your <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file. |
David Friedman | e23031c | 2015-05-22 03:20:03 -0700 | [diff] [blame] | 239 | To enable exception-handling support for individual modules', add the following line to |
David Friedman | 14d1777 | 2015-05-26 13:21:24 -0700 | [diff] [blame] | 240 | their respective <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files.</p> |
David Friedman | e23031c | 2015-05-22 03:20:03 -0700 | [diff] [blame] | 241 | |
| 242 | <pre> |
| 243 | APP_CPPFLAGS += -fexceptions |
| 244 | </pre> |
| 245 | |
| 246 | <h3 id="rt">RTTI</h3> |
| 247 | <p>In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimes |
| 248 | that support RTTI. However, to ensure compatibility with earlier releases, it compiles all C++ |
| 249 | sources with {@code -fno-rtti} by default. |
| 250 | |
| 251 | <p>To enable RTTI support for your entire app for your entire application, add the following line to |
David Friedman | 14d1777 | 2015-05-26 13:21:24 -0700 | [diff] [blame] | 252 | your <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file: |
David Friedman | e23031c | 2015-05-22 03:20:03 -0700 | [diff] [blame] | 253 | |
| 254 | <pre> |
| 255 | APP_CPPFLAGS += -frtti |
| 256 | </pre> |
| 257 | |
| 258 | To enable RTTI support for individual modules, add the following line to |
David Friedman | 14d1777 | 2015-05-26 13:21:24 -0700 | [diff] [blame] | 259 | their respective <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files: |
David Friedman | e23031c | 2015-05-22 03:20:03 -0700 | [diff] [blame] | 260 | |
| 261 | <pre> |
| 262 | LOCAL_CPP_FEATURES += rtti |
| 263 | </pre> |
| 264 | |
| 265 | Alternatively, you can use: |
| 266 | |
| 267 | <pre> |
| 268 | LOCAL_CPPFLAGS += -frtti |
| 269 | </pre> |
| 270 | |
| 271 | <h3 id="sr">Static runtimes</h3> |
| 272 | <p>Linking the static library variant of a C++ runtime to more than one binary may result in |
| 273 | unexpected behavior. For example, you may experience:</p> |
| 274 | |
| 275 | <ul> |
| 276 | <li>Memory allocated in one library, and freed in the other, causing memory leakage or heap |
| 277 | corruption.</li> |
| 278 | <li>Exceptions raised in {@code libfoo.so} going uncaught in {@code libbar.so}, causing your app |
| 279 | to crash.</li> |
| 280 | <li>Buffering of {@code std::cout} not working properly</li> |
| 281 | </ul> |
| 282 | |
| 283 | <p>In addition, if you link two shared libraries–or a shared library and an executable– |
| 284 | against the same static runtime, the final binary image of each shared library includes a copy of |
| 285 | the runtime's code. Having multiple instances of runtime code is problematic because of duplication |
| 286 | of certain global variables that the runtime uses or provides internally.</p> |
| 287 | |
| 288 | <p>This problem does not apply to a project comprising a single shared library. For example, |
| 289 | you can link against {@code stlport_static}, and expect your app to behave correctly. If your |
| 290 | project requires several shared library modules, we recommend that you use the shared library |
| 291 | variant of your C++ runtime.</p> |
| 292 | |
| 293 | <h3>Shared runtimes</h3> |
| 294 | <p>If your app targets a version of Android earlier than Android 4.3 (Android API level 18), |
| 295 | and you use the shared library variant of a given C++ runtime, you must load the shared library |
| 296 | before any other library that depends on it.</p> |
| 297 | |
| 298 | <p>For example, an app may have the following modules:</p> |
| 299 | |
| 300 | <ul> |
| 301 | <li>libfoo.so</li> |
| 302 | <li>libbar.so which is used by libfoo.so</li> |
| 303 | <li>libstlport_shared.so, used by both libfoo and libbar</li> |
| 304 | </ul> |
| 305 | |
David Friedman | 14d1777 | 2015-05-26 13:21:24 -0700 | [diff] [blame] | 306 | <p>You must load the libraries in reverse dependency order: </p> |
David Friedman | e23031c | 2015-05-22 03:20:03 -0700 | [diff] [blame] | 307 | <pre> |
| 308 | static { |
| 309 | System.loadLibrary("stlport_shared"); |
| 310 | System.loadLibrary("bar"); |
| 311 | System.loadLibrary("foo"); |
| 312 | } |
| 313 | </pre> |
| 314 | |
| 315 | <p class="note"><strong>Note: </strong>Do not use the {@code lib} prefix when calling |
| 316 | {@code System.loadLibrary()}.</p> |
| 317 | |
| 318 | <h2 id="li">Licensing</h2> |
| 319 | |
| 320 | <p>STLport is licensed under a BSD-style open-source license. See |
| 321 | {@code $NDK/sources/cxx-stl/stlport/README} for more details about STLport.</p> |
| 322 | |
| 323 | <p>GNU libstdc++ is covered by the GPLv3 license, and <em>not</em> the LGPLv2 or LGPLv3. For |
| 324 | more information, see <a href="http://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html"> |
| 325 | License</a> on the GCC website.</p> |
| 326 | |
| 327 | <p><a href="https://llvm.org/svn/llvm-project/libcxx/trunk/LICENSE.TXT">LLVM {@code libc++}</a> |
David Friedman | 14d1777 | 2015-05-26 13:21:24 -0700 | [diff] [blame] | 328 | is dual-licensed under both the University of Illinois "BSD-Like" license and the MIT license.</p> |