---
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:

```sh
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:

    ```sh
    azldev comp update -p <name>
    ```

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

   ```sh
   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:

  ```toml
  [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:

```sh
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.