Azldev Add Component

Add a component

Before you start

Confirm the component does not already exist:

azldev comp list -p <name> -q -O json

Inspect the upstream spec first

The reliable way to see what you are importing (direct web fetches of upstream

dist-git often fail bot detection):

• Add a bare entry so azldev can resolve the component: run azldev comp add <name>

(it appends [components.<name>] to the root config file), or hand-add

[components.<name>] to an included config file if you want it to live elsewhere.

A bare root entry is *perfect* for initial testing, but real distros will usually

segment the configuration into included files. Once the initial pass is done,

ensure the component is in the right place and remove the root entry.

• Create the initial lock so source resolution is pinned before inspection:

    azldev comp update -p <name>

• Pull the sources without overlays into a scratch dir under the work dir:

   azldev comp prep-sources -p <name> --skip-overlays --force -o base/build/work/scratch/<name> -q

• Read the spec and plan any overlays.

Inline vs dedicated file

• Inline — a bare upstream import with no changes stays in a shared config file:

  [components.jq]

• Dedicated — anything that needs overlays, build config, or a local spec gets its

own <name>/<name>.comp.toml. Rule of thumb: more than [components.<name>] earns a

dedicated file. An includes = ["**/*.comp.toml"] glob picks it up automatically.

azldev comp add <name> [<name>...] adds bare [components.<name>] entries that inherit

the distro defaults; it writes to the root config file and does not scaffold spec or

source files. If your distro keeps components in included or dedicated files, move the

entry there afterward.

Customize

For spec source types and overlays, read the azldev-comp-toml and azldev-overlays skills. Key

points when adding a component:

• Prefer overlays over forking the spec — overlays get upstream updates for free.

Forking a spec is a last resort and a long-term maintenance commitment. Get explicit

user sign-off first, document every change, and keep the delta minimal.

• Every overlay needs a description explaining why it is needed.
• Keep %check enabled. Disable it only as a last resort via build.check.skip = true

with a required build.check.skip_reason (see the azldev-build-component skill).

Validate

The initial lock pins the upstream revision you inspected. Refresh it after the

component inputs settle, then validate:

azldev comp update -p <name>          # resolve the upstream commit and write the lock
azldev comp render -p <name>          # apply overlays and write the rendered spec
azldev comp diff-sources -p <name>    # see exactly what the overlays change
azldev comp build -p <name>           # build the RPMs

Inspect the rendered spec under specs/. A new component always needs a

smoke test — see the azldev-build-component and azldev-mock skills.

After all component inputs are final, run azldev comp update -p <name> again and

re-render. Stage the component definition and sources, locks/<name>.lock, and

the rendered output before committing. Then re-render, stage

specs/<first-char>/<name>/, and amend the commit so %changelog and

Release: reflect it. See the azldev-update-component skill for the complete

finalization workflow.

Generated by azldev docs agent; do not hand-edit. Generated for azldev version v0.1.0.