Add two sections about variables to README.md

README.md

@@ -68,6 +68,43 @@ Root directory for installation of Pd library directories. Overrides the
 default install location.
 
 
+### platform detection and predefined variables ###
+
+
+Makefile.pdlibbuilder tries to detect architecture and operating system in
+order to define platform-specific variables. Since v0.6.0 we let the compiler
+report target platform, rather than taking the build machine as reference. This
+simplifies cross compilation. The kind of build options that are predefined:
+
+- optimizations useful for realtime DSP processing
+- options strictly required for the platform
+- options to make the build work accross a range of CPU's and OS versions
+
+The exact choice and definition predefined variables changes over time, as new
+platforms arrive and older platforms become obsolete. The easiest way to get an
+overview for your platform is by checking the flags categories in the output of
+target `vars`. Variables written in capitals (like `CFLAGS`) are intentionally
+exposed as user variables, although technically all makefile variables can be
+overridden by make command arguments.
+
+
+### specific language versions ###
+
+
+Makefile.pdlibbuilder handles C and C++, but can not detect if your code uses
+features of a specific version (like C99, C++11, C++14 etc.). In such cases
+your makefile should specify that version as compiler option:
+
+    cflags = -std=c++11
+
+Also you may need to be explicit about minimum OSX version. For example, C++11
+needs OSX 10.9 or higher:
+
+    define forDarwin
+      cflags = -mmacosx-version-min=10.9
+    endef
+
+
 ### documentation ###