From 90687f96bae1c3ed99520c547218eee8d09d843c Mon Sep 17 00:00:00 2001 From: Fabio Valentini Date: Jan 20 2022 17:24:55 +0000 Subject: [PATCH 1/2] clarifications for Rust Naming and Versioning guidelines --- diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc index ce11a75..67c1b04 100644 --- a/guidelines/modules/ROOT/pages/Rust.adoc +++ b/guidelines/modules/ROOT/pages/Rust.adoc @@ -23,17 +23,53 @@ or sometimes trimming the `Summary` if the upstream description text is too long == Package Naming -Packages for Rust crates MUST be named `rust-$crate`. - -Any library crates that get packaged MUST be published on crates.io, -since this enforces a certain standard in how crates are packaged and built, -and also ensures that all crate dependencies are available from crates.io as well. - -Crates that only contain an application -- but no library -- may be packaged -even if they are not published on crates.io, -because those packages are leaves and no other Rust packages can depend on them. - -Rust applications that are not published to crates.io MUST follow the default xref:Naming.adoc[Naming Guidelines]. +=== Library crates + +Source packages for Rust crates which contain a library with a public API +MUST be named `rust-$crate`. + +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, +ensures that all the crate's dependencies are available from crates.io as well, +and that there are no package name collisions +due to the unique crate names in the crates.io namespace. + +=== Mixed library / application crates + +Source packages for Rust crates +which contain both a library with a public API *and* an application +MUST be named `rust-$crate` +(i.e. follow the rules for library crates). + +NOTE: The convention set by `rust2rpm` for the name of the subpackage + that contains the application binary (or binaries) + is to use the name of the crate itself. + However, in some cases, + the crate name does not match the name of the built application(s), + and in this case the subpackage name SHOULD be adjusted + to match expectations. + +=== Application-only crates + +Packages for application-only crates that are published on crates.io +MUST NOT drop the `+rust-+` prefix from their source package names, +because a crate can start to include a public library API at any time, +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] +(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. + +NOTE: `rust2rpm` does not support generating `.spec` files + for packages without a `+rust-+` name prefix yet. + In this case, `.spec` files written by `rust2rpm` + will need to be manually edited after each update. == Package sources @@ -152,6 +188,16 @@ BuildRequires: (crate(clap/default) >= 2.24.1 with crate(clap/default) < 3.0.0) packagers SHOULD forward these patches to the upstream project to keep the divergence between downstream and upstream small over time. +CAUTION: Some crates are published with additional information + encoded into their version string. + For example, Rust bindings for native libraries + might add a `+x.y.z`-style suffix to indicate + which version of the native library is required or supported. + Suffixes like these MUST be removed from the crate's `Cargo.toml` file + and dropped from the package Version, + because they might introduce dependency resolution problems + when this suffix leaks into RPM `Provides` metadata. + === Compatibility packages for older crate versions If it is not possible to port a crate to the version of a dependency that is available in Rawhide, From 097f9f556d912b2ef88c01e016a3a4c54a3a15a0 Mon Sep 17 00:00:00 2001 From: Fabio Valentini Date: Jan 20 2022 17:24:55 +0000 Subject: [PATCH 2/2] more Rust guidelines cleanup, remove mentions of Fedora < 34 --- diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc index 67c1b04..4645bb7 100644 --- a/guidelines/modules/ROOT/pages/Rust.adoc +++ b/guidelines/modules/ROOT/pages/Rust.adoc @@ -1,25 +1,27 @@ = Rust Packaging Guidelines -:last-reviewed: 2021-01-24 - -CAUTION: The workflow for Rust packaging on Fedora will be different starting with Fedora 34. - Older releases (up until Fedora 33) do not ship source-only packages for Rust crates, - but only application packages created via a special build process. - In general, the Rust Packaging Guidelines apply to all current Fedora releases, - only the build process differs depending on the targeted Fedora release. +:last-reviewed: 2021-12-18 == rust2rpm Note that the https://pagure.io/fedora-rust/rust2rpm[*rust2rpm*] tool (packaged as `python3-rust2rpm` for Fedora) -automates most of the steps that are necessary for creating .spec files for Rust crates. +automates most of the steps that are necessary for creating `+.spec+` files for Rust crates. It is advisable to try `+rust2rpm $crate+` first, and to only modify its output for your needs, -before attempting to write a .spec file by hand. +before attempting to write a `+.spec+` file by hand. +Most of the time, `+rust2rpm+` output can be used almost without modifications. + +However, there are a few common situations +in which manual edits of the generated `+.spec+` file +or patches for upstream `+Cargo.toml+` files (with `+rust2rpm -p+`) +are required, for example: -Most of the time, rust2rpm output can be used almost without modifications, -except for adding `LICENSE` files with `+%license+` to the appropriate `+%files+` listings, -or sometimes trimming the `Summary` if the upstream description text is too long. +* trimming a generated `+Summary+` tag that is too long +* dropping non-linux platform-specific dependencies +* 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 == Package Naming @@ -127,7 +129,7 @@ These subpackages MUST be named `+rust-%{crate}+$FEATURE-devel+` for all features that are present in `Cargo.toml` after patching this file in `+%prep+`. NOTE: These feature subpackage definitions are automatically correctly generated - when using rust2rpm (if necessary, with the `-p` flag to apply any initial changes). + when using `+rust2rpm+` (if necessary, with the `-p` flag to apply any initial changes). The dependency generator then creates `Requires` for all features that a crate depends on. For example, a dependency on `syn` with the `visit` and `extra-traits` features @@ -307,10 +309,10 @@ CAUTION: The build process for Rust packages has evolved over time, 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 are included from Rawhide. -* Starting with Fedora 34, the workflow for building Rust packages will no longer be special -- + 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 special procedure for release branches. + 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], @@ -355,10 +357,6 @@ Some crates ship both a compiled binary and a reusable library component, in this case, both the `-devel` subpackage(s) *and* the subpackage containing the binary are built. -When building a package like this for a stable Fedora release (up to and including Fedora 33), -the .spec file SHOULD be modified to remove all `-devel` subpackages, -so no dangling broken dependencies on other (unavailable) library crates are introduced. - .rust-yubibomb.spec [source] ----