From acfedd8d40b51e05ae19be02bebe0ebae26c5c84 Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Wed, 21 Nov 2018 21:12:25 +0300
Subject: Document configuration classes in buildtab

---
 doc/manual.cli | 58 +++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 35 insertions(+), 23 deletions(-)

diff --git a/doc/manual.cli b/doc/manual.cli
index 0a94e74..c40aa29 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -845,30 +845,40 @@ machines (as reported by agents) to \i{build configurations} according to the
 are ignored. All other lines in this file have the following format:
 
 \
-<machine-pattern> <config> <target> [<config-args>] [<warning-regex>]
+<machine-pattern> <config> <target> <classes> [<config-arg>]* [<warning-regex>]*
 
-<config-args> = [<prefix>:](<variable>|<option>)
+<config-arg> = [<prefix>:](<variable>|<option>)
 <prefix> = <tool>[.<operation>[.<command>]]
 \
 
 Where \c{<machine-pattern>} is filesystem wildcard pattern that is matched
 against available machine names, \c{<config>} is the configuration name,
-\c{<target>} is the build target, optional \c{<config-args>} is a list of
-additional configuration options and variables, and optional
-\c{<warning-regex>} is a list of additional regular expressions that should be
-used to detect warnings in the logs.
+\c{<target>} is the build target, \c{<classes>} is a space-separated list of
+configuration classes that is matched against the package \c{builds} values,
+optional \c{<config-arg>} list is additional configuration options and
+variables, and optional \c{<warning-regex>} list is additional regular
+expressions that should be used to detect warnings in the logs.
+
+The build configurations can belong to multiple classes with their names
+reflecting some common configuration aspects, such as the operating system,
+compiler, build options, etc. Predefined class names are \c{default}, \c{all},
+and \c{none}. The default configurations are built by default. A configuration
+must also belong to the \c{all} unless it is hidden. Valid custom class names
+must contain only alpha-numeric characters, \c{_}, \c{+}, \c{-}, and \c{.},
+except as the first character for the last three. Class names that start with
+\c{_} are reserved for the future hidden/special class functionality.
 
 Regular expressions must start with \c{~}, to be distinguished from
-configuration options and variables. Note that \c{<config-args>} and
+configuration options and variables. Note that the \c{<config-arg>} and
 \c{<warning-regex>} lists have the same quoting semantics as in the \c{config}
-and the \c{warning-regex} values in the build task manifest. The matched
+and the \c{warning-regex} value in the build task manifest. The matched
 machine name, the target, configuration options/variables, and regular
 expressions are included into the build task manifest.
 
-Values in \c{<config-args>} can be opionally prefixed with the \i{step id} or
-a leading portion thereof to restrict it to a specific step, operation, or
-tool in the \i{worked script} (see \l{#arch-worker Worker Logic}). Unprefixed
-values only apply to the \c{bpkg.configure.create} and
+Values in the \c{<config-arg>} list can be opionally prefixed with the \i{step
+id} or a leading portion thereof to restrict it to a specific step, operation,
+or tool in the \i{worked script} (see \l{#arch-worker Worker
+Logic}). Unprefixed values only apply to the \c{bpkg.configure.create} and
 \c{b.test-installed.create} steps. Note that options with values can only be
 specified using the single argument notation. For example:
 
@@ -888,13 +898,13 @@ we wanted to test both 32 and 64-bit builds as well as debug and release, then
 we could have generated the following configurations:
 
 \
-windows*-vc_14* windows-vc_14-32-debug i686-microsoft-win32-msvc14.0 config.cc.coptions=/Z7 config.cc.loptions=/DEBUG ~\"warning C4\d{3}: \"
+windows*-msvc_14* windows-msvc_14-32-debug i686-microsoft-win32-msvc14.0 \"all default msvc i686\" config.cc.coptions=/Z7 config.cc.loptions=/DEBUG ~\"warning C4\d{3}: \"
 
-windows*-vc_14* windows-vc_14-32-release i686-microsoft-win32-msvc14.0 config.cc.coptions=/O2 ~\"warning C4\d{3}: \"
+windows*-msvc_14* windows-msvc_14-32-release i686-microsoft-win32-msvc14.0 \"all default msvc i686 optimized\" config.cc.coptions=/O2 ~\"warning C4\d{3}: \"
 
-windows*-vc_14* windows-vc_14-64-debug x86_64-microsoft-win32-msvc14.0 config.cc.coptions=/Z7 config.cc.loptions=/DEBUG ~\"warning C4\d{3}: \"
+windows*-msvc_14* windows-msvc_14-64-debug x86_64-microsoft-win32-msvc14.0 \"all default msvc x86_64\" config.cc.coptions=/Z7 config.cc.loptions=/DEBUG ~\"warning C4\d{3}: \"
 
-windows*-vc_14* windows-vc_14-64-release x86_64-microsoft-win32-msvc14.0 config.cc.coptions=/O2 ~\"warning C4\d{3}: \"
+windows*-msvc_14* windows-msvc_14-64-release x86_64-microsoft-win32-msvc14.0 \"all default msvc x86_64 optimized\" config.cc.coptions=/O2 ~\"warning C4\d{3}: \"
 \
 
 As another example, let's say we have \c{linux_fedora_25-gcc_6} and
@@ -902,13 +912,14 @@ As another example, let's say we have \c{linux_fedora_25-gcc_6} and
 builds on Linux, then our configurations could look like this:
 
 \
-linux*-gcc_6 linux-gcc_6-debug x86_64-linux-gnu config.cc.coptions=-g
-linux*-gcc_6 linux-gcc_6-release x86_64-linux-gnu config.cc.coptions=-O3
+linux*-gcc_6 linux-gcc_6-debug x86_64-linux-gnu \"all default gcc\" config.cc.coptions=-g
+
+linux*-gcc_6 linux-gcc_6-release x86_64-linux-gnu \"all default gcc optimized\" config.cc.coptions=-O3
 \
 
-If \c{<config-args>} contains the \c{config.install.root} variable that
-applies to the \c{bpkg.configure.create} step, then in addition to building
-and running tests, the \c{bbot} worker will also test installing and
+If the \c{<config-arg>} list contains the \c{config.install.root} variable
+that applies to the \c{bpkg.configure.create} step, then in addition to
+building and running tests, the \c{bbot} worker will also test installing and
 uninstalling each package. Furthermore, if the package contains the \c{tests}
 subdirectory that is a subproject, then the worker will additionally build and
 run tests against the installation.
@@ -926,8 +937,9 @@ As an example, the following two configurations could be used to test system
 and private installations:
 
 \
-linux*-gcc* linux-gcc-sys x86_64-linux-gnu config.install.root=/usr config.install.sudo=sudo
-linux*-gcc* linux-gcc-prv x86_64-linux-gnu config.install.root=/tmp/install config.cc.poptions=-I/tmp/install/include config.cc.loptions=-L/tmp/install/lib config.bin.rpath=/tmp/install/lib
+linux*-gcc* linux-gcc-sys x86_64-linux-gnu \"all default gcc\" config.install.root=/usr config.install.sudo=sudo
+
+linux*-gcc* linux-gcc-prv x86_64-linux-gnu \"all default gcc\" config.install.root=/tmp/install config.cc.poptions=-I/tmp/install/include config.cc.loptions=-L/tmp/install/lib config.bin.rpath=/tmp/install/lib
 \
 
 Note also that while building and running tests against the installation the
-- 
cgit v1.1