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 -> Use the default minimal C++ runtime library. 64 stlport_static -> Use STLport built as a static library. 65 stlport_shared -> Use STLport built as a shared library. 66 gnustl_static -> 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> 130
