Android std and stl support - C++ Library Support

https://developer.android.com/ndk/guides/cpp-support.html

The Android platform provides a very minimal C++ runtime support library (libstdc++).This minimal support does not include, for example:

• Standard C++ Library support (except a few trivial headers).
• C++ exceptions support
• RTTI support

The NDK provides headers for use with this default library. In addition, the NDK provides anumber of helper runtimes that provide additional features. This page provides information aboutthese helper runtimes, their characteristics, and how to use them.

Helper Runtimes

---

Table 1 provides names, brief explanations, and features of runtimes available inthe NDK.

Table 1. NDK Runtimes and Features.

Name	Explanation>	Features
libstdc++ (default)	The default minimal system C++ runtime library.	N/A
gabi++_static	The GAbi++ runtime (static).	C++ Exceptions and RTTI
gabi++_shared	The GAbi++ runtime (shared).	C++ Exceptions and RTTI
stlport_static	The STLport runtime (static).	C++ Exceptions and RTTI; Standard Library
stlport_shared	The STLport runtime (shared).	C++ Exceptions and RTTI; Standard Library
gnustl_static	The GNU STL (static).	C++ Exceptions and RTTI; Standard Library
gnustl_shared	The GNU STL (shared).	C++ Exceptions and RTTI; Standard Library
c++_static	The LLVM libc++ runtime (static).	C++ Exceptions and RTTI; Standard Library
c++_shared	The LLVM libc++ runtime (shared).	C++ Exceptions and RTTI; Standard Library

How to set your runtime

Use the APP_STL variable in your Application.mk file to specify the runtime you wish to use. Use the values inthe "Name" column in Table 1 as your setting. For example:

APP_STL := gnustl_static

You may only select one runtime for your app, and can only do inApplication.mk.

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 Standalone Toolchain.

Runtime Characteristics

---

libstdc++ (default system runtime)

This runtime only provides the following headers, with no support beyond them:

• cassert
• cctype
• cerrno
• cfloat
• climits
• cmath
• csetjmp
• csignal
• cstddef
• cstdint
• cstdio
• cstdlib
• cstring
• ctime
• cwchar
• new
• stl_pair.h
• typeinfo
• utility

GAbi++ runtime

This runtime provides the same headers as the default runtime, but adds support for RTTI(RunTime Type Information) and exception handling.

STLport runtime

This runtime is an Android port of STLport(http://www.stlport.org). It provides a complete set of C++standard library headers. It also, by embedding its own instance of GAbi++, provides support forRTTI and exception handling.

While shared and static versions of this runtime are avilable, we recommend using the sharedversion. For more information, see Static runtimes.

The shared library file is named libstlport_shared.so instead of libstdc++.soas is common on other platforms.

In addition to the static- and shared-library options, you can also force the NDK tobuild the library from sources by adding the following line to your Application.mkfile, or setting it in your environment prior to building:

STLPORT_FORCE_REBUILD := true

GNU STL runtime

This runtime is the GNU Standard C++ Library, (libstdc++-v3). Its shared library file isnamed libgnustl_shared.so.

libc++ runtime:

This runtime is an Android port of LLVM libc++. Itsshared library file is named libc++_shared.so.

By default, this runtime compiles with -std=c++11. As with GNU libstdc++, youneed to explicitly turn on exceptions or RTTI support. For information on how to do this, seeC++ Exceptions and RTTI.

The NDK provides prebuilt static and shared libraries for libc++, but you can force theNDK to rebuild libc++ from sources by adding the following line to yourApplication.mk file, or setting it in your environment prior to building:

LIBCXX_FORCE_REBUILD := true

Atomic support

If you include <atomic>, it's likely that you also need libatomic.If you are using ndk-build, add the following line:

LOCAL_LDLIBS += -latomic

If you are using your own toolchain, use:

-latomic

Compatibility

The NDK's libc++ is not stable. Not all the tests pass, and the test suite is not comprehensive.Some known issues are:

• Using c++_shared on ARM can crash when an exception is thrown.
• Support for wchar_t and the locale APIs is limited.

You should also make sure to check the "Known Issues" section of the changelog for the NDKrelease you are using.

Warning: Attempting to change to an unsupported locale willnot fail. The operation will succeed, but the locale will not change and thefollowing message will appear in logcat.

newlocale() WARNING: Trying to set locale to en_US.UTF-8 other than "", "C" or "POSIX"

Important Considerations

---

C++ Exceptions

In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimesthat support exception handling. However, to ensure compatibility with earlier releases, itcompiles all C++ sources with -fno-exceptions support by default. You can enable C++exceptions either for your entire app, or for individual modules.

To enable exception-handling support for your entire app, add the following line toyour Application.mk file.To enable exception-handling support for individual modules', add the following line totheir respective Android.mk files.

APP_CPPFLAGS += -fexceptions

RTTI

In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimesthat support RTTI. However, to ensure compatibility with earlier releases, it compiles all C++sources with -fno-rtti by default.

To enable RTTI support for your entire app for your entire application, add the following line toyour Application.mk file:

APP_CPPFLAGS += -frtti

To enable RTTI support for individual modules, add the following line totheir respective Android.mk files:

LOCAL_CPP_FEATURES += rtti

Alternatively, you can use:

LOCAL_CPPFLAGS += -frtti

Static runtimes

Linking the static library variant of a C++ runtime to more than one binary may result inunexpected behavior. For example, you may experience:

• Memory allocated in one library, and freed in the other, causing memory leakage or heapcorruption.
• Exceptions raised in libfoo.so going uncaught in libbar.so, causing your appto crash.
• Buffering of std::cout not working properly

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 ofthe runtime's code. Having multiple instances of runtime code is problematic because of duplicationof certain global variables that the runtime uses or provides internally.

This problem does not apply to a project comprising a single shared library. For example,you can link against stlport_static, and expect your app to behave correctly. If yourproject requires several shared library modules, we recommend that you use the shared libraryvariant of your C++ runtime.

Shared runtimes

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 librarybefore any other library that depends on it.

For example, an app may have the following modules:

• libfoo.so
• libbar.so which is used by libfoo.so
• libstlport_shared.so, used by both libfoo and libbar

You must load the libraries in reverse dependency order:

    static {
      System.loadLibrary("stlport_shared");
      System.loadLibrary("bar");
      System.loadLibrary("foo");
    }

Note: Do not use the lib prefix when callingSystem.loadLibrary().

Licensing

---

STLport is licensed under a BSD-style open-source license. See$NDK/sources/cxx-stl/stlport/README for more details about STLport.

GNU libstdc++ is covered by the GPLv3 license, and not the LGPLv2 or LGPLv3. Formore information, see License on the GCC website.

LLVM libc++is dual-licensed under both the University of Illinois "BSD-Like" license and the MIT license.