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

NAME

6       b - build system driver
7

SYNOPSIS

9       b --help
10       b --version
11       b [options] [variables] [buildspec]
12
13       buildspec = meta-operation(operation(target...[,parameters])...)...
14

DESCRIPTION

16       The build2 build system driver executes a set of meta-operations on op‐
17       erations on targets according to the build specification, or  buildspec
18       for short.  This process can be controlled by specifying driver options
19       and build system variables.
20
21       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
26       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. A meta-operation on operation is called an
31       action. Some operations and meta-operations may take additional parame‐
32       ters. For example:
33
34       $ b                       # perform(update(./))
35       $ b foo/                  # perform(update(foo/))
36       $ b foo/ bar/             # perform(update(foo/ bar/))
37       $ b update                # perform(update(./))
38       $ b 'clean(../)'          # perform(clean(../))
39       $ b perform               # perform(update(./))
40       $ b configure             # configure(?(./))
41       $ b 'configure(../)'      # configure(?(../))
42       $ b clean update          # perform(clean(./) update(./))
43       $ b configure update      # configure(?(./)) perform(update(./))
44       $ b 'create(conf/, cxx)'  # create(?(conf/), cxx)
45
46       Notice the question mark used to show the (imaginary) default operation
47       for the configure meta-operation. For configure the  default  operation
48       is  "all operations". That is, it will configure all the operations for
49       the specified target.
50
51       You can also "generate" multiple operations for the same  set  of  tar‐
52       gets.  Compare:
53
54       $ b 'clean(foo/ bar/)' 'update(foo/ bar/)'
55       $ b '{clean update}(foo/ bar/)'
56
57       Some more useful buildspec examples:
58
59       $ b '{clean update}(...)'        # rebuild
60       $ b '{clean update clean}(...)'  # make sure builds
61       $ b '{clean test clean}(...)'    # make sure passes tests
62       $ b '{clean disfigure}(...)'     # similar to distclean
63
64       In  POSIX  shells parenthesis are special characters and must be quoted
65       when used in a buildspec. Besides being  an  inconvenience  in  itself,
66       quoting also inhibits path auto-completion. To help with this situation
67       a shortcut syntax is available for  executing  a  single  operation  or
68       meta-operation, for example:
69
70       $ b clean: foo/ bar/                # clean(foo/ bar/)
71       $ b configure: src/@out/            # configure(src/@out/)
72       $ b create: conf/, cxx              # create(conf/, cxx)
73       $ b configure: config.cxx=g++ src/  # configure(src/) config.cxx=g++
74
75       To activate the shortcut syntax the first buildspec argument must start
76       with an operation or meta-operation name and end with a colon  (:).  To
77       transform  the shortcut syntax to the normal buildspec syntax the colon
78       is replaced with the opening parenthesis ('('), the rest of the  build‐
79       spec  arguments  are  treated  as is, and the final closing parenthesis
80       (')') is added.
81
82       For each target the driver expects to find buildfile either in the tar‐
83       get's  directory  or,  if  the  directory  is  part  of  the  out  tree
84       (out_base), in the corresponding src directory (src_base).
85
86       For example, assuming foo/ is the source directory of a project:
87
88       $ b foo/              # out_base=src_base=foo/
89       $ b foo-out/          # out_base=foo-out/ src_base=foo/
90       $ b foo-out/exe{foo}  # out_base=foo-out/ src_base=foo/
91
92       An exception to this requirement is a directory target in  which  case,
93       provided  the  directory  has subdirectories, an implied buildfile with
94       the following content is assumed:
95
96       # Implied directory buildfile: build all subdirectories.
97       #
98       ./: */
99
100       In the above example, we assumed that the build system driver was  able
101       to  determine  the  association  between out_base and src_base. In case
102       src_base and out_base are not the same directory, this is  achieved  in
103       one  of  two  ways:  the config module (which implements the configure,
104       disfigure, and create meta-operations) saves this association  as  part
105       of  the configuration process. If, however, the association hasn't been
106       saved, then we have to specify src_base explicitly using the  following
107       extended target syntax:
108
109       src-base/@target
110
111       Continuing with the previous example:
112
113       $ b foo/@foo-out/exe{foo}  # out_base=foo-out/ src_base=foo/
114
115       Normally, you would need to specify src_base explicitly only once, dur‐
116       ing configuration. For example, a typical usage would be:
117
118       $ b configure: foo/@foo-out/  # src_base is saved
119       $ b foo-out/                  # no need to specify src_base
120       $ b clean: foo-out/exe{foo}   # no need to specify src_base
121
122       Besides in and out of source builds, build2 also supports configuring a
123       project's source directory as forwarded to an out of source build. With
124       such a forwarded configuration in place, if we  run  the  build  system
125       driver  from  the  source directory, it will automatically build in the
126       output directory and backlink (using symlinks or another suitable mech‐
127       anism)  certain "interesting" targets (executables, documentation, etc)
128       to the source directory for easy access. Continuing with  the  previous
129       example:
130
131       $ b configure: foo/@foo-out/,forward  # foo/ forwarded to foo-out/
132       $ cd foo/
133       $ b                                   # build in foo-out/
134       $ ./foo                               # symlink to foo-out/foo
135
136       The  ability to specify build2 variables as part of the command line is
137       normally used to pass configuration values, for example:
138
139       $ b config.cxx=clang++ config.cxx.coptions=-O3
140
141       Similar to buildspec, POSIX shells often inhibit  path  auto-completion
142       on the right hand side of a variable assignment. To help with this sit‐
143       uation the assignment can be broken down into  three  separate  command
144       line arguments, for example:
145
146       $ b config.import.libhello = ../libhello/
147
148       The build system has the following built-in and pre-defined meta-opera‐
149       tions:
150
151       perform
152              Perform an operation.
153
154       configure
155              Configure all operations supported by a project and save the re‐
156              sult  in  the  project's build/config.build file. Implemented by
157              the config module. For example:
158
159              $ b configure                      \
160                  config.cxx=clang++             \
161                  config.cxx.coptions=-O3        \
162                  config.install.root=/usr/local \
163                  config.install.root.sudo=sudo
164
165              Use the forward parameter to instead configure a  source  direc‐
166              tory as forwarded to an out of source build. For example:
167
168              $ b configure: src/@out/,forward
169
170       disfigure
171              Disfigure  all  operations supported by a project and remove the
172              project's build/config.build file.  Implemented  by  the  config
173              module.
174
175              Use  the  forward parameter to instead disfigure forwarding of a
176              source directory to an out of source build. For example:
177
178              $ b disfigure: src/,forward
179
180       create
181              Create and configure a configuration project. Implemented by the
182              config module.
183
184              Normally  a  build2  project  is created manually by writing the
185              bootstrap.build and config.build files, adding source files, and
186              so on. However, a special kind of project, which we call config‐
187              uration, is often useful. Such a project doesn't have any source
188              files  of  its  own.   Instead, it serves as an amalgamation for
189              building other projects as part of it. Doing it this way has two
190              major benefits: sub-projects automatically resolve their imports
191              to other projects in the amalgamation and sub-projects  inherits
192              their  configuration  from  the  amalgamation (which means if we
193              want to change something, we only need to do it in one place).
194
195              As an example, let's assume we have two C++ projects:  the  lib‐
196              hello library in libhello/ and the hello executable that imports
197              it in hello/. And we want to build hello with clang++.
198
199              One way to do it would be to configure and build each project in
200              its own directory, for example:
201
202              $ b configure: libhello/@libhello-clang/ config.cxx=clang++
203              $ b configure: hello/@hello-clang/ config.cxx=clang++ \
204                  config.import.libhello=libhello-clang/
205
206              The  two  drawbacks, as mentioned above, are the need to explic‐
207              itly resolve the import and having to make changes  in  multiple
208              places  should,  for  example, we want to switch from clang++ to
209              g++.
210
211              We can, however, achieve the same end result but without any  of
212              the drawbacks using the configuration project:
213
214              $ b create: clang/,cxx config.cxx=clang++  # Creates clang/.
215              $ b configure: libhello/@clang/libhello/
216              $ b configure: hello/@clang/hello/
217
218              The targets passed to the create meta-operation must be directo‐
219              ries which should either not exist or be empty.  For  each  such
220              directory  create first initializes a project as described below
221              and then configures it by executing  the  configure  meta-opera‐
222              tion.
223
224              The first optional parameter to create is the list of modules to
225              load in root.build. By default, create appends  .config  to  the
226              names  of  these  modules  so that only their configurations are
227              loaded. You can override this behavior by specifying the  period
228              (.)   after the module name. You can also instruct create to use
229              the optional module load by prefixing the module name  with  the
230              question mark (?).
231
232              The  second optional parameter is the list of modules to load in
233              bootstrap.build. If not specified, then the test, dist, and  in‐
234              stall modules are loaded by default. The config module is always
235              loaded first.
236
237              Besides creating project's bootstrap.build and root.build,  cre‐
238              ate also writes the root buildfile with the following contents:
239
240              ./: {*/ -build/}
241
242              If  used,  this  buildfile  will build all the sub-projects cur‐
243              rently present in the configuration.
244
245       dist
246              Prepare a distribution containing all files necessary to perform
247              all operations in a project. Implemented by the dist module.
248
249       info
250              Print basic information (name, version, source and output direc‐
251              tories, etc) about one or more projects  to  stdout,  separating
252              multiple  projects with a blank line. Each project is identified
253              by its root directory target. For example (some output is  omit‐
254              ted):
255
256              $ b info: libfoo/ libbar/
257              project: libfoo
258              version: 1.0.0
259              src_root: /tmp/libfoo
260              out_root: /tmp/libfoo
261
262              project: libbar
263              version: 2.0.0
264              src_root: /tmp/libbar
265              out_root: /tmp/libbar-out
266
267              To  instead  print  this information in the JSON format, use the
268              json parameter, for example:
269
270              $ b info: libfoo/,json
271
272              In this case the output is a JSON array of objects which are the
273              serialized   representation   of   the   following   C++  struct
274              project_info:
275
276              struct subproject
277              {
278                string           path;
279                optional<string> name;
280              };
281
282              struct project_info
283              {
284                optional<string>   project;
285                optional<string>   version;
286                optional<string>   summary;
287                optional<string>   url;
288                string             src_root;
289                string             out_root;
290                optional<string>   amalgamation;
291                vector<subproject> subprojects;
292                vector<string>     operations;
293                vector<string>     meta_operations;
294                vector<string>     modules;
295              };
296
297              For example:
298
299              [
300                {
301                  "project": "libfoo",
302                  "version": "1.0.0",
303                  "summary": "libfoo C++ library",
304                  "src_root": "/tmp/libfoo",
305                  "out_root": "/tmp/gcc-debug/libfoo",
306                  "amalgamation": "..",
307                  "subprojects": [
308                    {
309                      "path": "tests"
310                    }
311                  ],
312                  "operations": [
313                    "update",
314                    "clean",
315                    "test",
316                    "update-for-test",
317                    "install",
318                    "uninstall",
319                    "update-for-install"
320                  ],
321                  "meta-operations": [
322                    "perform",
323                    "configure",
324                    "disfigure",
325                    "dist",
326                    "info"
327                  ],
328                  "modules": [
329                    "version",
330                    "config",
331                    "test",
332                    "install",
333                    "dist"
334                  ]
335                }
336              ]
337
338              See the JSON OUTPUT section below for  details  on  the  overall
339              properties  of this format and the semantics of the struct seri‐
340              alization.
341
342       The build system has the following built-in and pre-defined operations:
343
344       update
345              Update a target.
346
347       clean
348              Clean a target.
349
350       test
351              Test a target. Performs update as a  pre-operation.  Implemented
352              by the test module.
353
354       update-for-test
355              Update a target for testing. This operation is equivalent to the
356              update pre-operation as executed by the test operation  and  can
357              be  used  to  only  update what is necessary for testing. Imple‐
358              mented by the test module.
359
360       install
361              Install a target. Performs update  as  a  pre-operation.  Imple‐
362              mented by the install module.
363
364       uninstall
365              Uninstall  a  target. Performs update as a pre-operation. Imple‐
366              mented by the install module.
367
368       update-for-install
369              Update a target for installation. This operation  is  equivalent
370              to the update pre-operation as executed by the install operation
371              and can be used to only update what is necessary  for  installa‐
372              tion. Implemented by the install module.
373
374       Note  that  buildspec  and  command line variable values are treated as
375       buildfile fragments and so can use quoting and escaping as well as con‐
376       tain  variable  expansions and evaluation contexts. However, to be more
377       usable on various platforms, escaping in these two situations  is  lim‐
378       ited  to  the  effective  sequences  of \', \", \\, \$, and \( with all
379       other sequences interpreted as is. Together with double-quoting this is
380       sufficient to represent any value. For example:
381
382       $ b config.install.root=c:\projects\install
383       $ b "config.install.root='c:\Program Files\test\'"
384       $ b 'config.cxx.poptions=-DFOO_STR="foo"'
385

