Paketbaurichtlinien für Rust

Ähnlich wie bei anderen Sprachökosystemen in Fedora gibt es einen standardisierten Satz von Compiler-Flags, die unbedingt an den Rust-Compiler übergeben werden MÜSSEN.

Die Standardeinstellungen für Rust sind im Makro %build_rustflags des Pakets rust-srpm-macros definiert. Es ist Teil des Standard-Buildroots unter Fedora 39 und neuer, wo das Makro %set_build_flags die Umgebungsvariable $RUSTFLAGS automatisch anhand dieses Makros setzt.

Für die Kompatibilität zu älteren Versionen oder EPEL kann diese Umgebungsvariable manuell am Anfang von %build und %check in den Spec-Dateien des Pakets gesetzt werden:

Dies ist nicht notwendig für Pakete, die die Makros %cargo_prep, %cargo_build und %cargo_test verwenden, welche cargo so konfigurieren, dass die Standard-%build_rustflags direkt verwendet werden.

Die RPM-Makros, die grundlegende Funktionen zum Bauen aus Rust-Code bereitstellen, sind in rust-rpm-macros enthalten, das Teil des Standard-Buildroots in Fedora ist, da es eine Abhängigkeit von redhat-rpm-config darstellt. Beim Kompilieren für ELN oder EPEL8 ist dies nicht der Fall; hier müssen Pakete BuildRequires: rust-toolset verwenden.

Pakete, die Rust-Code mit Cargo erstellen – direkt oder indirekt – oder die eines der %cargo_*-Makros aufrufen, MÜSSEN BuildRequires: cargo-rpm-macros hinzufügen. Dieses Paket stellt die Implementierungen aller %cargo_*-Makros bereit. Es ist nicht Teil des Standard-Buildroots, da es zusätzliche Abhängigkeiten (z.B. einen Python-Interpreter) benötigt.

Da semantische Versionierung („SemVer“) das einzige unterstützte Versionierungsschema für Rust-Crates ist, werden Abhängigkeiten von Rust-Bibliotheken fast ausschließlich als „diese Version oder eine neuere Version, die dazu API-kompatibel ist“ angegeben, d.h. als ein Bereich unterstützter Versionen.

Diese unterstützten Versionsbereiche müssen korrekt in RPM-Abhängigkeiten übersetzt werden, da sonst möglicherweise eine falsche Version einer Abhängigkeit für die Bauvorgänge verwendet wird, was zu nicht hilfreichen Fehlermeldungen über fehlende Abhängigkeiten führt.

Da sich die Abhängigkeiten von Rust-Projekten häufig ändern, MÜSSEN Pakete für Projekte, die Rust-Code mit Cargo erstellen, dynamisch generierte BuildRequires verwenden, indem sie das Makro %cargo_generate_buildrequires im Scriptlet %generate_buildrequires aufrufen.

Eine Abhängigkeit von serde = "1.0.100", die in den Cargo.toml-Metadaten eines Projekts angegeben ist (eine Abhängigkeit von der Crate mit dem Namen "serde" in der Version "1.0.100" oder einer beliebigen API-kompatiblen Version mit "1.0.100" und aktivierten Standardfunktionen), würde beispielsweise dazu führen, dass für RPM eine Abhängigkeit wie diese generiert wird:

Informationen zum Übergeben von Feature-Flags an dieses Makro finden Sie im Abschnitt RPM-Makros.

Ähnlich wie bei anderen Sprachen, die statisch verknüpfte Binärdateien erzeugen, enthalten Rust-Executables (und Shared Libraries) Code, der aus anderen Paketen (d.h. Paketen für andere Rust-Crates) stammt, die wiederum anderen Lizenzbedingungen unterliegen.

Dies muss berücksichtigt werden, indem für das Teilpaket, das diese Binärdateien enthält, ein separates License-Tag gepflegt wird. Weitere Informationen zu License-Tags finden Sie in der Fedora Legal-Dokumentation.

Das Paket cargo-rpm-macros stellt zwei RPM-Makros bereit, die dabei helfen, das License-Tag für Projekte, die mit cargo erstellt wurden, korrekt auszufüllen:

