azldev-comp-toml
Read this before authoring, editing, or reviewing a *.comp.toml file; do not work from memory. Explains the azldev component definition format and review workflow, covering component structure, spec sources, build config, release calculation, render options, file organization, overlay hygiene, stale files, disabled tests, and testing verification. Triggers include comp.toml, component config, review component, component hygiene, spec source, upstream-distro, build defines, release calculation, includes.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 5.4k
- Forks
- 714
01 前言 Front Matter
- name
- azldev-comp-toml
- description
- Read this before authoring, editing, or reviewing a *.comp.toml file; do not work from memory. Explains the azldev component definition format and review workflow, covering component structure, spec sources, build config, release calculation, render options, file organization, overlay hygiene, stale files, disabled tests, and testing verification. Triggers include comp.toml, component config, review component, component hygiene, spec source, upstream-distro, build defines, release calculation, includes.
03 SKILL.md 正文
Component definition files (*.comp.toml)
A component definition tells azldev where a package's spec comes from and how to
customize it for your distro. Every component lives under [components.<name>].
Get the authoritative, always-current field list from the schema:
azldev config generate-schema
Structure
A bare entry inherits everything from your distro's defaults — most upstream packages need nothing more:
[components.curl]
Add sub-tables only for what you change. The fields you will reach for most:
| Field | Purpose |
|---|---|
spec |
where the spec comes from (see below) |
overlays / overlay-files |
targeted spec/source edits (see the azldev-overlays skill) |
build.defines / build.with / build.without |
RPM macro and bcond build tweaks |
release.calculation |
how the Release tag is managed |
render.skip-file-filter |
rendering edge-case escape hatch |
Spec source
The spec field selects where the spec is fetched from. When omitted, the component
inherits the distro default (normally an upstream import).
# Upstream import (the usual case) — inherits the distro's upstream version
[components.curl]
# Upstream, but pinned to a specific upstream distro/version
[components.curl]
spec = { type = "upstream", upstream-distro = { name = "fedora", version = "rawhide" } }
# Upstream package whose name differs from the component name
[components.mydistro-rpm-config]
spec = { type = "upstream", upstream-name = "redhat-rpm-config" }
# Local spec that lives in your repo (not imported from an upstream distro)
[components.mydistro-release]
spec = { type = "local", path = "mydistro-release.spec" }
Build configuration
[components.mypackage.build]
defines = { rhel = "11" } # override RPM macros
with = ["feature_x"] # enable %bcond_with conditionals
without = ["plugin_rhsm"] # disable %bcond_with conditionals
Release calculation
release.calculation controls the Release: tag. There are four modes:
auto(default) — leave%autoreleaseunchanged; otherwise bump a static integer Release once for each fingerprint-derived synthetic change.autorelease— force%autoreleasehandling (use when auto-detection misreads a spec that wraps%autoreleasein a conditional).static— require a non-%autoreleasestatic release. The default legacy calculation supports only an integer,integer%{?dist}, orinteger%{dist}; other forms requiremanualor an overlay.manual— you own theRelease:value. Use this only when render fails with a "non-standard Release tag" error. Amanualcomponent is not bumped by the render/commit/amend cycle, so increment its release yourself in the same change (see theazldev-update-componentskill).
[components.mypackage.release]
calculation = "manual"
The temporary --rpmdev-bumpspec flag on comp build, comp render, and
comp prepare-sources opts into transactional host handling while Azure Linux
migrates. Only that path requires rpmdev-bumpspec, rpmdev-packager, rpm,
rpmspec, and Python with its RPM module. It preserves the fixed team
identity/comment/datestamp and strict source-EVR transaction checks; locks and
synthetic history still determine the number and order of bumps. Without the
flag, no bumpspec runtime discovery occurs and the legacy static calculation is
used. %autorelease behavior is unchanged on either path.
Render configuration
render.skip-file-filter = true keeps all source and patch files during render.
azldev normally prunes files not referenced by the rendered spec; set this only for
the rare spec whose Source/Patch filenames use macros the filter cannot expand.
File organization
- Inline — put simple, customization-free components directly in a shared config
file (e.g.
[components.jq]). - Dedicated — give a component its own
<name>/<name>.comp.tomlonce it needs overlays, build config, or a local spec. Rule of thumb: anything more than[components.<name>]earns a dedicated file. - A parent config picks up dedicated files through an
includesglob, for exampleincludes = ["**/*.comp.toml"].
Review checklist
Start with azldev comp list -p <name> -q -O json, then use
azldev comp query -p <name> -q -O json when the review needs parsed spec details.
For a change review, focus on the diff while checking enough surrounding context to
ensure it fits the component and repository conventions.
- Organization: The component follows the repository's inline-versus-dedicated-file
convention; its name matches upstream or sets
spec.upstream-name; no stale or orphaned component files remain. - Spec source: The default upstream source is preferred. Pins explain why they are needed, and local specs are used only when overlays cannot express the change.
- Overlays: Every overlay explains why it exists. Prefer structured overlay types
over regex; scope unavoidable
spec-search-replaceexpressions by section and, when applicable, package, and use TOML literal strings.spec-search-replacecannot span lines. Remove overlays that upstream has made unnecessary. See theazldev-overlaysskill. - Build config: Defines and bcond overrides are necessary and correspond to the
spec. If
build.check.skip = true, require a specificbuild.check.skip_reasonand verify that fixing the tests is impractical; skipped%checkis a last resort. - Release mode:
autois the default. Forceautoreleaseorstaticonly when auto-detection is wrong. Usemanualonly for a non-standard release tag, and verify the component increments its release itself. - Generated state: The lock matches the final component inputs, and rendered output contains the intended changes without unrelated drift.
- Testing: Changes that can affect RPM output were built and smoke-tested in a mock chroot. Organization, comment, or documentation-only metadata edits do not require a rebuild when the resolved component inputs are unchanged.
Report findings by severity: errors for correctness or required-policy violations, warnings for maintainability risks, and info for optional improvements. Prefer small, actionable fixes over unrelated cleanup.
Documenting changes
Add a TOML comment explaining why a non-obvious field is set (a version pin, a
workaround), and link the upstream commit or bug when the change is based on one. For
overlays, use the overlay metadata table instead (see the azldev-overlays skill).
Generated by azldev docs agent; do not hand-edit.
04 同仓库更多 Skills
skill-metrics
[Skill] metrics, azure-monitor, aks - Query Azure Monitor metrics for Koji AKS node CPU, memory, disk usage, and pod readiness.
skill-mass-triage
[Skill] Batch-triage build failures from a JSON results file — diagnose with parallel sub-agents, bucketize by root cause, and produce a consolidated summary. Use when asked to triage a Koji results file. Triggers: batch triage, mass triage, triage results file, bucketize failures.
skill-kql-queries
[Skill] kql, queries, log analytics, container logs - KQL query templates for Koji container logs, pod errors, restarts, Kubernetes events, build job activity, and node resource usage via Log Analytics.
skill-koji-triage
[Skill] Examine Koji builds, fetch task info and logs from the Koji Web UI, identify failures, and provide root cause analysis. Use when triaging Koji build failures, investigating failed tasks, downloading build logs, or searching for broken packages. Triggers: koji failure, koji build failed, koji task, koji log, koji triage, build failure analysis.
skill-fedora-mirror-injections
[Skill] Diagnose Azure Linux Stage 1 (bootstrap-mirror) BuildRequires resolution failures and backfill missing RPMs into the prod Fedora updates mirror via the azl-infra injections file. Use when triaging stage-1 / azl4-bootstrap-mirror build failures, finding dependency gaps in the Fedora mirror, deciding whether a failure is a real mirror gap vs a transient timeout or a spec bug, adding entries to azl4-stage1-injections.yaml, or opening a PR with mirror injections. Triggers: bootstrap-mirror, stage 1 build failure, fedora mirror gap, missing BuildRequires, nothing provides crate, no match for argument, injections file, azl4-stage1-injections, mirror injection.
skill-deployment-context
[Skill] deployment context, aks, azure, koji - Resolve Koji AKS deployment context -- resource group, cluster name, subscription, Log Analytics workspace, and monitoring resource names from deployment_summary.yaml when available, or discover them dynamically from Azure.