azldev-add-component

name	azldev-add-component
description	Read this before adding or importing a component; follow the workflow instead of guessing. Explains how to add a new component to an azldev distro, covering inspecting the upstream spec, the inline-versus-dedicated-file decision, and validating with render, diff-sources, and build. Triggers include add component, new package, import package, create comp.toml, new 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):

1. 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.

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

   azldev comp update -p <name>
   

3. 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
   

4. 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.3.0.