1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
|
// file : bdep/bdep.cli
// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
// license : MIT; see accompanying LICENSE file
include <bdep/common.cli>;
"\section=1"
"\name=bdep"
"\summary=project dependency manager"
namespace bdep
{
{
"<command> <topic> <common-options> <command-options> <command-args>",
"\h|SYNOPSIS|
\c{\b{bdep --help}\n
\b{bdep --version}\n
\b{bdep help} [<command> | <topic>]\n
\b{bdep} [<common-options>] <command> [<command-options>] <command-args>}
\h|DESCRIPTION|
The \cb{build2} project dependency manager is used to manage the
dependencies of a project during development.
For a detailed description of any command or help topic, use the
\cb{help} command or see the corresponding man page (the man pages have
the \cb{bdep-} prefix, for example \l{bdep-help(1)}). Note also that
<command-options> and <command-args> can be specified in any order and
<common-options> can be specified as part of <command-options>."
}
// For usage it's nice to see the list of commands on the first page. So
// let's not put this "extended" description into usage.
//
{
"",
"",
"A \cb{bdep} project is a directory, normally under a version control
system such as \cb{git(1)}, called \i{project repository}. A project
contains one or more \i{packages}. If it contain several, then they are
normally related, for example, the \cb{libhello} library and the
\cb{hello} program.
Packages in a project may depend on other packages outside of the
project. To distinguish between the two we call them \i{project packages}
and \i{dependency packages}, respectively. Naturally, our project
packages may be someone else's dependency packages.
A simple, single-package project contains the package in the root of the
project repository. For example (note the location of the package
\cb{manifest} and \cb{lockfile}):
\
hello/
├── .git/
├── ...
├── lockfile
└── manifest
\
See \l{bpkg#manifest-package Package Manifest} for details on the
\cb{manifest} file.
If a project contains multiple packages or we wish to place the package
into a subdirectory, then the root of the project repository must
contain the \cb{packages.manifest} file that specifies the package
locations. For example:
\
hello/
├── .git/
├── hello/
│ ├── ...
│ ├── lockfile
│ └── manifest
├── libhello/
│ ├── ...
│ ├── lockfile
│ └── manifest
└── packages.manifest
\
For this project, \cb{packages.manifest} would have the following
contents:
\
: 1
location: hello/
:
location: libhello/
\
A project repository root would usually also contain the
\cb{repositories.manifest} file that lists the repositories that provide
the dependency packages. For example:
\
hello/
├── ...
├── manifest
└── repositories.manifest
\
If our \cb{hello} project wanted to use \cb{libhello} as a dependency
package, then \cb{repositories.manifest} could look like this:
\
: 1
role: prerequisite
location: https://example.com/libhello.git
:
role: base
summary: hello project repository
\
See \l{bpkg#manifest-repository-list Repository List Manifest} for
details on the \cb{repositories.manifest} file.
For development a \cb{bdep} project is associated with one or more
\l{bpkg(1)} \i{build configurations}. These configuration are used as a
\i{backing} for building project packages and their dependencies.
The list of the associated build configuration as well as the list of
project packages initialized in each configuration are stored in the
\cb{bdep} \i{project database} under the \cb{.bdep/} subdirectory of the
project root directory. For example:
\
hello-gcc/ # Build configuration for gcc.
hello-clang/ # Build configuration for clang.
hello/
├── .bdep/
├── .git/
└── ...
\
The core of \cb{bdep} functionality is \i{state synchronization} between
the project and one or more associated build configurations. For example,
if we list a new dependency in the package's \cb{manifest} file, then
\cb{bdep} fetches and configures this dependency in a build
configuration. Similarly, if we upgrade a dependency in a build
configuration, then \cb{bdep} updates the corresponding entry in the
package's \cb{lockfile}.
A typical \cb{bdep} workflow would consist of the following steps.
\dl|
\li|\b{Obtain the Project}\n
Normally we would use the version control system to obtail the
project we want to develop:
\
$ git clone ssh://example.com/hello.git
\
Alternatively, we can use the \l{bdep-new(1)} command to start a new
project:
\
$ bdep new -t exe -l c++ hello
\
Similar to version control tools, we normally run \cb{bdep} from the
project's directory or one of its subdirectories:
\
$ cd hello
\
See \l{bdep-projects-configs(1)} for alternative ways to specify
the project location.
|
\li|\b{Initialize the Project}\n
Next we use the \l{bdep-init(1)} command to create new or add
existing build configurations and initialize our project in these
configurations:
\
$ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
$ bdep init -A ../hello-clang @clang
\
We can now use the \l{bdep-status(1)} command to examine the status
of our project in its configuration:
\
$ bdep status -a
in configuration @gcc:
hello configured 0.1.0-a.0.19700101000000
in configuration @clang:
hello configured 0.1.0-a.0.19700101000000
\
Most \cb{bdep} commands operate on one or more build configurations
associated with the project. If we don't specify one explicitly, then
the \i{default configuration} (usually the first added; \cb{gcc} in
our case) is used. Alternatively, we can specify the configurations
by name (if assigned), as directories, or with \c{\b{--all}|\b{-a}}
(see \l{bdep-projects-configs(1)} for details). For example:
\
$ bdep status @clang @gcc # by name
$ bdep status -c ../hello-gcc # as a directory
\
If a command is operating on multiple configurations (like \cb{status
-a} in the previous example), then it will print a line identifying
each configuration before printing the command's result.
@@ build and run?
|
\li|\b{Add, Remove, or Change Dependencies}\n
Let's say we found \cb{libhello} that we would like to use in our
project. First we edit our project's \cb{repositories.manifest}
file and add the \cb{libhello}'s repository as our prerequisite:
\
$ cat repositories.manifest
...
role: prerequisite
location: https://example.com/libhello.git
...
\
Next we edit our \cb{manifest} file and specify a dependency on
\cb{libhello}:
\
$ cat manifest
...
depends: libhello >= 1.0.0
...
\
If we now run \l{bdep-status(1)}, we will notice that a new
\i{iteration} of our project is available for synchronization:
\
$ bdep status
hello configured 0.1.0-a.0.19700101000000
available 0.1.0-a.0.19700101000000#1
\
See \l{bpkg#package-version Package Version} for details on package
versions and iterations.|
\li|\b{Synchronize the Project with Configurations}\n
To synchronize changes in the project's dependency information with
its build configurations we use the \l{bdep-sync(1)} command.
Continuing with our example, this will result in \cb{libhello} being
downloaded and configured since our project now depends on it:
\
$ bdep sync
$ bdep status -i
hello configured 0.1.0-a.0.19700101000000#1
libhello >= 1.0.0 configured 1.0.0
\
|
\li|\b{Upgrade or Downgrade Dependencies}\n
The \l{bdep-sync(1)} command is also used to upgrade or downgrade
dependencies (and it is also executed as the last step of \cb{init}).
Let's say we learned a new version of \cb{libhello} was release and
we would like to try it out.
To refresh the list of available dependency packages we use the
\l{bdep-fetch(1)} command (or, as a shortcut, the \cb{-f} flag to
\cb{status}):
\
$ bdep fetch
$ bdep status libhello
libhello configured 1.0.0 available [1.1.0]
\
Without an explicit version or the \c{\b{--patch}|\b{-p}} option,
\cb{sync} will upgrade the specified dependency to the latest
available version:
\
$ bdep sync libhello
$ bdep status -i
hello configured 0.1.0-a.0.19700101000000#1
libhello >= 1.0.0 configured 1.1.0
\
Let's say we didn't like the new version and would like to go back to
using the old one. To downgrade a dependency we have to specify its
version explicitly:
\
$ bdep status -o libhello
libhello configured 1.1.0 available [1.0.0] (1.1.0)
$ bdep sync libhello/1.0.0
\
||
"
}
class commands
{
"\h|COMMANDS|"
//
// NOTE: Use the same sentence as in the page's \summary and make
// sure it is short enough to fit in one line in usage.
//
bool help
{
"[<topic>]",
"\l{bdep-help(1)} \- show help for a command or help topic",
""
}
bool new
{
"\l{bdep-new(1)} \- create and initialize new project"
}
bool init
{
"\l{bdep-init(1)} \- initialize project in build configurations"
}
bool sync
{
"\l{bdep-sync(1)} \- synchronize project and build configurations"
}
bool fetch
{
"\l{bdep-fetch(1)} \- fetch list of available project dependencies"
}
bool status
{
"\l{bdep-status(1)} \- print status of project and/or its dependencies"
}
bool config
{
"\l{bdep-config(1)} \- manage project's build configurations"
}
};
// Make sure these don't conflict with command names above.
//
class topics
{
"\h|HELP TOPICS|"
bool common-options
{
"\l{bdep-common-options(1)} \- details on common options"
}
bool projects-configs
{
"\l{bdep-projects-configs(1)} \- specifying projects and configurations"
}
};
class options: common_options
{
bool --help;
bool --version;
};
"\h|EXIT STATUS|
Non-zero exit status is returned in case of an error.
"
}
|