From 1540e984279d25e5a83894216c3610990528b95c Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Wed, 17 Apr 2019 22:41:20 +0300
Subject: Add override options to bdep-ci

Namely the options are: --override, --overrides-file, --builds and
--build-email.
---
 bdep/ci.cli | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

(limited to 'bdep/ci.cli')

diff --git a/bdep/ci.cli b/bdep/ci.cli
index 46a3488..928e884 100644
--- a/bdep/ci.cli
+++ b/bdep/ci.cli
@@ -3,6 +3,7 @@
 // license   : MIT; see accompanying LICENSE file
 
 include <bdep/project.cli>;
+include <bdep/ci-types.hxx>;
 
 "\section=1"
 "\name=bdep-ci"
@@ -55,6 +56,26 @@ namespace bdep
      \cb{git(1)}, the current branch and commit id are added as the repository
      URL fragment (see \l{bpkg-repository-types(1)} for details).
 
+     Some package manifest values can be overridden as part of the CI request
+     submission using the \cb{--override} and \cb{--overrides-file} options as
+     well as their \cb{--builds} and \cb{--build-email} shortcuts. This is
+     primarily useful for specifying alternative build configurations and/or
+     build notification emails. For example:
+
+     \
+     $ bdep ci --builds gcc
+     \
+
+     Note that manifest overrides override the entire value group that they
+     belong to. Currently, the following value groups can be overridden with
+     the \cb{build*-email} group overridden by default as if by specifying
+     an empty build email.
+
+     \
+     build-email build-{warning,error}-email
+     builds build-{include,exclude}
+     \
+
      While the exact interpretation of the CI request depends on the specific
      service, normally, the CI server will respond with a reference that can
      be used to query the results. See \l{brep#ci Package CI} for details on
@@ -83,6 +104,49 @@ namespace bdep
       "Remote repository URL for the project."
     }
 
+    // Note: the following options are for documentation only (see --overrides
+    // below for details).
+    //
+    strings --override
+    {
+      "<name>:<value>",
+      "Package manifest value override. Repeat this option to override
+       multiple values."
+    }
+
+    path --overrides-file
+    {
+      "<file>",
+      "Read manifest value overrides from the specified manifest fragment
+       file. Repeat this option to specify multiple override files."
+    }
+
+    strings --builds
+    {
+      "<class-expr>",
+      "Shortcut for \c{\b{--override\ builds:}<class-expr>}."
+    }
+
+    string --build-email
+    {
+      "<email>",
+      "Shortcut for \c{\b{--override\ build-email:}<email>}."
+    }
+
+    // All the overrides-related options are handled with a common parser and
+    // are collected in a single manifest value list that is accessible via
+    // the --overrides option accessor. The --overrides option is "fake" in
+    // that it only serves to collect the values in a single list while
+    // preserving their order. Note that for this trick (or hack, if you
+    // will) to work, this option should come after all the options it
+    // aliases.
+    //
+    ci_override --overrides      |
+                --override       |
+                --overrides-file |
+                --builds         |
+                --build-email;
+
     string --simulate
     {
       "<outcome>",
-- 
cgit v1.1