Rust-paketoinnin ohjeet

Rust is a strongly and statically typed, compiled programming language that supports concepts from both imperative and functional programming.

Because there is not yet a stable Rust ABI, and because conditional compilation is a widely used feature in the Rust ecosystem, Rust libraries ("crates") can not be distributed in compiled form, and are instead distributed as source code.

This document covers how to handle Rust code in packages, specific to the different ways in which projects can be set up:

For the first three of these cases, the rust2rpm tool can be used to generate spec files from cargo / crate metadata. It is designed to produce spec files that are in line with the (Rust) Packaging Guidelines.

There are also guidelines for packaging shared libraries that are implemented in Rust (usually built and installed with cargo-c).

Generic rules

This section covers rules that apply to all packages that ship Rust code.

Compiler flags

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:

export RUSTFLAGS="%build_rustflags"

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.

Mandatory BuildRequires

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.

License tags

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:

  • %cargo_license_summary

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).

  • %cargo_license

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.

Vendored dependencies

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.

Replacing git dependencies

One of the types of dependencies cargo supports are git snapshots, which are usually used to reference either a specific commit, or a reference to a downstream fork of a crate.

The project SHOULD be patched to use a version of this crate that is available on crates.io instead, if that is possible. If it turns out that depending on a git snapshot is no longer necessary, this patch SHOULD be submitted to the upstream project.

If the dependency is not published on crates.io, or if the versions published there are not a suitable replacement, a git snapshot of the crate can be bundled. This can be achieved by creating and supplying a tarball with the git snapshot as a separate source, unpacking the tarball in %prep, and patching Cargo.toml to replace the git-based dependency with a path-based dependency.

Replacing patched crate sources

Another way in which cargo supports specifying modified dependencies is by "patching" a crate source, specifying an alternative source for specific crates - which will likely be either git references or path-based dependencies that are present to override a crate that is published on crates.io with a (modified) local copy, or a git repository that points to a (modified) fork of the crate.

These replacements SHOULD be dropped in favor of using only published versions of crates. If that is not possible, they must be replaced by path-based dependencies, similar to the process described for git-type dependencies.

Using vendor tarballs

Official support for building with vendored dependencies was added in version 25 of cargo-rpm-macros and rust2rpm.

  • The %cargo_prep macro accepts a -v $VENDOR argument, where $VENDOR is the path to the directory that contains the vendored crate dependencies. When this argument is passed, the generated cargo configuration is set up for building against dependencies in this directory instead of dependencies from the system-wide registry.

  • The %cargo_generate_buildrequires macro MUST NOT be called when using vendored dependencies.

  • The %cargo_vendor_manifest macro generates a manifest (cargo-vendor.txt) that lists the names and versions of all crates in the vendor tarball. This macro MUST be called (for example, in the %build scriptlet), and the generated file MUST be added as a %license file in the appropriate package’s list of %files. An RPM generator parses this file and generates appropriate virtual Provides for all bundled crates, as is required for any bundled dependencies.

  • Packages that build with vendored dependencies MUST NOT provide a Rust library interface (i.e. in -devel subpackages), because the resulting packages would have broken dependencies.

Typically, the %prep scriptlet will look like this when using vendored dependencies (assuming Source1 is the vendor tarball, and it contains a top-level vendor directory):

%prep
%autosetup -%{crate}-%{version} -p1 -a1
%cargo_prep -v vendor

The necessary spec file adaptations and the generation of the vendor tarball itself happen automatically when running rust2rpm in "vendor" mode.

rust2rpm

The recommended way to write spec files for Rust projects is to use rust2rpm, and apply any necessary modifications on top of the generated spec file.

