// file      : bdep/common.cli
// license   : MIT; see accompanying LICENSE file

include <bdep/types.hxx>;
include <bdep/options-types.hxx>;

"\section=1"
"\name=bdep-common-options"
"\summary=details on common options"

namespace bdep
{
  {
    "<common-options>",

    "\h|SYNOPSIS|

     \c{\b{bdep} [<common-options>] ...}

     \h|DESCRIPTION|

     The common options control behavior that is common to all or most of the
     \cb{bdep} commands. They can be specified either before the command or
     after, together with the command-specific options."
  }

  class common_options = 0
  {
    "\h|COMMON OPTIONS|"

    // Retain this note only in the summary.
    //
    {
      "",
      "The common options are summarized below with a more detailed description
       available in \l{bdep-common-options(1)}.",
      ""
    }

    bool -v
    {
      "Print essential underlying 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.||"
    }

    bdep::stdout_format --stdout-format = bdep::stdout_format::lines
    {
      "<format>",
      "Representation format to use for printing to \cb{stdout}. Valid values
       for this option are \cb{lines} (default) and \cb{json}. See the JSON
       OUTPUT section below for details on the \cb{json} format."
    }

    int32_t --jobs|-j
    {
      "<num>",
      "Number of jobs to perform in parallel. If this option is not
       specified or specified with the \c{0} value, then the number of
       available hardware threads is used. If the specified value is negative,
       then the number of available hardware threads reduced by this value is
       used. This option is also propagated when executing package manager
       commands such as \l{bpkg-pkg-update(1)}, \l{bpkg-pkg-test(1)}, etc.,
       which in turn propagate it to the build system."
    }

    // When it comes to external programs (such as curl, git, etc), if stderr
    // is not a terminal, the logic is actually tri-state: With --no-progress
    // we suppress any progress. With --progress, we request full progress.
    // Finally, without any --*progress options we let the external program
    // decide what to do: it may do something intelligent (like curl) and
    // produce non-terminal-friendly progress (such as status lines printed
    // periodically) or it may disable progress all together (like git). Of
    // course, it may also do no detection and dump non-terminal-unfriendly
    // progress in which case we should probably do the detection ourselves
    // and suppress it.
    //
    bool --progress
    {
      "Display progress indicators for long-lasting operations, such as
       network transfers, building, etc. If printing to a terminal the
       progress is displayed by default for low verbosity levels. Use
       \cb{--no-progress} to suppress."
    }

    bool --no-progress
    {
      "Suppress progress indicators for long-lasting operations, such as
       network transfers, building, etc."
    }

    bool --diag-color
    {
      "Use color in diagnostics. If printing to a terminal the color is used
       by default provided the terminal is not dumb. Use \cb{--no-diag-color}
       to suppress."
    }

    bool --no-diag-color
    {
      "Don't use color in diagnostics."
    }

    path --bpkg
    {
      "<path>",
      "The package manager program to be used for build configuration
       management. This should be the path to the \cb{bpkg} executable. You
       can also specify additional options that should be passed to the
       package manager program with \cb{--bpkg-option}.

       If the package manager program is not explicitly specified, then
       \cb{bdep} will by default use \cb{bpkg} plus an executable suffix if
       one was specified when building \cb{bdep}. So, for example, if
       \cb{bdep} name was set to \cb{bdep-1.0}, then it will look for
       \cb{bpkg-1.0}."
    }

    strings --bpkg-option
    {
      "<opt>",
      "Additional option to be passed to the package manager program. See
       \cb{--bpkg} for more information on the package manager program.
       Repeat this option to specify multiple package manager options."
    }

    path --build
    {
      "<path>",
      "The build program to be used to build packages. This should be the path
       to the build2 \cb{b} executable. You can also specify additional options
       that should be passed to the build program with \cb{--build-option}.

       If the build program is not explicitly specified, then \cb{bdep} will
       by default use \cb{b} plus an executable suffix if one was specified
       when building \cb{bdep}. So, for example, if \cb{bdep} name was set
       to \cb{bdep-1.0}, then it will look for \cb{b-1.0}."
    }

    strings --build-option
    {
      "<opt>",
      "Additional option to be passed to the build program. See \cb{--build}
       for more information on the build program. Repeat this option to specify
       multiple build options."
    }

    path --curl = "curl"
    {
      "<path>",
      "The curl program to be used for network operations. You can also
       specify additional options that should be passed to the curl program
       with \cb{--curl-option}.

       If the curl program is not explicitly specified, then \cb{bdep} will use
       \cb{curl} by default. Note that this program will also be used by the
       underlying \cb{bpkg} invocations unless overridden."
    }

    strings --curl-option
    {
      "<opt>",
      "Additional option to be passed to the curl program. See \cb{--curl} for
       more information on the curl program. Repeat this option to specify
       multiple curl options.

       Note that these options will also be used by the underlying \cb{bpkg}
       invocations provided that curl is used."
    }

