Fabio Valentini
139bac2eca
rust-packaging >= 26 now has "official" support for overriding the installation of library sources / binary targets by setting RPM macros. This commit adds settings to correspond to the %cargo_install_lib and %cargo_install_bin macros and plugs them through to the spec generator. References to the the private %__cargo_is_bin and %__cargo_is_lib macros, which could previously be used to hack this behaviour, were removed.
234 lines
9.5 KiB
Text
234 lines
9.5 KiB
Text
= rust2rpm.toml(5)
|
|
|
|
:doctype: manpage
|
|
:manmanual: rust2rpm
|
|
:mansource: rust2rpm
|
|
|
|
== Name
|
|
|
|
rust2rpm.toml - package-specific configuration file for *rust2rpm*
|
|
|
|
== Description
|
|
|
|
Many aspects of *rust2rpm*(1) can be configured by setting package-specific
|
|
preferences in a *rust2rpm.conf* file. If a file with this name is present in
|
|
the current working directory when running rust2rpm, it is loaded automatically.
|
|
This is especially useful for changes that need to be permanently applied to
|
|
generated spec files.
|
|
|
|
== Options
|
|
|
|
The settings in *rust2rpm.toml* are split into different sections ("tables").
|
|
|
|
=== [package] table
|
|
|
|
This table contains settings that affect RPM metadata.
|
|
|
|
*summary*::
|
|
This setting is used to override the value of the RPM "Summary" tag and can be
|
|
used if the summary generated from crate metadata based on heuristics is not
|
|
good enough. Accepts a TOML string.
|
|
|
|
*description*::
|
|
This setting is used to override the value of the RPM %description. Accepts a
|
|
TOML string (for longer / multi-line descriptions, triple-quoted multi-line
|
|
strings can be used).
|
|
|
|
*supported-arches*::
|
|
This setting can be used to specify that the crate only has support for
|
|
limited architectures (i.e. not all CPU architectures that are supported by
|
|
the distribution). This setting accepts TOML array of strings. If this setting
|
|
is present, the "cargo build" and "cargo test" steps in the generated spec
|
|
file are wrapped with "%ifarch" conditionals.
|
|
|
|
*bin-package-name*::
|
|
This setting can be used to override the name of the subpackage that is
|
|
generated if there are any "bin" (or "cdylib") targets. The default is to
|
|
fall back to the name of the current crate ("%{crate}").
|
|
|
|
*cargo-install-lib*::
|
|
This setting controls whether library sources are installed by the
|
|
%cargo_install macro. Setting "false" for this key causes crate sources not
|
|
to be installed to %{crate_instdir} even if a library target is auto-detected
|
|
or the crate defines a [lib] target explicitly. The default value is "true".
|
|
|
|
*cargo-install-bin*::
|
|
This setting controls whether binary targets are installed by the
|
|
%cargo_install macro. Setting "false" for this key causes "bin" targets not
|
|
to be installed to %{_bindir} even if a "bin" target is auto-detected or the
|
|
crate defines any "bin" target explicitly. The default value is "true".
|
|
|
|
=== [tests] table
|
|
|
|
This table contains settings that control which tests are run. If any settings
|
|
that restrict which tests are run are present, the *comments* setting should
|
|
also be added with an explanation of *why* the tests are disabled.
|
|
|
|
*run*::
|
|
Specific (or all) tests can be turned off with this setting. It accepts a TOML
|
|
array of strings (with only "none", "all", "lib", "bin", "doc", "bins", and
|
|
"tests" being accepted values). Neither "none" or "all" can be used in
|
|
combination with other settings, but other settings can be combined freely. +
|
|
If this setting is not specified, the default is equivalent to "all" (i.e.
|
|
all tests are run, no arguments are passed to "cargo test"). If the setting
|
|
is set to "none", the "check" bcond is turned off. The other options specify
|
|
that only some parts of the cargo test suite are run.
|
|
|
|
*skip*::
|
|
This setting can be used to skip specific tests. They are passed as "--skip"
|
|
arguments to the cargo test harness. Accepts a TOML array of strings.
|
|
|
|
*skip-exact*::
|
|
This setting contols whether tests are skipped based on substring match
|
|
(the default) or only on exact match. Unless there is a large number of
|
|
skipped tests, it is recommended to enable this setting to avoid skipping
|
|
too many / unrelated tests. Accepts a TOML boolean. If this setting is
|
|
unspecified, the default behaviour is equivalent to setting it to "false".
|
|
|
|
*comments*::
|
|
Whenever any tests (or kinds of tests) are skipped or disabled, it is
|
|
strongly recomemended to add short comments (or links to upstream issues)
|
|
that explain *why* that is the case. Accepts a TOML array of strings.
|
|
The comment text is automatically formatted, line-wrapped to 80 columns,
|
|
and prefixed with "#". If *run* is set to *["none"]*, the comments are
|
|
added just before the disabled "check" bcond. Otherwise, the comments
|
|
are added just before the "%cargo_test" macro calls.
|
|
|
|
=== [features] table
|
|
|
|
The [features] table wraps settings that pertain to crate "features" and feature
|
|
flags that are passed to cargo.
|
|
|
|
*enable-all*::
|
|
When enabled, this setting causes the "-a" / "--all-features" flag to be
|
|
passed to all cargo calls. This can be used for crates where running tests
|
|
requires optional features to be enabled, or for applications where enabling
|
|
all features is desirable. Accepts a TOML boolean. Setting *enable-all* to
|
|
"true" requires the *enable* setting to be unspecified or to be an empty
|
|
array. The default behaviour if this setting is not specified is equivalent
|
|
to setting it to "false".
|
|
|
|
*enable*::
|
|
This setting provides more fine-grained control for passing feature flags to
|
|
cargo calls. Accepts a TOML array of strings that must be valid feature names.
|
|
Setting *enable* to a non-empty array requires the *enable-all* setting to be
|
|
unspecified or to be "false".
|
|
|
|
*hide*::
|
|
This setting can be used to prevent subpackages for crate features and
|
|
implicit features for optional dependencies from being generated in the spec
|
|
file. For example, this can be useful for crates that have unused non-default
|
|
features which pull in additional dependencies. Accepts a TOML array of
|
|
strings that must be valid feature names / names of optional dependencies with
|
|
associated implicit features. +
|
|
*NOTE*: Care needs to be taken to only "hide" features / optional dependencies
|
|
that are not dependencies of other "non-hidden" features, otherwise the
|
|
subpackages for the dependent features will have unsatisfiable dependencies.
|
|
All features that are marked as "hidden" by this setting must be "unreachable"
|
|
via feature dependencies from any feature subpackages that are still present
|
|
in the generated spec file. In some circumstances, the only way to cleanly
|
|
handle removal of unused non-default features is to patch Cargo.toml instead.
|
|
|
|
=== [requires] table
|
|
|
|
Additional RPM dependencies (Requires) for different types of subpackages can
|
|
be specified with settings in the [requires] table.
|
|
|
|
*build*::
|
|
Additional BuildRequires for the package can be specified with this setting.
|
|
Accepts a TOML array of strings that must be valid RPM dependency identifiers.
|
|
The BuildRequires included in this setting are either added in the
|
|
%generare_buildrequires scriptlet for targets where this is enabled, or as
|
|
plain BuildRequires for targets without dynamically generated BuildRequires.
|
|
|
|
*test*::
|
|
This setting allows specifying additional BuildRequires that are only needed
|
|
when running a project's test suite (i.e. "cargo test"). It works the same as
|
|
the setting for additional BuildRequires, except that all entries are wrapped
|
|
in an "%if %{with check}" conditional.
|
|
|
|
*lib*::
|
|
With this setting, additional dependencies (Requires) for the main "-devel"
|
|
subpackage of a "library crate" can be specified. For example, many "-sys"
|
|
bindings require the development headers for the wrapped C library to be
|
|
present during both build time of the package for the crate itself *and*
|
|
when building a package that depends on this crate. In these cases, the same
|
|
dependency often needs to be added in both _requires.build_ and
|
|
_requires.lib_. Accepts a TOML array of strings that must be valid RPM
|
|
dependency identifiers.
|
|
|
|
*bin*::
|
|
For crates that include application binaries / executables, this setting can
|
|
be used to add additional dependencies for the subpackage that contains these
|
|
executables. Accepts a TOML array of strings that must be valid RPM dependency
|
|
identifiers.
|
|
|
|
*features*::
|
|
This nested table can be used to specify additional dependencies for "feature
|
|
subpackages". The keys in this table must be valid names of crate features or
|
|
names of optional dependencies with associated implicit features, and values
|
|
are expected to be TOML arrays of strings that must be valid RPM dependency
|
|
identifiers.
|
|
|
|
== Migrating from rust2rpm.conf
|
|
|
|
The manual page for *rust2rpm.conf*(5) contains simple guide for migrating
|
|
old configuration files to TOML.
|
|
|
|
== Examples
|
|
|
|
=== Bindings for system libraries
|
|
|
|
One typical use case for a *rust2rpm.toml* file are in packages for crates that
|
|
contain bindings for system libraries, especially if crate features are used to
|
|
control which APIs of the library are made available.
|
|
|
|
Example file equivalent to the *rust2rpm.conf* example for "gtk4-sys" version
|
|
0.7.3 on Fedora 38, where version 4.10 of gtk4 is available:
|
|
|
|
[source,toml]
|
|
----
|
|
[features]
|
|
hide = ["v4_12", "v4_14"]
|
|
|
|
[requires]
|
|
build = ["pkgconfig(gtk4) >= 4.0.0"]
|
|
lib = ["pkgconfig(gtk4) >= 4.0.0"]
|
|
|
|
[requires.features]
|
|
v4_2 = ["pkgconfig(gtk4) >= 4.2"]
|
|
v4_4 = ["pkgconfig(gtk4) >= 4.4"]
|
|
v4_6 = ["pkgconfig(gtk4) >= 4.6"]
|
|
v4_8 = ["pkgconfig(gtk4) >= 4.7"]
|
|
v4_10 = ["pkgconfig(gtk4) >= 4.10"]
|
|
----
|
|
|
|
=== External dependencies of the Rust standard library
|
|
|
|
The Rust standard library depends on some crates that are also published
|
|
separately, and a "hack" is used when building these crates as part of "std".
|
|
The crate features and optional dependencies that are used for this purpose
|
|
are useless in other situations.
|
|
|
|
Example file from the package for "libc" version 0.2.149:
|
|
|
|
[source,toml]
|
|
----
|
|
[features]
|
|
hide = [
|
|
"rustc-dep-of-std",
|
|
"rustc-std-workspace-core",
|
|
]
|
|
|
|
[requires]
|
|
build = ["glibc-devel"]
|
|
lib = ["glibc-devel"]
|
|
----
|
|
|
|
== Homepage
|
|
|
|
https://pagure.io/fedora-rust/rust2rpm
|
|
|
|
== See also
|
|
|
|
*rust2rpm*(1), *rust2rpm.conf*(5)
|