docs: Add a packaging-and-integration guide

Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

docs/src/SUMMARY.md

@@ -64,6 +64,7 @@
 
 # More information
 
+- [Packaging and integration](packaging-and-integration.md)
 - [Package manager integration](package-managers.md)
 - [Relationship with other projects](relationships.md)
 - [Relationship with OCI artifacs](relationship-oci-artifacts.md)

docs/src/packaging-and-integration.md

@@ -0,0 +1,132 @@
+# Packaging and Integration
+
+This document describes how to build and package bootc for distribution in operating systems.
+
+### Build Requirements
+
+- Rust toolchain (see `rust-toolchain.toml` for the version)
+- `coreutils` and `make`
+
+### Basic Build Commands
+
+The primary build targets are:
+
+```bash
+make all
+```
+
+This builds:
+- Binary artifacts (`cargo build --release`)
+- Man pages (via `cargo xtask manpages`)
+
+The built binaries are placed in `target/release/`:
+- `bootc` - The main bootc CLI
+- `system-reinstall-bootc` - System reinstallation tool
+- `bootc-initramfs-setup` - Initramfs setup utility
+
+### Installation
+
+The `install` target supports the standard `DESTDIR` variable for staged installations, which is essential for packaging:
+
+```bash
+make install DESTDIR=/path/to/staging/root
+```
+
+
+The install target handles:
+- Binary installation to `$(prefix)/bin`
+- Man pages to `$(prefix)/share/man/man{5,8}`
+- systemd units to `$(prefix)/lib/systemd/system`
+- Documentation and examples to `$(prefix)/share/doc/bootc`
+- Dracut module to `/usr/lib/dracut/modules.d/51bootc`
+- Base image configuration files
+
+### Optional Installation Targets
+
+#### install-ostree-hooks
+
+For distributions that need bootc to provide compatibility with `ostree container` commands:
+
+```bash
+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`
+
+## Source Packaging
+
+### Vendored Dependencies
+
+bootc is written in Rust and has numerous dependencies. For distribution packaging, we recommend using a vendored tarball of Rust crates to ensure reproducible builds and avoid network access during the build process.
+
+#### Generating the Vendor Tarball
+
+Use the `cargo xtask package` command to generate both source and vendor tarballs:
+
+```bash
+cargo xtask package
+```
+
+This creates two files in the `target/` directory:
+- `bootc-<version>.tar.zstd` - Source tarball with git archive contents
+- `bootc-<version>-vendor.tar.zstd` - Vendored Rust dependencies
+
+The source tarball includes a `.cargo/vendor-config.toml` file that configures cargo to use the vendored dependencies.
+
+#### Using Vendored Dependencies in Builds
+
+When building with vendored dependencies:
+
+1. Extract both tarballs into your build directory
+2. Extract the vendor tarball to create a `vendor/` directory
+3. Ensure `.cargo/vendor-config.toml` is in place (included in source tarball)
+4. Build normally with `make all`
+
+The cargo build will automatically use the vendored crates instead of fetching from crates.io.
+
+### Version Management
+
+The version is derived from git tags. The `cargo xtask package` command automatically determines the version:
+- If the current commit has a tag: uses the tag (e.g., `v1.0.0` becomes `1.0.0`)
+- Otherwise: generates a timestamp-based version with commit hash (e.g., `202501181430.g1234567890`)
+
+This ensures that development snapshots have monotonically increasing version numbers.
+
+## 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:
+
+```bash
+make all CARGO_FEATURES="rhsm"
+```
+
+## Integration Testing
+
+For distributions that want to include integration tests, use:
+
+```bash
+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`
+
+## Base image content
+
+Alongside building the binary here, you may also want to prepare
+a base image. For that, see [bootc-images](bootc-images.md).
+
+## 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.
+