From 46f5d01e4f61cfba9e0f4bc7ecc59891c53ca8ec Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Sat, 30 Jan 2016 12:28:33 +0200 Subject: Add option documentation, reorganize things --- build2/b.cli | 221 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 build2/b.cli (limited to 'build2/b.cli') diff --git a/build2/b.cli b/build2/b.cli new file mode 100644 index 0000000..a34e336 --- /dev/null +++ b/build2/b.cli @@ -0,0 +1,221 @@ +// file : build2/options.cli +// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd +// license : MIT; see accompanying LICENSE file + +include ; + +"\section=1" +"\name=b" +"\summary=build2 build driver" + +namespace build2 +{ + { + " + ", + + "\h|SYNOPSIS| + + \cb{b --help}\n + \cb{b --version}\n + \c{\b{b} [] [] []} + + \h|DESCRIPTION| + + The \cb{build2} driver performs a set of meta-operations on operations on + targets according to the build specification, or for short. + The buildspec has the following form: + + \c{(...(...))...} + + All three components can be omitted. If is omitted, then + it defaults to \cb{perform}. If is omitted, then it default to + the default operation of this meta-operation. For \cb{perform} that would + be \cb{update}. Finally, if is omitted, then it default to the + current directory. For example: + + \ + b # perform(update(./)) + b foo/ # perform(update(foo/)) + b foo/ bar/ # perform(update(foo/ bar/)) + b update # perform(update(./)) + b 'clean(../)' # perform(clean(../)) + b perform # perform(update(./)) + b configure # configure(?(./)) + b clean update # perform(clean(./) update(./)) + b configure update # configure(?(./)) perform(update(./)) + \ + + Noice the question mark used to denote the default operation for the + \cb{configure} meta-operation. For \cb{configure} the default operation + is \"all operations\". That is, it will configure all the operations for + the specified target. + + You can also \"generate\" multiple operation for the same set of targets. + Compare: + + \ + b 'clean(foo/ bar/)' 'update(foo/ bar/)' + b '{clean update}(foo/ bar/)' + \ + + Some more useful buildspec examples: + + \ + b '{clean update clean}(...)' + b '{clean test clean}(...)' + b '{clean disfigure}(...)' # similar to distclean + \ + + For each the driver expects to find a \cb{buildfile} either in + the target's directory or, if the directory is part of the \cb{out} tree + (\cb{out_base}), in the corresponding \cb{src} directory (\cb{src_base}). + + For example, assuming \cb{foo/} is the source directory of a project: + + \ + b foo/ # out_base=src_base=foo/ + b foo-out/ # out_base=foo-out/ src_base=foo/ + b foo-out/exe{foo} # out_base=foo-out/ src_base=foo/ + \ + + In the above example, we assumed that the \c{build2} driver was able to + determine the association between \cb{out_base} and \cb{src_base}. This is + achieved in one of two ways: the \cb{config} module (which implements the + \cb{configure} and \cb{disfigure} meta-operations) saves this association + as part of the persistent configuration. If, however, the association + hasn't been saved, then we have to specify \cb{src_base} explicitly using + the following extended syntax: + + \c{/@} + + Continuing with the previous example: + + \ + b foo/@foo-out/exe{foo} # out_base=foo-out/ src_base=foo/ + \ + + Normally, you would only need to specify \cb{src_base} explicitly once, + during configuration. For example, a typical usage would be: + + \ + b foo/ + b 'configure(foo/@foo-out/)' # src_base is saved + b foo-out/ # no need to specify src_base + b 'clean(foo-out/exe{foo}' # no need to specify src_base + \ + + \cb{build2} has the following build-in and pre-defined meta-operations. + + \dl| + + \li|\cb{perform} + + Perform an operation.| + + \li|\cb{configure} + + Configure all operations in a project. Implemented by the \cb{config} + module.| + + \li|\cb{disfigure} + + Disfigure all operations in a project. Implemented by the \cb{config} + module.| + + \li|\cb{dist} + + Prepare a distribution for all operations in a project. Implemented + by the \cb{dist} module.|| + + \cb{build2} has the following build-in and pre-defined operations. + + \dl| + + \li|\cb{update} + + Update a target.| + + \li|\cb{clean} + + Clean a target.| + + \li|\cb{test} + + Test a target. Performs \cb{update} as a pre-operation. Implemented by + the \cb{test} module.| + + \li|\cb{install} + + Install a target. Performs \cb{update} as a pre-operation. Implemented + by the \cb{install} module.|| + + Before (but after ) you can set one or more + \c{build2} . This is normally used to pass the configuration + values, for example: + + \ + b config.cxx=clang++ config.cxx.coptions=-O3 \ + config.install.root=/usr/local config.install.root.sudo=sudo \ + configure + \ + " + } + + class options + { + "\h|OPTIONS|" + + bool -v + { + "Print actual commands being executed. This is equivalent to + \cb{--verbose 2}." + } + + bool -q + { + "Run quietly, only printing error messages. This is equivalent to + \cb{--verbose 0}." + } + + std::uint16_t --verbose = 1 + { + "", + "Set the diagnostics verbosity to between 0 and 6. Level 0 + disables any non-error messages while level 6 produces lots of + information, with level 1 beeing the default. The following additional + types of diagnostics are produced at each level: + + \ol| + + \li|High-level information messages.| + + \li|Essential underlying commands being executed.| + + \li|All underlying commands being executed.| + + \li|Information that could be helpful to the user.| + + \li|Information that could be helpful to the developer.| + + \li|Even more detailed information, including state dumps.||" + }; + + bool --help {"Print usage information and exit."}; + bool --version {"Print version and exit."}; + }; + + "\h|EXIT STATUS| + + Non-zero exit status is returned in case of an error. + " + + "\h|ENVIRONMENT| + + The \cb{HOME} environment variable is used to determine the user's home + directory. If it is not set, then \cb{getpwuid(3)} is used instead. This + value is used to shorten paths printed in diagnostics by replacing it with + '\cb{~}'. It is also made available to the buildfiles as the \cb{build.home} + variable. + " +} -- cgit v1.1