1<html><body><pre>
2C++ support with the Android NDK
3================================
4
5
6The Android platform provides a very minimal C++ runtime support library
7(/system/lib/libstdc++) and corresponding headers for it in the NDK.
8
9By 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
15However, the NDK provides various "helper C++ runtimes" which can provide them,
16or a subset of these features.
17
18To select the runtime you want to use, define APP_STL inside your
19Application.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
29The 'system' runtime is the default if there is no APP_STL definition in
30your Application.mk. As an example, to use the static GNU STL, add a line like:
31
32   APP_STL := gnustl_static
33
34To your Application.mk. You can only select a single C++ runtime that all
35your code will depend on. It is not possible to mix shared libraries compiled
36against different C++ runtimes.
37
38IMPORTANT: Defining APP_STL in Android.mk has no effect!
39
40If you are not using the NDK build system, you can still use the GNU STL,
41see docs/STANDALONE-TOOLCHAIN.html for more details.
42
43The 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++        no      yes        no
50    stlport       no      yes       yes
51    gnustl       yes      yes       yes
52
53
54I. Runtimes overview:
55---------------------
56
57I.1. System runtime:
58- - - - - - - - - - -
59
60The system runtime only provides a very small number of C++ standard headers.
61
62This corresponds to the actual C++ runtime provided by the Android platform.
63If you use it, your C++ binaries will automatically be linked against the
64system libstdc++.
65
66The 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
72Anything else is _not_ supported, including std::string or std::vector.
73
74
75I.2. GAbi++ runtime:
76- - - - - - - - - - -
77
78This is a new minimalistic runtime that provides the same headers than
79the system one, with the addition of RTTI (RunTime Type Information) support.
80
81There is very little reason to use it right now, but it is planned to become
82the basis for STLport's exceptions+RTTI support in the future.
83
84If you insist on using it, read the "RTTI Support" and
85"Static runtime considerations" sections below.
86
87
88I.3. STLport runtime:
89- - - - - - - - - - -
90
91This is a port of STLport (http://www.stlport.org) that can be used on
92Android. It will provide you with a complete set of C++ standard library
93headers, however it ONLY SUPPORTS RTTI, AND NO EXCEPTIONS!
94
95That's because the library embeds its own copy of GAbi++.
96
97Available as both both static and shared libraries. To use it, use either
98one of these two lines in your Application.mk:
99
100   APP_STL := stlport_shared
101   APP_STL := stlport_static
102
103Note that 'stlport_shared' is preferred, for reasons explained in
104"Static runtime considerations".
105
106
107I.4. GNU STL runtime:
108- - - - - - - - - - -
109
110This is the GNU Standard C++ Library (a.k.a. libstdc++-v3), providing the
111more features. Note that the shared library file is named "libgnustl_shared.so"
112instead of "libstdc++.so" as on other platforms.
113
114If you want to use it, please read the "C++ Exceptions support",
115"RTTI Support" and "Static runtime considerations" sections below.
116
117
118
119II. Important Considerations:
120-----------------------------
121
122
123II.1. C++ Exceptions support:
124- - - - - - - - - - - - - - -
125
126The NDK toolchain supports C++ exceptions, since NDK r5, however all C++
127sources are compiled with -fno-exceptions support by default, for
128compatibility reasons with previous releases.
129
130To enable it, use the new LOCAL_CPP_FEATURES variable in your Android.mk,
131as in:
132
133    LOCAL_CPP_FEATURES += exceptions
134
135See docs/ANDROID-MK.html for more details about this varibale.
136
137Another way to do the same is to define it in your LOCAL_CPPFLAGS definition
138(but using LOCAL_CPP_FEATURES is preferred), as in:
139
140    LOCAL_CPPFLAGS += -fexceptions
141
142More simply, add a single line to your Application.mk, the setting will
143automatically apply to all your project's NDK modules:
144
145    APP_CPPFLAGS += -fexceptions
146
147IMPORTANT: You *will* have to select a C++ runtime that supports
148           exceptions to be able to link / run your code. At this point
149           this means only 'gnustl_static' or "gnustl_shared'!
150
151
152II.2. RTTI support:
153- - - - - - - - - -
154
155Similarly, the NDK toolchain supports C++ RTTI (RunTime Type Information)
156since NDK r5, but all C++ sources are built with -fno-rtti by default for
157compatibility reasons. To enable it, add the following to your module
158declarations:
159
160    LOCAL_CPP_FEATURES += rtti
161
162This will be equivalent to:
163
164    LOCAL_CPPFLAGS += -frtti
165
166Or more simply to your Application.mk:
167
168    APP_CPPFLAGS += -frtti
169
170
171II.3. Static runtimes:
172- - - - - - - - - - - -
173
174Please keep in mind that the static library variant of a given C++ runtime
175SHALL ONLY BE LINKED INTO A SINGLE BINARY for optimal conditions.
176
177What this means is that if your project consists of a single shared
178library, you can link against, e.g., stlport_static, and everything will
179work correctly.
180
181On the other hand, if you have two shared libraries in your project
182(e.g. libfoo.so and libbar.so) which both link against the same static
183runtime, each one of them will  include a copy of the runtime's code in
184its final binary image. This is problematic because certain global
185variables used/provided internally by the runtime are duplicated.
186
187This is likely to result in code that doesn't work correctly, for example:
188
189  - memory allocated in one library, and freed in the other would leak
190    or even corrupt the heap.
191
192  - exceptions raised in libfoo.so cannot be caught in libbar.so (and may
193    simply crash the program).
194
195  - the buffering of std::cout not working properly
196
197This problem also happens if you want to link an executable and a shared
198library to the same static library.
199
200In other words, if your project requires several shared library modules,
201then use the shared library variant of your C++ runtime.
202
203
204II.4. Shared runtimes:
205- - - - - - - - - - - -
206
207If you use the shared library variant of a given C++ runtime, keep in mind
208that you must load it before any library that depends on it when your
209application starts.
210
211As an example, let's consider the case where we have the following modules
212
213  libfoo.so
214  libbar.so which is used by libfoo.so
215  libstlport_shared.so, used by both libfoo and libbar
216
217You will need to load the libraries in reverse dependency order, as in:
218
219  static {
220    System.loadLibrary("libstlport_shared");
221    System.loadLibrary("libbar");
222    System.loadLibrary("libfoo");
223  }
224
225
226III. EXTRAS:
227
228III.1. STLport-specific issues:
229-------------------------------
230
231This NDK provides prebuilt static and shared libraries for STLport,
232but you can force it to be rebuilt from sources by defining the following
233in your environment or your Application.mk before building:
234
235    STLPORT_FORCE_REBUILD := true
236
237STLport is licensed under a BSD-style open-source license. See
238sources/cxx-stl/stlport/README for more details about the library.
239
240
241III.2. GNU libstdc++ license is GPLv3 + linking exception!
242----------------------------------------------------------
243
244Be aware that the GNU libstdc++ is covered by the GPLv3 license (and *not*
245the LGPLv2 or LGPLv3 as some assume), full details available here:
246
247    http://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html
248
249Be sure that you comply with all clauses of this license.
250
251
252IV. Future Plans:
253-----------------
254
255  - Add exceptions support to GAbi++
256  - Add exceptions support to STLport (once it is in GAbi++)
257  - uSTL support?
258
259</pre></body></html>
260