ndk/docs/CPLUSPLUS-SUPPORT.html

   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 I. C++ Exceptions support:
  10 --------------------------
  11
  12 The NDK toolchain supports C++ exceptions, since NDK r5, however all C++
  13 sources are compiled with -fno-exceptions support by default, for
  14 compatibility reasons with previous releases.
  15
  16 To enable it, use the '-fexceptions' C++ compiler flag. This can be done
  17 by adding the following to every module definition in your Android.mk:
  18
  19     LOCAL_CPPFLAGS += -fexceptions
  20
  21 More simply, add a single line to your Application.mk, the setting will
  22 automatically apply to all your project's NDK modules:
  23
  24     APP_CPPFLAGS += -fexceptions
  25
  26 NOTE: The obsolete "arm-eabi-4.4.0" toolchain provided for backwards
  27       compatibility with this NDK does not support exceptions!
  28
  29
  30 II. RTTI support:
  31 ------------------
  32
  33 Similarly, the NDK toolchain supports C++ RTTI (RunTime Type Information)
  34 since NDK r5, but all C++ sources are built with -fno-rtti by default for
  35 compatibility reasons. To enable it, add the following to your module
  36 declarations:
  37
  38     LOCAL_CPPFLAGS += -frtti
  39
  40 Or more simply to your Application.mk:
  41
  42     APP_CPPFLAGS += -frtti
  43
  44
  45 NOTE: The obsolete "arm-eabi-4.4.0" toolchain provided for backwards
  46       compatibility with this NDK does not support RTTI!
  47
  48
  49 III. Selecting the C++ Standard Library Implementation:
  50 -------------------------------------------------------
  51
  52 By default, the headers and libraries for the minimal C++ runtime system
  53 library (/system/lib/libstdc++.so) are used when building C++ sources.
  54
  55 You can however select a different implementation by setting the variable
  56 APP_STL to something else in your Application.mk, for example:
  57
  58   APP_STL := stlport_static
  59
  60 To select the static STLport implementation provided with this NDK.
  61 Value APP_STL values are the following:
  62
  63    system              -&gt; Use the default minimal C++ runtime library.
  64    stlport_static      -&gt; Use STLport built as a static library.
  65    stlport_shared      -&gt; Use STLport built as a shared library.
  66    gnustl_static       -&gt; Use GNU libstdc++ as a static library.
  67
  68 WARNING: IMPORTANT CAVEAT
  69
  70      AT THE MOMENT, OUR STLPORT IMPLEMENTATION DOES NOT SUPPORT EXCEPTIONS
  71      AND RTTI. PLEASE BE SURE TO NOT USE -fexceptions OR -frtti IN ALL
  72      MODULES THAT USE IT.
  73
  74      IF YOU NEED THESE, PLEASE USE "gnustl_static".
  75
  76 WARNING: END OF IMPORTANT CAVEAT
  77
  78   "stlport_shared" is preferred if you have several shared libraries in your
  79   project that use the C++ STL, because it avoids duplication of functions
  80   and more importantly of global variables (e.g. std::cout) in each one of
  81   them, which can have surprising results.
  82
  83   On the other hand, you will have to load it explicitely when starting your
  84   application, as in the following example:
  85
  86      static {
  87          System.loadLibrary("stlport_shared");
  88          System.loadLibrary("foo");
  89          System.loadLibrary("bar");
  90      }
  91
  92   Where both "libfoo.so" and "libbar.so" depend on "libstlport_shared.so".
  93
  94   Note that the shared library's name if "libstlport_shared.so" to avoid
  95   naming conflicts with certain Android system images which include a
  96   system-level libstlport.so (which happens to not be ABI-stable and
  97   cannot be used from NDK-generated machine code).
  98
  99   "stlport_static" is preferred if you have only one shared library in your
 100   project: only the STL functions and variables you actually need will be
 101   linked to your machine code, reducing its code size, and you won't need
 102   to load the dynamic stlport_shared at startup.
 103
 104
 105   "gnustl_static" is preferred (and required) if you need C++ Exceptions
 106   and RTTI support at the moment.
 107
 108
 109 IV. STLport-specific issues:
 110 ----------------------------
 111
 112 This NDK provides prebuilt static and shared libraries for STLport,
 113 but you can force it to be rebuilt from sources by defining the following
 114 in your environment or your Application.mk before building:
 115
 116     STLPORT_FORCE_REBUILD := true
 117
 118 STLport is licensed under a BSD-style open-source license. See
 119 sources/cxx-stl/stlport/README for more details about the library.
 120
 121
 122 V. Future Plans:
 123 ----------------
 124
 125   - Make STLport compatible with C++ exceptions and RTTI
 126   - Shared GNU libstdc++ support
 127   - uSTL support?
 128
 129 </pre></body></html>