bpkg-common-options(1)

📦
version 0.17.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05

💖 bpkg-common-options — the manual page, but make it make sense 💖

okay bestie, so this is bpkg-common-options(1) from the General Commands Manual, and it's literally the cheat sheet for the options that every bpkg command shares. no cap. let's get into it 🦋

✨ NAME ✨

bpkg-common-options — the full tea on the common options ☕

✨ SYNOPSIS ✨

bpkg [common-options] ...

✨ DESCRIPTION ✨

So these "common options" are the ones that control behavior shared by all or most of the bpkg commands. The cute part? You can drop them either before the command or after it, right alongside the command-specific options. wherever, whenever, main character energy 💅

✨ COMMON OPTIONS ✨

  • -v — print the essential underlying commands that are actually being executed. this is giving exactly the same thing as --verbose 2. ✨
  • -V — print all the underlying commands being executed. equivalent to --verbose 3. full transparency, we love to see it 🔥
  • --quiet, -q — run quietly, only printing error messages. same vibe as --verbose 0. shhh 🤫
  • --verbose level — set the diagnostics verbosity to level, which lives between 0 and 6. Level 0 turns off every non-error message while level 6 is like, a LOT of info. level 1 is the default, bestie. and here's the extra diagnostics each level unlocks:
    1. High-level information messages.
    2. Essential underlying commands being executed.
    3. All underlying commands being executed.
    4. Information that could be helpful to the user.
    5. Information that could be helpful to the developer.
    6. Even more detailed information.
  • --stdout-format format — the representation format used when printing to stdout. the valid values are lines (the default, queen) and json. for the full rundown on the json format, go peep the JSON OUTPUT section below 👑
  • --jobs, -j num — how many jobs to run in parallel. if you don't specify this option, or you specify it with the value 0, then it uses the number of available hardware threads instead. this option also gets propagated when it performs build system operations like update, test, etc. multitasking icon behavior 🧚
  • --no-result — don't print the informational messages about the outcome of performing a command or some of its parts. but heads up bestie: if you specify this, then for certain long-running command parts, progress is displayed instead, unless you suppress it with --no-progress. plot twist 😭
  • --structured-result fmt — write the result of performing a command in a structured form. in this mode, instead of printing those informational messages about the outcome of a command (or some of its parts) to stderr, bpkg writes a machine-readable result description to stdout in the specified format. not all commands support producing structured result, and the valid fmt values are command-specific. so go consult the command documentation for the deets 📋
  • --progress — display progress indicators for long-lasting operations, like network transfers, building, etc. if it's printing to a terminal, the progress is displayed by default for low verbosity levels. use --no-progress to suppress it 🌀
  • --no-progress — suppress those progress indicators for long-lasting operations (network transfers, building, etc.). bye bye spinner 👋
  • --diag-color — use color in diagnostics. if printing to a terminal, color is used by default, provided the terminal is not dumb. use --no-diag-color to suppress. 🌈
  • --no-diag-color — don't use color in diagnostics. monochrome era 🖤
  • --build path — the build program used to build packages. this should be the path to the build2 b executable. you can also specify additional options that should be passed to the build program with --build-option.

if the build program isn't explicitly specified, then bpkg will by default use b plus an executable suffix if one was specified when building bpkg. so for example, if bpkg name was set to bpkg-1.0, then it will look for b-1.0. 🔍

  • --build-option opt — an additional option to be passed to the build program. see --build for more info on the build program. repeat this option to specify multiple build options. 🔁
  • --fetch path — the fetch program used to download resources. currently bpkg recognizes curl, wget, and fetch. note that the last component of path must contain one of these names as a substring in order for bpkg to recognize which program is being used. you can also specify additional options to pass to the fetch program with --fetch-option.

if the fetch program isn't specified, then bpkg will try to discover if one of the above programs is available and use that. currently bpkg has the following preference order: curl, wget, and fetch. 🏆

  • --fetch-option opt — an additional option to be passed to the fetch program. see --fetch for more info on the fetch program. repeat this option to specify multiple fetch options. 💫
  • --fetch-timeout sec — the fetch and fetch-like (for example, git) program timeout. while the exact semantics of the value depend on the program used, at a minimum it specifies in seconds the maximum time that can be spent without any network activity.

specifically, it's translated to the --max-time option for curl and to the --timeout option for wget and fetch. for git over HTTP/HTTPS this semantics is achieved using the http.lowSpeedLimit=1 http.lowSpeedTime=sec configuration values (the git:// and ssh:// protocols currently do not support timeouts).

see --fetch and --git for more information on the fetch programs. ⏱️

  • --pkg-proxy url — the HTTP proxy server to use when fetching package manifests and archives from remote pkg repositories. if specified, the proxy url must be in the http://host[:port] form. if port is omitted, 80 is used by default.

note that to allow caching, the proxied https:// URLs are converted to http:// in order to prevent the fetch program from tunneling (which is the standard approach for proxying HTTPS). if both HTTP and HTTPS repositories are used, it's assumed that the proxy server can figure out which URLs need to be converted back to https:// based on the request information (for example, host name).

for security, this mechanism should only be used with signed repositories or when the proxy is located inside a trusted network. 🔐
  • --git path — the git program used to fetch git repositories. you can also specify additional options to pass to the git program with --git-option.

