Rust Packaging Guidelines

Similarly to other language ecosystems in Fedora, there is a standardized set of compiler flags that MUST be passed to the Rust compiler.

The defaults for Rust are defined in the %build_rustflags macro from the rust-srpm-macros package. It is part of the default buildroot on Fedora 39+, where the %set_build_flags macro automatically sets the $RUSTFLAGS environment variable based on this macro.

For compatibility with older releases, this environment variable can be set manually at the start of %build and %check in package’s spec files:

This is not necessary for packages that use the %cargo_prep, %cargo_build, and %cargo_test macros, which configure cargo to use the default %build_rustflags directly.

The RPM macros that provide basic functionality for building Rust code are included in rust-rpm-macros, which is part of the default buildroot in Fedora, as it is a dependency of redhat-rpm-config. When building for ELN or EPEL8, this is not the case, and packages need to use BuildRequires: rust-toolset.

Packages that build Rust code with cargo - directly or indirectly - or which call any of the %cargo_* macros, MUST add BuildRequires: cargo-rpm-macros >= 24, which provides the implementations of all %cargo_* macros. This package is not part of the default buildroot, since it pulls in additional dependencies (i.e. a Python interpreter).

For backwards compatibility, packages MAY instead depend on earlier versions of the %cargo_* macros, which were provided in the rust-packaging package, if they do not depend on any of the features or macros that are only available with newer versions. When generating a spec file for a crate with rust2rpm, it will automatically detect usage of these features, and include the necessary BuildRequires for the RPM macro package automatically.

Similar to other languages that produce statically linked binaries, Rust executables (and shared libraries) contain code that originates in other packages (i.e. packages for other Rust crates), which in turn are covered by different license terms.

This needs to be taken into account by maintaining a separate License tag for the subpackage that contains these binaries. More information about License tags is available from the Fedora Legal docs.

The cargo-rpm-macros package provides two RPM macros that help with filling the License tag correctly:

This macro determines and prints a summary of all the licenses of the Rust crates that end up statically linked into final binaries (properly excluding build-only or test-only dependencies). This summary can then be copied from the build log into the spec file as a comment. The actual contents of the License tag can then be obtained by constructing a conjunction of these individial licenses (with SPDX AND operators).

This macro determines and prints a complete breakdown of all Rust crates that end up statically linked into final binaries (according to the same logic as in the %cargo_license_summary macro), their versions, and their individual license expressions. Generating this list dynamically at build-time ensures that its contents always match the actual dependencies.

Both macros accept the same arguments as all other %cargo_* macros (-a, -n, -f), and for their output to match the actual binaries, the same flags need to be passed to them and %cargo_build.

In general, packages SHOULD NOT use bundled crate dependencies, whenever possible.

Whenever vendored / bundled crate dependencies are used (no matter which mechanism is used for the purpose), all bundled crate dependencies MUST be declared with virtual Provides in the format Provides: bundled(crate($crate)) = $version in the subpackage that contains the Rust component. For example, these virtual Provides are used to determine the impact of security vulnerabilities on packages that use vendored Rust dependencies.

Building exclusively from vendored dependencies by using a tarball that was generated by running cargo vendor SHOULD only be a last resort. However, there are also two rare situations in which bundling at least some Rust crates is likely unavoidable.

The canonical source of Rust crates is crates.io.

Projects that are built with cargo and / or published on crates.io follow Semantic Versioning (with small cargo-specific tweaks). Since SemVer strings can contain characters that are invalid in RPM version strings, they MUST be translated to be RPM-compatible.

For example, pre-releases are denoted by a -<pre> suffix in SemVer, but the - character is invalid in RPM Versions. This can be solved by replacing - with the ~ character, which denotes pre-releases in RPM version strings. This translation happens automatically for the Version tag when generating a spec file with rust2rpm, and the "upstream" version is stored in a separate macro that can be used to refer to the "original" version string.

