Document project-specific configuration support

1 files changed, 775 insertions, 18 deletions

diff --git a/doc/manual.cli b/doc/manual.cli
index 5aea9c1..8821771 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -565,15 +565,15 @@ summary: hello C++ executable
 \
 
 The \c{config} module provides support for persistent configurations. While
-project configuration is a large topic that we will discuss in detail later,
-in a nutshell \c{build2} support for configuration is an integral part of the
-build system with the same mechanisms available to the build system core,
-modules, and your projects. However, without \c{config}, the configuration
-information is \i{transient}. That is, whatever configuration information was
-automatically discovered or that you have supplied on the command line is
-discarded after each build system invocation. With the \c{config} module,
-however, we can \i{configure} a project to make the configuration
-\i{persistent}. We will see an example of this shortly.
+build configuration is a large topic that we will be discussing in more detail
+later, in a nutshell \c{build2} support for configuration is an integral part
+of the build system with the same mechanisms available to the build system
+core, modules, and your projects. However, without \c{config}, the
+configuration information is \i{transient}. That is, whatever configuration
+information was automatically discovered or that you have supplied on the
+command line is discarded after each build system invocation. With the
+\c{config} module, however, we can \i{configure} a project to make the
+configuration \i{persistent}. We will see an example of this shortly.
 
 Next up are the \c{test}, \c{install}, and \c{dist} modules. As their names
 suggest, they provide support for testing, installation and preparation of
@@ -583,9 +583,11 @@ operations, and the \c{dist} module defines the \c{dist}
 (meta-)operation. Again, we will try them out in a moment.
 
 Moving on, the \c{root.build} file is optional though most projects will have
