path: root/bdep/ci.cli

// file      : bdep/ci.cli
// license   : MIT; see accompanying LICENSE file

include <bdep/project.cli>;
include <bdep/ci-types.hxx>;

"\section=1"
"\name=bdep-ci"
"\summary=submit project test request to CI server"

namespace bdep
{
  {
    "<options>
     <prj-spec> <prj-dir>
     <pkg-spec> <pkg-dir>
     <cfg-spec> <cfg-name> <cfg-dir>",

    "\h|SYNOPSIS|

     \c{\b{bdep ci} [<options>] [<cfg-spec>] [<pkg-spec>]}

     \c{<cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a} | \b{--forward}\n
        <pkg-spec> = (\b{--directory}|\b{-d} <pkg-dir>)... | <prj-spec>\n
        <prj-spec> = \b{--directory}|\b{-d} <prj-dir>}

     \h|DESCRIPTION|

     The \cb{ci} command submits the project packages test request to a CI
     server.

     If no project or package directory is specified, then the current working
     directory is assumed. If no configuration is specified, then the default
     configurations are used. If the specified directory is a project
     directory, then all the packages initialized in the configurations are
     submitted, unless the \cb{--forward} option is specified (see below). See
     \l{bdep-projects-configs(1)} for details on specifying projects and
     configurations.

     A CI request consists of the specified packages and their versions as
     well as the project's remote version control repository URL corresponding
     to the current (local) state of the project. The CI server should be able
     to fetch these package versions from this repository as well as any
     dependencies from this repository or its prerequisite/complement
     repositories, according to each package's \cb{repositories.manifest}.

     If the CI server is not explicitly specified with the \cb{--server}
     option, the request is submitted to \cb{ci.cppget.org} by default.

