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.
217 lines
8.6 KiB
Text
217 lines
8.6 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.
|
|
|
|
=== [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)
|