1b(1) General Commands Manual b(1)
2
6 b - build system driver
7
9 b --help
10 b --version
11 b [options] [variables] [buildspec]
12 buildspec = meta-operation(operation(target...[,parameters])...)...
14
16 The build2 build system driver executes a set of meta-operations on
17 operations on targets according to the build specification, or build‐
18 spec for short. This process can be controlled by specifying driver
19 options and build system variables.
20 Note that options, variables, and buildspec fragments can be specified
22 in any order. To avoid treating an argument that starts with '-' as an
23 option, add the '--' separator. To avoid treating an argument that con‐
24 tains '=' as a variable, add the second '--' separator.
25 All components in the buildspec can be omitted. If meta-operation is
27 omitted, then it defaults to perform. If operation is omitted, then it
28 defaults to the default operation for this meta-operation. For perform
29 it is update. Finally, if target is omitted, then it defaults to the
30 current working directory. Some operations and meta-operations may take
31 additional parameters. For example:
32 $ b # perform(update(./))
34 $ b foo/ # perform(update(foo/))
35 $ b foo/ bar/ # perform(update(foo/ bar/))
36 $ b update # perform(update(./))
37 $ b 'clean(../)' # perform(clean(../))
38 $ b perform # perform(update(./))
39 $ b configure # configure(?(./))
40 $ b 'configure(../)' # configure(?(../))
41 $ b clean update # perform(clean(./) update(./))
42 $ b configure update # configure(?(./)) perform(update(./))
43 $ b 'create(conf/, cxx)' # create(?(conf/), cxx)
44 Notice the question mark used to show the (imaginary) default operation
46 for the configure meta-operation. For configure the default operation
47 is "all operations". That is, it will configure all the operations for
48 the specified target.
49 You can also "generate" multiple operations for the same set of tar‐
51 gets. Compare:
52 $ b 'clean(foo/ bar/)' 'update(foo/ bar/)'
54 $ b '{clean update}(foo/ bar/)'
55 Some more useful buildspec examples:
57 $ b '{clean update}(...)' # rebuild
59 $ b '{clean update clean}(...)' # make sure builds
60 $ b '{clean test clean}(...)' # make sure passes tests
61 $ b '{clean disfigure}(...)' # similar to distclean
62 In POSIX shells parenthesis are special characters and must be quoted
64 when used in a buildspec. Besides being an inconvenience in itself,
65 quoting also inhibits path auto-completion. To help with this situation
66 a shortcut syntax is available for executing a single operation or
67 meta-operation, for example:
68 $ b clean: foo/ bar/ # clean(foo/ bar/)
70 $ b configure: src/@out/ # configure(src/@out/)
71 $ b create: conf/, cxx # create(conf/, cxx)
72 $ b configure: config.cxx=g++ src/ # configure(src/) config.cxx=g++
73 To activate the shortcut syntax the first buildspec argument must start
75 with an operation or meta-operation name and end with a colon (:). To
76 transform the shortcut syntax to the normal buildspec syntax the colon
77 is replaced with the opening parenthesis ('('), the rest of the build‐
78 spec arguments are treated as is, and the final closing parenthesis
79 (')') is added.
80 For each target the driver expects to find buildfile either in the tar‐
82 get's directory or, if the directory is part of the out tree
83 (out_base), in the corresponding src directory (src_base).
84 For example, assuming foo/ is the source directory of a project:
86 $ b foo/ # out_base=src_base=foo/
88 $ b foo-out/ # out_base=foo-out/ src_base=foo/
89 $ b foo-out/exe{foo} # out_base=foo-out/ src_base=foo/
90 An exception to this requirement is a directory target in which case,
92 provided the directory has subdirectories, an implied buildfile with
93 the following content is assumed:
94 # Implied directory buildfile: build all subdirectories.
96 #
97 ./: */
98 In the above example, we assumed that the build system driver was able
100 to determine the association between out_base and src_base. In case
101 src_base and out_base are not the same directory, this is achieved in
102 one of two ways: the config module (which implements the configure,
103 disfigure, and create meta-operations) saves this association as part
104 of the configuration process. If, however, the association hasn't been
105 saved, then we have to specify src_base explicitly using the following
106 extended target syntax:
107 src-base/@target
109 Continuing with the previous example:
111 $ b foo/@foo-out/exe{foo} # out_base=foo-out/ src_base=foo/
113 Normally, you would need to specify src_base explicitly only once, dur‐
115 ing configuration. For example, a typical usage would be:
116 $ b configure: foo/@foo-out/ # src_base is saved
118 $ b foo-out/ # no need to specify src_base
119 $ b clean: foo-out/exe{foo} # no need to specify src_base
120 Besides in and out of source builds, build2 also supports configuring a
122 project's source directory as forwarded to an out of source build. With
123 such a forwarded configuration in place, if we run the build system
124 driver from the source directory, it will automatically build in the
125 output directory and backlink (using symlinks or another suitable mech‐
126 anism) certain "interesting" targets (executables, documentation, etc)
127 to the source directory for easy access. Continuing with the previous
128 example:
129 $ b configure: foo/@foo-out/,forward # foo/ forwarded to foo-out/
131 $ cd foo/
132 $ b # build in foo-out/
133 $ ./foo # symlink to foo-out/foo
134 The ability to specify build2 variables as part of the command line is
136 normally used to pass configuration values, for example:
137 $ b config.cxx=clang++ config.cxx.coptions=-O3
139 Similar to buildspec, POSIX shells often inhibit path auto-completion
141 on the right hand side of a variable assignment. To help with this sit‐
142 uation the assignment can be broken down into three separate command
143 line arguments, for example:
144 $ b config.import.libhello = ../libhello/
146 The build system has the following built-in and pre-defined meta-opera‐
148 tions:
149 perform
151 Perform an operation.
152 configure
154 Configure all operations supported by a project and save the
155 result in the project's build/config.build file. Implemented by
156 the config module. For example:
157 $ b configure \
159 config.cxx=clang++ \
160 config.cxx.coptions=-O3 \
161 config.install.root=/usr/local \
162 config.install.root.sudo=sudo
163 Use the forward parameter to instead configure a source direc‐
165 tory as forwarded to an out of source build. For example:
166 $ b configure: src/@out/,forward
168 disfigure
170 Disfigure all operations supported by a project and remove the
171 project's build/config.build file. Implemented by the config
172 module.
173 Use the forward parameter to instead disfigure forwarding of a
175 source directory to an out of source build. For example:
176 $ b disfigure: src/,forward
178 create
180 Create and configure a configuration project. Implemented by the
181 config module.
182 Normally a build2 project is created manually by writing the
184 bootstrap.build and config.build files, adding source files, and
185 so on. However, a special kind of project, which we call config‐
186 uration, is often useful. Such a project doesn't have any source
187 files of its own. Instead, it serves as an amalgamation for
188 building other projects as part of it. Doing it this way has two
189 major benefits: sub-projects automatically resolve their imports
190 to other projects in the amalgamation and sub-projects inherits
191 their configuration from the amalgamation (which means if we
192 want to change something, we only need to do it in one place).
193 As an example, let's assume we have two C++ projects: the lib‐
195 hello library in libhello/ and the hello executable that imports
196 it in hello/. And we want to build hello with clang++.
197 One way to do it would be to configure and build each project in
199 its own directory, for example:
200 $ b configure: libhello/@libhello-clang/ config.cxx=clang++
202 $ b configure: hello/@hello-clang/ config.cxx=clang++ \
203 config.import.libhello=libhello-clang/
204 The two drawbacks, as mentioned above, are the need to explic‐
206 itly resolve the import and having to make changes in multiple
207 places should, for example, we want to switch from clang++ to
208 g++.
209 We can, however, achieve the same end result but without any of
211 the drawbacks using the configuration project:
212 $ b create: clang/,cxx config.cxx=clang++ # Creates clang/.
214 $ b configure: libhello/@clang/libhello/
215 $ b configure: hello/@clang/hello/
216 The targets passed to the create meta-operation must be directo‐
218 ries which should either not exist or be empty. For each such
219 directory create first initializes a project as described below
220 and then configures it by executing the configure meta-opera‐
221 tion.
222 The first optional parameter to create is the list of modules to
224 load in root.build. By default, create appends .config to the
225 names of these modules so that only their configurations are
226 loaded. You can override this behavior by specifying the period
227 (.) after the module name. You can also instruct create to use
228 the optional module load by prefixing the module name with the
229 question mark (?).
230 The second optional parameter is the list of modules to load in
232 bootstrap.build. If not specified, then the test, dist, and
233 install modules are loaded by default. The config module is
234 always loaded first.
235 Besides creating project's bootstrap.build and root.build, cre‐
237 ate also writes the root buildfile with the following contents:
238 ./: {*/ -build/}
240 If used, this buildfile will build all the sub-projects cur‐
242 rently present in the configuration.
243 dist
245 Prepare a distribution containing all files necessary to perform
246 all operations in a project. Implemented by the dist module.
247 info
249 Print basic information (name, version, source and output direc‐
250 tories, etc) about one or more projects to STDOUT, separating
251 multiple projects with a blank line. Each project is identified
252 by its root directory target. For example:
253 $ b info: libfoo/ libbar/
255 The build system has the following built-in and pre-defined operations:
257 update
259 Update a target.
260 clean
262 Clean a target.
263 test
265 Test a target. Performs update as a pre-operation. Implemented
266 by the test module.
267 update-for-test
269 Update a target for testing. This operation is equivalent to the
270 update pre-operation as executed by the test operation and can
271 be used to only update what is necessary for testing. Imple‐
272 mented by the test module.
273 install
275 Install a target. Performs update as a pre-operation. Imple‐
276 mented by the install module.
277 uninstall
279 Uninstall a target. Performs update as a pre-operation. Imple‐
280 mented by the install module.
281 update-for-install
283 Update a target for installation. This operation is equivalent
284 to the update pre-operation as executed by the install operation
285 and can be used to only update what is necessary for installa‐
286 tion. Implemented by the install module.
287 Note that buildspec and command line variable values are treated as
289 buildfile fragments and so can use quoting and escaping as well as con‐
290 tain variable expansions and evaluation contexts. However, to be more
291 usable on various platforms, escaping in these two situations is lim‐
292 ited to the effective sequences of \', \", \\, \$, and \( with all
293 other sequences interpreted as is. Together with double-quoting this is
294 sufficient to represent any value. For example:
295 $ b config.install.root=c:\projects\install
297 $ b "config.install.root='c:\Program Files (x86)\test\'"
298 $ b 'config.cxx.poptions=-DFOO_STR="foo"'
299
301 -v Print actual commands being executed. This options is equivalent
302 to --verbose 2.
303 -V Print all underlying commands being executed. This options is
305 equivalent to --verbose 3.
306 --quiet|-q
308 Run quietly, only printing error messages in most contexts. In
309 certain contexts (for example, while updating build system mod‐
310 ules) this verbosity level may be ignored. Use --silent to run
311 quietly in all contexts. This option is equivalent to --verbose
312 0.
313 --silent
315 Run quietly, only printing error messages in all contexts.
316 --verbose level
318 Set the diagnostics verbosity to level between 0 and 6. Level 0
319 disables any non-error messages (but see the difference between
320 --quiet and --silent) while level 6 produces lots of informa‐
321 tion, with level 1 being the default. The following additional
322 types of diagnostics are produced at each level:
323 1. High-level information messages.
325 2. Essential underlying commands being executed.
327 3. All underlying commands being executed.
329 4. Information that could be helpful to the user.
331 5. Information that could be helpful to the developer.
333 6. Even more detailed information.
335 --stat Display build statistics.
337 --dump phase
339 Dump the build system state after the specified phase. Valid
340 phase values are load (after loading buildfiles) and match
341 (after matching rules to targets). Repeat this option to dump
342 the state after multiple phases.
343 --progress
345 Display build progress. If printing to a terminal the progress
346 is displayed by default for low verbosity levels. Use --no-
347 progress to suppress.
348 --no-progress
350 Don't display build progress.
351 --jobs|-j num
353 Number of active jobs to perform in parallel. This includes both
354 the number of active threads inside the build system as well as
355 the number of external commands (compilers, linkers, etc)
356 started but not yet finished. If this option is not specified or
357 specified with the 0 value, then the number of available hard‐
358 ware threads is used.
359 --max-jobs|-J num
361 Maximum number of jobs (threads) to create. The default is 8x
362 the number of active jobs (--jobs|j) on 32-bit architectures and
363 32x on 64-bit. See the build system scheduler implementation for
364 details.
365 --queue-depth|-Q num
367 The queue depth as a multiplier over the number of active jobs.
368 Normally we want a deeper queue if the jobs take long (for exam‐
369 ple, compilation) and shorter if they are quick (for example,
370 simple tests). The default is 4. See the build system scheduler
371 implementation for details.
372 --max-stack num
374 The maximum stack size in KBytes to allow for newly created
375 threads. For pthreads-based systems the driver queries the stack
376 size of the main thread and uses the same size for creating
377 additional threads. This allows adjusting the stack size using
378 familiar mechanisms, such as ulimit. Sometimes, however, the
379 stack size of the main thread is excessively large. As a
380 result, the driver checks if it is greater than a predefined
381 limit (64MB on 64-bit systems and 32MB on 32-bit ones) and caps
382 it to a more sensible value (8MB) if that's the case. This
383 option allows you to override this check with the special zero
384 value indicating that the main thread stack size should be used
385 as is.
386 --serial-stop|-s
388 Run serially and stop at the first error. This mode is useful to
389 investigate build failures that are caused by build system
390 errors rather than compilation errors. Note that if you don't
391 want to keep going but still want parallel execution, add
392 --jobs|-j (for example -j 0 for default concurrency).
393 --dry-run|-n
395 Print commands without actually executing them. Note that com‐
396 mands that are required to create an accurate build state will
397 still be executed and the extracted auxiliary dependency infor‐
398 mation saved. In other words, this is not the "don't touch the
399 filesystem" mode but rather "do minimum amount of work to show
400 what needs to be done". Note also that only the perform meta-
401 operation supports this mode.
402 --match-only
404 Match the rules but do not execute the operation. This mode is
405 primarily useful for profiling.
406 --structured-result
408 Write the result of execution in a structured form. In this
409 mode, instead of printing to STDERR diagnostics messages about
410 the outcome of executing actions on targets, the driver writes
411 to STDOUT a structured result description one line per the
412 buildspec action/target pair. Each line has the following for‐
413 mat:
414 state meta-operation operation target
416 Where state can be one of unchanged, changed, or failed. If the
418 action is a pre or post operation, then the outer operation is
419 specified in parenthesis. For example:
420 unchanged perform update(test) /tmp/dir{hello/}
422 changed perform test /tmp/dir{hello/}
423 Note that only the perform meta-operation supports the struc‐
425 tured result output.
426 --mtime-check
428 Perform file modification time sanity checks. These checks can
429 be helpful in diagnosing spurious rebuilds and are enabled by
430 default for the staged version of the build system. Use --no-
431 mtime-check to disable.
432 --no-mtime-check
434 Don't perform file modification time sanity checks.
435 --no-column
437 Don't print column numbers in diagnostics.
438 --no-line
440 Don't print line and column numbers in diagnostics.
441 --buildfile path
443 The alternative file to read build information from. The default
444 is buildfile or build2file, depending on the project's build
445 file/directory naming scheme. If path is '-', then read from
446 STDIN. Note that this option only affects the files read as part
447 of the buildspec processing. Specifically, it has no effect on
448 the source and include directives. As a result, this option is
449 primarily intended for testing rather than changing the build
450 file names in real projects.
451 --config-guess path
453 The path to the config.guess(1) script that should be used to
454 guess the host machine triplet. If this option is not specified,
455 then b will fall back on to using the target it was built for as
456 host.
457 --config-sub path
459 The path to the config.sub(1) script that should be used to
460 canonicalize machine triplets. If this option is not specified,
461 then b will use its built-in canonicalization support which
462 should be sufficient for commonly-used platforms.
463 --pager path
465 The pager program to be used to show long text. Commonly used
466 pager programs are less and more. You can also specify addi‐
467 tional options that should be passed to the pager program with
468 --pager-option. If an empty string is specified as the pager
469 program, then no pager will be used. If the pager program is not
470 explicitly specified, then b will try to use less. If it is not
471 available, then no pager will be used.
472 --pager-option opt
474 Additional option to be passed to the pager program. See --pager
475 for more information on the pager program. Repeat this option to
476 specify multiple pager options.
477 --default-options dir
479 The directory to load additional default options files from.
480 --no-default-options
482 Don't load default options files.
483 --help Print usage information and exit.
485 --version
487 Print version and exit.
488
490 Instead of having a separate config file format for tool configuration,
491 the build2 toolchain uses default options files which contain the same
492 options as what can be specified on the command line. The default
493 options files are like options files that one can specify with
494 --options-file except that they are loaded by default.
495 The default options files for the build system driver are called
497 b.options and are searched for in the .build2/ subdirectory of the home
498 directory and in the system directory (for example, /etc/build2/) if
499 configured.
500 Once the search is complete, the files are loaded in the reverse order,
502 that is, beginning from the system directory (if any), followed by the
503 home directory, and finishing off with the options specified on the
504 command line. In other words, the files are loaded from the more
505 generic to the more specific with the command line options having the
506 ability to override any values specified in the default options files.
507 If a default options file contains --no-default-options, then the
509 search is stopped at the directory containing this file and no outer
510 files are loaded. If this option is specified on the command line, then
511 none of the default options files are searched for or loaded.
512 An additional directory containing default options files can be speci‐
514 fied with --default-options. Its configuration files are loaded after
515 the home directory.
516 The order in which default options files are loaded is traced at the
518 verbosity level 3 (-V option) or higher.
519
521 Non-zero exit status is returned in case of an error.
522
524 The HOME environment variable is used to determine the user's home
525 directory. If it is not set, then getpwuid(3) is used instead. This
526 value is used to shorten paths printed in diagnostics by replacing the
527 home directory with ~/. It is also made available to buildfile's as the
528 build.home variable.
529
531 Send bug reports to the users@build2.org mailing list.
532
534 Copyright (c) 2014-2019 Code Synthesis Ltd
535 Permission is granted to copy, distribute and/or modify this document
537 under the terms of the MIT License.
538build2 0.12.0 November 2019 b(1)