edit-spec-file

Fähigkeit: Spec-Datei bearbeiten

Zweck

Änderungen an Bottlerocket RPM-Spezifikationsdateien vornehmen, während die strengen Stilkonventionen des Projekts strikt eingehalten werden. Diese Fähigkeit gewährleistet konsistente, wartbare Spezifikationsdateien in allen Kit-Paketen.

Wann zu verwenden

• Hinzufügen neuer Quelldateien, Patches oder Vorlagen zu einem Paket
• Hinzufügen von systemd-Diensten oder Konfigurationsdateien
• Erstellen neuer Unterpakete (einschließlich FIPS-Varianten)
• Ändern von Build- oder Installationsabschnitten
• Jede Änderung an einer .spec-Datei in kits/*/packages/

Voraussetzungen

• Lesen Sie ./STYLE-GUIDE.md vollständig, bevor Sie Änderungen vornehmen
• Identifizieren Sie ein vorhandenes ähnliches Paket als Referenzmuster

Verfahren

1. Lesen Sie das Style-Guide

VERPFLICHTEND: Lesen Sie ./STYLE-GUIDE.md, bevor Sie Änderungen vornehmen.

Das Style-Guide enthält:

• [MUSS] Regeln, die zwingend erforderlich sind
• [DARF NICHT] Regeln, die verboten sind
• [SOLLTE] Regeln, die dringend empfohlen werden

2. Finden Sie ein Referenzpaket

Identifizieren Sie ein oder mehrere ähnliche vorhandene Pakete, die als Vorlage dienen:

# Für Go-Pakete
ls kits/bottlerocket-core-kit/packages/*/nvidia-k8s-device-plugin.spec

# Für C-Pakete mit systemd-Diensten
ls kits/bottlerocket-core-kit/packages/chrony/chrony.spec

# Für Pakete mit FIPS-Varianten
ls kits/bottlerocket-core-kit/packages/amazon-ssm-agent/amazon-ssm-agent.spec

3. Anwenden von Änderungen in der angegebenen Abschnittsreihenfolge

Spec-Dateien haben eine strenge Abschnittsreihenfolge:

1. %global-Definitionen
2. Paketmetadaten (Name, Version, Release, Summary, License, URL)
3. Quelldateien (nummeriert nach Bereich: <100 Sonstiges, 1xx systemd, 2xx tmpfiles, 3xx udev, 4xx Lizenzen)
4. Patches (nummeriert ab 1000+)
5. BuildRequires / Requires
6. %description
7. Unterpaketdefinitionen (%package, %description)
8. %prep
9. %build
10. %install
11. %files-Abschnitte

4. Quellen-Nummerierung

Befolgen Sie bei Bedarf die festgelegten Bereiche. Verwenden Sie die obigen Beispiele zur Orientierung:

• Source0-Source99: Hauptquellen und verschiedene Dateien
• Source100-Source199: Systemd-Unit-Dateien
• Source200-Source299: Tmpfiles-Konfigurationen
• Source300-Source399: Udev-Regeln
• Source400-Source499: Lizenzdateien

KRITISCH: Lassen Sie beim Entfernen von Quellen Lücken – nummerieren Sie vorhandene Quellen NICHT neu, es sei denn, sie befinden sich im gleichen Hunderter-Bereich.

5. Installieren von Dateien in Quellen-Reihenfolge

Dateien in %install müssen in derselben Reihenfolge installiert werden wie ihre Source-Deklarationen:

# Quellen deklariert als:
Source1: nvidia-k8s-device-plugin.service
Source2: nvidia-k8s-device-plugin-conf
Source3: nvidia-k8s-device-plugin-exec-start-conf

# Installieren in derselben Reihenfolge:
install -p -m 0644 %{S:1} %{buildroot}%{_cross_unitdir}
install -D -m 0644 %{S:2} %{buildroot}%{_cross_templatedir}/nvidia-k8s-device-plugin-conf
install -D -m 0644 %{S:3} %{buildroot}%{_cross_templatedir}/nvidia-k8s-device-plugin-exec-start-conf

6. Verwenden Sie korrekte Makros

Verwenden Sie immer Cross-Kompilierungsmakros:

• %{_cross_bindir} nicht /usr/bin
• %{_cross_unitdir} für systemd-Units
• %{_cross_templatedir} für Vorlagen
• %{_cross_factorydir}%{_cross_sysconfdir}/... für Factory-Standardeinstellungen
• %{_cross_fips_bindir} für FIPS-Binärdateien

