BOOTC-PACKAGING-AND-INTEGRATION(7)

✨ NAME ✨

bootc-packaging-and-integration — the whole "how do I package bootc for a distro" situation, explained. it's giving "packaging bible" ngl 💖

(and yeah bestie, this lives in the Miscellaneous Information Manual, section 7, BOOTC-PA...TEGRATION(7) — the name is truncated in the header but you know her 💅)

---

🎀 DESCRIPTION 🎀

okay so. this doc is literally the entire roadmap for how to build and package bootc so it can ship inside operating systems. if you're a distro packager, this is your moment, main character energy fr fr. 🌸

📦 Build Requirements

before you can even think about building, you need:

• a Rust toolchain (peep rust-toolchain.toml for the exact version, don't guess 🙈)
• coreutils and make

that's it. that's the list. slay. ✨

🛠️ Basic Build Commands

the main build targets you care about, starting with the big one:

make all

this builds:

• the binary artifacts (cargo build --release)
• the man pages (via cargo xtask manpages)

and the built binaries land in target/release/:

• bootc — the main bootc CLI, the icon herself 👑
• system-reinstall-bootc — the system reinstallation tool
• bootc-initramfs-setup — the initramfs setup utility

three binaries, one build, no cap. 🔥

🫶 Installation

the install target supports the standard DESTDIR variable for staged installations — which is essential for packaging, like actually non-negotiable:

make install DESTDIR=/path/to/staging/root

here's everything the install target handles:

• binaries → $(prefix)/bin
• man pages → $(prefix)/share/man/man{5,8}
• systemd units → $(prefix)/lib/systemd/system
• documentation and examples → $(prefix)/share/doc/bootc
• the dracut module → /usr/lib/dracut/modules.d/51bootc
• base image configuration files

not me listing all of that and it being the neatest little install ever 🎀

💫 Optional Installation Targets

install-ostree-hooks

for distributions that need bootc to provide compatibility with ostree container commands:

make install-ostree-hooks DESTDIR=/tmp/stage

this creates symbolic links in $(prefix)/libexec/libostree/ext/ for:

• ostree-container
• ostree-ima-sign
• ostree-provisional-repair

three lil symlinks, huge impact. 🦋

---

🌈 Source Packaging

Vendored Dependencies

bootc is written in Rust and has numerous dependencies — like, a lot, bestie 😭. for distribution packaging, the recommendation is to use a vendored tarball of Rust crates, because that gives you:

• reproducible builds
• zero network access during the build process

which is exactly the vibe your build system wants. 💜

🍓 Generating the Vendor Tarball

use the cargo xtask package command to generate both the source and vendor tarballs:

cargo xtask package

this creates two files in the target/ directory:

• bootc-<version>.tar.zstd — the source tarball with git archive contents
• bootc-<version>-vendor.tar.zstd — the vendored Rust dependencies

and! the source tarball includes a .cargo/vendor-config.toml file that configures cargo to use those vendored dependencies. thoughtful queen. 👑

Using Vendored Dependencies in Builds

when you're building with vendored dependencies, do it in this order:

1. extract both tarballs into your build directory
2. extract the vendor tarball to create a vendor/ directory
3. make sure .cargo/vendor-config.toml is in place (it's included in the source tarball, so it should just... be there)
4. build normally with make all

then the cargo build will automatically use the vendored crates instead of fetching from crates.io. no network, no drama, no crates.io knocking at your door. 🧚

Version Management

the version is derived from git tags. the cargo xtask package command figures it out automatically:

• if the current commit has a tag → it uses the tag (e.g., v1.0.0 becomes 1.0.0)
• otherwise → it generates a timestamp-based version with a commit hash (e.g., 202501181430.g1234567890)

why tho? because this ensures development snapshots have monotonically increasing version numbers. ascending numbers only, we don't do chaos here. ⭐

---

💅 Cargo Features

the build respects the CARGO_FEATURES environment variable. by default, the Makefile auto-detects whether to enable the rhsm (Red Hat Subscription Manager) feature, based on the build environment's /usr/lib/os-release.

to explicitly control features:

make all CARGO_FEATURES="rhsm"

the selinux feature is enabled by default and links against libselinux. distributions that don't use SELinux can build without the default features and add back the others they want — heads up: pre-6.15 is only needed to boot composefs systems on kernels older than 6.15:

make bin CARGO_OPTIONS='--no-default-features --features "install-to-disk pre-6.15"'

⚠️ okay important, listen up: such a build treats SELinux as disabled on the host, whatever the kernel says. it never reads selinuxfs, doesn't try to enter the install_t domain, and doesn't parse SELinux contexts — so it is not suitable for hosts that run SELinux. also note that libostree may still link libselinux itself, depending on how it was built, and that the unit test targets (make install-unit-tests) always use the default features. no exceptions bestie 😭

---

🧪 Integration Testing

for distributions that wanna include integration tests, use:

make install-all DESTDIR=/tmp/stage

this installs:

• everything from make install
• everything from make install-ostree-hooks
• the integration test binary as bootc-integration-tests

the deluxe combo pack. ate. 🔥

---

🖼️ Base image content

alongside building the binary here, you may also want to prepare a base image. for that, see bootc-images (see bootc-compatible-images(7)). ✨

---

📚 Additional Resources

• see Makefile for all available targets and variables
• see crates/xtask/src/xtask.rs for cargo xtask implementation details
• see contrib/packaging/bootc.spec for an example RPM spec file that uses all of the above

like genuinely, that spec file uses all of it. study her. 🎀

---

👀 SEE ALSO

bootc(8), bootc-compatible-images(7), bootc-docs(7)

---

🌟 VERSION

this is v1.17.1, periodt 💖

---

and that's the whole page bestie — brought to you by the Miscellaneous Information Manual, that big gorgeous BOOTC-PA...TEGRATION(7) header at the top and the exact same one down at the bottom, cute lil matching bookends 🫶💜 ok bye, go ship a distro package, you're doing amazing 🌈✨