Document ndk-build NDK_DEBUG=1 properly.

Change-Id: Ic030c628613b6765c423ad9e900c18a9be083a8f
diff --git a/docs/CHANGES.TXT b/docs/CHANGES.TXT
index e0ecad9..111827e 100644
--- a/docs/CHANGES.TXT
+++ b/docs/CHANGES.TXT
@@ -16,6 +16,10 @@
 - ndk-gdb: do not start activity unless --start or --launch is used.
   (the documentation was correct, the implementation wrong)
 
+- The system headers for all API levels have been cleaned up and will
+  not provide the declarations of functions that are not available in
+  the corresponding system libraries.
+
 IMPORTANT CHANGES:
 
 - Support for API level 9, which adds the following native features to the
@@ -48,20 +52,24 @@
 
        Note that most of these new features are targetted at game developers.
 
-- Support for module exports: A module can now define a set of compiler or
-  linker flags that will be automatically 'imported' by any other module that
-  depends on it, through LOCAL_STATIC_LIBRARIES or LOCAL_SHARED_LIBRARIES.
+- Easier debuggable builds: just invoke ndk-build while defining the
+  NDK_DEBUG variable to 1, as in:
 
-  This is achieved with the help of new Android.mk variables named
-  LOCAL_EXPORT_CFLAGS, LOCAL_EXPORT_CPPFLAGS, LOCAL_EXPORT_C_INCLUDES and
-  LOCAL_EXPORT_LDLIBS. See docs/ANDROID-MK.TXT for mode documentation, and
-  a 'samples/module-exports' for a sample project that uses this.
+      $NDK/ndk-build NDK_DEBUG=1
+
+  This will have the same result that setting the android:debuggable="true"
+  in the <application> element of your AndroidManifest.xml file. See the
+  file docs/NDK-BUILD.TXT for more details.
+
+  Note that you will need to use the SDKr8 build tools to use this feature
+  properly!
 
 - Refresh of system C++ headers:
 
      - Headers have been moved out of the platform directory hierarchy.
        This is to prevent conflicts with other STLs like STLport or the
-       GNU libstdc++ which provide their own version of the headers.
+       GNU libstdc++ which provide their own version of the headers, but
+       does not affect your builds.
 
      - The list of headers has grown to include the following:
 
@@ -76,6 +84,15 @@
   PREBUILT_STATIC_LIBRARIES build scripts. See the new documentation
   file named docs/PREBUILTS.TXT for explanations and usage examples.
 
+- Support for module exports: A module can now define a set of compiler or
+  linker flags that will be automatically 'imported' by any other module that
+  depends on it, through LOCAL_STATIC_LIBRARIES or LOCAL_SHARED_LIBRARIES.
+
+  This is achieved with the help of new Android.mk variables named
+  LOCAL_EXPORT_CFLAGS, LOCAL_EXPORT_CPPFLAGS, LOCAL_EXPORT_C_INCLUDES and
+  LOCAL_EXPORT_LDLIBS. See docs/ANDROID-MK.TXT for mode documentation, and
+  a 'samples/module-exports' for a sample project that uses this.
+
 - Add support to specify a different file name for generated files, through
   the new LOCAL_MODULE_FILENAME variable. See docs/ANDROID-MK.TXT for an
   example.
@@ -87,8 +104,9 @@
   See docs/IMPORT-MODULE.TXT for details.
 
 - Add the content of LOCAL_C_INCLUDES to gdb.setup to make native debugging
-  easier. Also fixes an issue that prevented clean parallel builds of debuggable
-  applications to work correctly. This fixes an error message that said:
+  easier. Also fixes an issue that prevented clean parallel builds of
+  debuggable applications to work correctly. This fixes an error message that
+  said:
 
       /bin/sh: <project>/libs/armeabi/gdb.setup: No such file or directory
 
diff --git a/docs/NDK-BUILD.TXT b/docs/NDK-BUILD.TXT
index c25ae3c..96fd843 100644
--- a/docs/NDK-BUILD.TXT
+++ b/docs/NDK-BUILD.TXT
@@ -38,6 +38,9 @@
   ndk-build NDK_LOG=1        --> display internal NDK log messages
                                  (used for debugging the NDK itself).
 
+  ndk-build NDK_DEBUG=1      --> force a debuggable build (see below)
+  ndk-build NDK_DEBUG=0      --> force a release build (see below)
+
   ndk-build NDK_APP_APPLICATION_MK=<file>
     --> rebuild, using a specific Application.mk pointed to by
         the NDK_APP_APPLICATION_MK command-line variable.
@@ -47,8 +50,37 @@
                                  don't want to 'cd' to it in your terminal.
 
 
-III. Requirements:
-------------------
+III. Debuggable versus Release builds:
+--------------------------------------
+
+In NDK r5, ndk-build has been modified to make it easier to switch between
+release and debug builds. This is done by using the NDK_DEBUG variable.
+For example:
+
+  $NDK/ndk-build NDK_DEBUG=1  => forces the generation of debug binaries
+  $NDK/ndk-build NDK_DEBUG=0  => forces the generation of release binaries
+
+If you don't specify NDK_DEBUG, ndk-build will keep its default behaviour,
+which is to inspect the AndroidManifest.xml, if any, and see if its
+<application> element has android:debuggable="true".
+
+IMPORTANT: If you use the build tools of SDK r8 (or higher), you
+           won't need to touch your AndroidManifest.xml file at all!
+
+           That's because if you build a debug package (e.g. with
+           "ant debug" or the corresponding option of the ADT plugin),
+           the tool will  automatically pick the native debug files
+           generated with NDK_DEBUG=1.
+
+Also, as a convenience, the release and debug object files generated by the
+NDK are now stored in different directories (e.g. obj/local/<abi>/objs and
+obj/local/<abi>/objs-debug). This avoids having to recompile all your sources
+when you switch between these two modes (even when you only modified one or
+two source files).
+
+
+IV. Requirements:
+-----------------
 
 You need GNU Make 3.81 or later to use 'ndk-build' or the NDK in general.
 The build scripts will detect that you're using a non-compliant Make tool
@@ -68,8 +100,8 @@
 Adapt to your shell and GNU Make 3.81 installation location.
 
 
-III. Internals:
----------------
+V. Internals:
+-------------
 
 'ndk-build' itself is a tiny wrapper around GNU Make, its purpose is simply
 to invoke the right NDK build script, it is equivalent to;