Azldev Overlays

Rules that trip people up

• spec-remove-tag without value removes every instance of the named tag. To remove one dependency, set both tag and the exact value to match:

  [[components.mypackage.overlays]]
  description = "Remove an unavailable build dependency"
  type = "spec-remove-tag"
  tag = "BuildRequires"
  value = "unwanted-package"

• section is optional only for spec-prepend-lines, spec-append-lines, and spec-search-replace (omit it to target the whole spec). It is required for spec-remove-section.

• package needs section on the whole-file-capable overlays — a sub-package is a sub-qualifier of a section. spec-remove-subpackage is the exception: it takes package and rejects section.

• replacement is literal — $1-style capture-group references are not expanded; omit it to delete matched text.

• Quote regex as a TOML literal string — write regex = '\.so$', not regex = "\.so$". A basic (double-quoted) TOML string interprets backslash escapes, so \s, \., \d and 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-replace is 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-replace matches 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-replace is different: it matches against the whole file, so multi-line patterns (and (?s)) work there.

• file is a glob (** supported) for the multi-file file overlays; for file-add and file-rename it is a single name, and file-rename's replacement is a filename only (not a path).

• source paths are relative to the config that declares the overlay — the overlay file when loaded via overlay-files, otherwise the component config.

• file-add lands 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 a SourceN tag plus %prep/%install steps, or use patch-add to change tracked sources.

• Don't rename the Name: tag with spec-update-tag/spec-set-tag. %{name} feeds Source* URLs, %setup -n, and %files paths, so renaming it silently breaks those references. Keep the spec Name aligned with the component instead.

• To add a real .patch file (rather than an inline edit), use patch-add; it copies the source into the component sources and registers a PatchN tag or %patchlist entry.

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.