1bdep-ci(1) General Commands Manual bdep-ci(1)
2
6 bdep-ci - submit project test request to CI server
7
9 bdep ci [options] [cfg-spec] [pkg-spec]
10 cfg-spec = (@cfg-name | --config|-c cfg-dir)... | --all|-a | --forward
12 pkg-spec = (--directory|-d pkg-dir)... | prj-spec
13 prj-spec = --directory|-d prj-dir
14
16 The ci command submits the project packages test request to a CI
17 server.
18 If no project or package directory is specified, then the current work‐
20 ing directory is assumed. If no configuration is specified, then the
21 default configurations are used. If the specified directory is a
22 project directory, then all the packages initialized in the configura‐
23 tions are submitted, unless the --forward option is specified (see be‐
24 low). See bdep-projects-configs(1) for details on specifying projects
25 and configurations.
26 A CI request consists of the specified packages and their versions as
28 well as the project's remote version control repository URL correspond‐
29 ing to the current (local) state of the project. The CI server should
30 be able to fetch these package versions from this repository as well as
31 any dependencies from this repository or its prerequisite/complement
32 repositories, according to each package's repositories.manifest.
33 If the CI server is not explicitly specified with the --server option,
35 the request is submitted to ci.cppget.org by default.
36 Unless the remote repository URL is specified with the --repository op‐
38 tion, it will be automatically derived from the version control's "re‐
39 mote" URL. In case of git(1), it will be based on the remote.origin.url
40 configuration value unless overridden with remote.origin.build2Url. The
41 repository URL is then adjusted to corresponding to the current (local)
42 state of the project. In case of git(1), the current branch and commit
43 id are added as the repository URL fragment (see bpkg-repository-
44 types(1) for details).
45 Some package manifest values can be overridden as part of the CI re‐
47 quest submission using the --override and --overrides-file options as
48 well as their --builds, --build-config, --target-config, --package-con‐
49 fig, and --build-email shortcuts. This is primarily useful for specify‐
50 ing alternative build configurations and/or build notification emails.
51 For example:
52 $ bdep ci --builds gcc
54 $ bdep ci --builds network/gcc
55 $ bdep ci --target-config 'linux*-gcc*'
56 $ bdep ci --package-config network
57 $ bdep ci --build-config 'network/linux*-gcc*'
58 $ bdep ci --override \
60 'default-build-config: config.foo.cache=true config.foo.buffer=16'
61 $ bdep ci --override 'mytest-build-config: config.foo.cache=true' \
63 --package-config mytest
64 Manifest overrides override the entire value group that they belong to.
66 Currently, the following value groups can be overridden. The
67 build-*email group is overridden by default as if by specifying an
68 empty build email.
69 build-email build-{warning,error}-email
71 builds build-{include,exclude}
72 *-builds *-build-{include,exclude}
73 *-build-config
74 For the package configuration-specific build constraint overrides the
76 corresponding configuration must exist in the package manifest. In con‐
77 trast, the package configuration override (*-build-config) adds a new
78 configuration if it doesn't exist and updates the arguments of the ex‐
79 isting configuration otherwise. In the former case, all the potential
80 build constraint overrides for such a newly added configuration must
81 follow the corresponding *-build-config override.
82 Note that the build constraints group values (both common and build
84 package configuration-specific) are overridden hierarchically so that
85 the [*-]build-{include,exclude} overrides don't affect the respective
86 [*-]builds values.
87 Note also that the common and build package configuration-specific
89 build constraints group value overrides are mutually exclusive. If the
90 common build constraints are overridden, then all the configuration-
91 specific constraints are removed. Otherwise, if any configuration-spe‐
92 cific constraints are overridden, then for the remaining configurations
93 the build constraints are reset to builds: none.
94 If supported by the CI service, a package can be tested interactively
96 in a specific build configuration using the --interactive|-i option. In
97 this mode the CI service provides the login information for the execu‐
98 tion environment and pauses the testing at the specified breakpoint.
99 While the exact interpretation of the CI request depends on the spe‐
101 cific service, normally, the CI server will respond with a reference
102 that can be used to query the results. See Package CI (#ci) for details
103 on the CI request handling.
104 If the --forward option is specified then the forwarded configurations
106 are used instead of the default configurations. In particular, this
107 means that in this mode the project doesn't need to be initialized and
108 all that's required is for package's source directories to be config‐
109 ured to forward to an out of source build configuration (see b(1) for
110 details on forwarded configurations). This, for example, can be used to
111 submit packages that don't use the standard version.
112
114 --yes|-y
115 Don't prompt for confirmation before submitting.
116 --interactive|-i cf[:bp]
118 Test the package interactively in the specified build configura‐
119 tion, pausing the execution at the specified breakpoint. The
120 build configuration is a target configuration (tc), optionally
121 for a specific package configuration (pc) and/or for a specific
122 target (tg):
123 cf = [pc/]tc | pc/tc/tg
125 Refer to the --build-config option for details on the build con‐
127 figuration component semantics. Note that for interactive test‐
128 ing they should identify a single build configuration. Failed
129 that, the test request will be aborted.
130 Valid breakpoint values are none (don't stop), error (stop after
132 first error), warning (stop after first warning), as well as the
133 CI service-specific step ids in which case the execution stops
134 before performing the specified step (see bbot worker step ids
135 (bbot#arch-worker)). If no breakpoint is specified, then error
136 is assumed.
137 --server url
139 CI server to submit the request to.
140 --repository url
142 Remote repository URL for the project.
143 --override name:value
145 Package manifest value override. Repeat this option to override
146 multiple values.
147 --overrides-file file
149 Read manifest value overrides from the specified manifest frag‐
150 ment file. Repeat this option to specify multiple override
151 files.
152 --builds [pc/]class-expr
154 Shortcut for the following option:
155 --override [pc-]builds:class-expr
157 Repeat this option to specify multiple build target configura‐
159 tion classes.
160 --build-config pc/tc[/tg]
162 Shortcut for the following options sequence:
163 --override pc-builds:all
165 --override pc-build-include:tc[/tg]
166 --override pc-build-exclude:**
167 Repeat this option to specify multiple build configurations.
169 --target-config tc[/tg]
171 Shortcut for the following options sequence:
172 --override builds:all
174 --override build-include:tc[/tg]
175 --override build-exclude:**
176 Repeat this option to specify multiple build target configura‐
178 tions.
179 --package-config pc
181 Shortcut for the following options sequence:
182 --override pc-builds:...
184 --override pc-build-include:...
185 --override pc-build-exclude:...
186 Where the override values are the build constraints for the
188 specified build package configuration from the package manifest.
189 Repeat this option to specify multiple build package configura‐
191 tions.
192 --build-email email
194 Shortcut for the following option:
195 --override build-email:email
197 --simulate outcome
199 Simulate the specified outcome of the CI process without actu‐
200 ally performing any externally visible actions (such as testing
201 the packages or publishing the result). The commonly used out‐
202 come value is success. For other recognized outcomes refer to
203 the CI service documentation.
204 --forward
206 Use the forwarded configuration for each package instead of the
207 default configuration.
208 --all|-a
210 Use all build configurations.
211 --config|-c dir
213 Specify the build configuration as a directory.
214 --directory|-d dir
216 Assume project/package is in the specified directory rather than
217 in the current working directory.
218 --config-name|-n name
220 Specify the build configuration as a name.
221 --config-id num
223 Specify the build configuration as an id.
224
226 The common options are summarized below with a more detailed descrip‐
227 tion available in bdep-common-options(1).
228 -v Print essential underlying commands being executed.
230 -V Print all underlying commands being executed.
232 --quiet|-q
234 Run quietly, only printing error messages.
235 --verbose level
237 Set the diagnostics verbosity to level between 0 and 6.
238 --stdout-format format
240 Representation format to use for printing to stdout.
241 --jobs|-j num
243 Number of jobs to perform in parallel.
244 --progress
246 Display progress indicators for long-lasting operations, such as
247 network transfers, building, etc.
248 --no-progress
250 Suppress progress indicators for long-lasting operations, such
251 as network transfers, building, etc.
252 --diag-color
254 Use color in diagnostics.
255 --no-diag-color
257 Don't use color in diagnostics.
258 --bpkg path
260 The package manager program to be used for build configuration
261 management.
262 --bpkg-option opt
264 Additional option to be passed to the package manager program.
265 --build path
267 The build program to be used to build packages.
268 --build-option opt
270 Additional option to be passed to the build program.
271 --curl path
273 The curl program to be used for network operations.
274 --curl-option opt
276 Additional option to be passed to the curl program.
277 --pager path
279 The pager program to be used to show long text.
280 --pager-option opt
282 Additional option to be passed to the pager program.
283 --options-file file
285 Read additional options from file.
286 --default-options dir
288 The directory to load additional default options files from.
289 --no-default-options
291 Don't load default options files.
292
294 See bdep-default-options-files(1) for an overview of the default op‐
295 tions files. For the ci command the search start directory is the
296 project directory. The following options files are searched for in each
297 directory and, if found, loaded in the order listed:
298 bdep.options
300 bdep-ci.options
301 The following ci command options cannot be specified in the default op‐
303 tions files:
304 --directory|-d
306
308 Send bug reports to the users@build2.org mailing list.
309
311 Copyright (c) 2014-2023 the build2 authors.
312 Permission is granted to copy, distribute and/or modify this document
314 under the terms of the MIT License.
315bdep 0.16.0 June 2023 bdep-ci(1)