diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual.cli | 45 |
1 files changed, 45 insertions, 0 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index 72611bc..ed96915 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -8871,6 +8871,42 @@ target-specific variables. Typed variable values are converted to string using the corresponding \c{builtin.string()} function overload before substitution. +While specifying substitution values as \c{buildfile} variables is usually +natural, sometimes this may not be possible or convenient. Specifically, we +may have substitution names that cannot be specified as \c{buildfile} +variables, for example, because they start with an underscore (and are thus +reserved) or because they refer to one of the predefined variables. Also, we +may need to have different groups of substitution values for different cases, +for example, for different platforms, and it would be convenient to pass such +groups around as a single value. + +To support these requirements the substitution values can alternatively be +specified as key-value pairs in the \c{in.substitutions} variable. Note that +entries in this substitution map take precedence over the \c{buildfile} +variables. For example: + +\ +/* config.h.in */ + +#define _GNU_SOURCE @_GNU_SOURCE@ +#define _POSIX_SOURCE @_POSIX_SOURCE@ +\ + +\ +# buildfile + +h{config}: in{config} +{ + in.symbol = '@' + in.mode = lax + + in.substitutions = _GNU_SOURCE@0 _POSIX_SOURCE@1 +} +\ + +\N|In the above example, the \c{@} characters in \c{in.symbol} and +\c{in.substitutions} are unrelated.| + Using an undefined variable in a substitution is an error. Using a \c{null} value in a substitution is also an error unless the fallback value is specified with the \c{in.null} variable. For example: @@ -8884,6 +8920,15 @@ h{config}: in{config} } \ +\N|To specify a \c{null} value using the \c{in.substitutions} mechanism omit +the value, for example: + +\ +in.substitutions = _GNU_SOURCE +\ + +| + A number of other build system modules, for example, \l{https://github.com/build2/libbuild2-autoconf/ \c{autoconf}}, \l{#module-version \c{version}}, and \l{#module-bash \c{bash}}, are based on |