There are a few common situations in which automatically generated spec files need manual changes:

  • invalid Summary / %description: The heuristics for generating the Summary or %description for the package from the crate metadata can fail to produce valid values (i.e. Summary tag that is too long). In this case, the Summary needs to be shortened manually. This can also be overridden in the package-specific rust2rpm configuration file.

  • unwanted dependencies / subpackages: Some crates provide non-default / optional features that are either unnecessary (i.e. only applicable to non-Linux systems), or have additional dependencies that are not packaged for Fedora. These features and unavailable optional dependencies MUST be removed from crate metadata - otherwise, the package will either fail to build, or produce subpackages with broken dependencies.

  • nightly-only / unstable features: Some crates provide features that are only available on a nightly version of the Rust compiler, or features that are unstable and require an opt-in by passing environment variables. Features like these SHOULD be removed from crate metadata, since they either cannot work (Fedora ships only the stable Rust toolchain) or are not feasible to support.

  • unwanted / unnecessary files ("bloat"): Some projects include files that are not required for the crate to function properly (files for CI settings, development / helper scripts, etc.). Files like these SHOULD be prevented from being installed (by adding / modifying the package.include or package.exclude settings in the crate metadata). It is recommended to submit changes like this to the upstream project.

  • incompatible compiler flags: Some crates include custom settings for the release profile that are incompatible with RPM packaging. These settings MUST be removed from the release profile by patching Cargo.toml.

Crates that provide Rust bindings for C libraries usually require some additional changes (if possible):

  • linking against system libraries: This often requires making some dependencies non-optional and / or modifying build.rs scripts to unconditionally link against system libraries instead of building and statically linking a bundled copy of the library.

  • regenerating Rust bindings (and tests for them) at build-time: This too often requires making the bindgen dependency non-optional and / or modifying build.rs to cause regeneration of Rust bindings at build-time.

Note that patching Cargo.toml files (especially changing the set of optional dependencies and features) MUST be done by running rust2rpm -p, since changes like these affect spec file generation (i.e. the list of generated subpackages), which is only correctly taken into account if the patch is created before generation of the spec file.

Rust crates

A large part of the process of packaging Rust crates can (and should) be automated by using rust2rpm. It is designed to generate spec files that are compliant with both the general and the Rust Packaging Guidelines.

Additionally, due to some properties of packages for Rust crates (i.e. subpackages that correspond to crate features / optional dependencies), rust2rpm MUST be re-run for every new version of a crate to ensure that generated feature subpackages stays in sync with crate metadata.

Package naming

The canonical source of Rust crates is crates.io.

Crates with Rust library interface

Crates that are published on crates.io and that are intended to provide a Rust library interface MUST be packaged with rust-$crate as the name of the source package (where $crate is the name of the project on crates.io). This ensures that there are no name collisions between Rust crates published on crates.io and Rust crates packaged for Fedora.

Projects from sources other than crates.io MUST NOT use the rust- prefix for source package names, and MUST follow the general Naming Guidelines instead. In this case, the guidelines for either single-crate Rust applications or cargo workspaces apply.

If a crate is also part of a larger project and it is not feasible to package the Rust crate separately, the Rust crate MAY be packaged from different sources (i.e. an upstream tarball) if and only if the crate is also published on crates.io under the same name and with matching versions.

In this case, the subpackage(s) that contain the Rust crate sources MUST be named rust-$crate-devel and rust-$crate+$feature-devel for all crate features and ensure that the virtual Provides for the Rust crate are correct. The rust- prefix is not required for the name of the source package.

Crates without Rust library interface

Crates that do not provide a Rust library interface (for example, crates that only contain executable targets) MAY drop the rust- prefix for the name of the source package or use the "project name" if it is different from the crate name if and only if the project will not provide (or need to provide) a Rust library interface in the future, since this would require renaming the source package to rust-$crate. In this case, the guidelines for single-crate Rust applications apply, and the package is not required to use the sources that are published on crates.io.

When building a crate with vendored dependencies the rust- prefix of the source package name MAY be dropped as well — since packages cannot provide a Rust library interface in this case — if and only if the project will not need to provide a Rust library interface.

When generating a package for a Rust crate that also (or exclusively) contains an application, the convention followed by rust2rpm is to generate a subpackage with a name that matches the crate’s name (i.e. the rust-$crate source package will have a $crate subpackage). If this name does not match expectations, it is recommended to either change the name of this subpackage, or to add virtual Provides for the expected name.

Package versioning

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.

Package sources

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.

Crate license

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.

