From 4b21203e46f9f134b4a5df4bfbfebf9b875d3677 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Mon, 4 Dec 2023 07:58:55 +0200
Subject: Document c.predefs and cxx.predefs functionality

---
 doc/manual.cli | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 87 insertions(+), 6 deletions(-)

(limited to 'doc/manual.cli')

diff --git a/doc/manual.cli b/doc/manual.cli
index 7731609..f6541b9 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -8180,7 +8180,7 @@ be customized with the \c{extension} variable.
 
 \h#c-objc|Objective-C Compilation|
 
-The \c{c} module provides the \c{c.objc} submodules which can be loaded in
+The \c{c} module provides the \c{c.objc} submodule which can be loaded in
 order to register the \c{m{\}} target type and enable Objective-C compilation
 in the \c{C} compile rule. Note that \c{c.objc} must be loaded after the \c{c}
 module and while the \c{m{\}} target type is registered unconditionally,
@@ -8209,14 +8209,12 @@ automatically link any necessary Objective-C runtime library (such as
 
 \h#c-as-cpp|Assembler with C Preprocessor Compilation|
 
-The \c{c} module provides the \c{c.as-cpp} submodules which can be loaded in
+The \c{c} module provides the \c{c.as-cpp} submodule which can be loaded in
 order to register the \c{S{\}} target type and enable Assembler with C
 Preprocessor compilation in the \c{C} compile rule. Note that \c{c.as-cpp}
 must be loaded after the \c{c} module and while the \c{S{\}} target type is
 registered unconditionally, compilation is only enabled if the C compiler
-supports Assembler with C Preprocessor compilation.
-
-Typical usage:
+supports Assembler with C Preprocessor compilation. Typical usage:
 
 \
 # root.build
@@ -8290,6 +8288,46 @@ if $assembler
 }
 \
 
+\h#c-predefs|C Compiler Predefined Macro Extraction|
+
+The \c{c} module provides the \c{c.predefs} submodule which can be loaded in
+order to register a rule that generates a C header with predefined compiler
+macros. Note that the \c{c.predefs} module must be loaded after the \c{c}
+module and the rule will only match with an explicit rule hint. Typical usage:
+
+\
+# root.build
+#
+using c
+using c.predefs
+\
+
+\
+# buildfile
+#
+[rule_hint=c.predefs] h{predefs}:
+\
+
+Note also that the MSVC compiler only supports the predefined macro extraction
+starting from Visual Studio 2019 (16.0; \c{cl.exe} version 19.20). If support
+for earlier versions is required, then you will need to provide a fallback
+implementation appropriate for your project. For example:
+
+\
+[rule_hint=c.predefs] h{predefs}:
+% update
+if ($c.id == 'msvc' && \
+    ($c.version.major < 19 || \
+     ($c.version.major == 19 && $c.version.minor < 20)))
+{{
+  diag c-predefs $>
+
+  cat <<EOF >$path($>)
+  #define _WIN32
+  EOF
+}}
+\
+
 
 \h1#module-cxx|\c{cxx} Module|
 
@@ -9984,7 +10022,7 @@ purviews.
 
 \h#cxx-objcxx|Objective-C++ Compilation|
 
-The \c{cxx} module provides the \c{cxx.objcxx} submodules which can be loaded
+The \c{cxx} module provides the \c{cxx.objcxx} submodule which can be loaded
 in order to register the \c{mm{\}} target type and enable Objective-C++
 compilation in the \c{C++} compile rule. Note that \c{cxx.objcxx} must be
 loaded after the \c{cxx} module and while the \c{mm{\}} target type is
@@ -10011,6 +10049,49 @@ made to automatically link any necessary Objective-C runtime library (such as
 \c{-lobjc}).
 
 
+\h#cxx-predefs|C++ Compiler Predefined Macro Extraction|
+
+The \c{cxx} module provides the \c{cxx.predefs} submodule which can be loaded
+in order to register a rule that generates a C++ header with predefined
+compiler macros. Note that the \c{cxx.predefs} module must be loaded after the
+\c{cxx} module and the rule will only match with an explicit rule
+hint. Typical usage:
+
+\
+# root.build
+#
+using cxx
+using cxx.predefs
+\
+
+\
+# buildfile
+#
+[rule_hint=cxx.predefs] hxx{predefs}:
+\
+
+Note also that the MSVC compiler only supports the predefined macro extraction
+starting from Visual Studio 2019 (16.0; \c{cl.exe} version 19.20). If support
+for earlier versions is required, then you will need to provide a fallback
+implementation appropriate for your project. For example:
+
+\
+[rule_hint=cxx.predefs] hxx{predefs}:
+% update
+if ($cxx.id == 'msvc' && \
+    ($cxx.version.major < 19 || \
+     ($cxx.version.major == 19 && $cxx.version.minor < 20)))
+{{
+  diag c++-predefs $>
+
+  cat <<EOF >$path($>)
+  #define _WIN32
+  #define __cplusplus 201402L
+  EOF
+}}
+\
+
+
 \h1#module-in|\c{in} Module|
 
 The \c{in} build system module provides support for \c{.in} (input) file
-- 
cgit v1.1