Home | History | Annotate | Download | only in docs
      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          -&gt; Use the default minimal system C++ runtime library.
     22     gabi++_static   -&gt; Use the GAbi++ runtime as a static library.
     23     gabi++_shared   -&gt; Use the GAbi++ runtime as a shared library.
     24     stlport_static  -&gt; Use the STLport runtime as a static library.
     25     stlport_shared  -&gt; Use the STLport runtime as a shared library.
     26     gnustl_static   -&gt; Use the GNU STL as a static library.
     27     gnustl_shared   -&gt; 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