RPM macros

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

  • %cargo_prep: This macro MUST be called in the %prep scriptlet after sources have been unpacked. It sets up the build environment for cargo and injects a cargo configuration file, which sets the default compiler flags and configures the local crate registry as a replacement for crates.io.

  • %cargo_generate_buildrequires: This macro MUST be called in the %generate_buildrequires scriptlet, except when building with vendored dependencies. This is the mechanism that automatically generates depepdencies on other Rust crates based on the metadata in Cargo.toml.

  • %cargo_build: This macro MUST be called in the %build scriptlet. It runs cargo build with the appropriate command line arguments. Calling this macro MAY be skipped if the crate is not supported on the current CPU architecture.

  • %cargo_install: This macro MUST be called in the %install scriptlet for crates that provide a library interface. It runs cargo package and installs the resulting directory tree into %{buildroot}/%{crate_instdir} (i.e. %{buildroot}/%{cargo_registry}/%{crate}-%{version}/). For crates that provide bin targets, it installs all built executables into %{buildroot}/%{_bindir}. If any built executables need to be installed in a different location, they can be moved after calling %cargo_install, or %cargo_install can be replaced with manual installation steps. To prevent installation of executables by this macro, the %cargo_install_bin macro can be defined to 0. To prevent installation of library sources by this macro, the %cargo_install_lib macro can be defined to 0.

  • %cargo_test: This macro MUST be called in the %check scriptlet. It runs cargo test with the appropriate command line arguments. Calling this macro MAY be skipped if the crate is not supported on the current CPU architecture or if tests are disabled in general.

  • %cargo_license / %cargo_license_summary: These macros MUST be called in the %build scriptlet after %cargo_build when building crates that include binary targets. They can be used to print the list of the licenses of the crates that are statically linked into any built executable or shared library (see License tags).

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):

  • -a: Causes the --all-features flag to be passed to cargo, and the %cargo_generate_buildrequires macro to resolve dependencies with all optional features enabled.

  • -n: Causes the --no-default-features flags to be passed to cargo, and the %cargo_generate_buildrequires macro to resolve dependencies with all default and optional features disabled.

  • -f foo,bar: Causes the --features foo,bar argument to be passed to cargo, and the %cargo_generate_buildrequires macro to resolve dependencies with the additional features foo and bar enabled. This argument accepts a comma-separated list of feature names (or names of optional dependencies).

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:

  • It can be necessary to enable additional features and / or optional dependencies to build and run the test suite of a crate. In this case, the required features MUST be enabled by passing the corresponding flags to all %cargo_* macros, unless the required optional dependencies are not packaged yet.

  • Some applications support additional / non-default features by passing feature flags. If it is desirable to build applications with these features enabled, the required features need to be enabled by passing the corresponding flags to all %cargo_* macros (including %cargo_license and %cargo_license_summary).

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.

Dynamically generated BuildRequires for crate dependencies

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:

BuildRequires:  (crate(serde/default) >= 1.0.100 with crate(serde/default) < 2.0.0~)

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.

Subpackages for crate features

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.

RPM generators for Provides and Requires

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:

  • the main rust-$crate-devel subpackage MUST provide crate($crate) = %{version}

  • the rust-$crate+$feature-devel subpackages MUST provide crate($crate/$feature) = %{version} and require crate($crate) = %{version} (i.e. rust-$crate-devel)

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

  • the main rust-$crate-devel subpackage MUST require the virtual Provides for all non-optional crate dependencies

  • the rust-$crate+$feature-devel subpackages MUST require the virtual Provides for the optional crate dependencies and features that are listed as the feature’s dependencies in crate metadata

Packaging multiple versions

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:

  • It is not feasible to port a crate to the version of a crate dependency in Fedora due to large API changes between the required and the packaged version.

  • The number of packages affected by a required SemVer-incompatible library update is very large.

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:

  • For crates that also includes an executable, only the package for the latest version can include this executable, and it MUST NOT be built and included in any older versions, to prevent both the name of the executable under /usr/bin and the name of the subpackage would conflict between the old and the new version of the package.

  • The packager SHOULD check whether running tests in the old version of the crate would cause additional, potentially undesirable dependencies, for example, older versions of other dependencies that would require creating additional "compat packages" - in this case, tests SHOULD be disabled (i.e. by flipping the check bcond).

