Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Package & Config Reference

This page is the reference for what InterGenOS ships and how to inspect it: the package tiers, the on-disk state that pkm records, and the commands that answer “what is installed, at what version, owning which files?” directly from the live system.

Because a hand-maintained package table drifts the moment a package is added, split, or superseded, this reference does not reproduce a frozen catalog of every package. Instead it tells you how the package set is structured and how to derive the authoritative, current answer from the machine in front of you.

Why the live system is the source of truth

A wiki table written once quietly falls out of step with the packages actually built, the versions actually shipped, and the files actually deployed. Once that happens the documentation stops being trustworthy, and a document you cannot trust is worse than no document.

InterGenOS treats documentation drift as a defect, not an inconvenience. The trustworthy reference is derived from the same sources that build the system — the package definitions and the recorded install state — so that what you read matches what is on disk. That is part of the wider posture of the distribution: a machine you understand, can modify, and can trust. You cannot trust a system you cannot accurately describe.

The two sources of truth are:

  • The package definitions. Each package is described by a package.yml under the package tree, grouped into build tiers. Seven fields are required of every definition — name, version, release, description, license, source, and build_style — and the parser recognizes a further register of optional keys — among them ones covering the build (tier, dependencies, configure_flags, patches, bundled_deps, validation, tests), packaging and placement (supersedes, ships_as, iso_include, homepage, installer_hooks, reboot_required), and verification (content_hash, verify_paths, build_artifacts). That register also carries narrower keys for bootstrap passes, vendor-payload handling, and gate declarations; the parser’s own known-field list is the complete, authoritative inventory. A key the parser does not recognize is rejected at parse time — the build halts with an error naming the key rather than ignoring it. Silently dropping an unrecognized field was a real defect once, caught only by audit; a later warn-on-standard-error stage proved easy to miss in a long build log, so the parser now fails closed, where the fix is a one-line edit and nothing has built yet.
  • The installed-state database. On a live system, pkm records every installed package, its version and tier, and every deployed file with its SHA-256 hash. See the package manager reference for the data model.

Reconciling these is what makes the reference trustworthy: the definitions say what should be built, and the database records what was installed.

What the reference covers

Per tier, the package set is described by:

  • Package name, version, and tier.
  • Short description.
  • Declared runtime dependencies.
  • Supersede relationships (which package replaces which), since InterGenOS upgrades packages by a supersede model rather than in-place replacement.
  • Tracked configuration files: the /etc/ entries that pkm manages specially to preserve user modifications.

See the package manager reference for supersede semantics and the configuration-file handling these fields are drawn from.

Build tiers

InterGenOS organizes packages into seven tiers, built in order during the image build: toolchain, core, base, desktop, extra, compute, and ai. The tier counts shift continuously as packages are added, split, or superseded, so any number printed in a wiki page is a snapshot rather than a contract.

Derive the live counts from the package tree or from pkm on a running system rather than treating a written number as permanent. For example, to count packages per tier from a checkout of the source tree:

for tier in toolchain core base desktop extra compute ai; do
  printf '%-12s %s\n' "$tier" "$(find packages/$tier -name package.yml | wc -l)"
done

That counts definitions. It is not the count of what is installed, and it is not the count of what ships on the image: extra and compute default to mirror-only, every other tier defaults to shipping, and individual packages override the default in both directions. To ask what is actually on the machine in front of you, ask the machine — pkm list — rather than counting files in a source tree.

The build itself runs as a fixed sequence of 21 phases, with an optional publish step at the end. Six of them build the tiers directly — core, base, desktop, extra, compute, and ai — with toolchain and chroot-tools producing the bootstrap compiler and temporary tools that precede them, and core-extra filling in the core packages that come from outside the base build book. The surrounding phases handle host validation, source verification, environment and chroot setup, system configuration, the kernel, the bootloader, image assembly, manifest generation, squashfs, UKI/dm-verity, and ISO creation. The phase list in the build orchestrator is the authority for the order; the section overview reproduces it.

Querying the real system

The authoritative live answer comes from the package manager itself. pkm keeps a SQLite database at /var/lib/igos/pkm.db and human-readable text manifests under /var/lib/igos/packages/, so the installed state is both fast to query and directly inspectable. The text manifests can be read with ordinary tools, no database client required.

Common queries against the live state:

  • pkm list — list installed packages.
  • pkm info <package> — show a package’s version, tier, and details.
  • pkm files <package> — list the files a package deployed.
  • pkm provides <path> — find which package owns a file.
  • pkm depends <package> — show declared dependencies.
  • pkm verify — recompute the SHA-256 hash of every installed file and compare it against the recorded hash, detecting both corruption and unauthorized modification.

That same hash data is what describes deployed files. For the full data model, operations, and integrity behavior, see the package manager reference.

Notes on scope

This reference describes what the distribution ships today, not what is planned. The shipped desktop is GNOME 49 on Wayland. The shipped local assistant is InterGen, which includes a built-in security-scanner subsystem, InterGen Sentinel.

InterGen and the llama.cpp inference engine are the two ai-tier packages that ship on the image — but they are not the whole tier. The ai tier also carries the model-tooling stack (PyTorch, Transformers, and their dependencies), which is mirror-only: defined and buildable, installable from the repository on demand, and absent from a default installation. Counting definitions and counting what is installed are different questions, and this page is careful to keep them apart.

Planned components, such as switchable desktops or additional application campaigns, are not part of the package tree until they are built, so they do not appear in the installed-state database until then.

This reference exists so that the packages and configuration on your machine can always be described accurately, and therefore audited.