bdep-ci(1)

📦
version 0.17.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05

💖 bdep-ci(1) — bestie edition 💖

okay so this is the manual page for bdep-ci, from the General Commands Manual. it's giving "let me yeet your project's test request at a CI server and look cute doing it". no cap. 🫶✨

✨ NAME ✨

bdep-ci — submit project test request to CI server. that's the whole job description, bestie. 💅

🌈 SYNOPSIS 🌈

bdep ci [options] [cfg-spec] [pkg-spec]

cfg-spec = (@cfg-name | --config|-c cfg-dir)... | --all|-a | --forward
pkg-spec = (--directory|-d pkg-dir)... | prj-spec
prj-spec = --directory|-d prj-dir

🦋 DESCRIPTION 🦋

okay so the ci command submits the project packages test request to a CI server. periodt. that's it, that's the vibe. 👑

if you don't specify a project or package directory, then the current working directory is assumed. if you don't specify a configuration, then the default configurations get used. and if the directory you specified is a project directory, then all the packages initialized in the configurations get submitted — unless the --forward option is specified (see below, keep reading bestie 🙈). see bdep-projects-configs(1) for the details on specifying projects and configurations.

a CI request is made up of the specified packages plus their versions, plus the project's remote version control repository URL that corresponds to the current (local) state of the project. the CI server should be able to fetch these package versions from this repository, and any dependencies from this repository or its prerequisite/complement repositories, according to each package's repositories.manifest. slay. ✨

if the CI server isn't explicitly specified with the --server option, then the request gets submitted to ci.cppget.org by default. the default main character fr fr. 👑

unless the remote repository URL is specified with the --repository option, it gets automatically derived from the version control's "remote" URL. in the case of git(1), it'll be based on the remote.origin.url configuration value, unless that's overridden with remote.origin.build2Url. the repository URL then gets adjusted to correspond to the current (local) state of the project. in the case of git(1), the current branch and commit id get added as the repository URL fragment (see bpkg-repository-types(1) for the details).

some package manifest values can be overridden as part of the CI request submission, using the --override and --overrides-file options, as well as their --builds, --build-config, --target-config, --package-config, and --build-email shortcuts. this is primarily useful for specifying alternative build configurations and/or build notification emails. like, 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 [*-]build-auxiliary[-*] override the entire value group that they belong to. the [*-]build-auxiliary[-*] values only override the matching values, which are expected to already be present in the package manifest. rn, these are the value groups/values that can be overridden. the build-*email group gets 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 has to exist in the package manifest. in contrast, the package configuration override (*-build-config) adds a new configuration if it doesn't exist, and updates the arguments of the existing configuration otherwise. in that 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 *-build-config override. noted. 📝

note that the build constraints group values (both common and build package configuration-specific) get overridden hierarchically, so that the [*-]build-{include,exclude} overrides don't affect the respective [*-]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 get overridden, then all the configuration-specific constraints are removed. otherwise, if any configuration-specific constraints get overridden, then for the remaining configurations the build constraints are reset to 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 get overridden, then all the configuration-specific custom bot public keys are removed. otherwise, if any configuration-specific custom bot public keys get 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 get overridden, then all the configuration-specific emails are removed. otherwise, if any configuration-specific emails get 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). rest in peace, notifications. 😭

