diff options
Diffstat (limited to 'doc/manual.cli')
| -rw-r--r-- | doc/manual.cli | 317 |
1 files changed, 307 insertions, 10 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index 5f023a3..a222620 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -582,13 +582,16 @@ shipped in the project root directory). The manifest installation rule in the actual snapshot number and id, just like during the preparation of distributions. -The version header rule pre-processes a template file (which means it can -be used to generate any kinds of files, not just C/C++ headers). It matches a -\c{file}-based target that has a corresponding \c{in} prerequisite and also -depends on the project's \c{manifest} file. As an example, let's assume we -want to auto-generate a header called \c{version.hxx} for our \c{libhello} -library. To acomplish this we add the \c{version.hxx.in} template as well as -something along these lines to our \c{buildfile}: +The version header rule is based on the \l{#module-in \c{in}} module rule and +can be used to preprocesses a template file with version information. While it +is usually used to generate C/C++ version headers (thus the name), it can +really generate any kind of files. + +The rule matches a \c{file}-based target that has the corresponding \c{in} +prerequisite and also depends on the project's \c{manifest} file. As an +example, let's assume we want to auto-generate a header called \c{version.hxx} +for our \c{libhello} library. To accomplish this we add the \c{version.hxx.in} +template as well as something along these lines to our \c{buildfile}: \ lib{hello}: ... hxx{version} @@ -597,10 +600,11 @@ hxx{version}: in{version} $src_root/file{manifest} hxx{version}: dist = true \ -The header rule is a line-based pre-processor that substitutes fragments +The header rule is a line-based preprocessor that substitutes fragments enclosed between (and including) a pair of dollar signs (\c{$}) with \c{$$} -being the escape sequence. As an example, let's assume our \c{version.hxx.in} -contains the following lines: +being the escape sequence (see the \l{#module-in \c{in}} module for +details). As an example, let's assume our \c{version.hxx.in} contains the +following lines: \ #ifndef LIBHELLO_VERSION @@ -2339,4 +2343,297 @@ to explicitly import the module and include the header, especially if the macros may not be needed by all consumers. This way we can also keep the header macro-only which means it can be included freely, in or out of module purviews. + + +\h1#module-in|\c{in} Module| + +The \c{in} build system module provides support for \c{.in} (input) file +preprocessing. Specifically, the \c{.in} file can contain a number of +\i{substitutions} \- build system variable names enclosed with the +substitution symbol (\c{$} by default) \- which are replaced with the +corresponding variable values to produce the output file. For example: + +\ +# build/root.build + +using in +\ + +\ +// config.hxx.in + +#define TARGET \"$cxx.target$\" +\ + +\ +# buildfile + +hxx{config}: in{config} +\ + +The \c{in} module defines the \c{in{\}} target type and implements the \c{in} +build system rule. + +While we can specify the \c{.in} extension explicitly, it is not necessary +because the \c{in{\}} target type implements \i{target-dependent search} by +taking into account the target it is a prerequisite of. In other words, the +following dependency declarations produce the same result: + +\ +hxx{config}: in{config} +hxx{config}: in{config.hxx} +hxx{config}: in{config.hxx.in} +\ + +By default the \c{in} rule uses \c{$} as the substitution symbol. This can be +changed using the \c{in.symbol} variable. For example: + +\ +// data.cxx.in + +const char data[] = \"@data@\"; +\ + +\ +# buildfile + +cxx{data}: in{data} +cxx{data}: in.symbol = '@' +cxx{data}: data = 'Hello, World!' +\ + +Note that the substitution symbol must be a single character. + +The default substitution mode is strict. In this mode every substitution +symbol is expected to start a substitution with unresolved (to a variable +value) names treated as errors. The double substitution symbol (for example, +\c{$$}) serves as an escape sequence. + +The substitution mode can be relaxed using the \c{in.substitution} variable. +Its valid values are \c{strict} (default) and \c{lax}. In the lax mode a pair +of substitution symbols is only treated as a substitution if what's between +them looks like a build system variable name (that is, it doesn't contain +spaces, etc). Everything else, including unterminated substitution symbols, is +copied as is. Note also that in this mode the double substitution symbol is +not treated as an escape sequence. + +The lax mode is mostly useful when trying to reuse existing \c{.in} files from +other build systems, such as \c{autoconf}. Note, however, that the lax mode is +still stricter than the \c{autoconf}'s semantics which also leaves unresolved +substitutions as is. For example: + +\ +# buildfile + +h{config}: in{config} # config.h.in +h{config}: in.symbol = '@' +h{config}: in.substitution = lax +h{config}: CMAKE_SYSTEM_NAME = $c.target.system +h{config}: CMAKE_SYSTEM_PROCESSOR = $c.target.cpu +\ + +The \c{in} rule tracks changes to the input file as well as the substituted +variable values and automatically regenerates the output file if any were +detected. Substituted variable values are looked up starting from the +target-specific variables. Typed variable values are converted to string +using the corresponding \c{builtin.string()} function overload before +substitution. + +A number of other build system modules, for example, \l{#module-version +\c{version}} and \l{#module-bash \c{bash}}, are based on the \c{in} module and +provide extended functionality. The \c{in} preprocessing rule matches any +\c{file{\}}-based target that has the corresponding \c{in{\}} prerequisite +provided none of the extended rules match. + + +\h1#module-bash|\c{bash} Module| + +The \c{bash} build system module provides modularization support for \c{bash} +scripts. It is based on the \l{#module-in \c{in}} build system module and +extends its preprocessing rule with support for \i{import substitutions} in +the \c{@import\ <module>@} form. During preprocessing, such imports are +replaced with suitable \c{source} builtin calls. For example: + +\ +# build/root.build + +using bash +\ + +\ +# hello/say-hello.bash + +function say_hello () +{ + echo \"Hello, $1!\" +} +\ + +\ +#!/usr/bin/env bash + +# hello/hello.in + +@import hello/say-hello@ + +say_hello 'World' +\ + +\ +# hello/buildfile + +exe{hello}: in{hello} bash{say-hello} +\ + +By default the \c{bash} preprocessing rule uses the lax substitution mode and +\c{@} as the substitution symbol but this can be overridden using the standard +\c{in} module mechanisms. + +In the above example, \c{say-hello.bash} is a \i{module}. By convention, +\c{bash} modules have the \c{.bash} extension and we use the \c{bash{\}} +target type (defined by the \c{bash} build system module) to refer to them in +buildfiles. + +The \c{say-hello.bash} module is \i{imported} by the \c{hello} script with the +\c{@import\ hello/say-hello@} substitution. The \i{import path} +(\c{hello/say-hello} in our case) is a relative path to the module file within +the project. Its first component (\c{hello} in our case) must be the project +base name. The \c{.bash} module extension can be omitted. + +During preprocessing, the import substitution will be replaced with a +\c{source} builtin call and the import path resolved to one of the \c{bash{\}} +prerequisites from the script's dependency declaration. The actual module path +used in \c{source} depends on whether the script is preprocessed for +installation. If it's not (development build), then the absolute path to the +module file is used. Otherwise, a path relative to the sourcing script's +directory is derived. This allows installed scripts and their modules to be +moved around. + +\N|The derivation of the sourcing script's directory works even if the script +is executed via a symbolic link from another directory. Implementing this, +however, requires \c{readlink(1)} with support for the \c{-f} option. One +notable platform that does not provide such \c{readlink(1)} by default is Mac +OS. The script, however, can provide a suitable implementation as a function. +See the \c{bash} module tests for a sample implementation of such a function.| + +By default, \c{bash} modules are installed into a subdirectory of the \c{bin/} +installation directory named as the project base name. For instance, in the +above example, the script will be installed as \c{bin/hello} and the module as +\c{bin/hello/say-hello.bash} with the script sourcing the module relative to +the \c{bin/} directory. Note that currently it is assumed the script and all +its modules are installed into the same \c{bin/} directory. + +Naturally, modules can import other modules and modules can be packaged into +\i{module libraries} and imported using the standard build system import +mechanism. For example, we could factor the \c{say-hello.bash} module into a +separate \c{libhello} project: + +\ +# build/export.build + +$out_root/ +{ + include libhello/ +} + +export $src_root/libhello/$import.target +\ + +\ +# libhello/say-hello.bash + +function hello_say_hello () +{ + echo \"Hello, $1!\" +} +\ + +And then import it in a module of our \c{hello} project: + +\ +# hello/hello-world.bash.in + +@import libhello/say-hello@ + +function hello_world () +{ + hello_say_hello 'World' +} +\ + +\ +#!/usr/bin/env bash + +# hello/hello.in + +@import hello/hello-world@ + +hello_world +\ + +\ +# hello/buildfile + +import mods = libhello%bash{say-hello} + +exe{hello}: in{hello} bash{hello-world} +bash{hello-world}: in{hello-world} $mods +\ + +The \c{bash} preprocessing rule also supports importation of installed modules +by searching in the \c{PATH} environment variable. + +By convention, \c{bash} module libraries should use the \c{lib} name prefix, +for example, \c{libhello}. If there is also a native library (that is, one +written in C/C++) that provides the same functionality (or the \c{bash} +library is a language binding for said library), then it is customary to add +the \c{.bash} extension to the \c{bash} library name, for example, +\c{libhello.bash}. Note that in this case the project base name is +\c{libhello}. + +Modules can be \i{private} or \i{public}. Private modules are implementation +details of a specific project and are not expected to be imported from other +projects. The \c{hello/hello-world.bash.in} module above is an example of a +private module. Public modules are meant to be used by other projects and are +normally packaged into libraries, like the \c{libhello/say-hello.bash} module +above. + +Public modules must take care to avoid name clashes. Since \c{bash} does not +have a notion of namespaces, the recommended way is to prefix all module +functions (and global variables, if any) with the library name (without the +\c{lib} prefix), like in the \c{libhello/say-hello.bash} module above. + +While using such decorated function names can be unwieldy, it is relatively +easy to create wrappers with shorter names and use those instead. For example: + +\ +@import libhello/say-hello@ + +function say_hello () { hello_say_hello \"$@\"; } +\ + +A module should normally also prevent itself from being sourced multiple +times. The recommended way to achieve this is to begin the module with a +\i{source guard}. For example: + +\ +# libhello/say-hello.bash + +if [ \"$hello_say_hello\" ]; then + return 0 +else + hello_say_hello=true +fi + +function hello_say_hello () +{ + echo \"Hello, $1!\" +} +\ + +The \c{bash} preprocessing rule matches \c{exe{\}} targets that have the +corresponding \c{in{\}} and one or more \c{bash{\}} prerequisites as well as +\c{bash{\}} targets that have the corresponding \c{in{\}} prerequisite (if you +need to preprocess a script that does not depend on any modules, you can use +the \c{in} module's rule). " |