aboutsummaryrefslogtreecommitdiff
path: root/doc/manual.cli
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2020-04-27 09:49:45 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2020-04-27 10:03:50 +0200
commit9e5750ae2e3f837f80860aaab6b01e4d556213ed (patch)
treed3b2e551e444c47b6ce0289969e78360161b6685 /doc/manual.cli
parent028e10ba787a7dbb46e3fcba6f88f496b76cebc5 (diff)
Rework tool importation along with cli module
Specifically, now config.<tool> (like config.cli) is handled by the import machinery (it is like a shorter alias for config.import.<tool>.<tool>.exe that we already had). And the cli module now uses that instead of custom logic. This also adds support for uniform tool metadata extraction that is handled by the import machinery. As a result, a tool that follows the "build2 way" can be imported with metadata by the buildfile and/or corresponding module without any tool-specific code or brittleness associated with parsing --version or similar outputs. See the cli tool/module for details. Finally, two new flavors of the import directive are now supported: import! triggers immediate importation skipping any rule-specific logic while import? is optional import (analogous to using?). Note that optional import is always immediate. There is also the import-specific metadata attribute which can be specified for these two import flavors in order to trigger metadata importation. For example: import? [metadata] cli = cli%exe{cli} if ($cli != [null]) info "cli version $($cli:cli.version)"
Diffstat (limited to 'doc/manual.cli')
-rw-r--r--doc/manual.cli23
1 files changed, 13 insertions, 10 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index ca57199..04bed52 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -2666,17 +2666,17 @@ library to be able to use it. They also need to know where to find its
headers, which other libraries to link, etc. This information is carried in a
set of target-specific \c{cxx.export.*} variables that parallel the \c{cxx.*}
set and that together with the library's prerequisites constitute the
-\i{library meta-information protocol}. Every time a source file that depends
-on a library is compiled or a binary is linked, this information is
-automatically extracted by the compile and link rules from the library
-dependency chain, recursively. And when the library is installed, this
-information is carried over to its \c{pkg-config(1)} file.
+\i{library metadata protocol}. Every time a source file that depends on a
+library is compiled or a binary is linked, this information is automatically
+extracted by the compile and link rules from the library dependency chain,
+recursively. And when the library is installed, this information is carried
+over to its \c{pkg-config(1)} file.
\N|Similar to the \c{c.*} and \c{cc.*} sets discussed earlier, there are also
\c{c.export.*} and \c{cc.export.*} sets.|
-Here are the parts relevant to the library meta-information protocol in the
-above \c{buildfile}:
+Here are the parts relevant to the library metadata protocol in the above
+\c{buildfile}:
\
int_libs = # Interface dependencies.
@@ -2773,7 +2773,7 @@ Note also that this only applies to shared libraries. In case of static
libraries, both interface and implementation dependencies are always linked,
recursively.|
-The remaining lines in the library meta-information fragment are:
+The remaining lines in the library metadata fragment are:
\
lib{hello}:
@@ -4365,7 +4365,7 @@ 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
+met. Examples of such conditions at the source code level include 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
@@ -4476,7 +4476,10 @@ 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.
+variable names in order to avoid clashes. Note also that when importing an
+executable target in the \c{<project>%exe{<project>\}} form, the
+\c{config.<project>} variable is treated as an alias for
+\c{config.import.<project>.<project>.exe}.
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