1This is a copy of LLVM's libc++ project, slightly modified to build
2with this NDK. It's currently *EXPERIMENTAL*.
3
4Upstream: See 'upstream.config' file in this directory.
5Patches: see patches.android/
6Tracking: 36496
7
8This is a version of LLVM's libc++ that was modified to be built
9with GAbi++. At the moment, only linking a small test executable is
10supported, and it will very likely crash as soon as you start it.
11
12It also includes Android-specific support code, providing missing C
13library functionality, under android/support. Most of the code there
14consists in stubs waiting for a real implementation.
15
16All patches are under patches.android/ to make it easier to update
17the upstream revision of the library while working on this.
18
19You need a recent NDK release, one which provides a version
20of the GAbi++ C++ runtime that supports rtti _and_ exceptions.
21
22Build instructions:
23
24  1/ Set NDK to the path of a recent Android NDK install path
25     (Use Android NDK r8e or above), e.g.:
26
27      NDK=$HOME/android/ndk-r8e
28
29  2/ From the top-level directory, do:
30
31      $NDK/ndk-build -C android/test
32
33     This is actually equivalent to:
34
35      cd android/test
36      $NDK/ndk-build
37
38  3/ To see build commands, use V=1, as in:
39
40      $NDK/ndk-build -C android/test V=1
41
42
43Android support files:
44
45  android/support/include:
46     Android system header wrappers, to add missing declarations
47
48  android/support/src:
49     Put the implementation of the missing system functions here.
50
51  Android.mk:
52     Main build file for the library. This builds one static and
53     one shared version of the library.
54
55     If modifications are not obvious, read $NDK/docs/ANDROID-MK.html
56     for a description of the Android.mk format.
57
58  android/test/jni:
59     NDK build project for two test programs that link against the
60     static and shared versions of the library.
61
62     See the Android.mk and Application.mk files in this directory
63     if you want to add new test files.
64
65
66Toolchain selection:
67  By default, ndk-build tries to build with GCC 4.6, however, experimental
68  versions of GCC 4.8 and Clang 3.4 are available with recent NDK releases.
69
70  Use the NDK_TOOLCHAIN_VERSION environment variable to switch to a
71  different one, valid examples:
72
73
74    export NDK_TOOLCHAIN_VERSION=4.6    # this is the default
75    $NDK/ndk-build -C android/test
76
77    # This is equivalent, but for GCC 4.8
78    $NDK/ndk-build -C android/test NDK_TOOLCHAIN_VERSION=4.8
79
80    # Also equivalent, but for Clang 3.4
81    NDK_TOOLCHAIN_VERSION=Clang3.4 $NDK/ndk-build -C android/test
82
83
84Updating the sources to a newer revision:
85
86  You can use the tools/update-upstream.sh script to automatically try
87  to update to a more recent version of the upstream sources.
88
89  In case of success, this adds all relevant changes to the current git
90  index so you can review them before committing them.
91
92  In case of problem, try using the --verbose and --no-cleanup options
93  to see the details of the failure. This may require manually updating
94  the patch files.
95