The check bcond

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.

Running tests

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

  • "unit tests": These tests are included alongside library / application source code in the src/ directory, and can reference private APIs (similar to "glass-box" tests).

  • "integration tests": These tests are usually separate files under the tests/ directory, and they can only rely on public API of the tested crate (similar to "black-box" tests).

  • "doctests": These tests are automatically extracted from code blocks in Markdown documentation, which is often used as a mechanism to ensure that code snippets in documentation for public methods are correct and continue to compile.

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:

  • %cargo_test — --lib: only run "unit tests" for the library interface

  • %cargo_test — --bin: only run "unit tests" for binaries

  • %cargo_test — --doc: only run "doctests"

  • %cargo_test — --tests: only run "integration tests"

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):

%cargo_test -- --lib -- --skip foo::bar::tests::test1

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 (non-crates.io crates)

Most rules that apply to Rust crates that are published in crates.io also apply to Rust projects that are built with cargo but not published on crates.io.

rust2rpm has basic support for generating spec files for this type of package by running rust2rpm path/to/Cargo.toml in unpacked upstream sources.

Packages that fall into this category MUST NOT ship crate sources in %{cargo_registry}, i.e. they cannot ship -devel subpackages that contain crate sources or have subpackages that have virtual provides for crate(…​) = %{version}.

To prevent the %cargo_install macro from installing library sources into %{cargo_registry}, the %cargo_install_lib macro can be defined to 0. When using rust2rpm with a path to a Cargo.toml file this macro definition is injected automatically.

Package naming

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.

Package sources

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

Rust applications (cargo workspace projects)

Some Rust projects are organized as "cargo workspaces", which are collections of Rust crates that are often considered "internal implementation details". In most cases, these "internal" crates are not published individually on crates.io.

Projects that use this setup can be handled similarly to Rust projects that are organized as a single crate but not published on crates.io.

rust2rpm has basic support for generating spec files for this type of package by running rust2rpm path/to/Cargo.toml in unpacked upstream sources, (where ./Cargo.toml must be the path to the "workspace root", i.e. the Cargo.toml file that contains the [workspace] table).

Packages that fall into this category MUST NOT ship crate sources in %{cargo_registry}, i.e. they cannot ship -devel subpackages that contain crate sources or have any subpackages that have virtual provides for crate(…​) = %{version}.

Package naming

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.

Package sources

The generic guidelines for referencing sources apply.

RPM macros

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.

Python projects

Python packages that use setuptools_rust or maturin to build a "native" Python extension also need to apply the generic rules for Rust packages in addition to following the Python Packaging Guidelines.

Both setuptools_rust and maturin build the native Python extension by calling cargo internally, so the basic setup for projects that build with cargo is required for packages like this as well.

This includes calling %cargo_prep in %prep to set up the build environment for cargo, and using %cargo_generate_buildrequires to dynamically generate the appropriate BuildRequires for Rust crate dependencies.

Additionally, %cargo_license and / or %cargo_license_summary MUST be used to determine the licenses that apply to the statically linked Python extension.

The packager also MUST ensure that the default compiler flags are passed to rustc.

Mixed Rust / C/C++ projects

Handling of projects that include both C/C++ and Rust code depends on how building the Rust code is integrated into the project’s build system.

Independent of the specific setup, the correct compiler flags MUST be passed to rustc, and the License tag of the package that contains the Rust component MUST take the licenses of statically linked crates into account.

Building with cargo internally

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.

Building with meson directly

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.

Building shared libraries with cargo-c

While it is not currently possible to build Rust crates as shared libraries, Rust projects can define a C-compatible public API so that they can be built as standard shared libraries with a C ABI.

In most cases, libraries like this are built with cargo-c, which provides convenient wrappers (cargo-cbuild and cargo-cinstall) for both building and installing shared libraries (including support for generating and installing header files and and pkg-config files).

The cargo-c package includes RPM macros for this functionality (%cargo_cbuild and %cargo_cinstall), which accept the same arguments as their cargo counterparts.