Fabio Valentini
f579129792
Remove documentation for rust2rpm.conf file format from the README. The custom INI-based format is deprecated in favor of rust2rpm.toml. Both formats are documented, including a migration guide from the old to the new format. The included build script shows how to build man pages from the asciidoc source files.
226 lines
9.1 KiB
Text
226 lines
9.1 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
|
|
|
|
*-, --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)
|