     Unless the remote repository URL is specified with the \cb{--repository}
     option, it will be automatically derived from the version control's
     \"remote\" URL. In case of \cb{git(1)}, it will be based on the
     \cb{remote.origin.url} configuration value unless overridden with
     \cb{remote.origin.build2Url}. The repository URL is then adjusted to
     corresponding to the current (local) state of the project. In case of
     \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}, \cb{--build-config}, \cb{--target-config},
     \cb{--package-config}, 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
     $ bdep ci --builds network/gcc
     $ bdep ci --target-config 'linux*-gcc*'
     $ bdep ci --package-config network
     $ bdep ci --build-config 'network/linux*-gcc*'

     $ bdep ci --override \
       'default-build-config: config.foo.cache=true config.foo.buffer=16'

     $ bdep ci --override 'mytest-build-config: config.foo.cache=true' \
       --package-config mytest

     $ bdep ci --override 'build-auxiliary: *-postgresql_16'
     \

     Manifest overrides other than \c{[\b{*-}]\b{build-auxiliary}[\b{-*}]}
     override the entire value group that they belong to. The
     \c{[\b{*-}]\b{build-auxiliary}[\b{-*}]} values only override the matching
     values, which are expected to already be present in the package manifest.
     Currently, the following value groups/values can be overridden. The
     \cb{build-*email} group is overridden by default as if by specifying an
     empty build email.

     \
     build-email build-{warning,error}-email
     builds build-{include,exclude}
     build-bot
     *-builds *-build-{include,exclude}
     *-build-bot
     *-build-config
     *-build-email *-build-{warning,error}-email

     [*-]build-auxiliary[-*]
     \

     For the package configuration-specific build constraint, email,
     auxiliary, and custom bot public key overrides, the corresponding
     configuration must exist in the package manifest. In contrast, the
     package configuration override (\cb{*-build-config}) adds a new
     configuration if it doesn't exist and updates the arguments of the
     existing configuration otherwise. In the former case, all the potential
     build constraint, email, auxiliary, and custom bot public key overrides
     for such a newly added configuration must follow the corresponding
     \cb{*-build-config} override.

     Note that the build constraints group values (both common and build
     package configuration-specific) are overridden hierarchically so that the
     \c{[\b{*-}]\b{build-}{\b{include},\b{exclude}\}} overrides don't affect
     the respective \c{[\b{*-}]\b{builds}} values.

     Note also that the common and build package configuration-specific build
     constraints group value overrides are mutually exclusive. If the common
     build constraints are overridden, then all the configuration-specific
     constraints are removed. Otherwise, if any configuration-specific
     constraints are overridden, then for the remaining configurations the
     build constraints are reset to \cb{builds:\ none}.

     Similar to the build constraints groups, the common and build package
     configuration-specific custom bot public key value overrides are mutually
     exclusive. If the common build custom bot public keys are overridden,
     then all the configuration-specific custom bot public keys are removed.
     Otherwise, if any configuration-specific custom bot public keys are
     overridden, then for the remaining configurations the custom bot public
     keys are left unchanged.

     Similar to the above, the common and build package configuration-specific
     build emails group value overrides are mutually exclusive. If the common
     build emails are overridden, then all the configuration-specific emails
     are removed. Otherwise, if any configuration-specific emails are
     overridden, then for the remaining configurations the build emails are
     reset to the empty values and the build warning and error emails are
     removed (which effectively disables email notifications for such
     configurations).

     If supported by the CI service, a package can be tested interactively
     in a specific build configuration using the \c{\b{--interactive}|\b{-i}}
     option. In this mode the CI service provides the login information for
     the execution environment and pauses the testing at the specified
     breakpoint.

     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
     the CI request handling.

     If the \cb{--forward} option is specified then the forwarded
     configurations are used instead of the default configurations. In
     particular, this means that in this mode the project doesn't need to be
     initialized and all that's required is for package's source directories
     to be configured to forward to an out of source build configuration (see
     \l{b(1)} for details on forwarded configurations). This, for example, can
     be used to submit packages that don't use the standard version.
     "
  }

  class cmd_ci_options: project_options
  {
    "\h|CI OPTIONS|"

    bool --yes|-y
    {
      "Don't prompt for confirmation before submitting."
    }

    string --interactive|-i
    {
      "<cf>[:<bp>]",
      "Test the package interactively in the specified build configuration,
       pausing the execution at the specified breakpoint. The build
       configuration is a target configuration (\ci{tc}), optionally for a
       specific package configuration (\ci{pc}) and/or for a specific target
       (\ci{tg}):

       \c{<cf> = [\i{pc}\b{/}]\i{tc} | \i{pc}\b{/}\i{tc}\b{/}\i{tg}}

       Refer to the \cb{--build-config} option for details on the build
       configuration component semantics. Note that for interactive testing
       they should identify a single build configuration. Failed that, the
       test request will be aborted.

       Valid breakpoint values are \cb{none} (don't stop), \cb{error} (stop
       after first error), \cb{warning} (stop after first warning), as well as
       the CI service-specific step ids in which case the execution stops
       before performing the specified step (see \l{bbot#arch-worker \cb{bbot}
       worker step ids}). If no breakpoint is specified, then \cb{error} is
       assumed."
    }

    url --server
    {
      "<url>",
      "CI server to submit the request to."
    }

    url --repository
    {
      "<url>",
      "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
    {
      "[<pc>/]<class-expr>",
      "Shortcut for the following option:

       \c{\b{--override\ }[<pc>\b{-}]\b{builds:}<class-expr>}

       Repeat this option to specify multiple build target configuration
       classes."
    }

    strings --build-config
    {
      "<pc>/<tc>[/<tg>]",
      "Shortcut for the following options sequence:

       \c{\b{--override\ }<pc>\b{-builds:all}}\n
       \c{\b{--override\ }<pc>\b{-build-include:}<tc>[\b{/}<tg>]}\n
       \c{\b{--override\ }<pc>\b{-build-exclude:**}}

       Repeat this option to specify multiple build configurations."
    }

    strings --target-config
    {
      "<tc>[/<tg>]",
      "Shortcut for the following options sequence:

       \c{\b{--override\ builds:all}}\n
       \c{\b{--override\ build-include:}<tc>[\b{/}<tg>]}\n
       \c{\b{--override\ build-exclude:**}}

       Repeat this option to specify multiple build target configurations."
    }

    strings --package-config
    {
      "<pc>",
      "Shortcut for the following options sequence:

       \c{\b{--override\ }<pc>\b{-builds:}...}\n
       \c{\b{--override\ }<pc>\b{-build-include:}...}\n
       \c{\b{--override\ }<pc>\b{-build-exclude:}...}

       Where the override values are the build constraints for the specified
       build package configuration from the package manifest.

       Repeat this option to specify multiple build package configurations."
    }

    string --build-email
    {
      "<email>",
      "Shortcut for the following option:

       \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.
    //
    cmd_ci_override --overrides      |
                    --override       |
                    --overrides-file |
                    --builds         |
                    --build-email;

    string --simulate
    {
      "<outcome>",
      "Simulate the specified outcome of the CI process without actually
       performing any externally visible actions (such as testing the packages
       or publishing the result). The commonly used outcome value is
       \cb{success}. For other recognized outcomes refer to the CI service
       documentation."
    }

    bool --forward
    {
      "Use the forwarded configuration for each package instead of the
       default configuration."
    }
  };

  "
   \h|DEFAULT OPTIONS FILES|

   See \l{bdep-default-options-files(1)} for an overview of the default
   options files. For the \cb{ci} command the search start directory is
   the project directory. The following options files are searched for in
   each directory and, if found, loaded in the order listed:

   \
   bdep.options
   bdep-ci.options
   \

   The following \cb{ci} command options cannot be specified in the
   default options files:

   \
   --directory|-d
   \
  "
}