aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2022-07-27 12:58:30 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2022-07-27 12:58:30 +0200
commit7749af635a20151f337661fe2cf04216604cd4e7 (patch)
treee9a0d1a3b02d88598769fdcb63c6f99787c4cb43 /doc
parentf52558e3c23f7ca30f3f5f4fe00a57a77cb32b8e (diff)
Documentation fixes
Diffstat (limited to 'doc')
-rw-r--r--doc/manual.cli54
1 files changed, 31 insertions, 23 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index 7dac6b0..6767f22 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -401,7 +401,7 @@ subset of the build system files along with the package's standard metadata
the package build system skeleton, or just package skeleton for short, and
includes the \c{build/bootstrap.build} and \c{build/root.build} files (or
their alternative naming scheme variants) as well as any files that may be
-sources by \c{root.build}.
+sourced by \c{root.build}.
The inclusion of \c{build/bootstrap.build} and \c{build/root.build} (if
present) as well as any \c{build/config/*.build} (or their alternative naming
@@ -559,10 +559,10 @@ The problem with the above attempt is that the default value could be greater
than 4KB, in which case \c{bpkg} will have no idea that there is a dependent
relying on this configuration value.
-Before each \c{prefer} clause re-evaluation, values that were first set by
-this dependent are reset to their defaults thus allowing the dependent to
-change its mind, for instance, in response to other configuration changes.
-For example:
+Before each \c{prefer} clause re-evaluation, variables that were first set to
+their current values by this dependent are reset to their defaults thus
+allowing the dependent to change its mind, for instance, in response to other
+configuration changes. For example:
\
# While we have no preference about the cache, if enabled/disabled,
@@ -587,7 +587,7 @@ to defaults semantics the \c{prefer} clause would have kept the buffer at 8KB
\N|Currently \c{accept} is always evaluated after \c{prefer} and temporary
variables (like \c{min_buffer} in the above example) set in \c{prefer} are
-visible in \c{accept}. But it's best not to rely on this in case this changes
+visible in \c{accept}. But it's best not to rely on this in case it changes
in the future. For example, we may try harder to resolve the \"yo-yo'ing\"
case mentioned above by checking if one of the alternating configurations
are acceptable to everyone without re-evaluation.
@@ -603,7 +603,7 @@ are only visible until the immediately following \c{reflect} clause. For
example, in the above listing, \c{config.libfoo.cache} would still be visible
in the \c{reflect} clause if it were to follow \c{accept} but no further. As a
result, if we need to make decisions based on configuration variables that we
-have no preference about, they need to be saved in the \c{prefer} clause. For
+have no preference about, they need to be saved in the \c{reflect} clause. For
example:
\
@@ -1638,10 +1638,10 @@ details).
The condition expression is evaluated after loading the package build system
skeleton, that is, after loading its \c{root.build} (see \l{#package-skeleton
Package Build System Skeleton} for details). As a result, variable values set
-by build system modules that are loaded in \c{root.build} as well as package's
-configuration (including previously reflected; see below) or computed values
-can be referenced in dependency conditions. For example, given the following
-\c{root.build}:
+by build system modules that are loaded in \c{root.build} as well as the
+package's configuration (including previously reflected; see below) or
+computed values can be referenced in dependency conditions. For example, given
+the following \c{root.build}:
\
# root.build
@@ -1661,7 +1661,7 @@ config [bool] config.hello.regex ?= false
We could have the following conditional dependencies:
\
-depends: libposix-getopt ^1.0.0 ? ($need_getop) ; Windows && !MinGW.
+depends: libposix-getopt ^1.0.0 ? ($need_getopt) ; Windows && !MinGW.
depends: libposix-regex ^1.0.0 ? ($config.hello.regex && \
$cxx.target.class == 'windows')
\
@@ -1703,7 +1703,7 @@ if $config.hello.external_regex
exe{hello}: ... $libs
\
-In the above example, if the \c{hello} package is built on Windows, then the
+In the above example, if the \c{hello} package is built for Windows, then the
dependency on \c{libposix-regex} will be enabled and the package will be
configured with \c{config.hello.external_regex=true}. This is used in the
\c{buildfile} to decide whether to import \c{libposix-regex}. While in this
@@ -1764,10 +1764,10 @@ practical experience shows that such extra user-friendliness would rarely
justify the potential confusion that it may cause.
Also note that it's not only the user that can pick a certain alternative but
-also a dependent package. Continue with the above example, if we had \c{hello}
-that depended on \c{libhello} but only supported MariaDB (or provided a
-configuration variable to explicitly select the database), then we could
-have the following in its \c{manifest}:
+also a dependent package. Continuing with the above example, if we had
+\c{hello} that depended on \c{libhello} but only supported MariaDB (or
+provided a configuration variable to explicitly select the database), then we
+could have the following in its \c{manifest}:
\
depends: libmariadb ; Select MariaDB in libhello.
@@ -1779,7 +1779,7 @@ depends: libhello ^1.0.0
Dependency alternatives can be combined with all the other features discussed
above: groups, conditional dependencies, and reflect. As mentioned earlier,
reflect is the only way to communicate the selection to subsequent \c{depends}
-values and package configuration. For example:
+values and the package configuration. For example:
\
depends: libmysqlclient >= 5.0.3 config.hello.db='mysql' | \
@@ -1886,11 +1886,12 @@ libmariadb ^10.2.2
}
\
-For more complex dependency configurations we use the \c{prefer} and
-\c{accept} clauses. The \c{prefer} clause can set configuration variables of
-any type and to any value in order to express the package's preferred
-configuration while the \c{accept} condition evaluates whether any given
-configuration is acceptable. For example:
+For more complex dependency configurations instead of \c{require} we can use
+the \c{prefer} and \c{accept} clauses. The \c{prefer} clause can set
+configuration variables of any type and to any value in order to express the
+package's preferred configuration while the \c{accept} condition evaluates
+whether any given configuration is acceptable. If used instead of \c{require},
+both \c{prefer} and \c{accept} must be present. For example:
\
libmariadb ^10.2.2
@@ -1911,6 +1912,13 @@ libmariadb ^10.2.2
}
\
+\N|The \c{require} clause is essentially a shortcut for specifying the
+\c{prefer}/\c{accept} clauses where the \c{accept} condition simply verifies
+all the variable values assigned in the \c{prefer} clause. It is, however,
+further restricted to the common case of only setting \c{bool} variables and
+only to \c{true} to allow additional optimizations during the configuration
+negotiation.|
+
The \c{require} and \c{prefer} clauses are arbitrary \c{buildfile} fragments
similar to \c{reflect} while the \c{accept} clause is a \c{buildfile} eval
context expression that should evaluate to \c{true} or \c{false}, similar to