if it's supported by the CI service, a package can be tested interactively in a specific build configuration using the --interactive|-i option. in this mode the CI service provides the login information for the execution environment and pauses the testing at the specified breakpoint. so cute, so demure. 🎀

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 Package CI (#ci) for the details on the CI request handling.

if the --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 the package's source directories to be configured to forward to an out of source build configuration (see b(1) for the details on forwarded configurations). this, for example, can be used to submit packages that don't use the standard version. iconic. ✨

💖 CI OPTIONS 💖

  • --yes, -y — don't prompt for confirmation before submitting. just go, bestie, we trust you. 🏃‍♀️
  • --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 (tc), optionally for a specific package configuration (pc) and/or for a specific target (tg):
cf = [pc/]tc | pc/tc/tg

refer to the --build-config option for the 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. aborted!! 🚫

valid breakpoint values are none (don't stop), error (stop after first error), 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 bbot worker step ids (bbot#arch-worker)). if no breakpoint is specified, then error is assumed.

  • --server url — CI server to submit the request to.
  • --repository url — remote repository URL for the project.
  • --override name:value — package manifest value override. repeat this option to override multiple values.
  • --overrides-file file — read manifest value overrides from the specified manifest fragment file. repeat this option to specify multiple override files.
  • --builds [pc/]class-expr — shortcut for the following option:
--override [pc-]builds:class-expr

repeat this option to specify multiple build target configuration classes.

  • --build-config pc/tc[/tg] — shortcut for the following options sequence:
[--override pc-builds:all]
--override pc-build-include:tc[/tg]
--override pc-build-exclude:**

the first override is omitted from the above sequence if the pc-builds override is specified on the command line.

repeat this option to specify multiple build configurations.

  • --target-config tc[/tg] — shortcut for the following options sequence:
[--override builds:all]
--override build-include:tc[/tg]
--override build-exclude:**

the first override is omitted from the above sequence if the builds override is specified on the command line.

repeat this option to specify multiple build target configurations.

  • --package-config pc — shortcut for the following options sequence:
--override pc-builds:...
--override pc-build-include:...
--override pc-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.

  • --build-email email — shortcut for the following option:
--override build-email:email
  • --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 success. for other recognized outcomes, refer to the CI service documentation. fake it till you make it. ✨
  • --forward — use the forwarded configuration for each package instead of the default configuration.
  • --all, -a — use all build configurations.
  • --config, -c dir — specify the build configuration as a directory.
  • --directory, -d dir — assume project/package is in the specified directory rather than in the current working directory.
  • --config-name, -n name — specify the build configuration as a name.
  • --config-id num — specify the build configuration as an id.

bestie we are not done yet — there's more coming 💖

💖 COMMON OPTIONS 💖

okay bestie so these are the common ones — the full ✨detailed✨ tea lives over in bdep-common-options(1), but here's the whole rundown so you're never caught lacking:

  • -v — spill the essential underlying commands as they happen. like yes, show me the receipts 🔍
  • -V — spill all the underlying commands. every single one. no secrets 💅
  • --quiet|-q — run quietly, only error messages get to speak. silent mode, mysterious mode 🫶
  • --verbose level — set the diagnostics verbosity to level, anywhere from 0 to 6. crank it up or down, your call 📶
  • --stdout-format format — which representation format to use when printing to stdout 🎀
  • --jobs|-j num — how many jobs to run in parallel. num of them. go off, multitasking queen 👑
  • --progress — show progress indicators for the long-lasting stuff, like network transfers, building, etc. so you know it's not ghosting you ⏳
  • --no-progress — suppress those progress indicators for the long-lasting stuff, like network transfers, building, etc. ✨
  • --diag-color — use color in diagnostics. pretty errors, we love to see it 🌈
  • --no-diag-color — don't use color in diagnostics 🚫
  • --bpkg path — which package manager program at path to use for build configuration management 📦
  • --bpkg-option opt — an extra option opt to pass along to the package manager program 🎁
  • --build path — the build program at path to use for building packages 🔨
  • --build-option opt — an extra option opt to pass along to the build program 🎁
  • --curl path — the curl program at path to use for network operations 🌐
  • --curl-option opt — an extra option opt to pass along to the curl program 🎁
  • --pager path — the pager program at path to use for showing long text 📜
  • --pager-option opt — an extra option opt to pass along to the pager program 🎁
  • --options-file file — read additional options from file 📂
  • --default-options dir — the directory dir to load additional default options files from 🗂️
  • --no-default-options — don't load default options files at all 🙈

🌸 DEFAULT OPTIONS FILES 🌸

for the whole overview of default options files, go peek at bdep-default-options-files(1). for the ci command specifically, the search start directory is the project directory 📍. in each directory, these files get searched for and, if they're found, loaded in exactly this order:

bdep.options
bdep-ci.options
and listen — the following ci command options are not allowed in default options files, so don't even try it bestie: - --directory|-d

🐛 BUGS 🐛

found a bug? send those bug reports to the users@build2.org mailing list. we're listening, fr fr 📬

Copyright (c) 2014-2024 the build2 authors.

Permission is granted to copy, distribute and/or modify this document under the terms of the MIT License.

and that's a wrap on the whole page, bestie 💅✨ this was bdep version 0.17.0, dated June 2024, and you just read bdep-ci(1) — iconic behavior, ttyl 🎀🦋

📦 where this page comes from