Additionally, some Rust crates carry extra "build" metadata in their versions (a <build>` suffix). This format is primarily used to carry information about the version of a bundled C library. This `<build> suffix MUST be removed from crate metadata with a patch, since it can interfere with RPM dependency / version resolution. This happens automatically when using rust2rpm version 25 or newer.

Projects from crates.io MUST be packaged from the sources that are published there (i.e. by using the %{crates_source} macro).

If the sources published on crates.io do not contain all files that are necessary for creating the package (for example, missing .desktop file or man pages), the upstream sources can be used as an additional source, but they MUST NOT be used for building the crate itself. It is recommended to file an issue with the upstream project about including these additional files in published crates.

Most tooling support for determining licenses requires accurate metadata about licenses in crate metadata, including the %cargo_license* macros, and other third-party tools like cargo-license and cargo-deny.

For this reason, the license metadata for all Rust crates packaged for Fedora MUST match the license tag of the Fedora package itself. Any crates that set package.license-file in their metadata (which is reserved for non-standard / non-SPDX licenses) MUST be patched to set package.license in their metadata instead in cases where this is not appropriate and an accurate SPDX expression can be provided. Patches like this SHOULD be submitted upstream.

The process of building and installing Rust crates is almost entirely automated with several RPM macros:

All packages for Rust crates MUST set either %bcond_without check or %bcond_with check. The value of this macro affects the behaviour of %cargo_generate_buildrequires.

All %cargo_* macros (except %cargo_prep and %cargo_vendor_manifest) accept a set of optional flags / arguments that can be used to control the feature flags that are passed to cargo (usually to enable optional / non-default features):

The -a and -n flags are mutually exclusive and cannot be passed together. The -a flag and -f arguments are also incompatible, since passing -a already enables all features. However, using the -n flag and specifically enabling some features with the -f argument is valid.

There are some common situations in which passing these flags or arguments is necessary:

Note that the -n flag should only be used in exceptional circumstances, for example when enabling a different backend than the one enabled by default, and MUST NOT be used to avoid missing dependencies that are part of the "default" feature set of a crate.

When passing any of the -a or -n flags or an -f argument to a %cargo_build and / or %cargo_install macro, the same flags MUST also be passed to %cargo_license and %cargo_license_summary (if present). Otherwise, the list of generated licenses and the generated license summary will not match what is used when the application or library is compiled.

It is recommended to set these flags in a rust2rpm.toml config file which causes the flags to be injected into generated spec files automatically, whereever necessary.

With Semantic Versioning ("SemVer") being the only supported versioning scheme for Rust crates, dependencies on Rust libraries are almost exclusively specified as "this version or any newer version that is API-compatible with it", i.e. a range of supported versions.

These ranges of supported versions need to be correctly translated into RPM dependencies, otherwise a wrong version of a dependency might get pulled in for builds, causing unhelpful error messages about missing dependencies.

Since dependencies of Rust projects often change with every new release, and keeping a list of BuildRequires up-to-date manually is tedious and error-prone, packages for projects that build Rust code with cargo MUST use dynamically generated BuildRequires by calling the %cargo_generate_buildrequires macro in the %generate_buildrequires scriptlet.

For example, a dependency on serde = "1.0.100" specified in a project’s Cargo.toml metadata (a dependency on the crate named "serde", with version "1.0.100" or any version API-compatible with "1.0.100", with default features enabled) would cause a dependency like this to be generated for RPM:

Refer to the section about RPM macros for how to pass feature flags to this macro.

Issues with the %cargo_generate_buildrequires macro that prevent it from being used for a package should be reported against cargo2rpm, the tool that provides the functionality of this macro.

Optional features / dependencies of Rust crates are translated into RPM subpackages to support resolving dependencies for features and optional dependencies of crates. The list of crate "features" (including any implicitly defined features for optional dependencies) MUST be kept in sync with the list of subpackages, i.e. for every feature $foo of the crate $crate, there must be a subpackage with name rust-$crate+$foo-devel, and vice-versa. This is required for RPM generators for Provides and Requires for these optional features / dependencies to work correctly.

If optional features that are not part of the default feature set are unused and would pull in additional (possibly unavailable) dependencies, the package MAY omit subpackages for these specific feature names. However, care needs to be taken that the features corresponding to the ommitted subpackages are not "reachable" via subpackages that have not been omitted, since this would result in packages with unsatisfiable dependencies. Disabling optional features sometimes cannot be handled correctly simply by omitting subpackages for specific features. In these cases, the crate metadata in Cargo.toml needs to be patched accordinly instead.

Beware that the "default" feature is always implicitly defined by cargo, even if the crate metadata does not contain a [features] table or an explicitly defined "default" feature, so the subpackage for the "default" feature will be present in all packages for Rust crates with a library interface.

The cargo-rpm-macros package includes RPM generators for automatically generating Provides and Requires for Rust crates that comply with the Packaging Guidelines (i.e. install their files into the correct location, %{crate_instdir}).

It is recommended to verify that the generated Provides and Requires are sane - for example, the following Provides and Requires must be present to ensure correct inter-subpackage dependencies:

Additionally, dependencies on external Rust crates must be as expected:

In most circumstances, the latest version of a crate SHOULD be packaged, and - if possible - packagers SHOULD port crates to use the latest available version of their dependencies, and submit these patches to upstream to limit divergence between the upstream project and the Fedora package.

However, there are two common scenarios in which it is often necessary to provide packages for multiple versions of a library crate simultaneously:

In these cases, a "compat package" can be created for the older version (i.e. usually the current version), and the suffix-less package can be updated to the newer version. rust2rpm supports automatically creating "compat packages" with names that are compliant with the Naming Guidelines for this case and compatible with the restrictions of Semantic Versioning by using the rust2rpm --compat flag.

All "compat packages" for Rust crates MUST follow the guidelines for Rust crates, and two additional rules apply when creating them:

The behaviour of some RPM macros depends on the presence and value of the _with_check macro, i.e. if %bcond_without check or %bcond_with check are used in the spec file - notably, the %cargo_generate_buildrequires macro only includes dev-dependencies (i.e. dependencies that are only used for compiling and / or running a project’s test suite with cargo) if the check bconf is enabled.

Additionally, packages for Rust crates or workspace projects that are generated by rust2rpm use the value of this macro to determine if the %check scriptlet is run.

Packages MUST set this bcond to avoid unexpected behaviour of the %cargo_* macros, by either explicitly enabling or disabling tests.

Rust crates can have three different kinds of tests in their test suites:

By default, running cargo test (i.e. by calling the %cargo_test macro), all three kinds of tests are run. They can also be invoked separately (for example, because parts of the test suite or large data files are not included in published sources) by passing through filtering arguments to the underlying cargo test command:

This can be combined with additional flags to skip tests with specific names (or that contain a specific string in their name) by passing the --skip argument through to the test harness (can be specified multiple times):

By default, cargo uses substring matching to match --skip arguments and actual names of tests, which can be turned off by using the --exact flag.

If any tests are skipped or disabled, the package SHOULD include comments that explain why this is the case, and include links to upstream issues, if available.

Rust applications that are "crates" but which are not published on crates.io MUST be named according to the generic Naming Guidelines, i.e. they MUST NOT use a rust- prefix for the source package name.

The generic guidelines for referencing sources apply. Notably, the %{crates_source} macro cannot be used for packages like this.

Rust projects that are organized as "cargo workspaces" MUST be named according to the generic Naming Guidelines, i.e. they MUST NOT use a rust- prefix for the source package name.

The generic guidelines for referencing sources apply.

All %cargo_* macros have support for cargo workspaces as of cargo-rpm-macros >= 24. Any unexpected results that occur when using these macros for projects that are set up as a cargo workspace should be reported against cargo2rpm.

Note that currently, any -a and -n flags or -f arguments that are passed to %cargo_generate_buildrequires are applied to all workspace members during dependency resolution.

Projects with build systems that call cargo internally to build Rust components MUST follow the same guidelines as other projects that build Rust code with cargo.

Packages MUST ensure that the cargo calls that are internal to the project’s build system do not pass flags or arguments that are incompatible with either the default compiler flags or cargo options that are set in the %cargo_build macro or configured by %cargo_prep.

Upcoming versions of meson will have support for building crate dependencies by reading Cargo.toml files directly, with meson supporting a similar mechanism for overriding crates.io sources with a local registry.