From 03f6d8842832a62e383761ae575db4e263979328 Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Tue, 20 Jun 2017 21:50:20 +0300
Subject: Add support for task manifest warning-regex value

---
 doc/manual.cli | 75 ++++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 57 insertions(+), 18 deletions(-)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index d581264..8e0d745 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -260,9 +260,10 @@ version:    <package-version>
 repository: <repository-url>
 trust:      <repository-fp>
 
-machine: <machine-name>
-target:  <target-triplet>
-config:  <config-vars>
+machine:       <machine-name>
+target:        <target-triplet>
+config:        <config-vars>
+warning-regex: <warning-regexes>
 \
 
 The task manifest describes a build task. It consists of two groups of values.
@@ -328,9 +329,38 @@ build configuration to use for building the package.
   config.cc.coptions=-O3 -stdlib='libc++'
   \
 
-  Variables can be separated with spaces or newlines.
+  Variables can be separated with spaces or newlines.|
 
-  ||
+\li|\n\c{warning-regex: <warning-regexes>}\n
+
+  Additional regular expressions that should be used to detect warnings in
+  the logs.
+
+  A single level of quotes (either single or double) is removed in each
+  expression before being used for search. For example, the following value:
+
+  \
+  warning-regex: \"warning C4\d{3}: \"
+  \
+
+  Will be treated as the following (single) regular expression (with a
+  trailing space):
+
+  \
+  warning C4\d{3}:
+  \
+
+  Expressions can be separated with spaces or newlines. They will be added to
+  the following default list of regular expressions that detect the \c{build2}
+  toolchain warnings:
+
+  \
+  ^warning:
+  ^.+: warning:
+  \
+
+  Note that this built-in list also covers GCC and Clang warnings (for the
+  English locale).||
 
 
 \h#arch-result-manifest|Result Manifest|
@@ -581,16 +611,22 @@ 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-name-pattern> <config-name> [<target>] [<config-vars>]
+<machine-pattern> <config> [<target>] [<config-vars>] [<warning-regex>]
 \
 
-Where \c{<machine-name-pattern>} is filesystem wildcard pattern that is
-matched against available machine names, \c{<config-name>} is the
-configuration name, optional \c{<target>} is the build target, and optional
-\c{<config-vars>} is a list of additional build system configuration variables
-with the same quoting semantics as in the \c{config} value in the build task
-manifest. The matched machine name, the target, and configuration variables
-are included into the build task manifest.
+Where \c{<machine-pattern>} is filesystem wildcard pattern that is
+matched against available machine names, \c{<config>} is the
+configuration name, optional \c{<target>} is the build target, optional
+\c{<config-vars>} is a list of additional build system configuration
+variables, and optional \c{<warning-regex>} is a list of additional regular
+expressions that should be used to detect warnings in the logs.
+
+Regular expressions must start with \c{~}, to be distinguished from
+configuration variables. Note that \c{<config-vars>} 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 machine name,
+the target, configuration variables, and regular expressions are included into
+the build task manifest.
 
 Note that each machine name is matched against every pattern and all the
 patterns that match produce a configuration. If a machine does not match any
@@ -599,15 +635,18 @@ testing its packages with this machine). If multiple machines match the same
 pattern, then only a single configuration using any of the machines is
 produced (meaning that this controller considers these machines equivalent).
 
-As an example, let's say we have a machine named \c{windows_10-vc_14u3}.  If
+As an example, let's say we have a machine named \c{windows_10-vc_14u3}. If
 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
-windows*-vc_14* windows-vc_14-32-release i686-microsoft-win32-msvc14.0   config.cc.coptions=\"/O2 /Oi\"
-windows*-vc_14* windows-vc_14-64-debug   x86_64-microsoft-win32-msvc14.0 config.cc.coptions=/Z7 config.cc.loptions=/DEBUG
-windows*-vc_14* windows-vc_14-64-release x86_64-microsoft-win32-msvc14.0 config.cc.coptions=\"/O2 /Oi\"
+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*-vc_14* windows-vc_14-32-release i686-microsoft-win32-msvc14.0   config.cc.coptions=\"/O2 /Oi\"                   ~\"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*-vc_14* windows-vc_14-64-release x86_64-microsoft-win32-msvc14.0 config.cc.coptions=\"/O2 /Oi\"                   ~\"warning C4\d{3}: \"
 \
 
 As another example, let's say we have \c{linux_fedora_25-gcc_6} and
-- 
cgit v1.1