Fix android#84. Add supporting docs.

CHANGELOG.md

@@ -0,0 +1,81 @@
+Changelog
+=========
+
+Report issues to [GitHub].
+
+[GitHub]: https://github.com/android-ndk/ndk/issues
+
+NDK
+---
+ * Removed all sysroots for pre-GB platform levels. We dropped support for them
+   in r11, but neglected to actually remove them.
+ * Exception handling when using `c++_shared` on ARM32 now mostly works (see
+   [Known Issues](#known-issues)). The unwinder will now be linked into each
+   linked object rather than into libc++ itself.
+ * Default compiler flags have been pruned:
+   https://github.com/android-ndk/ndk/issues/27.
+     * Full changes here: https://android-review.googlesource.com/#/c/207721/5.
+ * `-fno-limit-debug-info` has been enabled by default for Clang debug builds.
+   This should improve debugability with LLDB.
+ * `--build-id` is now enabled by default.
+     * This will be shown in native crash reports so you can easily identify
+       which version of your code was running.
+ * `NDK_USE_CYGPATH` should no longer cause problems with libgcc:
+   http://b.android.com/195486.
+ * `-Wl,--warn-shared-textrel` and`-Wl,--fatal-warnings` are now enabled by
+   default. If you have shared text relocations, your app will not load on
+   Marshmallow or later (and have never been allowed for 64-bit apps).
+ * Precompiled headers should work better:
+   https://github.com/android-ndk/ndk/issues/14 and
+   https://github.com/android-ndk/ndk/issues/16.
+
+Clang
+-----
+
+ * Clang has been updated to 3.8svn (r256229, build 2690385).
+     * Note that Clang packaged in the Windows 64 NDK is actually 32-bit.
+ * `__thread` should work for real this time.
+
+GCC
+---
+
+ * Synchronized with the ChromeOS GCC @ `google/gcc-4_9` r227810.
+ * Backported coverage sanitizer patch from ToT (r231296).
+ * Fixed libatomic to not use ifuncs:
+   https://github.com/android-ndk/ndk/issues/31.
+
+Binutils
+--------
+
+ * "Erratum 843419 found and fixed" info messages are silenced.
+ * Introduced option '--long-plt' to fix internal linker error when linking huge
+   arm32 binaries.
+ * Fixed wrong run time stubs for AArch64. This was causing jump addresses to be
+   calculated incorrectly for very large DSOs.
+ * Introduced default option '--no-apply-dynamic' to work around a dynamic
+   linker bug for earlier Android releases.
+ * NDK r11 KI for `dynamic_cast` not working with Clang, x86, `stlport_static`
+   and optimization has been fixed.
+
+GDB
+---
+
+ * Updated to GDB 7.11: https://www.gnu.org/software/gdb/news/.
+
+Known Issues
+------------
+
+ * This is not intended to be a comprehensive list of all outstanding bugs.
+ * x86 ASAN still does work. See discussion on
+   https://android-review.googlesource.com/#/c/186276/
+ * Exception unwinding with `c++_shared` still does not work for ARM on
+   Gingerbread or Ice Cream Sandwich.
+ * Bionic headers and libraries for Marshmallow and N are not yet exposed
+   despite the presence of android-24. Those platforms are still the Lollipop
+   headers and libraries (not a regression from r11).
+ * RenderScript tools are not present (not a regression from r11):
+   https://github.com/android-ndk/ndk/issues/7.
+ * r12 will most likely not work with Android Studio/Gradle right away. The
+   Gradle plugin will need to be updated to match the build changes we made in
+   `ndk-build`.
+ * We've regressed on http://b.android.com/41770.

OWNERS

@@ -0,0 +1,10 @@
+danalbert
+enh
+jmgao
+
+# For questions rather than code review, send email to:
+#
+# android-ndk@google.com (Googlers only)
+# android-ndk@googlegroups.com (public)
+#
+# Ask on Stack Overflow: http://stackoverflow.com/questions/tagged/android-ndk.

README.md

@@ -0,0 +1,137 @@
+Android Native Development Kit (NDK)
+====================================
+
+The latest version of this document is available at
+https://android.googlesource.com/platform/ndk/+/master/README.md.
+
+**Note:** This document is for developers _of_ the NDK, not developers
+that use the NDK.
+
+The NDK allows Android application developers to include
+native code in their Android application packages, compiled as JNI shared
+libraries.
+
+Other Resources
+---------------
+
+This doc gives a high level overview of the NDK's build, packaging, and test
+process. For other use cases, or more in depth documentation, refer to the
+following sources:
+
+ * User documentation is available on the [Android Developer website].
+ * Adding a new NDK API or platform version? Check [Generating Sysroots].
+ * Working on Clang or GCC? See [Toolchains.md].
+ * Discussions related to the Android NDK happen on the [android-ndk Google
+   Group].
+ * File bugs against the NDK at https://github.com/android-ndk/ndk/issues.
+
+[Android Developer website]: https://developer.android.com/ndk/index.html
+[android-ndk Google Group]: http://groups.google.com/group/android-ndk
+[Generating Sysroots]: docs/GeneratingSysroots.md
+[Toolchains.md]: docs/Toolchains.md
+
+Building the NDK
+================
+
+Both Linux and Windows host binaries are built on Linux machines. Windows host
+binaries are built via MinGW cross compiler. Systems without a working MinGW
+compiler can use `build/tools/build-mingw64-toolchain.sh` to generate their own
+and be added to the `PATH` for build scripts to discover.
+
+Building binaries for Mac OS X requires at least 10.8.
+
+Target headers and binaries are built on Linux.
+
+Components
+----------
+
+The NDK consists of three parts: host binaries, target prebuilts, and others
+(build system, docs, samples, tests).
+
+### Host Binaries
+
+* `toolchains/` contains GCC and Clang toolchains.
+    * `$TOOLCHAIN/config.mk` contains ARCH and ABIS this toolchain can handle.
+    * `$TOOLCHAIN/setup.mk` contains toolchain-specific default CFLAGS/LDFLAGS
+      when this toolchain is used.
+* `prebuilt/$HOST_TAG` contains build dependencies and additional tools.
+    * make, awk, python, yasm, and for Windows: cmp.exe and echo.exe
+    * `ndk-depends`, `ndk-stack` and `ndk-gdb` can also be found here.
+
+### Target Headers and Binaries
+
+* `platforms/android-$VERSION/arch-$ARCH_NAME/` contains headers and libraries
+  for each API level.
+    * The build system sets `--sysroot` to one of these directories based on
+      user-specified `APP_ABI` and `APP_PLATFORM`.
+* `sources/cxx-stl/$STL` contains the headers and libraries for the various C++
+  STLs.
+* `prebuilt/android-$ARCH/gdbserver` contains gdbserver.
+
+### Others
+
+* `build/` contains the ndk-build system and scripts to rebuild NDK.
+* `sources/android` and `sources/third_party` contain modules that can be used
+  in apps (cpufeatures, native\_app\_glue, etc) via `$(call import-module,
+  $MODULE)`
+* `tests/`
+
+Prerequisites
+-------------
+
+* [AOSP NDK Repository](http://source.android.com/source/downloading.html)
+    * Check out the branch `master-ndk`
+
+        ```bash
+        repo init -u https://android.googlesource.com/platform/manifest \
+            -b master-ndk
+
+        # Googlers, use
+        repo init -u \
+            persistent-https://android.git.corp.google.com/platform/manifest \
+            -b master-ndk
+        ```
+
+* Additional Linux Dependencies (available from apt):
+    * bison
+    * flex
+    * libtool
+    * mingw-w64
+    * pbzip2 (optional, improves packaging times)
+    * texinfo
+    * python3 (used for Vulkan validation layer generation)
+    * python-lxml (used for Vulkan validation layer generation)
+* Mac OS X also requires Xcode.
+
+Host/Target prebuilts
+---------------------
+
+### For Linux or Darwin:
+
+```bash
+$ python checkbuild.py
+```
+
+### For Windows, from Linux:
+
+```bash
+$ python checkbuild.py --system windows  # Or windows64.
+```
+
+`checkbuild.py` also accepts a variety of other options to speed up local
+builds, namely `--arch` and `--module`.
+
+Packaging
+---------
+
+By default, `checkbuild.py` will also package the NDK and run basic tests. To
+skip the packaging step, use the `--no-package` flag. Note that running the
+tests does require the packaging step.
+
+If you need to re-run just the packaging step without going through a build,
+packaging is handled by `build/tools/package.py`.
+
+Testing
+-------
+
+Testing is discussed in [Testing.md](docs/Testing.md).

docs/GeneratingSysroots.md

@@ -0,0 +1,87 @@
+Generating NDK Sysroots
+=======================
+
+The latest version of this document is available at
+https://android.googlesource.com/platform/ndk/+/master/docs/GeneratingSysroots.md.
+
+The `platforms/` subtree of an NDK package contains sysroots for each
+architecture and API level. The contents of these sysroots are generated as part
+of the NDK build.
+
+The Sysroot Defintions
+----------------------
+
+The contents of the sysroots are defined by `development/ndk/platforms`.
+Note that this is from the top level of the Android tree, not within the `ndk/`
+subdirectory.
+
+The layout of this tree is as follows:
+
+ * `android-$VERSION`
+     * `include`
+     * `arch-$ARCH`
+         * `include`
+             * Architecture specific headers. Typically the `asm` and `machine`
+               directories.
+         * `lib`
+             * Prebuilt static libraries.
+             * Note that for the time being these are only libc, libm, libz, and
+               libstdc++, and that they are rarely updated (we have versions for
+               android-3, android-9, and android-21, but not any other
+               releases).
+         * `src`
+             * Source for the CRT objects (crtbegin, crtend, etc.).
+         * `symbols`
+             * Contains interface definitions for the shared platform libraries.
+             * Discussed in detail in [Shared Library Definitions].
+
+These trees are a very reduced form of a sysroot. Not every header or library
+will be in every platform version. Instead, [gen-platforms.sh] will build the
+full sysroot from what is defined here. This is done to ease maintenance of the
+headers and libraries. If, for example, `string.h` remained the same between
+Gingerbread and KitKat, but was updated in Lollipop, there need only be a copy
+of `string.h` in android-9 and android-21, not in every intermediate release.
+
+Shared Library Defintions
+-------------------------
+
+When an NDK binary links against a platform library, rather than shipping a copy
+of the library with the binary, it loads the library from the system itself (in
+the case of an app, many of the libraries will already be loaded into the
+address space by the zygote). As such, the shared libraries in the NDK do not
+need to be valid aside from the symbols they expose. This simplifies things,
+because all we need to generate the shared libraries for a given architecture
+and platform version is a list of functions and variables.
+
+The `android-$VERSION/arch-$ARCH/symbols/*.txt` files contain these library
+definitions. Each file is named either `$LIBNAME.functions.txt` or
+`$LIBNAME.variables.txt`. For each such file, [gen-platforms.sh] will create a
+stub shared library for that library with the functions and variables defined in
+those lists.
+
+For some platform versions (currently only android-23), there is also a
+`$LIBNAME.versions.txt`. This is a linker version script that will be used to
+apply symbol versions when generating the stub shared library.
+
+Examples of each of these three file types can be found in
+[development/ndk/platforms/android-23/arch-arm64/symbols].
+
+Adding a New Platform API
+-------------------------
+
+These instructions are valid both for adding new native frameworks APIs and
+updating bionic.
+
+ 1. If the platform version you are adding your API to does not yet exist, there
+    are no special steps; just make the new directory.
+ 2. Add your (possibly new, possibly updated) headers to the include directory.
+ 3. Add [Shared Library Definitions] files for each architecture to the
+    `arch-$ARCH/symbols` directory.
+ 4. Add tests to [tests/device](../tests/device).
+ 5. Build and test an NDK (see [README.md](../README.md)).
+ 6. Upload your change(s) and add the current [NDK owners](../OWNERS) as
+    reviewers.
+
+[Shared Library Definitions]: #shared-library-defintions
+[gen-platforms.sh]: ../build/tools/gen-platforms.sh
+[development/ndk/platforms/android-23/arch-arm64/symbols]: https://android.googlesource.com/platform/development/+/master/ndk/platforms/android-23/arch-arm64/symbols