= rust2rpm(1) :doctype: manpage :manmanual: rust2rpm :mansource: rust2rpm == Name rust2rpm - generate RPM spec files for Rust crates and projects == Synopsis *rust2rpm* [_OPTION_]... [_crate_] [_version_] == Description 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 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 *-, --stdout*:: Write generated spec and patch files to stdout instead of writing to files. *NOTE*: The output written by rust2rpm when using this option is hard to parse when more than one file is written. *--suffix*=_SUFFIX_:: Generate a spec file for an alternative version of a crate, applying the specified version suffix to the package name. This option has been superseded by the _--compat_ flag. *--all-features*:: Generate a spec file where the _-a_ / _--all-features_ flag will be passed to all calls of cargo. It is recommended to set this permanently in a package-specific _rust2rpm.toml(5)_ configuration file instead. *--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. * set Release and %changelog for use with rpmautospec * rely on RPM generators for setting BuildRequires, Requires, and Provides * do not set Group tag (no longer used in Fedora) === Mageia * hard-code BuildRequires in the generated spec file * rely on RPM generators for setting package Requires and Provides * generate a manual changelog entry in the format expected on Mageia * set Group tag to "Development/Rust" === OpenSUSE * hard-code BuildRequires in the generated spec file * rely on RPM generators for setting package Requires and Provides * include spec file header as exepcted for OpenSUSE packages * generate a manual changelog entry in the format expected on OpenSUSE * set Group tag to "Development/Libraries/Rust" === Plain The "plain" target has more limited requirements, and should procude working packages for environments without RPM generators for Rust crates: * hard-code BuildRequires, Requires, and Provides in the generated spec file * generate a manual changelog entry in the generic format supported by RPM == Homepage https://pagure.io/fedora-rust/rust2rpm == See also *rust2rpm.toml*(5), *rust2rpm.conf*(5)