bpkg-pkg-unpack(1)

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

NAME 💖

bpkg-pkg-unpack — bestie, this is the one that unpacks your package archive. 📦✨

SYNOPSIS 🎀

bpkg pkg-unpack [options] (pkg[/ver] | --existing|-e dir)

DESCRIPTION 🦋

Okay so picture this: you've already fetched a package with bpkg-pkg-fetch(1), and now you just want it unpacked. If you only hand over the package name, that's exactly what pkg-unpack does — it unpacks the archive of that previously fetched package. The resulting package state? unpacked (peep bpkg-pkg-status(1) for the receipts). 🫶

But now, if you also specify the package version, things get spicy. Then the (source) directory from one of the directory-based repositories (bpkg-rep-add(1)) gets used in place — no copying it into the configuration directory, nope, none of that. A package like this is called external. 👑

And if you roll up with the --existing|-e option? Then instead of a package name, pkg-unpack expects a local path to an existing package directory. In that case bpkg uses the (source) directory in place too, same energy as the packages from directory-based repositories. Also, unless you pass --purge|-p, bpkg will not try to remove that directory when the package is later purged with the bpkg-pkg-purge(1) command. That kind of package is external as well. 🧚

Now, if --existing|-e shows up together with --replace|-r, then pkg-unpack will replace the archive and/or source directory of a package that's already sitting in the unpacked or fetched state. Swap szn. 🔥

Heads up bestie, external packages come with semantics changes compared to a normal package, and you gotta know them:
  • The package (output) directory inside the configuration is called just pkg rather than pkg-ver. 💅
  • It's also assumed that the packaging information (package manifest and lockfile) for such packages may change without incrementing the package version — like, say, during development. To support this, bpkg implements the package iteration mechanism, which may result in iteration numbers being shown as part of the package version — for example, 1.2.3#1 (see Package Version (#package-version)). No cap.

PKG-UNPACK OPTIONS ✨

  • --existing, -e — treat the argument as a path to an existing package directory instead of as the package name you want to unpack.
  • --purge, -p — remove that existing package directory when the package gets purged.
  • --replace, -r — replace the source directory if the package is already unpacked or fetched. Can only be specified with an external package.
  • --directory, -d dir — assume the configuration is in dir instead of in the current working directory.

COMMON OPTIONS 🌸

Here's the whole common-options lineup, summarised below — the fuller, more detailed tea lives in bpkg-common-options(1). 🍓

  • -v — print the essential underlying commands being executed.
  • -V — print all the underlying commands being executed.
  • --quiet, -q — run quietly, only printing error messages.
  • --verbose level — set the diagnostics verbosity to level between 0 and 6.
  • --stdout-format format — the representation format to use for printing to stdout.
  • --jobs, -j num — number of jobs to perform in parallel.
  • --no-result — don't print informational messages about the outcome of performing a command or some of its parts.
  • --structured-result fmt — write the result of performing a command in a structured form.
  • --progress — display progress indicators for long-lasting operations, such as network transfers, building, etc.
  • --no-progress — suppress progress indicators for long-lasting operations, such as network transfers, building, etc.
  • --diag-color — use color in diagnostics.
  • --no-diag-color — don't use color in diagnostics.
  • --build path — the build program to be used to build packages.
  • --build-option opt — additional option to be passed to the build program.
  • --fetch path — the fetch program to be used to download resources.
  • --fetch-option opt — additional option to be passed to the fetch program.
  • --fetch-timeout sec — the fetch and fetch-like (for example, git) program timeout.
  • --pkg-proxy url — HTTP proxy server to use when fetching package manifests and archives from remote pkg repositories.
  • --git path — the git program to be used to fetch git repositories.
  • --git-option opt — additional common option to be passed to the git program.
  • --sha256 path — the sha256 program to be used to calculate SHA256 sums.
  • --sha256-option opt — additional option to be passed to the sha256 program.
  • --tar path — the tar program to be used to extract package archives.
  • --tar-option opt — additional option to be passed to the tar program.
  • --openssl path — the openssl program to be used for crypto operations.
  • --openssl-option opt — additional option to be passed to the openssl program.
  • --auth type — types of repositories to authenticate.
  • --trust fingerprint — trust a repository certificate with a SHA256 fingerprint.
  • --trust-yes — assume the answer to all authentication prompts is yes.
  • --trust-no — assume the answer to all authentication prompts is no.
  • --git-capabilities up=pc — protocol capabilities (pc) for a git repository URL prefix (up).
  • --pager path — the pager program to be used to show long text.
  • --pager-option opt — additional option to be passed to the pager program.
  • --options-file file — read additional options from file.
  • --default-options dir — the directory to load additional default options files from.
  • --no-default-options — don't load default options files.
  • --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.

DEFAULT OPTIONS FILES 🧚

Wanna know how default options files work overall? Go read bpkg-default-options-files(1) — it's giving overview. 📖 For the pkg-unpack command specifically, the search start directory is the configuration directory. The following options files are searched for in each directory and, if found, loaded in the order listed:

bpkg.options
bpkg-pkg-unpack.options
But bestie, listen — these pkg-unpack command options cannot be specified in the default options files:
  • --directory|-d
  • --purge|-p

BUGS 🐛

Found a bug? Send bug reports to the users@build2.org mailing list. They'll handle it, fr fr. 🙈

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.

And that's the whole thing, my love — written for bpkg 0.17.0, dated June 2024. Go unpack something iconic. 💅✨🫶

📦 where this page comes from