212 lines
8.5 KiB
Text
212 lines
8.5 KiB
Text
|
= 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
|
||
|
|
|
||
|
|
*--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)
|