Skip to content

concepts.md

Latest commit

 

History

History
308 lines (202 loc) · 7.6 KB

concepts.md

File metadata and controls

308 lines (202 loc) · 7.6 KB

bpt concepts

This document is a terse reference for the concepts that show up repeatedly in bpt commands and configuration.

Package identifiers

pkgid

A pkgid fully identifies one package build:

pkgname@pkgver:arch

Example:

htop@3.4.1:x86_64

Its fields are:

  • pkgname: package name
  • pkgver: package version
  • arch: package architecture

A pkgid always has all three fields.

partid

A partid is a partial package identifier. It always has a package name, and may also include a version and/or architecture:

  • htop
  • htop@3.4.1
  • htop:x86_64
  • htop@3.4.1:x86_64

bpt resolves missing fields from context:

  • installed packages
  • repository contents
  • /etc/bpt/bpt.conf's default-archs

In practice:

  • pkgid names one exact package
  • partid describes what package the user means and lets bpt fill in the rest

Architectures

Named Arch

Named architectures are the usual explicit architecture values such as:

  • x86_64
  • aarch64
  • riscv64gc
  • noarch

noarch means architecture-independent content such as scripts or data files.

Arch::host

host means a portable binary package suitable for the current machine's architecture.

Example on an x86_64 machine:

  • host resolves to x86_64

This is still meant to be portable across machines of that architecture.

Arch::native

native means "build from source with non-portable optimizations tuned for this specific machine."

native is not a repository package format. It is a build request. A package built as native is built locally from a *.bbuild.

Arch::host vs Arch::native

  • host: prefer a portable prebuilt package for this architecture
  • native: prefer building locally for machine-specific optimization

What bpt install can take

bpt install is the clearest example of bpt's input model.

It can take:

  • A file path to a prebuilt binary package:
    • bpt install ./htop@3.4.1:x86_64.bpt
    • bpt opens it and installs it
  • A file path to a package build definition:
    • bpt install ./htop@3.4.1.bbuild
    • bpt opens it, builds it, then installs it
  • A URL to a prebuilt binary package:
    • bpt install https://example/repo/htop@3.4.1:x86_64.bpt
    • bpt downloads it, then installs it
  • A URL to a package build definition:
    • bpt install https://example/repo/htop@3.4.1.bbuild
    • bpt downloads it, builds it, then installs it
  • A partid for a repository binary package:
    • bpt install htop
    • bpt looks it up in configured repositories, downloads it, then installs it
  • A partid for a repository build definition:
    • if the repository only has htop@...:bbuild, or native is preferred and a bbuild is available, bpt looks it up, downloads it, builds it, then installs it

Other commands accept similar mixtures of:

  • file paths
  • URLs
  • repository package identifiers

bpt install is just the most common case.

Building native-optimized packages by default

By default, bpt configuration favors pre-built, portable binaries. If you prefer, it can be reconfigured to build packages locally optimized for your specific hardware. To do so:

  1. Enable repository bbuild indexes in /etc/bpt/repos/bedrock
# Enable bbuild indexes
# Provides instructions on how to build packages
https://bedrocklinux.org/repo/0.8/main/bbuild.pkgidx
https://bedrocklinux.org/repo/0.8/community/bbuild.pkgidx

# Optionally, either enable or disable pkgidx indexes.
# Disabling them ensures you always get from-source.
# Enabling them provides a fall-back if you can't build a package.
https://bedrocklinux.org/repo/0.8/main/x86_64.pkgidx
https://bedrocklinux.org/repo/0.8/community/x86_64.pkgidx

# Optionally, leave fileidx indexes.
# Used for `bpt files` and `bpt provides` look-ups without needing to
# build/install a package first.
https://bedrocklinux.org/repo/0.8/main/x86_64.fileidx
https://bedrocklinux.org/repo/0.8/community/x86_64.fileidx
  1. Configure /etc/bpt/bpt.conf to favor the "native" architecture
# Retain `noarch`, which can't be set to native
[general]
default-archs = noarch, native

World file

The world file is:

/etc/bpt/world

It records the packages the user explicitly wants installed.

Each entry is a partid, not necessarily a fully pinned pkgid.

Examples:

  • htop
  • htop:x86_64
  • htop@3.4.1:x86_64

This is desired state, not a list of every installed package.

Dependencies are usually not written there unless the user explicitly asked for them.

bpt apply

bpt apply treats the current world file as authoritative:

  1. read /etc/bpt/world
  2. resolve dependencies
  3. diff that desired package set against the installed package set
  4. apply the difference

Use bpt apply when:

  • the world file was edited manually
  • a previous operation only partially completed
  • you want to reconcile installed state to current desired state without changing the world file itself

Explicit vs dependency packages

An explicit package is one that appears in the world file.

A dependency package is installed only because something else needs it.

This distinction matters for:

  • bpt list --explicit
  • bpt list --dependency
  • whether removing one package should also remove now-unneeded dependencies

Repository indexes

pkgidx

A package index (*.pkgidx) lists packages available in a repository.

It maps package identifiers to package metadata and repository locations.

It is used for tasks such as:

  • bpt install htop
  • bpt list --repository
  • bpt info htop

It can point to:

  • prebuilt *.bpt packages
  • *.bbuild package build definitions

fileidx

A file index (*.fileidx) maps packages to the file paths they provide.

It is used for tasks such as:

  • bpt provides
  • repository file lookup

Repo indexes vs caches

Repository indexes are metadata about what the repository contains.

They are not packages or source code.

In practice:

  • bpt sync refreshes repository indexes
  • bpt clean removes cached packages and/or cached source
  • bpt clean does not remove installed packages

Package cache

The package cache stores downloaded package artifacts such as:

  • *.bpt
  • downloaded *.bbuild

It avoids downloading the same package repeatedly.

This is separate from:

  • repository indexes
  • installed package metadata
  • the world file

Source cache

The source cache stores downloaded upstream source material used while building packages from *.bbuild.

This is also separate from:

  • repository indexes
  • installed packages
  • the world file

Installed state vs caches vs world

These are different layers:

  • world file:
    • what the user explicitly wants
  • installed state:
    • what is actually installed under the target root
  • repository indexes:
    • metadata describing what repositories offer
  • package cache:
    • downloaded package/build-definition artifacts
  • source cache:
    • downloaded build source material

Keeping them distinct helps explain the main maintenance commands:

  • bpt apply: reconcile installed state to the world file
  • bpt sync: refresh repository index metadata
  • bpt clean: remove package/source cache entries

.bptnew files

Some package files are marked as backup files, typically local configuration files.

If bpt needs to install such a file but an existing on-disk file should not be overwritten, it writes the incoming version as:

<path>.bptnew

Example:

  • package wants to install etc/foo.conf
  • user already has a local etc/foo.conf
  • bpt writes etc/foo.conf.bptnew

This lets the user compare or merge the new packaged version manually.

If the incoming backup file is identical to the current on-disk file, bpt does not create a .bptnew.