---
name: azldev-build-component
description: "Read this before building a component or diagnosing a build failure; do not guess build flags or the inner loop. Explains how to build, iterate on, and debug an azldev component, covering comp build flags (local-repo, preserve-buildenv), the render/build/test inner loop, diff-sources, and disabling a failing %check via check.skip. Triggers include build component, build failed, build error, inner loop, preserve buildenv, local repo, disable check."
---

# Build and debug a component

**Never install built RPMs on your host** — they target the distro, not your dev
machine. Test them in a chroot with the `azldev-mock` skill. Building and testing are separate
steps: `azldev comp build` produces RPMs; it does not test them.

## Build

```sh
azldev comp build -p <name>                                     # one component
azldev comp build -p <a> -p <b> --local-repo-with-publish <dir> # chain deps via a local repo
azldev comp build -p <name> --local-repo <dir>                  # rebuild against a populated repo
```

Build foundational packages before their dependents. RPMs land in the project's
configured output directory (`out` by default). `-q` quiets output but hides build
progress — use it only for inner-loop builds you expect to succeed.

## The inner loop

investigate → modify → render → build → test → inspect

| Step | Command |
| --- | --- |
| Investigate | read the rendered spec under `specs/`, or `azldev comp diff-sources -p <name>` |
| Modify | edit the component's `.comp.toml` (see the `azldev-overlays` and `azldev-comp-toml` skills) |
| Verify | `azldev comp render -p <name>` (fast — skips source tarballs) |
| Build | `azldev comp build -p <name>` |
| Test | `azldev adv mock shell --add-package <rpm>` (see the `azldev-mock` skill) |
| Inspect | `azldev comp build -p <name> --preserve-buildenv always`, then a mock shell |

Prefer `comp render` for quick overlay verification; use `comp diff-sources` to see the
exact overlay effect (it fetches sources once, applies overlays to a copy, and diffs the
two trees). Builds can be slow — set generous timeouts.

Finalize with `azldev comp update -p <name>` before opening a PR (see the
`azldev-update-component` skill).

## Debugging build failures

1. **Render error mentioning a non-standard `Release` tag** — a release-calculation
   issue; see the `azldev-comp-toml` skill.
2. **Preview error mentioning `rpmdev-bumpspec`, `rpmdev-packager`, `rpm`, `rpmspec`,
   `python3`, or the Python RPM module** — this applies only when you explicitly use
   the temporary `--rpmdev-bumpspec` preview. Provision the named prerequisite for
   that opt-in path. Without the flag, azldev keeps the legacy static Release calculation.
3. **Overlay did not apply as expected** — `azldev comp diff-sources -p <name>` shows
   what the overlays actually change.
4. **Inspect the build environment** — `azldev comp build -p <name> --preserve-buildenv
   on-failure` (values `on-failure`, `always`, `never`), then enter a mock shell.
5. **Failing `%check`** — fix the tests first (root cause, upstream patches, targeted
   fixes). Only as a last resort, disable with `build.check.skip = true` and a required
   `build.check.skip_reason` explaining what fails, why it cannot be fixed, and whether it
   is temporary. A transient `--no-check` build flag exists for one-off local builds.

Per-component build tweaks (`build.defines`, `build.without`) live in the `.comp.toml` —
see the `azldev-comp-toml` skill.

Generated by `azldev docs agent`; do not hand-edit.