| |
@@ -1,5 +1,5 @@
|
| |
= Rust Packaging Guidelines
|
| |
- :last-reviewed: 2021-12-18
|
| |
+ :last-reviewed: 2022-08-23
|
| |
|
| |
== rust2rpm
|
| |
|
| |
@@ -7,7 +7,7 @@
|
| |
(packaged as `python3-rust2rpm` for Fedora)
|
| |
automates most of the steps that are necessary for creating `+.spec+` files for Rust crates.
|
| |
|
| |
- It is advisable to try `+rust2rpm $crate+` first,
|
| |
+ It is advisable to try `+rust2rpm -s $crate+` first,
|
| |
and to only modify its output for your needs,
|
| |
before attempting to write a `+.spec+` file by hand.
|
| |
Most of the time, `+rust2rpm+` output can be used almost without modifications.
|
| |
@@ -18,17 +18,13 @@
|
| |
are required, for example:
|
| |
|
| |
* trimming a generated `+Summary+` tag that is too long
|
| |
- * dropping non-linux platform-specific dependencies
|
| |
+ * dropping non-linux platform-specific dependencies (automated by rust2rpm v22+)
|
| |
* dropping features that are only supported by nightly builds of the Rust compiler
|
| |
* dropping unstable features that require manually overriding compiler flags
|
| |
* dropping *unused* optional features with missing dependencies
|
| |
+ (can be automated by using a `+rust2rpm.conf+` configuration file)
|
| |
|
| |
- == Package Naming
|
| |
-
|
| |
- === Library crates
|
| |
-
|
| |
- Source packages for Rust crates which contain a library with a public API
|
| |
- MUST be named `rust-$crate`.
|
| |
+ == Package Sources
|
| |
|
| |
Only library crates that are published on crates.io MAY be packaged for Fedora,
|
| |
since this enforces a certain standard of how crates are packaged and built,
|
| |
@@ -36,6 +32,24 @@
|
| |
and that there are no package name collisions
|
| |
due to the unique crate names in the crates.io namespace.
|
| |
|
| |
+ Crates that contain only an application but no library interface
|
| |
+ MAY be packaged even if they are not published on crates.io,
|
| |
+ because those packages are leaves
|
| |
+ and cannot be depended on by other Rust crates.
|
| |
+
|
| |
+ Complex projects with multiple components (i.e. bindings for other languages),
|
| |
+ which cannot be packaged from sources that are published on crates.io alone,
|
| |
+ MAY include subpackages for their Rust library interface
|
| |
+ (`+rust-$crate-devel+`, `+rust-$crate+feature-devel+`, etc.)
|
| |
+ ONLY if this crate is also published on crates.io under the same name.
|
| |
+
|
| |
+ == Package Naming
|
| |
+
|
| |
+ === Library crates
|
| |
+
|
| |
+ Source packages for Rust crates which contain a library with a public API
|
| |
+ MUST be named `rust-$crate`.
|
| |
+
|
| |
=== Mixed library / application crates
|
| |
|
| |
Source packages for Rust crates
|
| |
@@ -59,11 +73,8 @@
|
| |
in which case the "Mixed library / application crates" rules would apply,
|
| |
and the package would need to be renamed to include the `+rust-+` prefix.
|
| |
|
| |
- Crates that contain only an application but no library interface
|
| |
- MAY be packaged even if they are not published on crates.io,
|
| |
- because those packages are leaves
|
| |
- and cannot be depended on by other Rust crates.
|
| |
- Such packages MUST follow the default xref:Naming.adoc[Naming Guidelines]
|
| |
+ Application-only Rust projects which are not packaged from crates.io
|
| |
+ must follow the general xref:Naming.adoc[Naming Guidelines]
|
| |
(i.e. drop the `+rust-+` prefix from the source package name)
|
| |
so that they cannot introduce potential source package name collisions
|
| |
with crates from the crates.io namespace.
|
| |
@@ -289,28 +300,28 @@
|
| |
|
| |
----
|
| |
|
| |
- == Notes on the build process
|
| |
-
|
| |
- CAUTION: The build process for Rust packages has evolved over time,
|
| |
- especially for binary packages.
|
| |
- Packages for source-only library crates were historically only built on Rawhide,
|
| |
- but will also start being available on stable branches starting with Fedora 34.
|
| |
-
|
| |
- * Originally, binary packages for stable releases were built using Modularity,
|
| |
- leveraging its buildroot-only packages filtering capabilities,
|
| |
- but this approach was dropped in the Fedora 31 timeframe.
|
| |
- * From Fedora 31 to Fedora 33, binary packages are built with a special process
|
| |
- (leveraging koji side tags), using base packages from the relevant stable Fedora release,
|
| |
- except for Rust crates, which were included from Rawhide.
|
| |
- * From Fedora 34 onward, the workflow for building Rust packages will no longer be special --
|
| |
- packages for both library crates *and* applications will be available and built normally,
|
| |
- without having to rely on a different procedure for release branches.
|
| |
-
|
| |
- NOTE: Source-only Rust packages were granted a general exception to the
|
| |
- https://docs.fedoraproject.org/en-US/fesco/Updates_Policy/[Updates policy],
|
| |
- so they can be freely updated in release branches in addition to rawhide
|
| |
- (announced in the corresponding FESCo ticket:
|
| |
- https://pagure.io/fesco/issue/2474[F34 System-Wide Change: Rust Crate Packages For Release Branches]).
|
| |
+ NOTE: The patch to remove platform-specific dependencies for non-linux platforms
|
| |
+ is automatically generated by rust2rpm versions 22 and later.
|
| |
+ Additionally, a configuration file for rust2rpm (`+rust2rpm.conf+`)
|
| |
+ can be added to the package's dist-git repository
|
| |
+ to disable generation of subpackages for specific features,
|
| |
+ (for example, nightly-only features).
|
| |
+
|
| |
+ == Update process
|
| |
+
|
| |
+ Source-only Rust packages were granted a general exception to the
|
| |
+ https://docs.fedoraproject.org/en-US/fesco/Updates_Policy/[Updates policy],
|
| |
+ so they can be freely updated in release branches in addition to rawhide
|
| |
+ (announced in the corresponding FESCo ticket:
|
| |
+ https://pagure.io/fesco/issue/2474[F34 System-Wide Change: Rust Crate Packages For Release Branches]).
|
| |
+
|
| |
+ If possible, packages for Rust library crates SHOULD be updated
|
| |
+ to the same version across all currently supported branches of Fedora.
|
| |
+ Exceptions for this rule might be:
|
| |
+
|
| |
+ * system dependencies are too old on older branches (for example, `+libgit2+`)
|
| |
+ * pushing API-incompatible versions would result in broken packages on stable
|
| |
+ branches (for example, packages for the `+gtk-rs+` project crates)
|
| |
|
| |
== Examples
|
| |
|
| |
decathorpe
commented 2 years ago
I've split the changes into different commits for easier review.
last-revieweddate to $TODAY