Document changes since v7.0.2 in user-facing READMEs

Author: DrGeoff

src/compiletools/README.ct-cake.rst

@@ -129,6 +129,28 @@ add, say:
 Because the code and build flags are defined so close to each other, its
 much easier to tweak the compilation locally.
 
+CPPFLAGS and CXXFLAGS
+---------------------
+
+By default, CPPFLAGS and CXXFLAGS are unified into a single deduplicated set.
+This means flags specified via ``//#CPPFLAGS=`` or ``--CPPFLAGS`` are also
+applied as CXXFLAGS and vice versa. Use ``--separate-flags-CPP-CXX`` to keep
+them separate if your build requires different flags for preprocessing and
+compilation.
+
+Computed Includes
+-----------------
+
+ct-cake's ``direct`` dependency mode (the default) now resolves computed
+``#include`` directives where the path is specified via a macro, for example:
+
+.. code-block:: cpp
+
+    #define PLATFORM_HEADER "linux_extra.h"
+    #include PLATFORM_HEADER
+
+Previously this required ``--headerdeps=cpp`` to track correctly.
+
 Performance
 ===========
 

src/compiletools/README.ct-commandline.rst

@@ -37,6 +37,20 @@ OPTIONS
     are merged with system and user configs according to precedence rules:
     command line > environment variables > config files > defaults.
 
+--include PATH [PATH ...]
+    Extra path(s) to add to the include search path. Accepts one or more
+    space-separated paths, e.g. ``--include path/to/headers another/path``.
+
+--CPPFLAGS FLAGS [FLAGS ...]
+    C preprocessor flags (override). By default unified with CXXFLAGS.
+
+--CXXFLAGS FLAGS [FLAGS ...]
+    C++ compiler flags (override). By default unified with CPPFLAGS.
+
+--separate-flags-CPP-CXX
+    Keep CPPFLAGS and CXXFLAGS as separate values instead of merging them.
+    By default they are unified into a single deduplicated set.
+
 -v, --verbose
     Increase output verbosity. Can be specified multiple times for more detail
     (e.g., ``-vv`` or ``-v -v``).

src/compiletools/README.ct-cppdeps.rst

@@ -30,16 +30,16 @@ filename [filename ...]
 DESCRIPTION
 ===========
 ct-cppdeps generates the header dependencies for the file you specify at the
-command line.  There are two possible methodologys:
+command line.  There are two possible methodologies:
 
-* "--headerdeps=direct" uses a regex to find the "#include" lines in the source
-  code. This methodology is fast and is supposed to generate the same results as
-  using the compiler to preprocess the file.  However, its own simple
-  preprocessor does not handle all the complexities of a real C/C++
-  preprocessor and so it is possible to generate incorrect results.
-
-* "--headerdeps=cpp" executes "$CPP -MM -MF" which is slower but guarantees correctness.
+* ``--headerdeps=direct`` (default) uses a built-in preprocessor to find
+  ``#include`` directives. It handles conditional compilation (``#if``,
+  ``#ifdef``, ``#ifndef``, ``#undef``) and computed includes where the path
+  is specified via a macro, e.g. ``#include PLATFORM_HEADER``. This is fast
+  and correct for the vast majority of real-world code.
 
+* ``--headerdeps=cpp`` executes ``$CPP -MM -MF``, which is slower but
+  delegates entirely to the system compiler's preprocessor.
 
 The tool recursively follows #include directives to discover all header files
 that the specified source file depends upon, either directly or transitively.

src/compiletools/README.ct-headertree.rst

@@ -21,6 +21,11 @@ DESCRIPTION
 ===========
 Create a tree of header dependencies starting at a given C/C++ file.
 
+The default ``direct`` mode uses a built-in preprocessor that handles
+conditional compilation (``#if``, ``#ifdef``, ``#ifndef``, ``#undef``) and
+computed includes (``#include MACRO_NAME``). Use ``--headerdeps=cpp`` to
+delegate to the system compiler's preprocessor instead.
+
 OPTIONS
 =======
   --style {tree,depth,dot,flat}

src/compiletools/README.ct-magicflags.rst

@@ -89,6 +89,13 @@ preferred over manual ``LDFLAGS`` because:
 The PKG-CONFIG magic flag works with any library that provides a .pc file,
 including common libraries like gtk+-3.0, libpng, libcurl, openssl, and many more.
 
+CPPFLAGS and CXXFLAGS Unification
+==================================
+By default, ``CPPFLAGS`` and ``CXXFLAGS`` magic flags are merged into a single
+deduplicated set. A flag set via ``//#CPPFLAGS=`` is also applied as a CXXFLAGS
+and vice versa. Use ``--separate-flags-CPP-CXX`` on the command line to keep
+them separate.
+
 VALID MAGIC FLAGS
 =================
 A magic flag follows the pattern ``//#key=value``. Whitespace around the