rust2rpm - Man Page

rust2rpm [OPTION]... [pkgid]

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.

pkgid

This argument accepts a PKGID string similar to cargo for referring to a crate name and version on crates.io, with both components being optional:

• <name>
• <name>@<version>
• @<version>

If the <name> component is missing, the crate name is inferred from existing spec file contents and / or the name of the output directory. If the <version> component is missing, crates.io is queried for available versions of the specified crate, and the greatest stable version is used.

If the <version> component is a valid SemVer version, crates.io is queried for this exact version of the specified crate. An error is raised if the specified version does not exist. Alternatively, if the <version> component is a partial version or SemVer version requirement, crates.io is queried for versions that match the given version requirement, and the greatest matching version is used.

Pre-release versions are never chosen automatically, and always need to be specified explicitly.

When used in conjunction with the --path argument, default project name and version can be overridden with this argument.

-C [PATH], --config-file=[PATH]

Load rust2rpm configuration from the specified path instead of the default path (./rust2rpm.toml). Raises an error if this file does not exist.

-o [PATH], --output-directory=[PATH]

Specify the directory to which any output files should be written. If this directory does not exist yet, it will be created.

--path=[PATH]

Path to unpacked sources (project root directory or Cargo.toml file) for generating a spec file for non-crate projects.

-t [TARGET], --target=[TARGET]

Write spec file tailored to the specified distribution target. The default value is determined by the contents of os-release(5). Valid values are fedora, epel8, mageia, opensuse, and plain.

-V,  --vendor=[MODE]

This option enables generating a spec file that builds against dependencies from a vendor tarball instead of packaged Rust crates. The default mode is off, i.e. generate a spec file for building without a vendor tarball. In auto mode, a vendor tarball is automatically generated with default settings, but both automatic and manually written patches (--patch option) are taken into account. Using manual mode skips the automatic generation of the vendor tarball and is intended to be used when manually creating a vendor tarball in cases where auto mode is not flexible enough.

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

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

-o, --offline

Avoid accessing network resources (crates.io, src.fedoraproject.org). This mode requires specifying crate versions fully on the command line, since matching versions cannot be queried from crates.io, and the corresponding .crate file needs to already have been downloaded into the cache. This flag has no effect in combination with the "--path" argument.

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

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

-r, --reuse-patch

This flag can be used to attempt re-applying an existing patch file instead of opening an editor, for example for non-interactive use or when re-running rust2rpm for a reason other than changing the patch for Cargo.toml. This flag works in conjunction with the --patch flag: If only this flag is present and the existing patch fails to apply, rust2rpm exits with an error. If both flags are present, rust2rpm falls back to opening Cargo.toml in an editor so the patch can be manually rebased.

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

-v, --validate-only

Only load configuration files, validate them, and exit. Crate metadata is not loaded in this mode, so not all configuration options can be fully validated.

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

https://pagure.io/fedora-rust/rust2rpm

rust2rpm.toml(5), rust2rpm.conf(5)

rust2rpm.conf(5), rust2rpm.toml(5).