Add docs/HOWTO.TXT to list a few important tips for NDK users
Also remove reference to docs/ROADMAP.TXT from README.TXT (doh)
diff --git a/ndk/README.TXT b/ndk/README.TXT
index fc4cdad..43ea633 100644
--- a/ndk/README.TXT
+++ b/ndk/README.TXT
@@ -21,8 +21,7 @@
note that the NDK is *not* a good way to write non-JNI native code for the
Android platform.
-The document docs/ROADMAP.TXT gives a tentative roadmap for upcoming
-NDK features and improvements.
+See docs/HOWTO.TXT for a few useful tips and tricks when using the NDK.
Finally, discussions related to the Android NDK happen on the public
"android-ndk" forum located at the following address:
diff --git a/ndk/docs/HOWTO.TXT b/ndk/docs/HOWTO.TXT
new file mode 100644
index 0000000..d2fa95f
--- /dev/null
+++ b/ndk/docs/HOWTO.TXT
@@ -0,0 +1,98 @@
+Android NDK How-To:
+===================
+
+A collection of tips and tricks for NDK users
+
+
+How to force the display of build commands:
+-------------------------------------------
+
+Do "make APP=<yourapp> V=1" and actual build commands will be
+displayed. This can be used to verify that things are compiled
+as you expect them to, and check for bugs in the NDK build system.
+
+(The V=1 trick comes from the Linux kernel build system)
+
+
+
+How to force a rebuild of all your sources:
+-------------------------------------------
+
+Use GNU Make's "-B" option, as in:
+
+ make APP=<yourapp> -B
+
+
+How to store your native sources in under your project's path:
+--------------------------------------------------------------
+
+It is often more convenient to store your native sources at a
+different location than $NDK_ROOT/sources. For example, you would
+typically place them under the same directory than your other project
+files, to keep everything under source control, etc...
+
+The NDK build system needs to access the sources from $NDK_ROOT/sources
+and your Application.mk from $NDK_ROOT/apps/<name>. This is essentially
+to keep its implementation sane and simple, and to ensure that certain
+features, like automatic dependency management, work reliably.
+
+You can however use simple symlinks to redirect paths to your project's
+storage location. For example:
+
+ $NDK_ROOT/sources/<foo> ----> $PROJECT_PATH/jni/<foo>
+ $NDK_ROOT/apps/<foo> ----> $PROJECT_PATH/jni/<foo>
+
+Where $PROJECT_PATH/jni/<foo> contains both an Android.mk and an
+Application.mk. Note that things like $(call my-dir) will always evaluate
+to the NDK paths (i.e. $NDK_ROOT/sources/<foo>) at build time.
+
+Windows users: The NDK is only supported on Cygwin, which implements
+symbolic links through the "ln -s" command, as in:
+
+ ln -s <target> <link>
+
+
+How to properly add include directories to your module declaration:
+-------------------------------------------------------------------
+
+If you define several modules, it is common to need to include one
+module's header while compiling another one. For example, consider
+the following example:
+
+ $NDK_ROOT/sources/foo/
+ Android.mk
+ foo.h
+ foo.c
+
+ $NDK_ROOT/sources/bar/
+ Android.mk
+ bar.c
+
+Where the 'bar.c' uses '#include <foo.h>'. You will need to add the
+path to the 'foo' module in bar/Android.mk to build it properly.
+
+One is tempted to use the following:
+
+ LOCAL_CPPFLAGS := -I../foo
+
+However this will not work because all compilation happens from the
+root NDK directory (i.e. $NDK_ROOT), and include files must be relative
+to it. The above line really translates to:
+
+ LOCAL_CPPFLAGS := -I$(NDK_ROOT)/../foo
+
+Which adds a non-existing directory to the C include path. The correct
+line is instead:
+
+ LOCAL_CPPFLAGS := -Isources/foo
+
+Or even better:
+
+ LOCAL_CPPFLAGS := $(LOCAL_PATH)/../foo
+
+Which uses a path relative to $(LOCAL_PATH), in the case where you would
+need to move 'foo' and 'bar' to a deeper level in the 'sources' hierarchy.
+
+
+
+