Dieses Makro ermittelt alle Lizenzen der Rust-Crates und gibt eine Zusammenfassung aus, die statisch in die finalen Binärdateien eingebunden werden (wobei Bau- oder Testabhängigkeiten korrekt ausgeschlossen werden). Diese Zusammenfassung kann anschließend als Kommentar aus dem Bauprotokoll in die Spec-Datei kopiert werden. Der tatsächliche Inhalt des License-Tags lässt sich dann durch Verknüpfung dieser einzelnen Lizenzen (mithilfe des SPDX-AND-Operators) ermitteln.

Dieses Makro ermittelt und gibt eine vollständige Aufschlüsselung aller Rust-Crates aus, die statisch in die finalen Binärdateien eingebunden werden (nach der gleichen Logik wie im Makro %cargo_license_summary), sowie deren Versionen und Lizenzausdrücke. Die dynamische Generierung dieser Liste zur Bauzeit stellt sicher, dass ihr Inhalt stets den tatsächlichen Abhängigkeiten entspricht.

Beide Makros akzeptieren die gleichen Argumente wie andere %cargo_*-Makros (-a, -n, -f), und damit ihre Ausgabe mit den tatsächlichen Binärdateien übereinstimmt, MÜSSEN die gleichen Flags an sie und %cargo_build übergeben werden.

Im Allgemeinen SOLLTEN Pakete nach Möglichkeit KEINE gebündelten Crate-Abhängigkeiten verwenden.

Wenn Vendored- oder gebündelte Abhängigkeiten von Crates verwendet werden (unabhängig vom verwendeten Mechanismus), müssen alle gebündelten Crate-Abhängigkeiten mit virtuellen Provides im Format Provides: bundled(crate($crate)) = $version im Teilpaket, das die Rust-Komponente enthält, deklariert werden. Diese virtuellen Provides werden beispielsweise verwendet, um die Auswirkungen von Sicherheitslücken auf Pakete zu ermitteln, die Vendored-Rust-Abhängigkeiten verwenden.

Es gibt außerdem zwei Situationen, in denen das Bündeln von zumindest einigen Rust-Crates in der Regel unvermeidbar ist:

Die empfohlene Methode zum Schreiben von Spec-Dateien für Rust-Crates ist die Verwendung von rust2rpm und die Anwendung aller notwendigen Änderungen auf die generierte Spec-Datei.

Es gibt einige häufige Situationen, in denen automatisch generierte Spec-Dateien manuell angepasst werden müssen:

Crates, die Rust-Bindings für C-Bibliotheken bereitstellen, erfordern in der Regel einige zusätzliche Änderungen (sofern möglich):

Beachten Sie, dass das Patchen von Cargo.toml-Dateien (insbesondere das Ändern der optionalen Abhängigkeiten und Funktionen) unbedingt mit dem Befehl rust2rpm -p erfolgen MUSS, da solche Änderungen die Generierung der Spec-Datei (d.h. die Liste der generierten Teilpakete) beeinflussen. Das würde aber nur dann korrekt berücksichtigt werden, wenn der Patch vor der Generierung der Spec-Datei erstellt wird.

Es wird empfohlen, nicht-leere rust2rpm.toml-Konfigurationsdateien im Paket-Repository zusammen mit der generierten .spec-Datei zu verwalten.

Pakete für Rust-Crates von crates.io MÜSSEN rust-$crate als Namen des Quellpakets verwenden (wobei $crate der Name des Projekts auf crates.io ist).

Dadurch wird sichergestellt, dass es keine Namenskonflikte zwischen Rust-Crates gibt, die auf crates.io veröffentlicht werden, und Rust-Crates, die für Fedora paketiert wurden.

Beim Generieren eines Pakets für eine Rust-Crate mit ausführbaren Zielen wird gemäß der Konvention von rust2rpm ein Teilpaket mit dem Namen der Crate erstellt (d.h. das Quellpaket rust-$crate enthält ein Teilpaket $crate). Dieses Teilpaket kann bei Bedarf umbenannt werden, beispielsweise wenn der Name nicht den Erwartungen entspricht oder mit einem bereits existierenden Paket in Konflikt gerät.

