From 550abb95e35589cc1b834c1654c3b620f4c9e02c Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Wed, 6 Mar 2024 11:15:22 +0200
Subject: Document new build-auxiliary package manifest value

---
 doc/manual.cli | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)

diff --git a/doc/manual.cli b/doc/manual.cli
index 99e3caa..6963893 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -1083,12 +1083,16 @@ license: <licenses> [; <comment>]
 [builds]: <class-expr> [; <comment>]
 [build-include]: <config>[/<target>] [; <comment>]
 [build-exclude]: <config>[/<target>] [; <comment>]
+[build-auxiliary]: <config> [; <comment>]
+[build-auxiliary-<name>]: <config> [; <comment>]
 
 [*-build-config]: <args> [; <comment>]
 
 [*-builds]: <class-expr> [; <comment>]
 [*-build-include]: <config>[/<target>] [; <comment>]
 [*-build-exclude]: <config>[/<target>] [; <comment>]
+[*-build-auxiliary]: <config> [; <comment>]
+[*-build-auxiliary-<name>]: <config> [; <comment>]
 
 [*-build-email]: <email> [; <comment>]
 [*-build-warning-email]: <email> [; <comment>]
@@ -2372,6 +2376,104 @@ Note that the comment of the matching exclusion is used by the web interface
 (\c{brep}) to display the reason for the build target configuration exclusion.
 
 
+\h2#manifest-package-build-auxiliary|\c{build-auxiliary}|
+
+\
+[build-auxiliary]: <config> [; <comment>]
+[build-auxiliary-<name>]: <config> [; <comment>]
+\
+
+The common package build auxiliary configurations. The \c{build-auxiliary}
+values can be used to specify auxiliary configurations that provide additional
+components which are required for building or testing a package and that are
+impossible or impractical to provide as part of the build configuration
+itself. For example, a package may need access to a suitably configured
+database, such as PostgreSQL, in order to run its tests.
+
+The \i{config} value is a filesystem wildcard patterns which is matched
+against the auxiliary configuration names (which are in turn derived from
+auxiliary machine names; see the \l{bbot \c{bbot} documentation} for
+details). In particular, the \c{*} wildcard matches zero or more characters
+within the name component while the \c{**} sequence matches across the
+components. Plus, wildcard-only pattern components match absent name
+components. For example:
+
+\
+build-auxiliary: linux_debian_12-postgresql_16
+build-auxiliary: linux_*-postgresql_*
+build-auxiliary: *-postgresql**
+\
+
+\N|If multiple auxiliary configurations match the specified pattern, then
+one is picked at random for every build.|
+
+If multiple auxiliary configurations are required, then they must be given
+distinct names with the \i{name} component. For example:
+
+\
+build-auxiliary-pgsql: *-postgresql_*
+build-auxiliary-mysql: *-mysql_*
+\
+
+Another example:
+
+\
+build-auxiliary-primary: *-postgresql_*
+build-auxiliary-secondary: *-postgresql_*
+\
+
+Auxiliary machines communicate information about their setup to the build
+machine using environment variables (see
+\l{bbot#arch-task-auxiliary-environment \c{auxiliary-environment}} for
+details). For example, an auxiliary machine that provides a test PostgreSQL
+database may need to communicate the host IP address and port on which it can
+be accessed as well as the user to login as and the database name to use. For
+example:
+
+\
+DATABASE_HOST=192.168.0.1
+DATABASE_PORT=5432
+DATABASE_USER=test
+DATABASE_NAME=test
+\
+
+If the auxiliary configuration is specified as \c{build-auxiliary-<name>},
+then capitalized \i{name}_ is used as a prefix in the environment variables
+corresponding to the machine. For example, for the auxiliary configurations
+specified as:
+
+\
+build-auxiliary-pgsql: *-postgresql_*
+build-auxiliary-mysql: *-mysql_*
+\
+
+The environment variables could be:
+
+\
+PGSQL_DATABASE_HOST=192.168.0.1
+PGSQL_DATABASE_PORT=5432
+...
+
+MYSQL_DATABASE_HOST=192.168.0.2
+MYSQL_DATABASE_PORT=3306
+...
+\
+
+The auxiliary environment variables are in effect for the entire build. The
+recommended place to propagate them to the package configuration is the
+\c{build-config} value. For example:
+
+\
+build-auxiliary: *-postgresql_*
+build-config:
+\\
+config.hello.pgsql_host=$getenv(DATABASE_HOST)
+config.hello.pgsql_port=$getenv(DATABASE_PORT)
+...
+\\
+\
+
+
 \h2#manifest-package-build-config|\c{*-build-config}|
 
 \
@@ -2390,6 +2492,8 @@ Note that the comment of the matching exclusion is used by the web interface
 [*-builds]: <class-expr> [; <comment>]
 [*-build-include]: <config>[/<target>] [; <comment>]
 [*-build-exclude]: <config>[/<target>] [; <comment>]
+[*-build-auxiliary]: <config> [; <comment>]
+[*-build-auxiliary-<name>]: <config> [; <comment>]
 
 [*-build-email]: <email> [; <comment>]
 [*-build-warning-email]: <email> [; <comment>]
-- 
cgit v1.1