1bdep(1) General Commands Manual bdep(1)
2
6 bdep - project dependency manager
7
9 bdep --help
10 bdep --version
11 bdep help [command | topic]
12 bdep [common-options] command [command-options] command-args
13
15 The build2 project dependency manager is used to manage the dependen‐
16 cies of a project during development.
17 For a detailed description of any command or help topic, use the help
19 command or see the corresponding man page (the man pages have the bdep-
20 prefix, for example bdep-help(1)). Note also that command-options and
21 command-args can be specified in any order and common-options can be
22 specified as part of command-options.
23 A bdep project is a directory, normally under a version control system
25 such as git(1), called project repository. A project contains one or
26 more packages. If it contain several, then they are normally related,
27 for example, the libhello library and the hello program.
28 Packages in a project may depend on other packages outside of the
30 project. To distinguish between the two we call them project packages
31 and dependency packages, respectively. Naturally, our project packages
32 may be someone else's dependency packages.
33 A simple, single-package project contains the package in the root of
35 the project repository. For example (note the location of the package
36 manifest and lockfile):
37 hello/
39 |-- .git/
40 |-- ...
41 |-- lockfile
42 `-- manifest
43 See Package Manifest (#manifest-package) for details on the manifest
45 file.
46 If a project contains multiple packages or we wish to place the package
48 into a subdirectory, then the root of the project repository must con‐
49 tain the packages.manifest file that specifies the package locations.
50 For example:
51 hello/
53 |-- .git/
54 |-- hello/
55 | |-- ...
56 | |-- lockfile
57 | `-- manifest
58 |-- libhello/
59 | |-- ...
60 | |-- lockfile
61 | `-- manifest
62 `-- packages.manifest
63 For this project, packages.manifest would have the following contents:
65 : 1
67 location: hello/
68 :
69 location: libhello/
70 A project repository root would usually also contain the reposito‐
72 ries.manifest file that lists the repositories that provide the depen‐
73 dency packages. For example:
74 hello/
76 |-- ...
77 |-- manifest
78 `-- repositories.manifest
79 If our hello project wanted to use libhello as a dependency package,
81 then its repositories.manifest could look like this:
82 : 1
84 summary: hello project repository
85 :
86 role: prerequisite
87 location: https://example.com/libhello.git
88 See Repository List Manifest (#manifest-repository-list) for details on
90 the repositories.manifest file.
91 For development a bdep project is associated with one or more bpkg(1)
93 build configurations. These configuration are used as a backing for
94 building project packages and their dependencies.
95 The list of the associated build configuration as well as the list of
97 project packages initialized in each configuration are stored in the
98 bdep project database under the .bdep/ subdirectory of the project root
99 directory. For example:
100 hello-gcc/ # Build configuration for gcc.
102 hello-clang/ # Build configuration for clang.
103 hello/
104 |-- .bdep/
105 |-- .git/
106 `-- ...
107 The core of bdep functionality is state synchronization between the
109 project and one or more associated build configurations. For example,
110 if we list a new dependency in the package's manifest file, then bdep
111 fetches and configures this dependency in a build configuration. Simi‐
112 larly, if we upgrade or downgrade a dependency in a build configura‐
113 tion, then bdep updates the corresponding entry in the package's lock‐
114 file.
115 A typical bdep workflow would consist of the following steps.
117 Obtain the Project
119 Normally we would use the version control system to obtain the
120 project we want to develop:
121 $ git clone ssh://example.com/hello.git
123 Alternatively, we can use the bdep-new(1) command to start a new
125 project (see Package Name (#package-name) for details on project
126 naming):
127 $ bdep new -l c++ -t exe hello
129 Similar to version control tools, we normally run bdep from the
131 project's directory or one of its subdirectories:
132 $ cd hello
134 See bdep-projects-configs(1) for alternative ways to specify the
136 project location.
137 Initialize the Project
139 Next we use the bdep-init(1) command to create new or add exist‐
140 ing build configurations and initialize our project in these
141 configurations:
142 $ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
144 $ bdep init -A ../hello-clang @clang
145 If the configuration directory is next to the project and its
147 name is in the prj-name-cfg-name form, then the shortcut version
148 of the init can be used instead:
149 $ bdep init -C @gcc cc config.cxx=g++
151 $ bdep init -A @clang
152 After initialization we can use the bdep-status(1) command to
154 examine the status of our project in its configurations:
155 $ bdep status -a
157 in configuration @gcc:
158 hello configured 0.1.0-a.0.19700101000000
159 in configuration @clang:
161 hello configured 0.1.0-a.0.19700101000000
162 Most bdep commands operate on one or more build configurations
164 associated with the project. If we don't specify one explicitly,
165 then the default configuration (usually the first added; gcc in
166 our case) is used. Alternatively, we can specify the configura‐
167 tions by name (if assigned), as directories, or with --all|-a
168 (see bdep-projects-configs(1) for details). For example:
169 $ bdep status @clang @gcc # by name
171 $ bdep status -c ../hello-gcc # as a directory
172 If a command is operating on multiple configurations (like sta‐
174 tus -a in the previous example), then it will print a line iden‐
175 tifying each configuration before printing the command's result.
176 By default the project's source directory is configured to for‐
178 ward to the default build configuration. That is, we can run the
179 build system in the source directory and it will automatically
180 build in the forwarded configuration as well as link the results
181 back to the source directory using symlinks or another suitable
182 mechanism (see bdep-config(1) for details). For example:
183 $ b # build in gcc
185 <...>
186 $ ./hello # run the result
188 Using the build system directly on configurations other than the
190 default requires explicitly specifying their paths. To make this
191 more convenient, the bdep-update(1), bdep-test(1), and bdep-
192 clean(1) commands allow us to refer to them by names, perform
193 the desired build system operation on several of them at once,
194 and, in case of test, perform it on immediate or all dependen‐
195 cies or a project. For example:
196 $ bdep test @gcc @clang
198 in configuration @gcc:
199 <...>
200 in configuration @clang:
202 <...>
203 To deinitialize a project in one or more build configurations we
205 can use the bdep-deinit(1) command. For example:
206 $ bdep deinit -a
208 Add, Remove, or Change Dependencies
210 Let's say we found libhello that we would like to use in our
211 project. First we edit our project's repositories.manifest file
212 and add the libhello's repository as our prerequisite:
213 $ cat repositories.manifest
215 ...
216 role: prerequisite
217 location: https://example.com/libhello.git
218 ...
219 Next we edit our manifest file and specify a dependency on lib‐
221 hello:
222 $ cat manifest
224 ...
225 depends: libhello ^1.0.0
226 ...
227 If we now run bdep-status(1), we will notice that a new itera‐
229 tion of our project is available for synchronization:
230 $ bdep status
232 hello configured 0.1.0-a.0.19700101000000
233 available 0.1.0-a.0.19700101000000#1
234 See Package Version (#package-version) for details on package
236 versions and iterations.
237 Synchronize the Project with Configurations
239 To synchronize changes in the project's dependency information
240 with its build configurations we use the bdep-sync(1) command.
241 Continuing with our example, this will result in libhello being
242 downloaded and configured since our project now depends on it:
243 $ bdep sync
245 synchronizing:
246 build libhello/1.0.0 (required by hello)
247 upgrade hello/0.1.0-a.0.19700101000000#1
248 $ bdep status -i
250 hello configured 0.1.0-a.0.19700101000000#1
251 libhello ^1.0.0 configured 1.0.0
252 Note that by default build configurations are automatically syn‐
254 chronized on every build system invocation (see bdep-config(1)
255 for details). As a result, we rarely need to run the sync com‐
256 mand explicitly and instead can just run the desired build sys‐
257 tem operation (for instance, update or test) directly. For exam‐
258 ple:
259 $ b test
261 synchronizing:
262 build libhello/1.0.0 (required by hello)
263 upgrade hello/0.1.0-a.0.19700101000000#1
264 <...>
265 It is also possible for several projects to share a build con‐
267 figuration. In this case all the projects are synchronized at
268 once regardless of the originating project. For example, if we
269 were also the authors of libhello and hosted it in a separate
270 version control repository (as opposed to being a package in the
271 hello repository), then it would have been natural to develop it
272 together with hello in the same configurations:
273 $ cd ../libhello
275 $ bdep init -A ../hello-gcc @gcc
276 $ bdep sync # synchronizes both hello and libhello
277 Upgrade or Downgrade Dependencies
279 The bdep-sync(1) command is also used to upgrade or downgrade
280 dependencies (and it is also executed as the last step of init).
281 Let's say we learned a new version of libhello was released and
282 we would like to try it out.
283 To refresh the list of available dependency packages we use the
285 bdep-fetch(1) command (or, as a shortcut, the -f flag to sta‐
286 tus):
287 $ bdep fetch
289 $ bdep status libhello
291 libhello configured 1.0.0 available [1.1.0]
292 Without an explicit version or the --patch|-p option, sync will
294 upgrade the specified dependency to the latest available ver‐
295 sion:
296 $ bdep sync libhello
298 synchronizing:
299 upgrade libhello/1.1.0
300 reconfigure hello/0.1.0
301 $ bdep status -i
303 hello configured 0.1.0-a.0.19700101000000#1
304 libhello ^1.0.0 configured 1.1.0
305 Let's say we didn't like the new version and would like to go
307 back to using the old one. To downgrade a dependency we have to
308 specify its version explicitly:
309 $ bdep status -o libhello
311 libhello configured 1.1.0 available [1.0.0] (1.1.0)
312 $ bdep sync libhello/1.0.0
314 synchronizing:
315 downgrade libhello/1.1.0
316 reconfigure hello/0.1.0
317
319 help [topic]
320 bdep-help(1) – show help for a command or help topic
321 new bdep-new(1) – create and initialize new project
323 init bdep-init(1) – initialize project in build configurations
325 sync bdep-sync(1) – synchronize project and build configurations
327 fetch bdep-fetch(1) – fetch list of available project dependencies
329 status bdep-status(1) – print status of project and/or its dependencies
331 ci bdep-ci(1) – submit project test request to CI server
333 release
335 bdep-release(1) – manage project's version during release
336 publish
338 bdep-publish(1) – publish project to archive repository
339 deinit bdep-deinit(1) – deinitialize project in build configurations
341 config bdep-config(1) – manage project's build configurations
343 test bdep-test(1) – test project in build configurations
345 update bdep-update(1) – update project in build configurations
347 clean bdep-clean(1) – clean project in build configurations
349
351 common-options
352 bdep-common-options(1) – details on common options
353 projects-configs
355 bdep-projects-configs(1) – specifying projects and configura‐
356 tions
357 default-options-files
359 bdep-default-options-files(1) – specifying default options
360 argument-grouping
362 bdep-argument-grouping(1) – argument grouping facility
363
365 The common options are summarized below with a more detailed descrip‐
366 tion available in bdep-common-options(1).
367 -v Print essential underlying commands being executed.
369 -V Print all underlying commands being executed.
371 --quiet|-q
373 Run quietly, only printing error messages.
374 --verbose level
376 Set the diagnostics verbosity to level between 0 and 6.
377 --stdout-format format
379 Representation format to use for printing to stdout.
380 --jobs|-j num
382 Number of jobs to perform in parallel.
383 --progress
385 Display progress indicators for long-lasting operations, such as
386 network transfers, building, etc.
387 --no-progress
389 Suppress progress indicators for long-lasting operations, such
390 as network transfers, building, etc.
391 --bpkg path
393 The package manager program to be used for build configuration
394 management.
395 --bpkg-option opt
397 Additional option to be passed to the package manager program.
398 --build path
400 The build program to be used to build packages.
401 --build-option opt
403 Additional option to be passed to the build program.
404 --curl path
406 The curl program to be used for network operations.
407 --curl-option opt
409 Additional option to be passed to the curl program.
410 --pager path
412 The pager program to be used to show long text.
413 --pager-option opt
415 Additional option to be passed to the pager program.
416 --options-file file
418 Read additional options from file.
419 --default-options dir
421 The directory to load additional default options files from.
422 --no-default-options
424 Don't load default options files.
425
427 Non-zero exit status is returned in case of an error.
428
430 The BDEP_DEF_OPT environment variable is used to suppress loading of
431 default options files in nested bdep invocations. Its values are false
432 or 0 to suppress and true or 1 to load.
433
435 Send bug reports to the users@build2.org mailing list.
436
438 Copyright (c) 2014-2022 the build2 authors.
439 Permission is granted to copy, distribute and/or modify this document
441 under the terms of the MIT License.
442bdep 0.15.0 July 2022 bdep(1)