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

include <set>;

include <bpkg/types>;
include <bpkg/options-types>;

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

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

    "\h|SYNOPSIS|

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

     \h|DESCRIPTION|

     The common options control behavior that is common to all or most of the
     \cb{bpkg} 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{bpkg-common-options(1)}.",
      ""
    }

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

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

    path --build = "b"
    {
      "<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{bpkg} will use
       \cb{b} by default."
    }

    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 --fetch
    {
      "<path>",
      "The fetch program to be used to download resources. Currently,
       \cb{bpkg} recognizes \cb{curl}, \cb{wget}, and \cb{fetch}. Note that
       the last component of <path> must contain one of these names as a
       substring in order for \cb{bpkg} to recognize which program is being
       used. You can also specify additional options that should be passed
       to the fetch program with \cb{--fetch-option}.

       If the fetch program is not specified, then \cb{bpkg} will try to
       discover if one of the above programs is available and use that.
       Currently, \cb{bpkg} has the following preference order: \cb{wget}
       1.16 or higher (supports \cb{--show-progress}), \cb{curl},
       \cb{wget}, and \cb{fetch}."
    }

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

    path --sha256
    {
      "<path>",
      "The sha256 program to be used to calculate SHA256 sums. Currently,
       \cb{bpkg} recognizes \cb{sha256}, \cb{sha256sum}, and \cb{shasum}.
       Note that the last component of <path> must contain one of these names
       as a substring in order for \cb{bpkg} to recognize which program is
       being used. You can also specify additional options that should be
       passed to the sha256 program with \cb{--sha256-option}.

       If the sha256 program is not specified, then \cb{bpkg} will try to
       discover if one of the above programs is available and use that.
       Currently, \cb{bpkg} has the following preference order: \cb{sha256},
       \cb{sha256sum}, and \cb{shasum}."
    }

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

    path --tar = "tar"
    {
      "<path>",
      "The tar program to be used to extract package archives. For example,
       \cb{gtar} or \cb{bsdtar}. You can also specify additional options that
       should be passed to the tar program with \cb{--tar-option}. If the tar
       program is not explicitly specified, then \cb{bpkg} will use \cb{tar}
       by default."
    }

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

    path --openssl = "openssl"
    {
      "<path>",
      "The openssl program to be used for crypto operations. You can also
       specify additional options that should be passed to the openssl
       program with \cb{--openssl-option}. If the openssl program is not
       explicitly specified, then \cb{bpkg} will use \cb{openssl} by default."
    }

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

    bpkg::auth --auth = bpkg::auth::remote
    {
      "<type>",
      "Repository types be authenticated. Valid values for this option are
       \cb{none}, \cb{remote}, \cb{all}. By default only remote repositories
       are authenticated. You can request authentication of local repositories
       by passing \cb{all} or disable authentication completely by passing
       \cb{none}."
    }

    std::set<string> --trust
    {
      "<fingerprint>",
      "Trust repository certificate with a SHA256 <fingerprint>. Such a
       certificate is trusted automatically, without prompting the user for
       a confirmation. Repeat this option to trust multiple certificates.

       Note that by default \cb{openssl} prints a SHA1 fingerprint and to
       obtain a SHA256 one you will need to pass the \cb{-sha256} option,
       for example:

       \
       openssl x509 -sha256 -fingerprint -noout -in cert.pem
       \
      "
    }

    bool --trust-yes|-y
    {
      "Assume the answer to all authentication prompts is \cb{yes}."
    }

    bool --trust-no|-n
    {
      "Assume the answer to all authentication prompts is \cb{no}."
    }

    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{bpkg} 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 appearing on a
       separate line optionally followed by space 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. You can repeat this
       option to specify more than one options file."
    }
  };
}