azldev

# Using azldev azldev builds a Linux distribution from TOML configuration. It imports RPM specs from an upstream distro and customizes them with an overlay system — no spec forking. Components render to specs and sidecar build inputs, then build into RPMs; images assemble RPMs into bootable artifacts. ## Orient yourself - Run azldev from the repo root (where `azldev.toml` lives), or pass `-C <dir>`. - Global, agent-friendly flags: **`-q`** (quiet) and **`-O json`** (machine-readable output). They work on every command. - Config is a stitched TOML hierarchy: `azldev.toml` includes the distro and project config, which include the component files (`**/*.comp.toml`) into one namespace. ## Core concepts - **Component** — a unit of packaging that renders to a spec and sidecar build inputs, then builds into one or more RPMs. Its spec source is upstream (default), a pinned upstream distro/version, or a local spec. - **Overlay** — a semantic patch applied to a spec or source file at render time, so you customize upstream without forking it. - **Distro** — a named build target (`*.distro.toml`) with upstream URIs, release versions, and build inputs. - **Rendered spec** — the generated `.spec` after overlays; a build input, never hand-edited. - **Lock** — a per-component file pinning the resolved upstream commit and an input fingerprint. ## Common commands Top-level commands in this build: - `azldev completion` — Generate the autocompletion script for the specified shell - `azldev component` — Manage components - `azldev config` — Manage tool configuration - `azldev docs` — Documentation commands - `azldev image` — Manage Azure Linux images - `azldev package` — Manage binary package configuration - `azldev project` — Manage Azure Linux projects - `azldev repo` — Inspect and manage RPM repositories - `azldev version` — Print the CLI version Everyday tasks (add `-q -O json` when scripting): | Task | Command | | --- | --- | | List components | `azldev comp list -a` | | Inspect one component | `azldev comp list -p <name>` | | Add a component | `azldev comp add` | | Build a component | `azldev comp build -p <name>` | | Render specs | `azldev comp render -p <name>` (or `-a`) | | Refresh a lock | `azldev comp update -p <name>` | | List / build images | `azldev image list` / `azldev image build` | `comp` is an alias for `component`. Always confirm current syntax with `azldev <command> --help`. The hidden `advanced` group (`adv`) contains specialist integrations such as MCP and mock helpers; it is intentionally omitted from normal help. ## Where to go next - Add a new component — read the `azldev-add-component` skill. - Edit or review a component's TOML — read the `azldev-comp-toml` skill. - Add or change overlays — read the `azldev-overlays` skill. - Annotate an overlay's intent (category, upstream status, provenance) — read the `azldev-overlay-metadata` skill. - Build, iterate, and debug a component — read the `azldev-build-component` skill. - Build, boot, and register images — read the `azldev-image` skill. - Refresh a lock and finalize for a PR — read the `azldev-update-component` skill. - Remove a component — read the `azldev-remove-component` skill. - Test built RPMs in a chroot — read the `azldev-mock` skill. ## Golden rules - **Never edit generated output** — rendered specs and the output/work/log dirs are produced by azldev. Change the source config and re-render. - **Re-run `azldev comp update` before opening a PR** — the lock fingerprint covers the whole component config, and lock / rendered-spec CI checks run on committed state. - **Every overlay needs a `description`** explaining why the change is needed. Generated by `azldev docs agent`; do not hand-edit.