azldev-overlays
Read this before adding, changing, or diagnosing any overlay; never edit a spec or rendered file from memory. Explains how to modify a component's RPM spec or loose source files with azldev overlays (semantic patches applied at render time) instead of forking the spec, covering overlay types, the render-and-inspect loop, common failures, pitfalls, and metadata. Triggers include overlay, overlay failed, no match, spec-add-tag, spec-remove-tag, patch-add, fix spec, backport, disable test, prune subpackage, edit spec.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 5.4k
- Forks
- 714
01 前言 Front Matter
- name
- azldev-overlays
- description
- Read this before adding, changing, or diagnosing any overlay; never edit a spec or rendered file from memory. Explains how to modify a component's RPM spec or loose source files with azldev overlays (semantic patches applied at render time) instead of forking the spec, covering overlay types, the render-and-inspect loop, common failures, pitfalls, and metadata. Triggers include overlay, overlay failed, no match, spec-add-tag, spec-remove-tag, patch-add, fix spec, backport, disable test, prune subpackage, edit spec.
03 SKILL.md 正文
Working with overlays
Overlays are semantic patches applied to a component's RPM spec and loose source files at render time. They let you make targeted changes to an upstream spec without forking it. Prefer an overlay over hand-editing a rendered spec: overlays are re-applied on every render, so a manual edit to a rendered spec is overwritten.
The inner loop
Overlays live in the component's TOML config — inline [[components.<name>.overlays]]
entries, or per-file overlay documents referenced by the component's overlay-files
glob. They apply in order and are non-atomic: if one fails part-way, the
overlays before it stay applied.
-
Add or edit the overlay in the component config.
-
Re-render and inspect the result:
azldev comp render -p <name>Read the rendered spec (under
specs/) to confirm the change landed where you intended, and iterate until it is correct. -
Finalize the lock and changelog with the normal end-of-work refresh (see the
azldev-update-componentskill): update the lock, commit, then re-render and amend.
Config errors reference the offending overlay by its description, so give every
overlay a short, specific description.
Diagnose common failures
Start with azldev comp diff-sources -p <name> to see the exact overlay effect.
Use separate pre/post prep-sources directories only when you need persistent trees
for deeper inspection.
| Symptom | Likely cause and fix |
|---|---|
spec-add-tag: tag already exists |
Upstream already has the tag. Use spec-set-tag, or spec-update-tag when its prior existence is an invariant. |
spec-search-replace: no match |
Inspect the current upstream line, check TOML regex quoting, and narrow the expression to the actual section/package. |
| Section or file not found | Inspect the upstream spec/source names; upstream may have renamed or removed the target. |
| Overlay applies but output/build is wrong | Inspect diff-sources for an over-broad match, malformed replacement, or a dependency/file change the overlay omitted. |
Choosing an overlay type
Match the change to the narrowest overlay type. Required fields are enforced when the config loads, so a missing field fails fast rather than at apply time.
Spec overlays (structured .spec edits)
| Type | Use for | Required |
|---|---|---|
spec-add-tag |
add a tag; fails if it already exists | tag, value |
spec-insert-tag |
add a tag next to its family (e.g. after the last Source*) |
tag, value |
spec-set-tag |
set a tag, replacing it if present or adding it if not | tag, value |
spec-update-tag |
change an existing tag; fails if it is missing | tag, value |
spec-remove-tag |
delete tag instances; without value, deletes every instance |
tag |
spec-prepend-lines |
insert lines at the top of a section (or the whole file) | lines |
spec-append-lines |
insert lines at the end of a section (or the whole file) | lines |
spec-search-replace |
regex replace within a section (or the whole spec) | regex |
spec-remove-section |
delete a whole section | section |
spec-remove-subpackage |
delete every section of a sub-package | package |
patch-add |
add a .patch file and register it in the spec |
source |
patch-remove |
remove a patch and its spec references | file |
File overlays (loose non-spec files; never .spec)
| Type | Use for | Required |
|---|---|---|
file-prepend-lines |
prepend lines to a file | file, lines |
file-search-replace |
regex replace in a file | file, regex |
file-add |
copy in a new file; fails if it already exists | file, source |
file-remove |
delete a file | file |
file-rename |
rename a file in place | file, replacement |
Rules that trip people up
-
spec-remove-tagwithoutvalueremoves every instance of the named tag. To remove one dependency, set bothtagand the exactvalueto match:[[components.mypackage.overlays]] description = "Remove an unavailable build dependency" type = "spec-remove-tag" tag = "BuildRequires" value = "unwanted-package" -
sectionis optional only forspec-prepend-lines,spec-append-lines, andspec-search-replace(omit it to target the whole spec). It is required forspec-remove-section. -
packageneedssectionon the whole-file-capable overlays — a sub-package is a sub-qualifier of a section.spec-remove-subpackageis the exception: it takespackageand rejectssection. -
replacementis literal —$1-style capture-group references are not expanded; omit it to delete matched text. -
Quote
regexas a TOML literal string — writeregex = '\.so$', notregex = "\.so$". A basic (double-quoted) TOML string interprets backslash escapes, so\s,\.,\dand friends are mangled before the regex engine ever sees them; single quotes keep the pattern verbatim. -
Anchor regex overlays to whole lines, and prefer macro toggles. When
spec-search-replaceis unavoidable, anchor the full line (for example,regex = '^%setup -q$') instead of matching a fragment, and combine several near-identical patterns into one rather than stacking brittle overlays. If the upstream spec already exposes a conditional such as%if 0%{?rhel}/%if 0%{?fedora}or a definable macro, set that macro instead of rewriting the line with regex; the explicit toggle survives upstream changes more reliably. -
spec-search-replacematches one line at a time — the pattern is applied to each spec line independently, so it can never span a newline and(?s)/DOTALL does nothing. For a multi-line change use a structured spec overlay (spec-remove-section,spec-prepend-lines/spec-append-lines, etc.).file-search-replaceis different: it matches against the whole file, so multi-line patterns (and(?s)) work there. -
fileis a glob (**supported) for the multi-file file overlays; forfile-addandfile-renameit is a single name, andfile-rename'sreplacementis a filename only (not a path). -
sourcepaths are relative to the config that declares the overlay — the overlay file when loaded viaoverlay-files, otherwise the component config. -
file-addlands beside the spec, in the dist-git sources root — not inside the extracted upstream tree. Adding a file there does not make the build use it; wire it in with aSourceNtag plus%prep/%installsteps, or usepatch-addto change tracked sources. -
Don't rename the
Name:tag withspec-update-tag/spec-set-tag.%{name}feedsSource*URLs,%setup -n, and%filespaths, so renaming it silently breaks those references. Keep the specNamealigned with the component instead. -
To add a real
.patchfile (rather than an inline edit), usepatch-add; it copies thesourceinto the component sources and registers aPatchNtag or%patchlistentry.
Document intent with metadata
Give non-trivial overlays a metadata table. It is documentation only — excluded from
the component fingerprint, so editing it never invalidates the build cache — but it
records why the overlay exists and when it can be dropped. Every metadata block
requires category; pick the narrowest of:
upstream-backport, azl-pruning, azl-compatibility, azl-temp-workaround,
azl-branding-policy, azl-disable-flaky-tests, azl-disable-unsupported-tests,
azl-security-compliance, azl-release-management, azl-platform-adaptation.
It also requires upstream-status: upstreamed, upstreamable,
needs-upstream-hook, inapplicable, or unknown. Add commits and bugs as
{ url = "https://..." } entries where they apply. commits is required for
upstream-backport, whose status must be upstreamed or upstreamable. When several
overlays share one provenance, put them in a per-file overlay document (overlay-files)
with a single file-level [metadata].
For how to choose the right category and upstream-status, disambiguation tips, and
the TOML forms, read the azldev-overlay-metadata skill.
Full reference
The tables above are the working subset. For the exhaustive field rules, metadata
constraints, and the per-file overlay format, generate the machine-readable schema
with azldev config generate-schema (see the ComponentOverlay definition), or read
azldev's overlays configuration reference.
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.