OPTIONS

387       -v     Print actual commands being executed. This options is equivalent
388              to --verbose 2.
389
390       -V     Print all underlying commands being executed.  This  options  is
391              equivalent to --verbose 3.
392
393       --quiet|-q
394              Run  quietly,  only printing error messages in most contexts. In
395              certain contexts (for example, while updating build system  mod‐
396              ules)  this  verbosity level may be ignored. Use --silent to run
397              quietly in all contexts.  This option is equivalent to --verbose
398              0.
399
400       --silent
401              Run quietly, only printing error messages in all contexts.
402
403       --verbose level
404              Set  the diagnostics verbosity to level between 0 and 6. Level 0
405              disables any non-error messages (but see the difference  between
406              --quiet  and  --silent)  while level 6 produces lots of informa‐
407              tion, with level 1 being the default. The  following  additional
408              types of diagnostics are produced at each level:
409
410              1.  High-level information messages.
411
412              2.  Essential underlying commands being executed.
413
414              3.  All underlying commands being executed.
415
416              4.  Information that could be helpful to the user.
417
418              5.  Information that could be helpful to the developer.
419
420              6.  Even more detailed information.
421
422       --stat Display build statistics.
423
424       --progress
425              Display  build  progress. If printing to a terminal the progress
426              is displayed by default for  low  verbosity  levels.  Use  --no-
427              progress to suppress.
428
429       --no-progress
430              Don't display build progress.
431
432       --jobs|-j num
433              Number of active jobs to perform in parallel. This includes both
434              the number of active threads inside the build system as well  as
435              the  number  of  external  commands  (compilers,  linkers,  etc)
436              started but not yet finished. If this option is not specified or
437              specified  with  the 0 value, then the number of available hard‐
438              ware threads is used.
439
440       --max-jobs|-J num
441              Maximum number of jobs (threads) to create. The  default  is  8x
442              the number of active jobs (--jobs|j) on 32-bit architectures and
443              32x on 64-bit. See the build system scheduler implementation for
444              details.
445
446       --queue-depth|-Q num
447              The  queue depth as a multiplier over the number of active jobs.
448              Normally we want a deeper queue if the jobs take long (for exam‐
449              ple,  compilation)  and  shorter if they are quick (for example,
450              simple tests). The default is 4. See the build system  scheduler
451              implementation for details.
452
453       --file-cache impl
454              File cache implementation to use for intermediate build results.
455              Valid values are noop (no caching or compression)  and  sync-lz4
456              (no  caching  with synchronous LZ4 on-disk compression). If this
457              option is not specified, then a suitable default  implementation
458              is used (currently sync-lz4).
459
460       --max-stack num
461              The  maximum  stack  size  in  KBytes to allow for newly created
462              threads. For pthreads-based systems the driver queries the stack
463              size  of the main thread and uses the same size for creating ad‐
464              ditional threads. This allows adjusting the stack size using fa‐
465              miliar  mechanisms,  such  as  ulimit.   Sometimes, however, the
466              stack size of the main thread is excessively large.   As  a  re‐
467              sult, the driver checks if it is greater than a predefined limit
468              (64MB on 64-bit systems and 32MB on 32-bit ones) and caps it  to
469              a  more sensible value (8MB) if that's the case. This option al‐
470              lows you to override this check with the special zero value  in‐
471              dicating that the main thread stack size should be used as is.
472
473       --serial-stop|-s
474              Run serially and stop at the first error. This mode is useful to
475              investigate build failures that are caused by build  system  er‐
476              rors rather than compilation errors. Note that if you don't want
477              to keep going but still want parallel execution,  add  --jobs|-j
478              (for example -j 0 for default concurrency).
479
480       --dry-run|-n
481              Print  commands  without actually executing them. Note that com‐
482              mands that are required to create an accurate build  state  will
483              still  be executed and the extracted auxiliary dependency infor‐
484              mation saved. In other words, this is not the "don't  touch  the
485              filesystem"  mode  but rather "do minimum amount of work to show
486              what needs to be done". Note also that only the perform meta-op‐
487              eration supports this mode.
488
489       --match-only
490              Match  the  rules but do not execute the operation. This mode is
491              primarily useful for profiling.
492
493       --no-external-modules
494              Don't load external modules during project bootstrap. Note  that
495              this  option  can  only be used with meta-operations that do not
496              load the project's buildfiles, such as info.
497
498       --structured-result fmt
499              Write the result of execution in  a  structured  form.  In  this
500              mode,  instead  of printing to stderr diagnostics messages about
501              the outcome of executing actions on targets, the  driver  writes
502              to stdout a machine-readable result description in the specified
503              format. Valid values for this option are lines  and  json.  Note
504              that  currently  only  the  perform  meta-operation supports the
505              structured result output.
506
507              If the output format is lines, then the result  is  written  one
508              line  per  the  buildspec  action/target pair. Each line has the
509              following form:
510
511              state meta-operation operation target
512
513              Where state can be one of unchanged, changed, or failed. If  the
514              action  is  a pre or post operation, then the outer operation is
515              specified in parenthesis. For example:
516
517              unchanged perform update(test) /tmp/dir{hello/}
518              changed perform test /tmp/hello/exe{test}
519
520              If the output format is json, then the output is a JSON array of
521              objects which are the serialized representation of the following
522              C++ struct target_action_result:
523
524              struct target_action_result
525              {
526                string           target;
527                string           quoted_target;
528                string           target_type;
529                optional<string> target_path;
530                string           meta_operation;
531                string           operation;
532                optional<string> outer_operation;
533                string           state;
534              };
535
536              For example:
537
538              [
539                {
540                  "target": "/tmp/dir{hello/}",
541                  "quoted_target": "/tmp/dir{hello/}",
542                  "target_type": "dir",
543                  "target_path": "/tmp/hello",
544                  "meta_operation": "perform",
545                  "operation": "update",
546                  "outer_operation": "test",
547                  "state": "unchanged"
548                },
549                {
550                  "target": "/tmp/dir{hello/}",
551                  "quoted_target": "/tmp/dir{hello/}",
552                  "target_type": "dir",
553                  "target_path": "/tmp/hello",
554                  "meta_operation": "perform",
555                  "operation": "test",
556                  "state": "changed"
557                }
558              ]
559
560              See the JSON OUTPUT section below for  details  on  the  overall
561              properties  of this format and the semantics of the struct seri‐
562              alization.
563
564              The target member is a "display" target name, the same as in the
565              lines format. The quoted_target member is a target name that, if
566              required, is quoted so that it can be passed back to the  driver
567              on  the command line. The target_type member is the type of tar‐
568              get. The target_path member is an absolute path to the target if
569              the target type is path-based or dir.
570
571       --mtime-check
572              Perform  file  modification time sanity checks. These checks can
573              be helpful in diagnosing spurious rebuilds and  are  enabled  by
574              default  on  Windows  (which is known not to guarantee monotoni‐
575              cally increasing mtimes) and for the staged version of the build
576              system on other platforms. Use --no-mtime-check to disable.
577
578       --no-mtime-check
579              Don't perform file modification time sanity checks. See --mtime-
580              check for details.
581
582       --dump phase
583              Dump the build system state after  the  specified  phase.  Valid
584              phase  values are load (after loading buildfiles) and match (af‐
585              ter matching rules to targets). Repeat this option to  dump  the
586              state after multiple phases.
587
588       --trace-match target
589              Trace  rule matching for the specified target. This is primarily
590              useful during troubleshooting. Repeat this option to trace  mul‐
591              tiple targets.
592
593       --trace-execute target
594              Trace rule execution for the specified target. This is primarily
595              useful during troubleshooting. Repeat this option to trace  mul‐
596              tiple targets.
597
598       --no-column
599              Don't print column numbers in diagnostics.
600
601       --no-line
602              Don't print line and column numbers in diagnostics.
603
604       --buildfile path
605              The alternative file to read build information from. The default
606              is buildfile or build2file, depending  on  the  project's  build
607              file/directory  naming  scheme.  If  path is '-', then read from
608              stdin. Note that this option only affects the files read as part
609              of  the  buildspec processing. Specifically, it has no effect on
610              the source and include directives. As a result, this  option  is
611              primarily  intended  for  testing rather than changing the build
612              file names in real projects.
613
614       --config-guess path
615              The path to the config.guess(1) script that should  be  used  to
616              guess the host machine triplet. If this option is not specified,
617              then b will fall back on to using the target it was built for as
618              host.
619
620       --config-sub path
621              The  path  to  the  config.sub(1)  script that should be used to
622              canonicalize machine triplets. If this option is not  specified,
623              then  b  will  use  its  built-in canonicalization support which
624              should be sufficient for commonly-used platforms.
625
626       --pager path
627              The pager program to be used to show long  text.  Commonly  used
628              pager  programs  are  less  and more. You can also specify addi‐
629              tional options that should be passed to the pager  program  with
630              --pager-option.  If  an  empty  string is specified as the pager
631              program, then no pager will be used. If the pager program is not
632              explicitly  specified, then b will try to use less. If it is not
633              available, then no pager will be used.
634
635       --pager-option opt
636              Additional option to be passed to the pager program. See --pager
637              for more information on the pager program. Repeat this option to
638              specify multiple pager options.
639
640       --options-file file
641              Read additional options from file. Each option should appear  on
642              a  separate  line optionally followed by space or equal sign (=)
643              and an option value. Empty lines and lines starting with  #  are
644              ignored.   Option values can be enclosed in double (") or single
645              (') quotes to preserve leading and trailing whitespaces as  well
646              as  to specify empty values. If the value itself contains trail‐
647              ing or leading quotes, enclose it with an extra pair of  quotes,
648              for  example  '"x"'. Non-leading and non-trailing quotes are in‐
649              terpreted as being part of the option value.
650
651              The semantics of providing options in a file  is  equivalent  to
652              providing  the same set of options in the same order on the com‐
653              mand line at the point where the --options-file option is speci‐
654              fied except that the shell escaping and quoting is not required.
655              Repeat this option to specify more than one options file.
656
657       --default-options dir
658              The directory to load additional default options files from.
659
660       --no-default-options
661              Don't load default options files.
662
663       --help Print usage information and exit.
664
665       --version
666              Print version and exit.
667

DEFAULT OPTIONS FILES

669       Instead of having a separate config file format for tool configuration,
670       the  build2 toolchain uses default options files which contain the same
671       options as what can be specified on the command line. The  default  op‐
672       tions files are like options files that one can specify with --options-
673       file except that they are loaded by default.
674
675       The default options files for the build system driver are called  b.op‐
676       tions and are searched for in the .build2/ subdirectory of the home di‐
677       rectory and in the system directory (for example, /etc/build2/) if con‐
678       figured.  Note that besides options these files can also contain global
679       variable overrides.
680
681       Once the search is complete, the files are loaded in the reverse order,
682       that  is, beginning from the system directory (if any), followed by the
683       home directory, and finishing off with the  options  specified  on  the
684       command  line.   In  other  words,  the  files are loaded from the more
685       generic to the more specific with the command line options  having  the
686       ability to override any values specified in the default options files.
687
688       If  a  default  options  file  contains  --no-default-options, then the
689       search is stopped at the directory containing this file  and  no  outer
690       files are loaded. If this option is specified on the command line, then
691       none of the default options files are searched for or loaded.
692
693       An additional directory containing default options files can be  speci‐
694       fied  with  --default-options. Its configuration files are loaded after
695       the home directory.
696
697       The order in which default options files are loaded is  traced  at  the
698       verbosity level 3 (-V option) or higher.
699

JSON OUTPUT

701       Commands  that support the JSON output specify their formats as a seri‐
702       alized representation of a C++ struct or an array thereof. For example:
703
704       struct package
705       {
706         string name;
707       };
708
709       struct configuration
710       {
711         uint64_t         id;
712         string           path;
713         optional<string> name;
714         bool             default;
715         vector<package>  packages;
716       };
717
718       An example of the serialized JSON representation of  struct  configura‐
719       tion:
720
721       {
722         "id": 1,
723         "path": "/tmp/hello-gcc",
724         "name": "gcc",
725         "default": true,
726         "packages": [
727           {
728             "name": "hello"
729           }
730         ]
731       }
732
733       This  sections  provides details on the overall properties of such for‐
734       mats and the semantics of the struct serialization.
735
736       The order of members in a JSON object is fixed as specified in the cor‐
737       responding  struct.  While  new members may be added in the future (and
738       should be ignored by older consumers), the semantics  of  the  existing
739       members  (including  whether the top-level entry is an object or array)
740       may not change.
741
742       An object member is required unless its type is  optional<>,  bool,  or
743       vector<>  (array).  For  bool members absent means false.  For vector<>
744       members absent means empty. An empty top-level array is always present.
745
746       For example, the following JSON text is a possible serialization of the
747       above struct configuration:
748
749       {
750         "id": 1,
751         "path": "/tmp/hello-gcc"
752       }
753

EXIT STATUS

755       Non-zero exit status is returned in case of an error.
756

ENVIRONMENT

758       The  HOME environment variable is used to determine the user's home di‐
759       rectory. If it is not set, then getpwuid(3) is used instead. This value
760       is  used  to shorten paths printed in diagnostics by replacing the home
761       directory with ~/. It is also made  available  to  buildfile's  as  the
762       build.home variable.
763
764       The  BUILD2_VAR_OVR  environment  variable  is used to propagate global
765       variable overrides to nested build system driver invocations. Its value
766       is a list of global variable assignments separated with newlines.
767
768       The  BUILD2_DEF_OPT environment variable is used to suppress loading of
769       default options files in nested build system  driver  invocations.  Its
770       values are false or 0 to suppress and true or 1 to load.
771

BUGS

773       Send bug reports to the users@build2.org mailing list.
774
776       Copyright (c) 2014-2022 the build2 authors.
777
778       Permission  is  granted to copy, distribute and/or modify this document
779       under the terms of the MIT License.
780
781
782
783build2 0.15.0                      July 2022                              b(1)
Impressum