aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2016-01-30 15:45:02 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2016-01-30 15:45:02 +0200
commitd1f0cfae60d762ecf09e2df89a9fec11ffda49ff (patch)
tree9875d16242981b2dd8bdc8998ed41cfb4b50e447
parent79b1374a7fbf5476e80538215b3eb26fbc5de08c (diff)
Various changes to documentation
-rw-r--r--build2/b.cli117
1 files changed, 70 insertions, 47 deletions
diff --git a/build2/b.cli b/build2/b.cli
index a34e336..05cce03 100644
--- a/build2/b.cli
+++ b/build2/b.cli
@@ -6,12 +6,12 @@ include <build2/types>;
"\section=1"
"\name=b"
-"\summary=build2 build driver"
+"\summary=build2 driver"
namespace build2
{
{
- "<options> <variable> <buildspec>
+ "<options> <variables> <buildspec>
<meta-operation> <operation> <target> <src-base>",
"\h|SYNOPSIS|
@@ -30,28 +30,29 @@ namespace build2
All three components can be omitted. If <meta-operation> is omitted, then
it defaults to \cb{perform}. If <operation> is omitted, then it default to
- the default operation of this meta-operation. For \cb{perform} that would
- be \cb{update}. Finally, if <target> is omitted, then it default to the
+ the default operation for this meta-operation. For \cb{perform} it is
+ \cb{update}. Finally, if <target> is omitted, then it defaults 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(./))
+ 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 '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.
+ Notice the question mark used to show the (imaginary) 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.
+ You can also \"generate\" multiple operations for the same set of targets.
Compare:
\
@@ -62,13 +63,14 @@ namespace build2
Some more useful buildspec examples:
\
- b '{clean update clean}(...)'
- b '{clean test clean}(...)'
- b '{clean disfigure}(...)' # similar to distclean
+ b '{clean update}(...)' # rebuild
+ b '{clean update clean}(...)' # make sure builds
+ b '{clean test clean}(...)' # make sure passes tests
+ b '{clean disfigure}(...)' # similar to distclean
\
- For each <target> 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
+ For each <target> the driver expects to find \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:
@@ -79,13 +81,13 @@ namespace build2
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
+ In the above example, we assumed that the \cb{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 <target> syntax:
+ as part of the configuration process. If, however, the association hasn't
+ been saved, then we have to specify \cb{src_base} explicitly using the
+ following extended <target> syntax:
\c{<src-base>/@<target>}
@@ -95,17 +97,16 @@ namespace build2
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,
+ Normally, you would need to specify \cb{src_base} explicitly only 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
+ b 'clean(foo-out/exe{foo})' # no need to specify src_base
\
- \cb{build2} has the following build-in and pre-defined meta-operations.
+ \cb{build2} has the following build-in and pre-defined meta-operations:
\dl|
@@ -115,20 +116,22 @@ namespace build2
\li|\cb{configure}
- Configure all operations in a project. Implemented by the \cb{config}
- module.|
+ Configure all operations supported by a project and save the result
+ in the project's \cb{build2/config.build} file. Implemented by the
+ \cb{config} module.|
\li|\cb{disfigure}
- Disfigure all operations in a project. Implemented by the \cb{config}
- module.|
+ Disfigure all operations supported by a project and remove the
+ project's \cb{build2/config.build} file. Implemented by the
+ \cb{config} module.|
\li|\cb{dist}
- Prepare a distribution for all operations in a project. Implemented
- by the \cb{dist} module.||
+ Prepare a distribution containing all files necessary to perform all
+ operations in a project. Implemented by the \cb{dist} module.||
- \cb{build2} has the following build-in and pre-defined operations.
+ \cb{build2} has the following build-in and pre-defined operations:
\dl|
@@ -151,8 +154,8 @@ namespace build2
by the \cb{install} module.||
Before <buildspec> (but after <options>) you can set one or more
- \c{build2} <variables>. This is normally used to pass the configuration
- values, for example:
+ \cb{build2} <variables>. This is normally used to specify the
+ configuration values, for example:
\
b config.cxx=clang++ config.cxx.coptions=-O3 \
@@ -183,7 +186,7 @@ namespace build2
"<level>",
"Set the diagnostics verbosity to <level> 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
+ information, with level 1 being the default. The following additional
types of diagnostics are produced at each level:
\ol|
@@ -199,10 +202,30 @@ namespace build2
\li|Information that could be helpful to the developer.|
\li|Even more detailed information, including state dumps.||"
- };
+ }
+
+ string --pager // String to allow empty value.
+ {
+ "<path>",
+ "The pager program to be used to show long text. Commonly used pager
+ programs are \cb{less} and \cb{more}. You can also specify additional
+ options that should be passed to the pager program with
+ \cb{--pager-option}. If an empty string is specified as the pager
+ program, then no pager will be used. If the pager program is not
+ explicitly specified, then \cb{b} will try to use \cb{less}. If it
+ is not available, then no pager will be used."
+ }
+
+ strings --pager-option
+ {
+ "<opt>",
+ "Additional option to be passed to the pager program. See \cb{--pager}
+ for more information on the pager program. Repeat this option to
+ specify multiple pager options."
+ }
- bool --help {"Print usage information and exit."};
- bool --version {"Print version and exit."};
+ bool --help {"Print usage information and exit."}
+ bool --version {"Print version and exit."}
};
"\h|EXIT STATUS|
@@ -214,8 +237,8 @@ namespace build2
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.
+ value is used to shorten paths printed in diagnostics by replacing the home
+ directory with \cb{~/}. It is also made available to \cb{buildfile}'s as the
+ \cb{build.home} variable.
"
}