rust2rpm - Man Page

generate RPM spec files for Rust crates and projects

Synopsis

rust2rpm [OPTION]... [crate] [version]

rust2rpm is a tool for automatically generating RPM spec files for Rust crates and projects built with cargo. Its primary target is Fedora Linux, with support for other target distributions being provided on a best-effort basis.

Some aspects of its behaviour can be controlled with command-line options, and some settings can be stored permanently in package-specific configuration files (c.f. rust2rpm.toml(5)), which are read if they are found in the current working directory.

When packaging Rust crates that provide a library interface, it is required to re-generate the spec file for every new version to ensure the exact correspondence between crate "features" (including implicit features for optional dependencies) and RPM subpackages is maintained. If this is not the case, the resulting RPM package will either fail to build, have incomplete or wrong metadata (i.e. Provides or Requires), or fail to install due to unresolvable dependencies.

Positional Arguments

crate

This argument accepts three different kinds of identifiers for projects:

Name of the crate on crates.io
Path to a local .crate file
Path to a local project directory

If the argument is the name of a crate, rust2rpm downloads the specified crate from crates.io and generates a spec file for a Rust crate (including -devel subpackages, if applicable).

If the argument is a path to a .crate file or a local directory, rust2rpm generates a spec file for non-crate cargo projects (no -devel subpackages).

If this argument is not passed, the crate argument is "guessed" based on two heuristics (the value of the %crate RPM macro if there is a valid "rust-$crate.spec" file in the current directory, or the name of the current working directory if it matches "rust-$crate").

version

This argument accepts two kinds of version identifiers:

Version of the crate on crates.io
Partial version / SemVer version requirement

If the version argument is a valid version according to SemVer, rust2rpm generates a spec file for the specified version (if there is a matching version published for the crate on crates.io).

If the version argument is a valid SemVer requirement instead, rust2rpm queries crates.io for all versions that are available for the current crate, and generates a spec file for the greatest version that matches the specified requirement.

If the argument does not parse as either a valid version or a valid version requirement, an error is raised.

If this argument is not passed, rust2rpm will default to the greatest available stable version of the crate on crates.io. Pre-release versions need to be explicitly specified.

Options

Options affecting command behaviour

-s, --store-crate: Store the .crate file downloaded from crates.io in the current directory (not applicable if the crate argument points to a local file or directory). If this option is not passed, crates are only stored in rust2rpm’s cache directory ($HOME/.cache/rust2rpm/).
-p, --patch: Open Cargo.toml in the default editor to apply changes and generate a patch file before loading project metadata from this file. This is the only supported way to patch Cargo.toml, since many changes to this file affect the content of the generated spec file.
-V, --vendor: Create a vendor tarball with cargo vendor and generate a spec file that builds against dependencies from the vendor tarball instead of packaged Rust crates. Both automatic and manually written patches (--patch option) are taken into account. Using this option disables generation of devel subpackages when packaging crates.
--compat: Generate a spec file for an alternative version of a crate, applying a version suffix automatically derived from the crate version to the package name. This is the recommended way to create "compat" packages, since it will generate packages that follow the guidelines for package names when packaging multiple versions of the same project. For versions past 1.0, the suffix is the <major> version, for versions between 0.1 and 1.0, the suffix is <0.minor>, and for versions before 0.1 the suffix is <0.0.patch>, according to the SemVer API stability guarantees as implemented in cargo.
--no-existence-check: Do not check whether the package already exists in Fedora dist-git. The default setting is enabled on Fedora but disabled for other targets. This first checks whether the dist-git repository exists, and if it exists, whether there is a spec file in the current rawhide branch (so retired packages also count as "non-existent").
--no-patch-foreign: Do not automatically strip non-applicable target-specific dependencies from Cargo.toml. This option can be used if the implementation for stripping these dependencies results in broken metadata. Please file bug reports for cases like this (including the name and version of the affected crate).
-t, --target={plain,fedora,mageia,opensuse}: Write spec file tailored to the specified distribution target. The default value is determined by the contents of os-release(5).
-i, --interactive: Enable interactive mode (only applicable when rust2rpm is called for a cargo "workspace" project). This is only required when the "main" crate within a cargo workspace cannot be determined with heuristics.

Options affecting spec file generation

-a, --rpmautospec, --no-rpmautospec: Explicitly enable or disable use of rpmautospec. The default setting is enabled on Fedora but disabled for other targets - the Target Support section has more information about the differences between supported targets.
--no-auto-changelog-entry: Do not include a generic %changelog entry in the generated spec file. By default, this is enabled on all targets. Passing this option will result in more easily diffable spec files.
--relative-license-paths: Use relative paths when listing license files in the %files section of the generated spec file. Causes a copy of the license files to be installed in the default license directory. This is disabled by default on all targets.

Deprecated options

--show-license-map: Print the mapping between SPDX license identifiers and Fedora / Callaway identifiers that’s used internally for "translating" crate licenses from SPDX instead of generating a spec file.
SPDX identifiers are now used for the License tag on all targets except mageia.
--translate-license: Parse the crate argument as a license expression, and print the result of translating it from SPDX into Fedora / Callaway notations instead of generating a spec file.
SPDX identifiers are now used for the License tag on all targets except mageia.

Target Support

While the primary supported target is Fedora Linux, rust2rpm also has best-effort support for generating spec files that should work on other distributions (Mageia, OpenSUSE, and other generic RPM-based Linux with the "plain" target).

Fedora

The "fedora" target enables all features that are supported by rust2rpm, but which often require the latest versions of rust-packaging (i.e. cargo-rpm-macros) and / or cargo2rpm.