    bool --offline
    {
      "Do not attempt to download resources (packages, repository metadata,
       etc), instead taking them from the local fetch cache if available and
       failing otherwise. See \l{bpkg-common-options(1)} for details on the
       offline mode."
    }

    bool --no-fetch-cache
    {
      "Disable local caching of download resources (packages, repository
       metadata, etc). By default these are cached in a permanent local
       cache. See \l{bpkg-common-options(1)} for details on the fetch cache."
    }

    string --fetch-cache
    {
      "<mode>",
      "Comma-separated list of local fetch cache modes. See
       \l{bpkg-common-options(1)} for details on the available modes. Note
       that the default for \cb{bdep} is to enable sharing of cached source
       directories for dependencies during the configuration creation."
    }

    string --fetch-cache-session
    {
      "<id>",
      "The local fetch cache session. Specifying the same session id across
       multiple \cb{bdep} invocations allows eliminating repeated up-to-date
       checks of repository metadata. Any value, such as UUID, that is
       guaranteed not to clash with previous sessions can be used as a session
       id. See \l{bpkg-common-options(1)} for details on the fetch cache."
    }

    bdep::sqlite_synchronous --sqlite-synchronous = bdep::sqlite_synchronous::normal
    {
      "<mode>",
      "Filesystem synchronization mode for the project SQLite database. Valid
       values are \cb{off}, \cb{normal} (default), \cb{full}, and \cb{extra}.
       See the SQLite documentation on the \cb{synchronous} pragma for
       details. See also the \cb{BUILD2_SQLITE_SYNCHRONOUS} environment
       variable.

       Note that WAL (Write-Ahead Logging) journaling mode is used for the
       project database. Note also that this option is not passed to the
       underlying \cb{bpkg} commands (use \cb{--bpkg-option} for that)."
    }

    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{bdep} 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."
    }

    // The following option is "fake" in that it is actually handled by
    // argv_file_scanner. We have it here for documentation.
    //
    string --options-file
    {
      "<file>",
      "Read additional options from <file>. Each option should appear on a
       separate line optionally followed by space or equal sign (\cb{=}) and
       an option value. Empty lines and lines starting with \cb{#} are
       ignored. Option values can be enclosed in double (\cb{\"}) or single
       (\cb{'}) quotes to preserve leading and trailing whitespaces as well as
       to specify empty values. If the value itself contains trailing or
       leading quotes, enclose it with an extra pair of quotes, for example
       \cb{'\"x\"'}. Non-leading and non-trailing quotes are interpreted as
       being part of the option value.

       The semantics of providing options in a file is equivalent to providing
       the same set of options in the same order on the command line at the
       point where the \cb{--options-file} option is specified except that
       the shell escaping and quoting is not required. Repeat this option
       to specify more than one options file."
    }

    dir_path --default-options
    {
      "<dir>",
      "The directory to load additional default options files from."
    }

    bool --no-default-options
    {
      "Don't load default options files."
    }
  };

  {
    "",
    "
    \h|JSON OUTPUT|

    Commands that support the JSON output specify their formats as a
    serialized representation of a C++ \cb{struct} or an array thereof. For
    example:

    \
    struct package
    {
      string name;
    };

    struct configuration
    {
      uint64_t         id;
      string           path;
      optional<string> name;
      bool             default;
      vector<package>  packages;
    };
    \

    An example of the serialized JSON representation of \cb{struct}
    \cb{configuration}:

    \
    {
      \"id\": 1,
      \"path\": \"/tmp/hello-gcc\",
      \"name\": \"gcc\",
      \"default\": true,
      \"packages\": [
        {
          \"name\": \"hello\"
        }
      ]
    }
    \

    This sections provides details on the overall properties of such formats
    and the semantics of the \cb{struct} serialization.

    The order of members in a JSON object is fixed as specified in the
    corresponding \cb{struct}. While new members may be added in the
    future (and should be ignored by older consumers), the semantics of the
    existing members (including whether the top-level entry is an object or
    array) may not change.

    An object member is required unless its type is \cb{optional<>},
    \cb{bool}, or \cb{vector<>} (array). For \cb{bool} members absent means
    \cb{false}. For \cb{vector<>} members absent means empty. An empty
    top-level array is always present.

    For example, the following JSON text is a possible serialization of
    the above \cb{struct} \cb{configuration}:

    \
    {
      \"id\": 1,
      \"path\": \"/tmp/hello-gcc\"
    }
    \
    "
  }

  "
   \h|DEFAULT OPTIONS FILES|

   See \l{bdep-default-options-files(1)} for an overview of the default
   options files. The following common options cannot be specified in the
   default options files:

   \
   --fetch-cache-session
   \
  "
}
