aboutsummaryrefslogtreecommitdiff
path: root/doc/manual.cli
diff options
context:
space:
mode:
authorKaren Arutyunov <karen@codesynthesis.com>2024-01-31 18:27:27 +0300
committerKaren Arutyunov <karen@codesynthesis.com>2024-02-02 13:43:02 +0300
commitc77d65b4472ef0e2734ffde5556e279e62bb964a (patch)
treee24d4b47690c6a9e8649ef8cfe7a85a57499635d /doc/manual.cli
parentc835121db614efa56093dde7a1557372a43ab09b (diff)
Add support for enable clause in tests package manifest value
Diffstat (limited to 'doc/manual.cli')
-rw-r--r--doc/manual.cli63
1 files changed, 53 insertions, 10 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index 999d924..99e3caa 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -2142,9 +2142,13 @@ configuration. See the \l{bbot \c{bbot} documentation} for details.
\h2#manifest-package-tests-examples-benchmarks|\c{tests}, \c{examples}, \c{benchmarks}|
\
-[tests]: [*] <name> [<version-constraint>]
-[examples]: [*] <name> [<version-constraint>]
-[benchmarks]: [*] <name> [<version-constraint>]
+[tests]: [*] <package> ['?' <enable-cond>] [<reflect-var>]
+[examples]: [*] <package> ['?' <enable-cond>] [<reflect-var>]
+[benchmarks]: [*] <package> ['?' <enable-cond>] [<reflect-var>]
+
+<package> = <name> [<version-constraint>]
+<enable-cond> = '(' <buildfile-eval-expr> ')'
+<reflect-var> = <config-var> '=' <value>
\
Separate tests, examples, and benchmarks packages. If the value starts with
@@ -2163,7 +2167,7 @@ example:
\
name: hello
-tests : hello-tests
+tests: hello-tests
examples: hello-examples
\
@@ -2176,18 +2180,57 @@ it can also be specified in terms of the primary package's version (see the
tests: hello-tests ~$
\
-Note that normally the tests, etc., packages themselves do not have an
-explicit dependency on the primary package (in a sense, the primary package
-has a special dependency on them). They are also not built by automated build
-bots separately from their primary package but may have their own build
-constraints, for example, to be excluded from building on some platforms where
-the primary package is still built, for example:
+Note that normally the tests, etc., packages themselves (we'll call them all
+test packages for short) do not have an explicit dependency on the primary
+package (in a sense, the primary package has a special test dependency on
+them). They are also not built by automated build bots separately from their
+primary package but may have their own build constraints, for example, to be
+excluded from building on some platforms where the primary package is still
+built, for example:
\
name: hello-tests
builds: -windows
\
+Also note that a test package may potentially be used as a test dependency for
+multiple primary packages. In this case a primary package normally needs to
+reflect to the test package the fact that it is the one being tested. This can
+be achieved by setting the test package's configuration variable (see the
+\l{#manifest-package-depends \c{depends}} value for details on
+reflection). For example:
+
+\
+name: hello-foo
+tests: hello-tests config.hello_tests.test=hello-foo
+
+name: hello-bar
+tests: hello-tests config.hello_tests.test=hello-bar
+\
+
+If it is plausible that the test package may also be built explicitly, for
+example, to achieve a more complicated setup (test multiple main packages
+simultaneously, etc), then the test dependencies need to be made conditional
+in the primary packages so that the explicit configuration is preferred over
+the reflections (see the \l{#manifest-package-depends \c{depends}} value for
+details on conditional dependencies). For example:
+
+\
+name: hello-foo
+tests: hello-tests \
+? (!$defined(config.hello_tests.test)) config.hello_tests.test=hello-foo
+
+name: hello-bar
+tests: hello-tests \
+? (!$defined(config.hello_tests.test)) config.hello_tests.test=hello-bar
+\
+
+Note that in contrast to the \l{#manifest-package-depends \c{depends}} value,
+both the reflection and condition refer to the variables defined not by the
+package which specifies the test dependency (primary package), but the package
+such a dependency refers to (test package).
+
+
\h2#manifest-package-builds|\c{builds}|
\