blob: 21df6afbb6629ea17c41cb357709a596e38c41dd [file] [log] [blame]
David Friedmane23031c2015-05-22 03:20:03 -07001page.title=C++ Library Support
2@jd:body
3
4<div id="qv-wrapper">
5 <div id="qv">
6 <h2>On this page</h2>
7
8 <ol>
9 <li><a href="#hr">Helper Runtimes</a></li>
10 <li><a href="#rc">Runtime Characteristics</a></li>
11 <li><a href="#ic">Important Considerations</a></li>
12 <li><a href="#li">Licensing</a></li>
13 </ol>
14 </div>
15 </div>
16
17<p>The Android platform provides a very minimal C++ runtime support library ({@code libstdc++}).
18This minimal support does not include, for example:</p>
19
20<ul>
21 <li>Standard C++ Library support (except a few trivial headers).</li>
22 <li>C++ exceptions support</li>
23 <li>RTTI support</li>
24</ul>
25
26<p>The NDK provides headers for use with this default library. In addition, the NDK provides a
27number of helper runtimes that provide additional features. This page provides information about
28these helper runtimes, their characteristics, and how to use them.
29</p>
30
31<h2 id="hr">Helper Runtimes</h2>
32
33<p>Table 1 provides names, brief explanations, and features of runtimes available inthe NDK.</p>
34
David Friedmana766e682015-05-26 17:41:42 -070035<p class="table-caption" id="runtimes">
David Friedmane23031c2015-05-22 03:20:03 -070036 <strong>Table 1.</strong> NDK Runtimes and Features.</p>
37
38<table>
39<tr>
40<th>Name</th>
41<th>Explanation>
42<th>Features
43</tr>
44
45<tr>
46<td><a href="#system">{@code libstdc++} (default)</a> </td>
47<td>The default minimal system C++ runtime library.</td>
48<td>N/A</td>
49</tr>
50
51<tr>
52<td><a href="#ga">{@code gabi++_static}</a> </td>
53<td>The GAbi++ runtime (static).</td>
54<td>C++ Exceptions and RTTI</td>
55</tr>
56
57<tr>
58<td><a href="#ga">{@code gabi++_shared}</a> </td>
59<td>The GAbi++ runtime (shared).</td>
60<td>C++ Exceptions and RTTI</td>
61</tr>
62
63<tr>
64<td><a href="#stl">{@code stlport_static}</a> </td>
65<td>The STLport runtime (static).</td>
66<td> C++ Exceptions and RTTI; Standard Library</td>
67</tr>
68
69<tr>
70<td><a href="#stl">{@code stlport_shared}</a> </td>
71<td>The STLport runtime (shared).</td>
72<td> C++ Exceptions and RTTI; Standard Library</td>
73</tr>
74
75<tr>
76<td><a href="#gn">{@code gnustl_static}</a> </td>
77<td>The GNU STL (static).</td>
78<td> C++ Exceptions and RTTI; Standard Library</td>
79</tr>
80
81<tr>
82<td><a href="#gn">{@code gnustl_shared}</a> </td>
83<td>The GNU STL (shared).</td>
84<td> C++ Exceptions and RTTI; Standard Library</td>
85</tr>
86
87<tr>
88<td><a href="#cs">{@code c++_static}</a> </td>
89<td>The LLVM libc++ runtime (static).</td>
90<td> C++ Exceptions and RTTI; Standard Library</td>
91</tr>
92
93<tr>
94<td><a href="#cs">{@code c++_shared}</a> </td>
95<td>The LLVM libc++ runtime (shared).</td>
96<td> C++ Exceptions and RTTI; Standard Library</td>
97</tr>
98</table>
99
100<h3>How to set your runtime</h3>
101
102<p>Use the {@code APP_STL} variable in your <a href="{@docRoot}ndk/guides/application_mk.html">
103{@code Application.mk}</a> file to specify the runtime you wish to use. Use the values in
104the "Name" column in Table 1 as your setting. For example:</p>
105
106<pre>
107APP_STL := gnustl_static
108</pre>
109
110<p>You may only select one runtime for your app, and can only do in
111<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a>.</p>
112
113<p>Even if you do not use the NDK build system, you can still use STLport, libc++ or GNU STL.
114For 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>
115
116<h2 id="rc">Runtime Characteristics</h2>
David Friedman14d17772015-05-26 13:21:24 -0700117<h3 id="system">libstdc++ (default system runtime)</h3>
David Friedmane23031c2015-05-22 03:20:03 -0700118
119<p>This runtime only provides the following headers, with no support beyond them:</p>
120<ul>
121 <li>{@code cassert}</li>
122 <li>{@code cctype}</li>
123 <li>{@code cerrno}</li>
124 <li>{@code cfloat}</li>
125 <li>{@code climits}</li>
126 <li>{@code cmath}</li>
127 <li>{@code csetjmp}</li>
128 <li>{@code csignal}</li>
129 <li>{@code cstddef}</li>
130 <li>{@code cstdint}</li>
131 <li>{@code cstdio}</li>
132 <li>{@code cstdlib}</li>
133 <li>{@code cstring}</li>
134 <li>{@code ctime}</li>
135 <li>{@code cwchar}</li>
136 <li>{@code new}</li>
137 <li>{@code stl_pair.h}</li>
138 <li>{@code typeinfo}</li>
139 <li>{@code utility}</li>
140</ul>
141
142<h3 id="ga">GAbi++ runtime</h3>
143<p>This runtime provides the same headers as the default runtime, but adds support for RTTI
144(RunTime Type Information) and exception handling.</p>
145
146
147<h3 id="stl">STLport runtime</h3>
148<p>This runtime is an Android port of STLport
149(<a href="http://www.stlport.org">http://www.stlport.org</a>). It provides a complete set of C++
150standard library headers. It also, by embedding its own instance of GAbi++, provides support for
151RTTI and exception handling.</p>
152
153<p>While shared and static versions of this runtime are avilable, we recommend using the shared
154version. For more information, see <a href="#sr">Static runtimes</a>.</p>
155
156<p>The shared library file is named {@code libstlport_shared.so} instead of {@code libstdc++.so}
157as is common on other platforms.</p>
158
159<p>In addition to the static- and shared-library options, you can also force the NDK to
160build the library from sources by adding the following line to your {@code Application.mk}
161file, or setting it in your environment prior to building: </p>
162
163<pre>
164STLPORT_FORCE_REBUILD := true
165</pre>
166
167
168<h3 id="gn">GNU STL runtime</h3>
169<p>This runtime is the GNU Standard C++ Library, ({@code libstdc++-v3}). Its shared library file is
170named {@code libgnustl_shared.so}.</p>
171
172
173<h3 id="cs">libC++ runtime:</h3>
174<p>This runtime is an Android port of <a href="http://libcxx.llvm.org/">LLVM libc++</a>. Its
175shared library file is named {@code libc++_shared.so}.</p>
176
177<p>By default, this runtime compiles with {@code -std=c++11}. As with GNU {@code libstdc++}, you
David Friedman14d17772015-05-26 13:21:24 -0700178need to explicitly turns on exceptions or RTTI support. For information on how to do this, see
David Friedmane23031c2015-05-22 03:20:03 -0700179<a href="#xp">C++ Exceptions</a> and <a href="#rt">RTTI</a>.</p>
180
181<p>The NDK provides prebuilt static and shared libraries for {@code libc++} compiled by Clang 3.4,
182but you can force the NDK to rebuild {@code libc++} from sources by adding the following line to
183your {@code Application.mk} file, or setting it in your environment prior to building: </p>
184
185<pre>
186LIBCXX_FORCE_REBUILD := true
187</pre>
188
189<h4>atomic support</h4>
190
Neil Fuller71fbb812015-11-30 09:51:33 +0000191<p>If you include {@code <atomic>}, it's likely that you also need {@code libatomic}.
David Friedmane23031c2015-05-22 03:20:03 -0700192If you are using {@code ndk-build}, add the following line:</p>
193
194<pre>
195LOCAL_LDLIBS += -latomic
196</pre>
197
198<p>If you are using your own toolchain, use:</p>
199
200<pre>
201-latomic
202</pre>
203
204<p class="note"><strong>Note: </strong>{@code -latomic} is only available for GCC 4.8.
205Because Clang 3.5 and Clang 3.6 use GCC 4.8's headers and libraries, as well as its
206{@code as} and {@code ld} options, those versions of Clang also get {@code -latomic}.</p>
207
208
209<h4>Compatibility</h4>
210
211<p>Around 99% of tests pass when compiling {@code libc++} with Clang 3.4 for all supported ABIs.
212The failures are mostly in the areas of {@code wchar_t} and locales that Android bionic
213doesn't support. Switching locale from the default produces the following warning in
214{@code logcat}:</p>
215
216<pre>
217newlocale() WARNING: Trying to set locale to en_US.UTF-8 other than "", "C" or "POSIX"
218</pre>
219
220<p>We do not recommend using {@code libc++} with GCC 4.6 because of GCC 4.6's limited c++11
221support.</p>
222
223<p>For information on {@code libc++} tests that fail to compile, {@code black_list*} in
224{@code $NDK/tests/device/test-libc++-shared-full/jni/Android.mk}. For information about tests
225that fail to run correctly, see {@code $NDK/tests/device/test-libc++-shared-full/BROKEN_RUN}.
226{@code $NDK}, here, is the your NDK installation's root directory.</p>
227
228
229<h2 id="ic">Important Considerations</h2>
230
231<h3 id="xp">C++ Exceptions</h3>
232<p>In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimes
233that support exception handling. However, to ensure compatibility with earlier releases, it
234compiles all C++ sources with {@code -fno-exceptions} support by default. You can enable C++
235exceptions either for your entire app, or for individual modules.
236
237<p>To enable exception-handling support for your entire app, add the following line to
David Friedman14d17772015-05-26 13:21:24 -0700238your <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file.
David Friedmane23031c2015-05-22 03:20:03 -0700239To enable exception-handling support for individual modules', add the following line to
David Friedman14d17772015-05-26 13:21:24 -0700240their respective <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files.</p>
David Friedmane23031c2015-05-22 03:20:03 -0700241
242<pre>
243APP_CPPFLAGS += -fexceptions
244</pre>
245
246<h3 id="rt">RTTI</h3>
247<p>In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimes
248that support RTTI. However, to ensure compatibility with earlier releases, it compiles all C++
249sources with {@code -fno-rtti} by default.
250
251<p>To enable RTTI support for your entire app for your entire application, add the following line to
David Friedman14d17772015-05-26 13:21:24 -0700252your <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file:
David Friedmane23031c2015-05-22 03:20:03 -0700253
254<pre>
255APP_CPPFLAGS += -frtti
256</pre>
257
258To enable RTTI support for individual modules, add the following line to
David Friedman14d17772015-05-26 13:21:24 -0700259their respective <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files:
David Friedmane23031c2015-05-22 03:20:03 -0700260
261<pre>
262LOCAL_CPP_FEATURES += rtti
263</pre>
264
265Alternatively, you can use:
266
267<pre>
268LOCAL_CPPFLAGS += -frtti
269</pre>
270
271<h3 id="sr">Static runtimes</h3>
272<p>Linking the static library variant of a C++ runtime to more than one binary may result in
273unexpected behavior. For example, you may experience:</p>
274
275<ul>
276<li>Memory allocated in one library, and freed in the other, causing memory leakage or heap
277corruption.</li>
278<li>Exceptions raised in {@code libfoo.so} going uncaught in {@code libbar.so}, causing your app
279to crash.</li>
280<li>Buffering of {@code std::cout} not working properly</li>
281</ul>
282
283<p>In addition, if you link two shared libraries&ndash;or a shared library and an executable&ndash;
284against the same static runtime, the final binary image of each shared library includes a copy of
285the runtime's code. Having multiple instances of runtime code is problematic because of duplication
286of certain global variables that the runtime uses or provides internally.</p>
287
288<p>This problem does not apply to a project comprising a single shared library. For example,
289you can link against {@code stlport_static}, and expect your app to behave correctly. If your
290project requires several shared library modules, we recommend that you use the shared library
291variant of your C++ runtime.</p>
292
293<h3>Shared runtimes</h3>
294<p>If your app targets a version of Android earlier than Android 4.3 (Android API level 18),
295and you use the shared library variant of a given C++ runtime, you must load the shared library
296before any other library that depends on it.</p>
297
298<p>For example, an app may have the following modules:</p>
299
300<ul>
301<li>libfoo.so</li>
302<li>libbar.so which is used by libfoo.so</li>
303<li>libstlport_shared.so, used by both libfoo and libbar</li>
304</ul>
305
David Friedman14d17772015-05-26 13:21:24 -0700306<p>You must load the libraries in reverse dependency order: </p>
David Friedmane23031c2015-05-22 03:20:03 -0700307<pre>
308 static {
309 System.loadLibrary("stlport_shared");
310 System.loadLibrary("bar");
311 System.loadLibrary("foo");
312 }
313</pre>
314
315<p class="note"><strong>Note: </strong>Do not use the {@code lib} prefix when calling
316{@code System.loadLibrary()}.</p>
317
318<h2 id="li">Licensing</h2>
319
320<p>STLport is licensed under a BSD-style open-source license. See
321{@code $NDK/sources/cxx-stl/stlport/README} for more details about STLport.</p>
322
323<p>GNU libstdc++ is covered by the GPLv3 license, and <em>not</em> the LGPLv2 or LGPLv3. For
324more information, see <a href="http://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html">
325License</a> on the GCC website.</p>
326
327<p><a href="https://llvm.org/svn/llvm-project/libcxx/trunk/LICENSE.TXT">LLVM {@code libc++}</a>
David Friedman14d17772015-05-26 13:21:24 -0700328is dual-licensed under both the University of Illinois "BSD-Like" license and the MIT license.</p>