The Ur Project

Documenting the craft of stacking things so they remain stacked. For a very long time.

pkg-set(1)

NAME

pkg-set - list or inspect package sets published across the chain

SYNOPSIS

pkg set list

pkg set show name

DESCRIPTION

Sets are nothing more than lists of packages. A member can be a package like gcc, a single subpackage like kernel-headers/dev, or another set. That last one is what lets +gnome pull in +gdm-login without repeating it.

pkg set shows you sets the way the repository chain publishes them. It's a look at what's on offer. For what this machine is rooted on, see pkg-list-sets(1). For what a set is and how its membership is unioned across the chain, see pkg-sets(7).

COMMANDS

pkg set list

Lists every set name published across the chain. It's the same thing as pkg list-sets --all, and documented there.

pkg set show name

Shows one set's membership, unioned across the chain: which repository contributed each member, and what each member resolves to through the pins chain.

You can give name with or without the leading +. A @repo qualifier is refused. A set is chain-wide by nature, so there's no single repository to point at.

An unknown set is an error. A member that no repository in the chain pins is held and listed separately at the end. That's information, not a failure.

OPTIONS

None of its own. All global options apply; see pkg(1).

OUTPUT

+archive Archive and compression/decompression format tools defined in: Base, Common

member from resolves to brotli Common 1.2.0-2 @Common bzip2 Base held (no pin in chain) p7zip Common 26.02-4 @Common tar Base 1.35-9 @Base

held (no repo in the chain answers these): bzip2

defined in lists every repository that contributes to the union, highest precedence first. The description comes from the first one.

from is which repository listed that member. The resolution (@Common) is which repository won the member's name through the ordinary chain rules. Those two aren't necessarily the same repository. Set union and package shadowing are separate things, and one doesn't affect the other.

What else can "resolves to" say?

  • unpinned @repo: that repository carries the name, but pins no current build for it.
  • held (@repo ships no subpkg subpackage): the member names a subpackage, and the repository that won the name doesn't ship it. That's held too.
  • (set: members): the member is a nested set. Its row lists what it expands to, and its members are part of the flattened list.
  • (invalid: reason): the member couldn't be parsed. It's one bad row, and the rest of the set still prints.

If the set can't be flattened at all, a cycle for instance, the held list is replaced by an unresolvable: line saying why.

JSON

{ "ok": true, "set": "archive", "description": "...", "defined_in": ["Common", "Base"], "members": [ { "member": "brotli", "kind": "package", "from": ["Common"], "package": "brotli", "subpkg": null, "resolves_to": { "state": "pinned", "repo": "Common", "version": "1.2.0", "release": 2 } }, { "member": "bzip2", "kind": "package", "from": ["Base"], "package": "bzip2", "subpkg": null, "resolves_to": { "state": "held" } }, { "member": "+base-tools", "kind": "set", "from": ["Base"] } ], "expanded": ["brotli", "bzip2", ...], "unresolved": null }

resolves_to.state is pinned, unpinned or held. A held member whose winning repository lacks the subpackage also carries "reason": "no_such_subpkg", repo and subpkg. A set member has no resolves_to.

expanded is the flattened member list after nested sets are resolved. unresolved carries the reason when it couldn't be produced, and expanded is then empty.

EXAMPLES

What sets exist?

pkg set list

What's in one?

pkg set show +console pkg set show console

Deciding whether to install a set

pkg set show +xfce pkg install +xfce --dry-run pkg install +xfce

Which members are held?

pkg set show +archive | sed -n '/^held/,$p'

Or in JSON:

pkg --json set show +archive \ | jq -r '.members[] | select(.resolves_to.state == "held") | .member'

The flat member list, for scripting

pkg --json set show +console | jq -r '.expanded[]'

Installing a set's members one by one

For when you want the packages, but not the set root:

pkg install $(pkg --json set show +console | jq -r '.expanded[]')

Mind the difference, though. This records each member as a package root of its own, so when the set changes upstream, this machine won't follow. Installing +console records the set instead, and works out its membership again on every converge.

Which repository contributed each member?

pkg --json set show +console \ | jq -r '.members[] | "(.member)\t(.from | join(","))"'

Sets that overlap

comm -12 \ <(pkg --json set show +console | jq -r '.expanded[]' | sort) \ <(pkg --json set show +storage | jq -r '.expanded[]' | sort)

Members that narrow to one subpackage

pkg --json set show +console \ | jq -r '.members[] | select(.subpkg) | "(.package)/(.subpkg)"'

Inspecting a set in a repository that isn't configured

pkg --repo /srv/mirror/Common --repos-dir /nonexistent set show +console

Composing from a set, after checking it resolves

Compose refuses held members, so look first:

pkg set show +console pkg compose root --output /srv/roots/console \ --closure +console --trust-key "$PUBKEY"

EXIT STATUS

0 on success. 1 for an unknown set, a set reference with an @repo qualifier, or a chain that can't be built. Held members aren't a failure.

SEE ALSO

pkg(1), pkg-list-sets(1), pkg-install(1), pkg-remove(1), pkg-autoremove(1), pkg-compose(1), pkg-state(5), pkg-sets(7), pkg-chain(7)

docs/design/package-sets.md, docs/design/naming.md