1bdep(1)                     General Commands Manual                    bdep(1)
2
3
4

NAME

6       bdep - project dependency manager
7

SYNOPSIS

9       bdep --help
10       bdep --version
11       bdep help [command | topic]
12       bdep [common-options] command [command-options] command-args
13

DESCRIPTION

15       The  build2  project dependency manager is used to manage the dependen‐
16       cies of a project during development.
17
18       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
24       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
29       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
34       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
38       hello/
39       ├── .git/
40       ├── ...
41       ├── lockfile
42       └── manifest
43
44       See Package Manifest (#manifest-package) for details  on  the  manifest
45       file.
46
47       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
52       hello/
53       ├── .git/
54       ├── hello/
55       │   ├── ...
56       │   ├── lockfile
57       │   └── manifest
58       ├── libhello/
59       │   ├── ...
60       │   ├── lockfile
61       │   └── manifest
62       └── packages.manifest
63
64       For this project, packages.manifest would have the following contents:
65
66       : 1
67       location: hello/
68       :
69       location: libhello/
70
71       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
75       hello/
76       ├── ...
77       ├── manifest
78       └── repositories.manifest
79
80       If our hello project wanted to use libhello as  a  dependency  package,
81       then its repositories.manifest could look like this:
82
83       : 1
84       summary: hello project repository
85       :
86       role: prerequisite
87       location: https://example.com/libhello.git
88
89       See Repository List Manifest (#manifest-repository-list) for details on
90       the repositories.manifest file.
91
92       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
96       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
101       hello-gcc/     # Build configuration for gcc.
102       hello-clang/   # Build configuration for clang.
103       hello/
104       ├── .bdep/
105       ├── .git/
106       └── ...
107
108       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
116       A typical bdep workflow would consist of the following steps.
117
118       Obtain the Project
119              Normally  we  would use the version control system to obtain the
120              project we want to develop:
121
122              $ git clone ssh://example.com/hello.git
123
124              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
128              $ bdep new -l c++ -t exe hello
129
130              Similar to version control tools, we normally run bdep from  the
131              project's directory or one of its subdirectories:
132
133              $ cd hello
134
135              See bdep-projects-configs(1) for alternative ways to specify the
136              project location.
137
138       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
143              $ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
144              $ bdep init -A ../hello-clang @clang
145
146              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
150              $ bdep init -C @gcc cc config.cxx=g++
151              $ bdep init -A @clang
152
153              After initialization we can use the  bdep-status(1)  command  to
154              examine the status of our project in its configurations:
155
156              $ bdep status -a
157              in configuration @gcc:
158              hello configured 0.1.0-a.0.19700101000000
159
160              in configuration @clang:
161              hello configured 0.1.0-a.0.19700101000000
162
163              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
170              $ bdep status @clang @gcc      # by name
171              $ bdep status -c ../hello-gcc  # as a directory
172
173              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
177              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
184              $ b        # build in gcc
185              <...>
186
187              $ ./hello  # run the result
188
189              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
197              $ bdep test @gcc @clang
198              in configuration @gcc:
199              <...>
200
201              in configuration @clang:
202              <...>
203
204              To deinitialize a project in one or more build configurations we
205              can use the bdep-deinit(1) command. For example:
206
207              $ bdep deinit -a
208
209       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
214              $ cat repositories.manifest
215              ...
216              role: prerequisite
217              location: https://example.com/libhello.git
218              ...
219
220              Next we edit our manifest file and specify a dependency on  lib‐
221              hello:
222
223              $ cat manifest
224              ...
225              depends: libhello ^1.0.0
226              ...
227
228              If  we  now run bdep-status(1), we will notice that a new itera‐
229              tion of our project is available for synchronization:
230
231              $ bdep status
232              hello configured 0.1.0-a.0.19700101000000
233                    available  0.1.0-a.0.19700101000000#1
234
235              See Package Version (#package-version) for  details  on  package
236              versions and iterations.
237
238       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
244              $ bdep sync
245              synchronizing:
246                build libhello/1.0.0 (required by hello)
247                upgrade hello/0.1.0-a.0.19700101000000#1
248
249              $ bdep status -i
250              hello configured 0.1.0-a.0.19700101000000#1
251                libhello ^1.0.0 configured 1.0.0
252
253              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
260              $ 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
266              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
274              $ cd ../libhello
275              $ bdep init -A ../hello-gcc @gcc
276              $ bdep sync  # synchronizes both hello and libhello
277
278       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
284              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
288              $ bdep fetch
289
290              $ bdep status libhello
291              libhello configured 1.0.0 available [1.1.0]
292
293              Without an explicit version or the --patch|-p option, sync  will
294              upgrade  the  specified  dependency to the latest available ver‐
295              sion:
296
297              $ bdep sync libhello
298              synchronizing:
299                upgrade libhello/1.1.0
300                reconfigure hello/0.1.0
301
302              $ bdep status -i
303              hello configured 0.1.0-a.0.19700101000000#1
304                libhello ^1.0.0 configured 1.1.0
305
306              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
310              $ bdep status -o libhello
311              libhello configured 1.1.0 available [1.0.0] (1.1.0)
312
313              $ bdep sync libhello/1.0.0
314              synchronizing:
315                downgrade libhello/1.1.0
316                reconfigure hello/0.1.0
317

COMMANDS

319       help [topic]
320              bdep-help(1) – show help for a command or help topic
321
322       new    bdep-new(1) – create and initialize new project
323
324       init   bdep-init(1) – initialize project in build configurations
325
326       sync   bdep-sync(1) – synchronize project and build configurations
327
328       fetch  bdep-fetch(1) – fetch list of available project dependencies
329
330       status bdep-status(1) – print status of project and/or its dependencies
331
332       ci     bdep-ci(1) – submit project test request to CI server
333
334       release
335              bdep-release(1) – manage project's version during release
336
337       publish
338              bdep-publish(1) – publish project to archive repository
339
340       deinit bdep-deinit(1) – deinitialize project in build configurations
341
342       config bdep-config(1) – manage project's build configurations
343
344       test   bdep-test(1) – test project in build configurations
345
346       update bdep-update(1) – update project in build configurations
347
348       clean  bdep-clean(1) – clean project in build configurations
349

HELP TOPICS

351       common-options
352              bdep-common-options(1) – details on common options
353
354       projects-configs
355              bdep-projects-configs(1) – specifying  projects  and  configura‐
356              tions
357
358       default-options-files
359              bdep-default-options-files(1) – specifying default options
360
361       argument-grouping
362              bdep-argument-grouping(1) – argument grouping facility
363

COMMON OPTIONS

365       The  common  options are summarized below with a more detailed descrip‐
366       tion available in bdep-common-options(1).
367
368       -v     Print essential underlying commands being executed.
369
370       -V     Print all underlying commands being executed.
371
372       --quiet|-q
373              Run quietly, only printing error messages.
374
375       --verbose level
376              Set the diagnostics verbosity to level between 0 and 6.
377
378       --jobs|-j num
379              Number of jobs to perform in parallel.
380
381       --no-progress
382              Suppress progress indicators for long-lasting  operations,  such
383              as network transfers, building, etc.
384
385       --bpkg path
386              The  package  manager program to be used for build configuration
387              management.
388
389       --bpkg-option opt
390              Additional option to be passed to the package manager program.
391
392       --build path
393              The build program to be used to build packages.
394
395       --build-option opt
396              Additional option to be passed to the build program.
397
398       --curl path
399              The curl program to be used for network operations.
400
401       --curl-option opt
402              Additional option to be passed to the curl program.
403
404       --pager path
405              The pager program to be used to show long text.
406
407       --pager-option opt
408              Additional option to be passed to the pager program.
409
410       --options-file file
411              Read additional options from file.
412
413       --default-options dir
414              The directory to load additional default options files from.
415
416       --no-default-options
417              Don't load default options files.
418

EXIT STATUS

420       Non-zero exit status is returned in case of an error.
421

ENVIRONMENT

423       The BDEP_DEF_OPT environment variable is used to  suppress  loading  of
424       default  options files in nested bdep invocations. Its values are false
425       or 0 to suppress and true or 1 to load.
426

BUGS

428       Send bug reports to the users@build2.org mailing list.
429
431       Copyright (c) 2014-2021 the build2 authors.
432
433       Permission is granted to copy, distribute and/or modify  this  document
434       under the terms of the MIT License.
435
436
437
438bdep 0.14.0                      October 2021                          bdep(1)
Impressum