if the git program isn't explicitly specified, then bpkg will use git by default. 🌿

  • --git-option opt — an additional common option to be passed to the git program. note that the common options are the ones that precede the git command. see --git for more info on the git program. repeat this option to specify multiple git options. 🎀
  • --sha256 path — the sha256 program used to calculate SHA256 sums. currently bpkg recognizes sha256, sha256sum, and shasum. note that the last component of path must contain one of these names as a substring in order for bpkg to recognize which program is being used. you can also specify additional options to pass to the sha256 program with --sha256-option.

if the sha256 program isn't specified, then bpkg will try to discover if one of the above programs is available and use that. currently bpkg has the following preference order: sha256, sha256sum, and shasum. 🔢

  • --sha256-option opt — an additional option to be passed to the sha256 program. see --sha256 for more info on the sha256 program. repeat this option to specify multiple sha256 options. 🧮
  • --tar path — the tar program used to extract package archives. for example, gtar or bsdtar. you can also specify additional options to pass to the tar program with --tar-option. if the tar program isn't explicitly specified, then bpkg will use tar by default. 🗜️
  • --tar-option opt — an additional option to be passed to the tar program. see --tar for more info on the tar program. repeat this option to specify multiple tar options. 📦
  • --openssl path — the openssl program used for crypto operations. you can also specify additional options to pass to the openssl program with --openssl-option. if the openssl program isn't explicitly specified, then bpkg will use openssl by default.

the --openssl* values can be optionally qualified with the openssl command in the command:value form. this makes the value only applicable to the specific command, for example:

bpkg rep-create                      \
  --openssl pkeyutl:/path/to/openssl \
  --openssl-option pkeyutl:-engine   \
  --openssl-option pkeyutl:pkcs11    \
  ...

note that for openssl versions prior to 3.0.0 bpkg uses the rsautl command instead of 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, --openssl :C:\bin\openssl. to see openssl commands executed by bpkg, use the verbose mode (-v option). 🔑

  • --openssl-option opt — an additional option to be passed to the openssl program. see --openssl for more info on the openssl program. the values can be optionally qualified with the openssl command, as discussed in --openssl. repeat this option to specify multiple openssl options. 💜
  • --auth type — the types of repositories to authenticate. valid values for this option are none, remote, all. by default only remote repositories are authenticated. you can request authentication of local repositories by passing all, or disable authentication completely by passing none. 🛡️
  • --trust fingerprint — trust a 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 openssl prints a SHA1 fingerprint, and to obtain a SHA256 one you'll need to pass the -sha256 option, for example:

openssl x509 -sha256 -fingerprint -noout -in cert.pem
  • --trust-yes — assume the answer to all authentication prompts is yes. ✅
  • --trust-no — bestie, just say no to everything 💅 every single authentication prompt gets an automatic "nope" from you.
  • --git-capabilities up=pc — sets protocol capabilities (pc) for a git repository URL prefix (up). The valid capability values are, and I quote: dumb (no shallow clone support), smart (support for shallow clone, but not for fetching unadvertised commits), and unadv (support for shallow clone and for fetching unadvertised commits). Like, for example:
bpkg build https://example.org/foo.git#master \
  --git-capabilities https://example.org=smart

See bpkg-repository-types(1) for the deets on git protocol capabilities. iykyk 🧚

  • --pager path — the pager program used to show long text. The commonly used pager programs are less and more. You can also specify extra options that should be passed to the pager program with --pager-option. If you pass an empty string as the pager program, then no pager will be used, periodt. If the pager program is not explicitly specified, then bpkg will try to use less. If it's not available, then no pager will be used. 🙈
  • --pager-option opt — an additional option to be passed to the pager program. See --pager for more info on the pager program. Repeat this option to specify multiple pager options. slay 🎀
  • --options-file file — read additional options from file. Each option should appear on a separate line, optionally followed by space or equal sign (=) and an option value. Empty lines and lines starting with # are ignored. Option values can be enclosed in double (") or single (') 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 '"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 --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. ✨

  • --default-options dir — the directory to load additional default options files from.
  • --no-default-options — don't load default options files. not me choosing chaos 🙈
  • --keep-tmp — don't remove 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. (Main character energy for people who debug. 👑)

🌈 JSON OUTPUT 🌈

Commands that support the JSON output specify their formats as a serialized representation of a C++ 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 struct configuration:

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

This section provides details on the overall properties of such formats and the semantics of the struct serialization. 🦋

The order of members in a JSON object is fixed as specified in the corresponding 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. lowkey important, highkey forever.

An object member is required unless its type is optional<>, bool, or vector<> (array). For bool members, absent means false. For 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 struct configuration:

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

💀 BUGS 💀

Send bug reports to the users@build2.org mailing list. (Be nice, they're lovely.)

Copyright (c) 2014-2024 the build2 authors.

Permission is granted to copy, distribute and/or modify this document under the terms of the MIT License.

okay that's the whole vibe check bestie — this was bpkg-common-options(1) from bpkg 0.17.0, dated June 2024. go forth and --keep-tmp responsibly, mwah 💖✨🎀

📦 where this page comes from