| page.title=C++ Library Support |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>On this page</h2> |
| |
| <ol> |
| <li><a href="#hr">Helper Runtimes</a></li> |
| <li><a href="#rc">Runtime Characteristics</a></li> |
| <li><a href="#ic">Important Considerations</a></li> |
| <li><a href="#li">Licensing</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>The Android platform provides a very minimal C++ runtime support library ({@code libstdc++}). |
| This minimal support does not include, for example:</p> |
| |
| <ul> |
| <li>Standard C++ Library support (except a few trivial headers).</li> |
| <li>C++ exceptions support</li> |
| <li>RTTI support</li> |
| </ul> |
| |
| <p>The NDK provides headers for use with this default library. In addition, the NDK provides a |
| number of helper runtimes that provide additional features. This page provides information about |
| these helper runtimes, their characteristics, and how to use them. |
| </p> |
| |
| <h2 id="hr">Helper Runtimes</h2> |
| |
| <p>Table 1 provides names, brief explanations, and features of runtimes available inthe NDK.</p> |
| |
| <p class="table-caption" id="runtimes"> |
| <strong>Table 1.</strong> NDK Runtimes and Features.</p> |
| |
| <table> |
| <tr> |
| <th>Name</th> |
| <th>Explanation> |
| <th>Features |
| </tr> |
| |
| <tr> |
| <td><a href="#system">{@code libstdc++} (default)</a> </td> |
| <td>The default minimal system C++ runtime library.</td> |
| <td>N/A</td> |
| </tr> |
| |
| <tr> |
| <td><a href="#ga">{@code gabi++_static}</a> </td> |
| <td>The GAbi++ runtime (static).</td> |
| <td>C++ Exceptions and RTTI</td> |
| </tr> |
| |
| <tr> |
| <td><a href="#ga">{@code gabi++_shared}</a> </td> |
| <td>The GAbi++ runtime (shared).</td> |
| <td>C++ Exceptions and RTTI</td> |
| </tr> |
| |
| <tr> |
| <td><a href="#stl">{@code stlport_static}</a> </td> |
| <td>The STLport runtime (static).</td> |
| <td> C++ Exceptions and RTTI; Standard Library</td> |
| </tr> |
| |
| <tr> |
| <td><a href="#stl">{@code stlport_shared}</a> </td> |
| <td>The STLport runtime (shared).</td> |
| <td> C++ Exceptions and RTTI; Standard Library</td> |
| </tr> |
| |
| <tr> |
| <td><a href="#gn">{@code gnustl_static}</a> </td> |
| <td>The GNU STL (static).</td> |
| <td> C++ Exceptions and RTTI; Standard Library</td> |
| </tr> |
| |
| <tr> |
| <td><a href="#gn">{@code gnustl_shared}</a> </td> |
| <td>The GNU STL (shared).</td> |
| <td> C++ Exceptions and RTTI; Standard Library</td> |
| </tr> |
| |
| <tr> |
| <td><a href="#cs">{@code c++_static}</a> </td> |
| <td>The LLVM libc++ runtime (static).</td> |
| <td> C++ Exceptions and RTTI; Standard Library</td> |
| </tr> |
| |
| <tr> |
| <td><a href="#cs">{@code c++_shared}</a> </td> |
| <td>The LLVM libc++ runtime (shared).</td> |
| <td> C++ Exceptions and RTTI; Standard Library</td> |
| </tr> |
| </table> |
| |
| <h3>How to set your runtime</h3> |
| |
| <p>Use the {@code APP_STL} variable in your <a href="{@docRoot}ndk/guides/application_mk.html"> |
| {@code Application.mk}</a> file to specify the runtime you wish to use. Use the values in |
| the "Name" column in Table 1 as your setting. For example:</p> |
| |
| <pre> |
| APP_STL := gnustl_static |
| </pre> |
| |
| <p>You may only select one runtime for your app, and can only do in |
| <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a>.</p> |
| |
| <p>Even if you do not use the NDK build system, you can still use STLport, libc++ or GNU STL. |
| 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> |
| |
| <h2 id="rc">Runtime Characteristics</h2> |
| <h3 id="system">libstdc++ (default system runtime)</h3> |
| |
| <p>This runtime only provides the following headers, with no support beyond them:</p> |
| <ul> |
| <li>{@code cassert}</li> |
| <li>{@code cctype}</li> |
| <li>{@code cerrno}</li> |
| <li>{@code cfloat}</li> |
| <li>{@code climits}</li> |
| <li>{@code cmath}</li> |
| <li>{@code csetjmp}</li> |
| <li>{@code csignal}</li> |
| <li>{@code cstddef}</li> |
| <li>{@code cstdint}</li> |
| <li>{@code cstdio}</li> |
| <li>{@code cstdlib}</li> |
| <li>{@code cstring}</li> |
| <li>{@code ctime}</li> |
| <li>{@code cwchar}</li> |
| <li>{@code new}</li> |
| <li>{@code stl_pair.h}</li> |
| <li>{@code typeinfo}</li> |
| <li>{@code utility}</li> |
| </ul> |
| |
| <h3 id="ga">GAbi++ runtime</h3> |
| <p>This runtime provides the same headers as the default runtime, but adds support for RTTI |
| (RunTime Type Information) and exception handling.</p> |
| |
| |
| <h3 id="stl">STLport runtime</h3> |
| <p>This runtime is an Android port of STLport |
| (<a href="http://www.stlport.org">http://www.stlport.org</a>). It provides a complete set of C++ |
| standard library headers. It also, by embedding its own instance of GAbi++, provides support for |
| RTTI and exception handling.</p> |
| |
| <p>While shared and static versions of this runtime are avilable, we recommend using the shared |
| version. For more information, see <a href="#sr">Static runtimes</a>.</p> |
| |
| <p>The shared library file is named {@code libstlport_shared.so} instead of {@code libstdc++.so} |
| as is common on other platforms.</p> |
| |
| <p>In addition to the static- and shared-library options, you can also force the NDK to |
| build the library from sources by adding the following line to your {@code Application.mk} |
| file, or setting it in your environment prior to building: </p> |
| |
| <pre> |
| STLPORT_FORCE_REBUILD := true |
| </pre> |
| |
| |
| <h3 id="gn">GNU STL runtime</h3> |
| <p>This runtime is the GNU Standard C++ Library, ({@code libstdc++-v3}). Its shared library file is |
| named {@code libgnustl_shared.so}.</p> |
| |
| |
| <h3 id="cs">libC++ runtime:</h3> |
| <p>This runtime is an Android port of <a href="http://libcxx.llvm.org/">LLVM libc++</a>. Its |
| shared library file is named {@code libc++_shared.so}.</p> |
| |
| <p>By default, this runtime compiles with {@code -std=c++11}. As with GNU {@code libstdc++}, you |
| need to explicitly turns on exceptions or RTTI support. For information on how to do this, see |
| <a href="#xp">C++ Exceptions</a> and <a href="#rt">RTTI</a>.</p> |
| |
| <p>The NDK provides prebuilt static and shared libraries for {@code libc++} compiled by Clang 3.4, |
| but you can force the NDK to rebuild {@code libc++} from sources by adding the following line to |
| your {@code Application.mk} file, or setting it in your environment prior to building: </p> |
| |
| <pre> |
| LIBCXX_FORCE_REBUILD := true |
| </pre> |
| |
| <h4>atomic support</h4> |
| |
| <p>If you include {@code <atomic>}, it's likely that you also need {@code libatomic}. |
| If you are using {@code ndk-build}, add the following line:</p> |
| |
| <pre> |
| LOCAL_LDLIBS += -latomic |
| </pre> |
| |
| <p>If you are using your own toolchain, use:</p> |
| |
| <pre> |
| -latomic |
| </pre> |
| |
| <p class="note"><strong>Note: </strong>{@code -latomic} is only available for GCC 4.8. |
| Because Clang 3.5 and Clang 3.6 use GCC 4.8's headers and libraries, as well as its |
| {@code as} and {@code ld} options, those versions of Clang also get {@code -latomic}.</p> |
| |
| |
| <h4>Compatibility</h4> |
| |
| <p>Around 99% of tests pass when compiling {@code libc++} with Clang 3.4 for all supported ABIs. |
| The failures are mostly in the areas of {@code wchar_t} and locales that Android bionic |
| doesn't support. Switching locale from the default produces the following warning in |
| {@code logcat}:</p> |
| |
| <pre> |
| newlocale() WARNING: Trying to set locale to en_US.UTF-8 other than "", "C" or "POSIX" |
| </pre> |
| |
| <p>We do not recommend using {@code libc++} with GCC 4.6 because of GCC 4.6's limited c++11 |
| support.</p> |
| |
| <p>For information on {@code libc++} tests that fail to compile, {@code black_list*} in |
| {@code $NDK/tests/device/test-libc++-shared-full/jni/Android.mk}. For information about tests |
| that fail to run correctly, see {@code $NDK/tests/device/test-libc++-shared-full/BROKEN_RUN}. |
| {@code $NDK}, here, is the your NDK installation's root directory.</p> |
| |
| |
| <h2 id="ic">Important Considerations</h2> |
| |
| <h3 id="xp">C++ Exceptions</h3> |
| <p>In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimes |
| that support exception handling. However, to ensure compatibility with earlier releases, it |
| compiles all C++ sources with {@code -fno-exceptions} support by default. You can enable C++ |
| exceptions either for your entire app, or for individual modules. |
| |
| <p>To enable exception-handling support for your entire app, add the following line to |
| your <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file. |
| To enable exception-handling support for individual modules', add the following line to |
| their respective <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files.</p> |
| |
| <pre> |
| APP_CPPFLAGS += -fexceptions |
| </pre> |
| |
| <h3 id="rt">RTTI</h3> |
| <p>In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimes |
| that support RTTI. However, to ensure compatibility with earlier releases, it compiles all C++ |
| sources with {@code -fno-rtti} by default. |
| |
| <p>To enable RTTI support for your entire app for your entire application, add the following line to |
| your <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file: |
| |
| <pre> |
| APP_CPPFLAGS += -frtti |
| </pre> |
| |
| To enable RTTI support for individual modules, add the following line to |
| their respective <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files: |
| |
| <pre> |
| LOCAL_CPP_FEATURES += rtti |
| </pre> |
| |
| Alternatively, you can use: |
| |
| <pre> |
| LOCAL_CPPFLAGS += -frtti |
| </pre> |
| |
| <h3 id="sr">Static runtimes</h3> |
| <p>Linking the static library variant of a C++ runtime to more than one binary may result in |
| unexpected behavior. For example, you may experience:</p> |
| |
| <ul> |
| <li>Memory allocated in one library, and freed in the other, causing memory leakage or heap |
| corruption.</li> |
| <li>Exceptions raised in {@code libfoo.so} going uncaught in {@code libbar.so}, causing your app |
| to crash.</li> |
| <li>Buffering of {@code std::cout} not working properly</li> |
| </ul> |
| |
| <p>In addition, if you link two shared libraries–or a shared library and an executable– |
| against the same static runtime, the final binary image of each shared library includes a copy of |
| the runtime's code. Having multiple instances of runtime code is problematic because of duplication |
| of certain global variables that the runtime uses or provides internally.</p> |
| |
| <p>This problem does not apply to a project comprising a single shared library. For example, |
| you can link against {@code stlport_static}, and expect your app to behave correctly. If your |
| project requires several shared library modules, we recommend that you use the shared library |
| variant of your C++ runtime.</p> |
| |
| <h3>Shared runtimes</h3> |
| <p>If your app targets a version of Android earlier than Android 4.3 (Android API level 18), |
| and you use the shared library variant of a given C++ runtime, you must load the shared library |
| before any other library that depends on it.</p> |
| |
| <p>For example, an app may have the following modules:</p> |
| |
| <ul> |
| <li>libfoo.so</li> |
| <li>libbar.so which is used by libfoo.so</li> |
| <li>libstlport_shared.so, used by both libfoo and libbar</li> |
| </ul> |
| |
| <p>You must load the libraries in reverse dependency order: </p> |
| <pre> |
| static { |
| System.loadLibrary("stlport_shared"); |
| System.loadLibrary("bar"); |
| System.loadLibrary("foo"); |
| } |
| </pre> |
| |
| <p class="note"><strong>Note: </strong>Do not use the {@code lib} prefix when calling |
| {@code System.loadLibrary()}.</p> |
| |
| <h2 id="li">Licensing</h2> |
| |
| <p>STLport is licensed under a BSD-style open-source license. See |
| {@code $NDK/sources/cxx-stl/stlport/README} for more details about STLport.</p> |
| |
| <p>GNU libstdc++ is covered by the GPLv3 license, and <em>not</em> the LGPLv2 or LGPLv3. For |
| more information, see <a href="http://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html"> |
| License</a> on the GCC website.</p> |
| |
| <p><a href="https://llvm.org/svn/llvm-project/libcxx/trunk/LICENSE.TXT">LLVM {@code libc++}</a> |
| is dual-licensed under both the University of Illinois "BSD-Like" license and the MIT license.</p> |