-it. This is the place where we normally establish project-wide settings as
-well as load build system modules that provide support for the languages/tools
-that we use. Here is what it could look like for our \c{hello} example:
+it. This is the place where we define project's configuration variables
+(subject of \l{#proj-config Project Configuration}), establish project-wide
+settings, as well as load build system modules that provide support for the
+languages/tools that we use. Here is what it could look like for our \c{hello}
+example:
 
 \
 cxx.std = latest
@@ -1391,7 +1393,7 @@ if ($c.target.class != 'windows')
   c.libs += -lpthread  # only C
 \
 
-Additionally, as we will see in \l{#intro-operations-config Configuration},
+Additionally, as we will see in \l{#intro-operations-config Configuring},
 there are also the \c{config.cc.*}, \c{config.c.*}, and \c{config.cxx.*} sets
 which are used by the users of our projects to provide external configuration.
 The initial values of the \c{cc.*}, \c{c.*}, and \c{cxx.*} variables are taken
@@ -1620,11 +1622,11 @@ Other than \c{version}, all the modules we load define new operations. Let's
 examine each of them starting with \c{config}.
 
 
-\h2#intro-operations-config|Configuration|
+\h2#intro-operations-config|Configuring|
 
 As mentioned briefly earlier, the \c{config} module provides support for
 persisting configurations by having us \i{configure} our projects. At first it
-may feel natural to call \c{configure} another operation. There is, however, a
+may feel natural to call \c{configure} an operation. There is, however, a
 conceptual problem: we don't really configure a target. And, perhaps after
 some meditation, it should become clear that what we are really doing is
 configuring operations on targets. For example, configuring updating a C++
@@ -2102,7 +2104,7 @@ For details on the unit test support implementation see \l{#intro-unit-test
 Implementing Unit Testing}.|
 
 
-\h2#intro-operations-install|Installation|
+\h2#intro-operations-install|Installing|
 
 The \c{install} module defines the \c{install} and \c{uninstall} operations.
 As the name suggests, this module provides support for project installation.
@@ -2287,7 +2289,7 @@ header would have been installed as
 \c{.../include/libhello/details/utility.hxx}.
 
 
-\h2#intro-operations-dist|Distribution|
+\h2#intro-operations-dist|Distributing|
 
 The last module that we load in our \c{bootstrap.build} is \c{dist} which
 provides support for the preparation of distributions and defines the \c{dist}
@@ -3063,7 +3065,7 @@ libhello/
 \
 
 And we want to build them with several compilers, let's say GCC and Clang. As
-we have already seen in \l{#intro-operations-config Configuration}, we can
+we have already seen in \l{#intro-operations-config Configuring}, we can
 configure several out of source builds for each compiler, for example:
 
 \
@@ -4336,6 +4338,737 @@ the number of jobs to perform in parallel, the stack size, queue depths, etc.
 See the \l{b(1)} man pages for details.
 
 
+\h1#proj-config|Project Configuration|
+
+As discussed in the introduction (specifically, \l{#intro-proj-struct Project
+Structure}) support for build configurations is an integral part of \c{build2}
+with the same mechanism used by the build system core (for example, for
+project importation via the \c{config.import.*} variables), by the build
+system modules (for example, for supplying compile options such as
+\c{config.cxx.coptions}), as well as by our projects to provide any
+project-specific configurability. Project configuration is the topic of this
+chapter.
+
+\N|The \c{build2} build system currently provides no support for
+\c{autoconf}-style probing of the build environment in order to automatically
+discover available libraries, functions, features, etc.
+
+The main reason for omitting this support is the fundamental ambiguity and the
+resulting brittleness of such probing due to the reliance on compiler, linker,
+or test execution failures. Specifically, in many such tests it is impossible
+for a build system to distinguish between a missing feature, a broken test,
+and a misconfigured build environment. This leads to requiring a user
+intervention in the best case and to a silently misconfigured build in the
+worst. Other issues with this approach include portability, speed (compiling
+and linking takes time), as well as limited applicability during
+cross-compilation (specifically, inability to run tests).
+
+As a result, we recommend using \i{expectation-based} configuration where your
+project assumes a feature to be available if certain conditions are
+met. Examples of such conditions at the source code level include C++ feature
+test macros, platform macros, runtime library macros, compiler macros, etc.,
+with the build system modules exposing some of the same information via
+variables to allow making similar decisions in \c{buildfiles}. Another
+alternative is to automatically adapt to missing features using more advanced
+techniques such as C++ SFINAE. And in situations where none of this is
+possible, we recommend delegating the decision to the user via a configuration
+value.  Our experience with \c{build2} as well as those of other large
+cross-platform projects such as Boost show that this is a viable strategy.
+
+Having said that, \c{build2} does provide the ability to extract configuration
+information from the environment (\c{$getenv()} function) or other tools
+(\c{$process.run*()} family of functions). Note, however, that for this to
+work reliably there should be no ambiguity between the \"no configuration
+available\" case (if such a case is possible) and the \"something went wrong\"
+case. We show a realistic example of this in \l{#proj-config-report
+Configuration Report} where we extract the GCC plugin directory while dealing
+with the possibility of it Bunin configured without plugin support.|
+
+Before we delve into the technical details, let's discuss the overall need for
+project configurability. While it may seem that making ones project more
+user-configurable is always a good idea, there are costs: by having a choice
+we increase the complexity and open the door for potential incompatibility.
+Specifically, we may end up with two projects in the same build needing a
+shared dependency with incompatible configurations.
+
+\N|While some languages, such as Rust, support having multiple
+differently-configured projects in the same build, this is not something that
+is done often in C/C++. This ability is also not without its drawbacks, most
+notably code bloat.|
+
+As a result, our recommendation is to strive for simplicity and avoid user
+configurability whenever possible. For example, there is a common desire to
+make certain functionality optional in order not to make the user pay for
+things they don't need. This, however, is often better addressed either by
+always providing the optional functionality if it's fairly small or by
+factoring it into a separate project if it's substantial. If a configuration
+value is to be provided, it should have a sensible default with a bias for
+simplicity and compatibility rather than the optimal result. For example, in
+the optional functionality case, the default should probably be to provide it.
+
+As discussed in the introduction, the central part of the build configuration
+functionality are the \i{configuration variables}. One of the key features
+that make them special is support for automatic persistence in the
+\c{build/config.build} file provided by the \c{config} module (see
+\l{#intro-operations-config Configuring} for details). The following example,
+based on the \c{libhello} project from the introduction, gives an overview of
+the project configuration functionality with the remainder of the chapter
+providing the detailed explanation of all the parts shown as well as the
+alternative approaches.
+
+\
+libhello/
+├── build/
+│   ├── root.build
+│   └── ...
+├── libhello/
+│   ├── hello.cxx
+│   ├── buildfile
+│   └── ...
+└── ...
+\
+
+\
+# build/root.build
+
+config [string] config.libhello.greeting ?= 'Hello'
+\
+
+\
+# libhello/buildfile
+
+cxx.poptions += \"-DLIBHELLO_GREETING=\\\"$config.libhello.greeting\\\"\"
+\
+
+\
+// lihello/hello.cxx
+
+void say_hello (ostream& o, const string& n)
+{
+  o << LIBHELLO_GREETING \", \" << n << '!' << endl;
+}
+\
+
+\
+$ b configure config.libhello.greeting=Hi -v
+config libhello@/tmp/libhello/
+  greeting   Hi
+
+$ cat build/config.build
+config.libhello.greeting = Hi
+
+$ b -v
+g++ ... -DLIBHELLO_GREETING=\"Hi\" ...
+\
+
+By (enforced) convention, configuration variables start with \c{config.}, for
+example, \c{config.import.libhello}. In case of a build system module, the
+second component in its configuration variables should be the module name, for
+example, \c{config.cxx}, \c{config.cxx.coptions}. Similarly, project-specific
+configuration variables should have the project name as their second
+component, for example, \c{config.libhello.greeting}.
+
+\N|More precisely, a project configuration variable must match the
+\c{config[.**].<project>.**} pattern where additional components may be
+present after \c{config.} in case of subprojects. Overall, the recommendation
+is to use hierarchical names, such as \c{config.libcurl.tests.remote} for
+subprojects, similar to build system submodules.
+
+If a build system module for a tool (such as a source code generator) and the
+tool itself share a name, then they may need to coordinate their configuration
+variable names in order to avoid clashes.
+
+The build system core reserves \c{build} and \c{import} as the second
+component in configuration variables as well as \c{configured} as the third
+and further components.|
+
+
+\h#proj-config-directive|\c{config} Directive|
+
+To define a project configuration variable we add the \c{config} directive
+into the project's \c{build/root.build} file (see \l{#intro-proj-struct
+Project Structure}). For example:
+
+
+\
+config [bool]   config.libhello.fancy    ?= false
+config [string] config.libhello.greeting ?= 'Hello'
+\
+
+\N|The irony does not escape us: these configuration variables are exactly of
+the kind that we advocate against. However, finding reasonable example of
+build-time configurability in a \i{\"Hello, World!\"} library is not easy. In
+fact, it probably shouldn't have any. So, for this chapter, do as we say, not
+as we do.|
+
+Similar to \c{import} (see \l{#intro-import Target Importation}), the
+\c{config} directive is a special kind of variable assignment. Let's examine
+all its parts in turn.
+
+First comes the optional list of variable attributes inside \c{[\ ]}. The only
+attribute that we have in the above example is the variable type, \c{bool} and
+\c{string}, respectively. It is generally a good idea to assign static types
+to configuration variables because their values will be specified by the users
+of our project and the more automatic validation we provide the better (see
+\l{#variables Variables} for the list of available types). For example, this
+is what will happen if we misspell the value of the \c{fancy} variable:
+
+\
+$ b configure config.libhello.fancy=fals
+error: invalid bool value 'fals' in variable config.libhello.fancy
+\
+
+After the attribute list we have the variable name. The \c{config} directive
+will validate that it matches the \c{config[.**].<project>.**} pattern (with
+one exception discussed in \l{#proj-config-report Configuration Report}).
+
+Finally, after the variable name comes optional default value. Note that
+unlike normal variables, default value assignment (\c{?=}) is the only valid
+form of assignment in the \c{config} directive.
+
+The semantics of the \c{config} directive is as follows: First an overridable
+variable is entered with the specified name, type (if any), and global
+visibility. Then, if the variable is undefined and the default value is
+specified, it is assigned the default value. After this, if the variable is
+defined (either as user-defined or default), it is marked for persistence.
+Finally, a defined variable is also marked for reporting as discussed in
+\l{#proj-config-report Configuration Report}. Note that if the variable
+is user-defined, then the default value is not evaluated.
+
+Note also that if the configuration value is not specified by the user and you
+haven't provided the default, the variable will be undefined, not \c{null},
+and, as a result, omitted from the persistent configuration
+(\c{build/config.build} file). However, \c{null} is a valid default value. It
+is is traditionally used for \i{optional} configuration values. For example:
+
+\
+config [string] config.libhello.fallback_name ?= [null]
+\
+
+A common approach for representing an C/C++ enum-like value is to use
+\c{string} as a type and pattern matching for validation. In fact, validation
+and propagation can often be combined. For example, if our library needed to
+use a database for some reason, we could handle it like this:
+
+\
+config [string] config.libhello.database ?= [null]
+
+using cxx
+
+switch $config.libhello.database
+{
+  case [null]
+  {
+    # No database in use.
+  }
+  case 'sqlite'
+  {
+    cxx.poptions += -DLIBHELLO_WITH_SQLITE
+  }
+  case 'pgsql'
+  {
+    cxx.poptions += -DLIBHELLO_WITH_PGSQL
+  }
+  default
+  {
+    fail \"invalid config.libhello.database value \
+'$config.libhello.database'\"
+  }
+}
+\
+
+While it is generally a good idea to provide a sensible default for all your
+configuration variables, if you need to force the user to specify its value
+explicitly, this can be achieved with an extra check. For example:
+
+\
+config [string] config.libhello.database
+
+if! $defined(config.libhello.database)
+  fail 'config.libhello.database must be specified'
+\
+
+And if you want to also disallow \c{null} values, then the above check should
+be rewritten like this: \N{An undefined variable expands into a \c{null}
+value.}
+
+\
+if ($config.libhello.database == [null])
+  fail 'config.libhello.database must be specified'
+\
+
+If computing the default value is expensive or requires elaborate logic, then
+handling of a configuration variable can be broken down into two steps along
+these lines:
+
+\
+config [string] config.libhello.greeting
+
+if! $defined(config.libhello.greeting)
+{
+  greeting = ... # Calculate default value.
+
+  if ($greeting == [null])
+    fail \"unable to calculate default greeting, specify manually \
+with config.libhello.greeting\"
+
+  config config.libhello.greeting ?= $greeting
+}
+\
+
+Other than assigning the default value via the \c{config} directive,
+configuration variables should not be modified by the project's
+\c{buildfiles}. Instead, if further processing of the configuration value is
+necessary, we should assign the configuration value to a different,
+non-\c{config.*}, variable and modify that. The two situations where this is
+commonly required are post-processing of configuration values to be more
+suitable for use in \c{buildfiles} as well as further customization of
+configuration values. Let's see examples of both.
+
+To illustrate the first situation, let's say we need to translate the database
+identifiers specified by the user:
+
+\
+config [string] config.libhello.database ?= [null]
+
+switch $config.libhello.database
+{
+  case [null]
+    database = [null]
+
+  case 'sqlite'
+    database = 'SQLITE'
+
+  case 'pgsql'
+    database = 'PGSQL'
+
+  case 'mysql'
+  case 'mariadb'
+    database = 'MYSQL'
+
+  default
+    fail \"...\"
+  }
+}
+
+using cxx
+
+if ($database != [null])
+  cxx.poptions += \"-DLIBHELLO_WITH_$database\"
+\
+
+For the second situation, the typical pattern looks like this:
+
+\
+config [strings] config.libhello.options
+
+options  = # Overridable options go here.
+options += $config.libhello.options
+options += # Non-overridable options go here.
+\
+
+That is, assuming that the subsequently specified options (for example,
+command line options) override any previously specified, we first set default
+\c{buildfile} options that are allowed to be overridden by options from the
+configuration value, then append such options, if any, and finish off by
+appending \c{buildfile} options that should always be in effect.
+
+As a concrete example of this approach, let's say we want to make the compiler
+warning level of our project configurable (likely a bad idea; also ignores
+compiler differences):
+
+\
+config [strings] config.libhello.woptions
+
+woptions  = -Wall -Wextra
+woptions += $config.libhello.woptions
+woptions += -Werror
+
+using cxx
+
+cxx.coptions += $woptions
+\
+
+With this arrangement, the users of our project can customize the warning
+level but cannot disable the treatment of warnings as errors. For example:
+
+\
+$ b -v config.libhello.woptions=-Wno-extra
+g++ ... -Wall -Wextra -Wno-extra -Werror ...
+\
+
+While we have already seen some examples of how to propagate the configuration
+values to our source code, \l{#proj-config-propag Configuration Propagation}
+discusses this topic in more detail.
+
+this topic is discussed further in
+.
+
+
+\h#proj-config-report|Configuration Report|
+
+One of the effects of the \c{config} directive is to mark a defined
+configuration variable for reporting. The project configuration report is
+printed automatically at the sufficiently high verbosity level along with the
+build system module configuration. For example (some of the \c{cxx} module
+configuration is omitted for brevity):
+
+\
+$ b config.libhello.greeting=Hey -v
+cxx libhello@/tmp/libhello/
+  cxx        g++@/usr/bin/g++
+  id         gcc
+  version    9.1.0
+  ...
+config libhello@/tmp/libhello/
+  fancy      false
+  greeting   Hey
+\
+
+\N|The configuration report is printed immediately after loading the project's
+\c{build/root.build} file. It is always printed at verbosity level \c{3}
+(\c{-V}) or higher. It is also printed at verbosity level \c{2} (\c{-v}) if
+any of the reported configuration variables have a \i{new} value. A value is
+considered new if it was set to default or was overridden on the command
+line.|
+
+The project configuration report header (the first line) starts with the
+special \c{config} module name (the \c{config} module itself does not have a
+report) followed by the project name and its \c{out_root} path. After the
+header come configuration variables with the \c{config[.**].<project>} prefix
+removed. The configuration report for each variable can be customized using a
+number of \c{config.report*} attributes as discussed next.
+
+The \c{config.report} attribute controls whether the variable is included into
+the report and, if so, the format to print its value in. For example, this is
+how we can exclude a variable from the report:
+
+\
+config [bool, config.report=false] config.libhello.selftest ?= false
+\
+
+While we would normally want to report all our configuration variables , if
+some of them are internal and not meant to be used by the users of our
+project, it probably makes sense to exclude them.
+
+The only currently supported alternative printing format is \c{multiline}
+which prints a list value one element per line. \N{Other printing formats may
+be supported in the future.} For example:
+
+\
+config [dir_paths, config.report=multiline] config.libhello.search_dirs
+\
+
+\
+$ b config.libhello.search_dirs=\"/etc/default /etc\" -v
+config libhello@/tmp/libhello/
+  search_dirs
+    /etc/default/
+    /etc/
+\
+
+The \c{config.report} attribute can also be used to include a non-\c{config.*}
+variable into a report. This is primarily useful for configuration values
+that are always discovered automatically but that are still useful to report
+for troubleshooting. Here is a realistic example:
+
+\
+using cxx
+
+# Determine the GCC plugin directory.
+#
+if ($cxx.id == 'gcc')
+{
+  plugin_dir = [dir_path] $process.run($cxx.path -print-file-name=plugin)
+
+  # If plugin support is disabled, then -print-file-name will print
+  # the name we have passed (the real plugin directory will always
+  # be absolute).
+  #
+  if (\"$plugin_dir\" == plugin)
+    fail \"$recall($cxx.path) does not support plugins\"
+
+  config [config.report] plugin_dir
+}
+\
+
+\N|This is the only situation where a variable that does not match the
+\c{config[.**].<project>.**} pattern is allowed in the \c{config} directive.
+Note also that a value of such a variable is never considered new.|
+
+Note that this mechanism should not be used to report configuration values
+that require post-processing because of the loss of the new value status
+(unless you are reporting both the original and post-processed values).
+Instead, use the \c{config.report.variable} attribute to specify an
+alternative variable for the report. For example:
+
+\
+config [strings, config.report.variable=woptions] \
+  config.libhello.woptions
+
+woptions  = -Wall -Wextra
+woptions += $config.libhello.woptions
+woptions += -Werror
+\
+
+\
+$ b config.libhello.woptions=-Wno-extra -v
+config libhello@/tmp/libhello/
+  woptions   -Wall -Wextra -Wno-extra -Werror
+\
+
+
+\h#proj-config-propag|Configuration Propagation|
+
+Using configuration values in our \c{buildfiles} is straightforward: they are
+like any other \c{buildfile} variables and we can access them directly. For
+example, this is how we could provide optional functionality in our library by
+conditionally including certain source files: \N{See \l{#intro-if-else
+Conditions (\c{if-else})} for why we should not use \c{if} to implement
+this.}
+
+\
+# build/root.build
+
+config [strings] config.libhello.io ?= true
+\
+
+\
+# libhello/buildfile
+
+lib{hello}: {hxx ixx txx cxx}{** -version -hello-io} hxx{version}
+lib{hello}: {hxx cxx}{hello-io}: include = $config.libhello.io
+\
+
+On the other hand, it is often required to propagate the configuration
+information to our source code. In fact, we have already seen one way to do
+it: we can pass this information via C/C++ preprocessor macros defined on the
+compiler's command line. For example:
+
+\
+# build/root.build
+
+config [bool]   config.libhello.fancy    ?= false
+config [string] config.libhello.greeting ?= 'Hello'
+\
+
+\
+# libhello/buildfile
+
+if $config.libhello.fancy
+  cxx.poptions += -DLIBHELLO_FANCY
+
+cxx.poptions += \"-DLIBHELLO_GREETING=\\\"$config.libhello.greeting\\\"\"
+\
+
+\
+// lihello/hello.cxx
+
+void say_hello (ostream& o, const string& n)
+{
+#ifdef LIBHELLO_FANCY
+  // TODO: something fancy.
+#else
+  o << LIBHELLO_GREETING \", \" << n << '!' << endl;
+#endif
+}
+\
+
+We can even use the same approach to export certain configuration information
+to our library's users (see \l{#intro-lib Library Exportation and Versioning}
+for details):
+
+\
+# libhello/buildfile
+
+# Export options.
+#
+if $config.libhello.fancy
+  lib{hello}: cxx.export.poptions += -DLIBHELLO_FANCY
+\
+
+This mechanism is simple and works well across compilers so there is no reason
+not to use it when the number of configuration values passed and their size
+are small. However, it can quickly get unwieldy as these numbers grow. For
+such cases, it may make sense to save this information into a separate
+auto-generated source file with the help of the \l{#module-in \c{in}} module,
+similar to how we do it for the version header.
+
+The often-used approach is to generate a header file and include it into
+source files that need access to the configuration information. Historically,
+this was a C header full of macros called \c{config.h}. However, for C++
+projects, there is no reason not to make it a C++ header and, if desired, to
+use modern C++ features instead of macros. Which is what we will do here.
+
+As an example of this approach, let's convert the above command line-based
+implementation to use the configuration header. We will continue using macros
+as a start (or in case this is a C project) and try more modern techniques
+later. The \c{build/root.build} file is unchanged except for loading the
+\c{in} module:
+
+\
+# build/root.build
+
+config [bool]   config.libhello.fancy    ?= false
+config [string] config.libhello.greeting ?= 'Hello'
+
+using in
+\
+
+The \c{libhello/config.hxx.in} file is new:
+
+\
+// libhello/config.hxx.in
+
+#pragma once
+
+#define LIBHELLO_FANCY    $config.libhello.fancy$
+#define LIBHELLO_GREETING \"$config.libhello.greeting$\"
+\
+
+As you can see, we can reference our configuration variables directly in the
+\c{config.hxx.in} substitutions (see \l{#module-in \c{in} Module} for details
+on how this works). The rest is changed as follows:
+
+\
+# libhello/buildfile
+
+lib{hello}: {hxx ixx txx cxx}{** -version -config} hxx{version config}
+
+hxx{config}: in{config}
+{
+  install = false
+}
+\
+
+\
+// lihello/hello.cxx
+
+#include <libhello/config.hxx>
+
+void say_hello (ostream& o, const string& n)
+{
+#if LIBHELLO_FANCY
+  // TODO: something fancy.
+#else
+  o << LIBHELLO_GREETING \", \" << n << '!' << endl;
+#endif
+}
+\
+
+\N|With this setup, the way to export configuration information to our
+library's users is to make the configuration header public and install it,
+similar to how we do it for the version header.|
+
+Now that the macro-based version is working, let's see how we can take
+advantage of modern C++ features to hopefully improve on some of their
+drawbacks. As a first step, we can replace the \c{LIBHELLO_FANCY} macro with a
+compile-time constant and use \c{if\ constexpr} instead of \c{#ifdef} in our
+implementation:
+
+\
+// libhello/config.hxx.in
+
+namespace hello
+{
+  inline constexpr bool fancy = $config.libhello.fancy$;
+}
+\
+
+\
+// lihello/hello.cxx
+
+#include <libhello/config.hxx>
+
+void say_hello (ostream& o, const string& n)
+{
+  if constexpr (fancy)
+  {
+    // TODO: something fancy.
+  }
+  else
+    o << LIBHELLO_GREETING \", \" << n << '!' << endl;
+}
+\
+
+\N|Note that with \c{if\ constexpr} the branch not taken must still be valid,
+parsable code. This is both one of the main benefits of using it instead of
+\c{#if} (the code we are not using is still guaranteed to be syntactically
+correct) as well as its main drawbacks (it cannot be used, for example, for
+platform-specific code without extra efforts, such as providing shims for
+missing declarations, etc).|
+
+Next, we can do the same for \c{LIBHELLO_GREETING}:
+
+\
+// libhello/config.hxx.in
+
+namespace hello
+{
+  inline constexpr char greeting[] = \"$config.libhello.greeting$\";
+}
+\
+
+\
+// lihello/hello.cxx
+
+#include <libhello/config.hxx>
+
+void say_hello (ostream& o, const string& n)
+{
+  if constexpr (fancy)
+  {
+    // TODO: something fancy.
+  }
+  else
+    o << greeting << \", \" << n << '!' << endl;
+}
+\
+
+\N|Note that for \c{greeting} we can achieve the same result without using
+inline variables or \c{constexpr} and which would be usable in older C++ and
+even C. All we have to do is add the \c{config.cxx.in} source file next to
+our header with the definition of the \c{greeting} variable. For example:
+
+\
+// libhello/config.hxx.in
+
+namespace hello
+{
+  extern const char greeting[];
+}
+\
+
+\
+// libhello/config.cxx.in
+
+#include <libhello/config.hxx>
+
+namespace hello
+{
+  const char greeting[] = \"$config.libhello.greeting$\";
+}
+\
+
+\
+# libhello/buildfile
+
+lib{hello}: {hxx ixx txx cxx}{** -config} {hxx cxx}{config}
+
+hxx{config}: in{config}
+{
+  install = false
+}
+
+cxx{config}: in{config}
+\
+
+As this illustrates, the \c{in} module can produce as many auto-generated
+source files as we need. For example, we could use this to split the
+configuration header into two, one public and installed while the other
+private.|
+
+
 \h1#attributes|Attributes|
 
 \N{This chapter is a work in progress and is incomplete.}
@@ -4576,6 +5309,30 @@ name). Project-qualified names are never considered to be patterns.
 
 \N{This chapter is a work in progress and is incomplete.}
 
+The following variable/value types can currently be used in \c{buildfiles}:
+
+\
+bool
+
+uint64
+uint64s
+
+string
+strings
+
+path
+paths
+dir_path
+dir_paths
+
+name
+names
+name_pair
+
+project_name
+target_triplet
+\
+
 Note that while expansions in the target and prerequisite-specific assignments
 happen in the corresponding target and prerequisite contexts, respectively,
 for type/pattern-specific assignments they happen in the scope context. Plus,