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

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