From 8c0eef3d35039bcf4b555ff6f5d30be47c3840f5 Mon Sep 17 00:00:00 2001
From: David 'Digit' Turner <digit@google.com>
Date: Mon, 1 Jun 2009 21:17:04 +0200
Subject: [PATCH] Add docs/HOWTO.TXT to list a few important tips for NDK users
 Also remove reference to docs/ROADMAP.TXT from README.TXT (doh)

---
 README.TXT     |  3 +-
 docs/HOWTO.TXT | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+), 2 deletions(-)
 create mode 100644 docs/HOWTO.TXT

diff --git a/README.TXT b/README.TXT
index fc4cdad..43ea633 100644
--- a/README.TXT
+++ b/README.TXT
@@ -21,8 +21,7 @@ We recommend developers to make themselves familiar with JNI concepts. Also
 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/docs/HOWTO.TXT b/docs/HOWTO.TXT
new file mode 100644
index 0000000..d2fa95f
--- /dev/null
+++ b/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.
+
+
+
+
-- 
2.11.0