diff options
Diffstat (limited to 'bpkg/common.cli')
| -rw-r--r-- | bpkg/common.cli | 178 |
1 files changed, 160 insertions, 18 deletions
diff --git a/bpkg/common.cli b/bpkg/common.cli index 49a7788..c7d28bc 100644 --- a/bpkg/common.cli +++ b/bpkg/common.cli @@ -80,6 +80,14 @@ namespace bpkg \li|Even more detailed information.||" } + bpkg::stdout_format --stdout-format = bpkg::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." + } + size_t --jobs|-j { "<num>", @@ -90,32 +98,63 @@ namespace bpkg \cb{test}, etc." } - // In the future we may also have --structured-result, similar to the - // build system. - // bool --no-result { "Don't print informational messages about the outcome of performing - a command." + a command or some of its parts. Note that if this option is specified, + then for certain long-running command parts progress is displayed + instead, unless suppressed with \cb{--no-progress}." + } + + string --structured-result + { + "<fmt>", + "Write the result of performing a command in a structured form. In + this mode, instead of printing to \cb{stderr} informational messages + about the outcome of performing a command or some of its parts, + \cb{bpkg} writes to \cb{stdout} a machine-readable result description + in the specified format. Not all commands support producing structured + result and valid <fmt> values are command-specific. Consult the command + documentation for details." } // 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 (which we may add in the - // future), 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. + // 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 --build { "<path>", @@ -149,8 +188,7 @@ namespace bpkg 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}, + Currently, \cb{bpkg} has the following preference order: \cb{curl}, \cb{wget}, and \cb{fetch}." } @@ -162,6 +200,13 @@ namespace bpkg specify multiple fetch options." } + // Undocumented equivalents to bdep's --curl* options. We "merge" them + // into --fetch/--fetch-option in an ad hoc manner (see fetch.cxx for + // details). + // + path --curl; + strings --curl-option; + size_t --fetch-timeout { "<sec>", @@ -277,13 +322,17 @@ namespace bpkg only applicable to the specific command, for example: \ - bpkg rep-create \ - --openssl rsautl:/path/to/openssl \ - --openssl-option rsautl:-engine \ - --openssl-option rsautl:pkcs11 \ + bpkg rep-create \ + --openssl pkeyutl:/path/to/openssl \ + --openssl-option pkeyutl:-engine \ + --openssl-option pkeyutl:pkcs11 \ ... \ + Note that for \cb{openssl} versions prior to \cb{3.0.0} \cb{bpkg} uses + the \cb{rsautl} command instead of \cb{pkeyutl} for the data signing + and recovery operations. + An unqualified value that contains a colon can be specified as qualified with an empty command, for example, \cb{--openssl :C:\\bin\\openssl}. To see openssl commands executed by \cb{bpkg}, use @@ -341,6 +390,24 @@ namespace bpkg "Assume the answer to all authentication prompts is \cb{no}." } + git_capabilities_map --git-capabilities + { + "<up>=<pc>", + "Protocol capabilities (<pc>) for a \cb{git} repository URL prefix + (<up>). Valid values for the capabilities are \cb{dumb} (no shallow + clone support), \cb{smart} (support for shallow clone, but not for + fetching unadvertised commits), \cb{unadv} (support for shallow clone + and for fetching unadvertised commits). For example: + + \ + bpkg build https://example.org/foo.git#master \ + --git-capabilities https://example.org=smart + \ + + See \l{bpkg-repository-types(1)} for details on the \cb{git} protocol + capabilities." + } + string --pager // String to allow empty value. { "<path>", @@ -394,5 +461,80 @@ namespace bpkg { "Don't load default options files." } + + bool --keep-tmp + { + "Don't remove the \cb{bpkg}'s temporary directory at the end of the + command execution and print its path at the verbosity level 2 or + higher. This option is primarily useful for troubleshooting." + } }; + + { + "", + " + \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\" + } + \ + " + } } |