Projekte, die mit Cargo erstellt und/oder auf crates.io veröffentlicht werden, verwenden semantische Versionierung (mit kleinen Cargo-spezifischen Anpassungen). Da SemVer-Strings Zeichen enthalten können, die in RPM-Versionszeichenketten unzulässig sind, MÜSSEN sie in RPM-kompatible Zeichen übersetzt werden.

Beispielsweise werden Vorabversionen in SemVer durch das Suffix -<pre> gekennzeichnet, das Zeichen - ist jedoch in RPM-Versionen unzulässig. Dieses Problem lässt sich beheben, indem man - durch das Zeichen ~ ersetzt, welches in RPM-Versionszeichenketten Vorabversionen kennzeichnet. Diese Übersetzung erfolgt automatisch für das Version-Tag beim Generieren einer Spec-Datei mit rust2rpm. Die „Upstream“-Version wird in einem separaten Makro gespeichert, mit dem auf die „ursprüngliche“ Versionszeichenkette verwiesen werden kann.

Zusätzlich enthalten manche Rust-Crates in ihren Versionsnummern weitere „Build“-Metadaten (ein Suffix <build>`). Dieses Format dient hauptsächlich dazu, Informationen über die Version einer mitgelieferten C-Bibliothek zu übermitteln. Das Suffix `<build> MUSS per Patch aus den Crate-Metadaten entfernt werden, da es die Auflösung von RPM-Abhängigkeiten bzw. -Versionen beeinträchtigen kann. Dies geschieht automatisch bei Verwendung von rust2rpm Version 25 oder neuer.

Die offizielle Quelle für Rust-Crates ist crates.io. Projekte von crates.io MÜSSEN aus den dort veröffentlichten Quellen paketiert werden (d.h. mithilfe des Makros %{crates_source}).

Falls die auf crates.io veröffentlichten Quellen nicht alle für die Paketerstellung notwendigen Dateien enthalten (z.B. die fehlende .desktop-Datei oder fehlende Handbuchseiten), können die Upstream-Quellen als zusätzliche Quelle verwendet werden. Sie DÜRFEN jedoch NICHT zum Erstellen des Crates selbst verwendet werden. Es wird empfohlen, beim Upstream-Projekt ein Problem zu melden, um die Aufnahme dieser zusätzlichen Dateien in die veröffentlichten Crates zu beantragen.

Alternativ kann, falls das betreffende Projekt keine Rust-Bibliotheksschnittstelle bereitstellt, es als Nicht-Crate-Rust-Projekt unter Verwendung der Upstream-Quellen paketiert werden.

Die meisten Werkzeuge zur Lizenzbestimmung benötigen exakte Metadaten über Lizenzen in den Crate-Metadaten, einschließlich der %cargo_license*-Makros, sowie Werkzeuge von Drittanbietern wie cargo-license und cargo-deny.

Aus diesem Grund MÜSSEN die Lizenzmetadaten aller für Fedora paketierten Rust-Crates mit dem Lizenz-Tag des Fedora-Pakets selbst übereinstimmen. Alle Crates, die package.license-file in ihren Metadaten verwenden (was für nicht standardmäßige/nicht SPDX-Lizenzen reserviert ist), MÜSSEN so angepasst werden, dass sie package.license in ihren Metadaten verwenden und stattdessen einen korrekten SPDX-Ausdruck angeben. Solche Patches SOLLTEN an die Upstream-Entwickler übermittelt werden.

Optionale Funktionsmerkmale und Abhängigkeiten von Rust-Crates werden in RPM-Teilpakete ausgelagert, um die Auflösung von Abhängigkeiten für Funktionsmerkmale und optionale Abhängigkeiten von Crates zu unterstützen. Die Liste der Crate-Funktionsmerkmale (einschließlich aller implizit definierten Funktionsmerkmale für optionale Abhängigkeiten) MUSS mit der Liste der Teilpakete synchronisiert sein. Das heißt, für jedes Funktionsmerkmal $foo der Crate $crate muss es ein Teilpaket mit dem Namen rust-$crate+$foo-devel geben und umgekehrt. Dies ist erforderlich, damit die RPM-Generatoren für Provides und Requires diese optionalen Funktionsmerkmale und Abhängigkeiten korrekt bereitstellen können.

Wenn optionale Funktionsmerkmale, die nicht zum Standardfunktionsumfang gehören, nicht verwendet werden und zusätzliche (möglicherweise nicht verfügbare) Abhängigkeiten nach sich ziehen würden, KANN das Paket Teilpakete für diese spezifischen Funktionsmerkmalnamen weglassen. Es muss jedoch sichergestellt werden, dass die Funktionsmerkmale, die den weggelassenen Teilpaketen entsprechen, nicht über Teilpakete „erreichbar“ sind, die nicht weggelassen wurden, da dies zu Paketen mit nicht erfüllbaren Abhängigkeiten führen würde. Das Deaktivieren optionaler Funktionsmerkmale kann manchmal nicht einfach durch Weglassen von Teilpaketen für bestimmte Funktionsmerkmale korrekt erfolgen. In diesen Fällen müssen die Crate-Metadaten in Cargo.toml entsprechend angepasst werden.

Beachten Sie, dass das „default“-Funktionsmerkmal immer implizit von Cargo definiert wird, selbst wenn die Metadaten der Crate keine [features]-Tabelle oder ein explizit definiertes „default“-Funktionsmerkmal enthalten. Daher ist das Teilpaket für das „default“-Funktionsmerkmal in allen Paketen für Rust-Crates mit einer Bibliotheksschnittstelle vorhanden.

Das Paket cargo-rpm-macros enthält RPM-Generatoren zum automatischen Generieren von Provides und Requires für Rust-Crates, die den Paktebaurichtlinien entsprechen (d.h. ihre Dateien am richtigen Ort, %{crate_instdir}, installieren).

Es wird empfohlen, zu überprüfen, ob die generierten Provides und Requires sinnvoll sind – beispielsweise müssen die folgenden Provides und Requires vorhanden sein, um korrekte Abhängigkeiten zwischen den Teilpaketen sicherzustellen:

Darüber hinaus werden Abhängigkeiten von externen Rust-Crates wie folgt erwartet:

In den meisten Fällen SOLLTE die neueste Version einer Crate paketiert werden, und - wenn möglich - SOLLTEN Paketierer Crates so portieren, dass sie die neueste verfügbare Version ihrer Abhängigkeiten verwenden, und diese Patches an das Upstream-Projekt übermitteln, um Abweichungen zwischen dem Upstream-Projekt und dem Fedora-Paket zu begrenzen.

Es gibt jedoch zwei häufige Szenarien, in denen es oft notwendig ist, Pakete für mehrere Versionen einer Bibliotheks-Crate gleichzeitig bereitzustellen:

In diesen Fällen kann ein „Kompatibilitätspaket“ für die ältere Version (in der Regel die aktuelle Version) erstellt und das Paket ohne Suffix auf die neuere Version aktualisiert werden. rust2rpm unterstützt die automatische Erstellung von „Kompatibilitätspaketen“ mit Namen, die den Benennungsrichtlinien für diesen Fall entsprechen und zu den Einschränkungen der semantischen Versionierung kompatibel sind. Dies wird durch die Verwendung des Flags rust2rpm --compat ermöglicht.

Alle „Kompatibilitätspakete“ für Rust-Crates MÜSSEN den Richtlinien für Rust-Crates entsprechen, und bei ihrer Erstellung gelten zwei zusätzliche Regeln:

Das Verhalten einiger RPM-Makros hängt vom Vorhandensein und Wert des Makros _with_check ab, d.h. davon, ob in der Spec-Datei %bcond_without check oder %bcond_with check verwendet wird – insbesondere schließt das Makro %cargo_generate_buildrequires nur dev-dependencies (d.h. Abhängigkeiten, die nur zum Kompilieren und/oder Ausführen der Testsuite eines Projekts mit Cargo verwendet werden) ein, wenn die check-Bedingung aktiviert ist.

Darüber hinaus verwenden Pakete für Rust-Crates, die von rust2rpm generiert werden, den Wert dieses Makros, um zu bestimmen, ob das %check-Skript ausgeführt wird.

Pakete für Rust-Crates MÜSSEN diese Bedingung setzen, um unerwartetes Verhalten der %cargo_*-Makros zu vermeiden, indem sie Tests explizit entweder aktivieren oder deaktivieren.

Rust-Crates können drei verschiedene Arten von Tests in ihren Test-Suites enthalten:

Standardmäßig werden beim Ausführen von cargo test (d.h. durch Aufruf des Makros %cargo_test) alle drei Testarten ausgeführt. Sie können auch separat aufgerufen werden (beispielsweise weil Teile der Testsuite oder große Datendateien nicht in den veröffentlichten Quellen enthalten sind), indem Filterargumente an den zugrunde liegenden Befehl cargo test übergeben werden:

Dies kann mit zusätzlichen Flags kombiniert werden, um Tests mit bestimmten Namen (oder solche, die eine bestimmte Zeichenkette in ihrem Namen enthalten) zu überspringen, indem das Argument --skip an das Test-Framework übergeben wird (kann mehrfach angegeben werden):

Standardmäßig verwendet Cargo die Teilzeichenkettensuche, um --skip-Argumente und tatsächliche Namen von Tests abzugleichen. Diese Funktion kann mit dem Flag --exact deaktiviert werden.

Falls Tests übersprungen oder deaktiviert werden, SOLLTE das Paket Kommentare enthalten, die erklären, warum dies der Fall ist, und gegebenenfalls Links zu den entsprechenden Upstream-Fehlermeldungen enthalten.

Pakete für Nicht-Crate-Rust-Projekte MÜSSEN gemäß den allgemeinen Benennungsrichtlinien benannt werden, d.h. sie DÜRFEN KEIN rust- Präfix für den Quellpaketnamen verwenden.

Es gelten die allgemeinen Richtlinien für die Referenzierung von Quellen.

Das Makro %{crates_source} SOLLTE NICHT für Pakete wie dieses verwendet werden, selbst wenn es sich um eine Rust-Crate handelt, die auch auf crates.io veröffentlicht ist.

Alle -a- und -n-Flags oder -f-Argumente, die an %cargo_generate_buildrequires übergeben werden, werden während der Abhängigkeitsauflösung auf alle Workspace-Elemente angewendet.

Das Makro %cargo_install SOLLTE NICHT für Pakete wie dieses verwendet werden. Verwenden Sie stattdessen install oder cp, um die erstellten ausführbaren Dateien oder gemeinsam genutzten Bibliotheken bei Bedarf explizit aus target/rpm/* in das Buildroot-Verzeichnis zu kopieren.

Projekte mit Bausystemen, die intern Cargo aufrufen, um Rust-Komponenten zu erstellen, MÜSSEN die gleichen Richtlinien befolgen wie andere Projekte, die Rust-Code mit Cargo erstellen.

In Paketen MUSS sichergestellt sein, dass die Cargo-Aufrufe, die intern zum Bausystem des Projekts gehören, keine Flags oder Argumente übergeben, die zu den Standard-Compiler-Flags oder den Cargo-Optionen, die im Makro %cargo_build festgelegt oder mit %cargo_prep konfiguriert werden, inkompatibel sind.

Neuere Versionen von meson bieten nur eingeschränkte Unterstützung für das Erstellen von Crate-Abhängigkeiten ohne Cargo. Um die paketierten Crate-Abhängigkeiten zu verwenden, müssen die Crate-Quellen manuell mit der lokalen Registry überschrieben werden.

Überprüfen Sie, ob die Projektlizenzdatei(en) und die Datei LICENSE.dependencies wie erwartet in den erstellten Paketen enthalten sind (rpm -qL -p <Pfad zum RPM-Paket>), wenn Sie %pyproject_save_files -l verwenden.