docs: Discuss variable settings and inclusion order

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/README b/README
index c9e4c0f9234f2fe42bac8187dd98c88784bb417a..cfd7ad03d1853cc3b8e68b6847ee1df079d401ca 100644 (file)
--- a/README
+++ b/README
@@ -105,6 +105,19 @@ is already provided in subdirmk, for you to reference like this:
   &:include subdirmk/clean.sd.mk
 For example you could put that in Perdir.sd.mk.
 
   &:include subdirmk/clean.sd.mk
 For example you could put that in Perdir.sd.mk.
 

+The top-level Subdir.sd.mk is the first makefile included after the
+autogenerated `main.mk' which merely has some basic settings and
+includes.  So if you want to get in early and set global variables,
+put them near the top of Subdir.sd.mk.
+
+subdirmk's filter script itself sets (only) these variables:
+  top_srcdir
+  abs_top_srcdir
+  SUBDIRMK_MAKEFILES
+  MAKEFILE_TEMPLATES
+You are likely to want to define $(PWD), and shorter names for
+top_srdir and abs_top_srcdir (we suggest $(src) and $(abs_src)).
+

 Global definitions
 ------------------
 
 Global definitions
 ------------------