// file      : build2/b.cli
// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

include <build2/types>;

"\section=1"
"\name=b"
"\summary=build2 driver"

namespace build2
{
  {
    "<options> <variables> <buildspec>",

    "\h|SYNOPSIS|

     \cb{b --help}\n
     \cb{b --version}\n
     \c{\b{b} [<options>] [<variables>] [<buildspec>]}

     \h|DESCRIPTION|

     The \cb{build2} driver performs a set of meta-operations on operations on
     targets according to the build specification, or <buildspec> for short.
     This process can be controlled by specifying driver <options> and build
     system <variables>.

     Note that <options>, <variables>, and <buildspec> fragments can be
     specified in any order. To avoid treating an argument that starts with
     \cb{'-'} as an option, add the \cb{'--'} separator. To avoid treating an
     argument that contains \cb{'='} as a variable, add the second \cb{'--'}
     separator."
  }

  // For usage it's nice to see the list of options on the first page. So
  // let's not put this "extended" description into usage.
  //
  {
    "<meta-operation> <operation> <target> <src-base>",
    "",

    "The buildspec has the following form:

     \c{<meta-operation>(<operation>...(<target>...))...}

     All three components can be omitted. If <meta-operation> is omitted, then
     it defaults to \cb{perform}. If <operation> is omitted, then it defaults
     to 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 'configure(../)'   # configure(?(../))
     b clean update       # perform(clean(./) update(./))
     b configure update   # configure(?(./)) perform(update(./))
     \

     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 operations 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}(...)'        # 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 \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 \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 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>}

     Continuing with the previous example:

     \
     b foo/@foo-out/exe{foo}  # out_base=foo-out/ src_base=foo/
     \

     Normally, you would need to specify \cb{src_base} explicitly only once,
     during configuration. For example, a typical usage would be:

     \
     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
     \

     The build system has the following built-in and pre-defined
     meta-operations:

     \dl|

     \li|\cb{perform}

         Perform an operation.|

     \li|\cb{configure}

         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 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 containing all files necessary to perform all
         operations in a project. Implemented by the \cb{dist} module.||

     The build system has the following built-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.||

     The ability to specify \cb{build2} variables as part of the command line
     is normally used to pass configuration values, for example:

     \
     b config.cxx=clang++ config.cxx.coptions=-O3 \
       config.install.root=/usr/local config.install.root.sudo=sudo \
       configure
     \

     Note also that buildspec and command line variable values are treated as
     \cb{buildfile} fragments and so can use quoting and escaping as well as
     contain variable expansions and evaluation contexts. However, to be more
     usable on various platforms, escaping in these two situations is limited
     to the \i{effective sequences} of \cb{\\'}, \cb{\\\"}, \cb{\\\\},
     \cb{\\$}, and \cb{\\(} with all other sequences interpreted as is.
     Together with double-quoting this is sufficient to represent any value.
     For example:

     \
     b config.install.root=c:\projects\install
     b \"config.install.root='c:\Program Files (x86)\test\'\"
     b 'config.cxx.poptions=-DFOO_STR=\"foo\"'
     \
     "
  }

  class options
  {
    "\h|OPTIONS|"

    bool -v
    {
      "Print actual commands being executed. This is equivalent to
       \cb{--verbose 2}."
    }

    bool -V
    {
      "Print all underlying commands being executed. This is equivalent to
       \cb{--verbose 3}."
    }

    bool --quiet|-q
    {
      "Run quietly, only printing error messages. This is equivalent to
       \cb{--verbose 0}."
    }

    uint16_t --verbose = 1
    {
      "<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 being 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.||"
    }

    size_t --jobs|-j
    {
      "<num>",
      "Number of jobs to perform in parallel. This includes both the number of
       active threads inside the build system as well as the number of external
       commands (compilers, linkers, etc) started but not yet finished. If this
       option is not specified, then the number of available hardware threads
       is used."
    }

    bool --no-column
    {
      "Don't print column numbers in diagnostics."
    }

    bool --no-line
    {
      "Don't print line and column numbers in diagnostics."
    }

    path --buildfile = "buildfile"
    {
      "<path>",
      "The alternative file to read build information from. The default is
       \cb{buildfile}. If <path> is '\cb{-}', then read from \cb{STDIN}. Note
       that this option only affects the files read as part of the buildspec
       processing. Specifically, it has no effect on the \cb{source} and
       \cb{include} directives. As a result, this option is primarily intended
       for testing rather than changing the build file names in real projects."
    }

    path --config-guess
    {
      "<path>",
      "The path to the \cb{config.guess(1)} script that should be used to
       guess the host machine triplet. If this option is not specified, then
       \cb{b} will fall back on to using the target it was built for as host."
    }

    path --config-sub
    {
      "<path>",
      "The path to the \cb{config.sub(1)} script that should be used to
       canonicalize machine triplets. If this option is not specified, then
       \cb{b} will use its built-in canonicalization support which should
       be sufficient for commonly-used platforms."
    }

    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."}
  };

  "\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 the home
  directory with \cb{~/}. It is also made available to \cb{buildfile}'s as the
  \cb{build.home} variable.
  "
}