7. FIPS-Unterpaket-Muster

Beim Hinzufügen von Binärdateien, die FIPS-Varianten benötigen:

%package bin
Summary: Paket-Binärdateien
Provides: %{name}(binaries)
Requires: (%{_cross_os}image-feature(no-fips) and %{name})
Conflicts: (%{_cross_os}image-feature(fips) or %{name}-fips-bin)

%description bin
%{summary}.

%package fips-bin
Summary: Paket-Binärdateien, FIPS-Edition
Provides: %{name}(binaries)
Requires: (%{_cross_os}image-feature(fips) and %{name})
Conflicts: (%{_cross_os}image-feature(no-fips) or %{name}-bin)

%description fips-bin
%{summary}.

8. Dateiberechtigungen

Verwenden Sie konsistente Berechtigungen:

• 0755 für ausführbare Dateien
• 0644 für Konfigurationsdateien, Vorlagen, Dienstdateien
• Verwenden Sie install -p, um Zeitstempel zu erhalten
• Verwenden Sie install -D, wenn übergeordnete Verzeichnisse erstellt werden müssen

Validierungs-Checkliste

Übergeben Sie vor dem Commit einen Sub-Agenten zur unabhängigen Überprüfung. Verweisen Sie dabei auf dieses Dokument und die 'Validierungs-Checkliste':

• Quelldateien in korrekten Bereichen nummeriert
• Installationsreihenfolge entspricht der Source-Deklarationsreihenfolge
• Alle Pfade verwenden %{_cross_*}-Makros
• Keine Dateien nach /etc oder /var installiert (Factory-Standards-Muster verwenden)
• %{_cross_attribution_file} im Haupt-%files-Abschnitt
• %license-Direktive für Lizenzdateien
• %dir-Direktive für Verzeichnisse, die dem Paket gehören
• Keine Debugging-Befehle (ls -la, etc.)
• Keine unnötigen Kommentare
• Einheitliche Formatierung (keine abschließenden Leerzeichen, konsistente Einrückung)
• Release: 1%{?dist}-Format (kein Punkt vor %)

Änderungen committen

Verwenden Sie beim Committen von Spec-Datei-Änderungen -F mit einer Datei, um Zeilenumbrüche in Commit-Nachrichten zu erhalten:

# Nachricht in Datei schreiben, dann mit -F committen
msg = """paket-name: Zusammenfassung der Änderung

Detaillierte Beschreibung, was geändert wurde und warum.

Signed-off-by: Name <email>"""
write("create", "/tmp/commit-msg.txt", file_text=msg)
bash("git -c commit.gpgsign=false commit -F /tmp/commit-msg.txt")

NICHT git commit -m mit repr() oder maskierten Strings verwenden – dies schreibt literal \n anstelle von Zeilenumbrüchen.

Häufige Anti-Patterns

NICHT:

• Release: 1.%{?dist} verwenden (falsch: enthält Punkt)
• ./-Präfix in Dateipfaden verwenden
• Kommentare hinzufügen, die offensichtliche Operationen wiederholen
• %exclude als Ersatz für eine korrekte Build-Konfiguration verwenden
• Quellen beim Entfernen neu nummerieren
• Dateien außerhalb der Quellen-Reihenfolge installieren
• Hartcodierte Pfade anstelle von Makros verwenden
• Paketübergreifende symbolische Links erstellen

Kurzreferenz

Hinzufügen eines systemd-Dienstes

1. Quelle im 100er-Bereich hinzufügen: Source101: myservice.service
2. In unitdir installieren: install -p -m 0644 %{S:101} %{buildroot}%{_cross_unitdir}
3. Zu %files hinzufügen: %{_cross_unitdir}/myservice.service

Hinzufügen einer Vorlage

1. Quelle hinzufügen: Source5: mytemplate-conf
2. Installieren: install -D -m 0644 %{S:5} %{buildroot}%{_cross_templatedir}/mytemplate-conf
3. Zu %files hinzufügen: %{_cross_templatedir}/mytemplate-conf

Hinzufügen eines Drop-in-Verzeichnisses

1. Verzeichnis erstellen: install -d %{buildroot}%{_cross_unitdir}/myservice.service.d
2. Zu %files hinzufügen: %dir %{_cross_unitdir}/myservice.service.d