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.
195 lines
7.8 KiB
Text
195 lines
7.8 KiB
Text
= rust2rpm.conf(5)
|
|
|
|
:doctype: manpage
|
|
:manmanual: rust2rpm
|
|
:mansource: rust2rpm
|
|
|
|
== Name
|
|
|
|
rust2rpm.conf - package-specific configuration file for *rust2rpm* (deprecated)
|
|
|
|
== Description
|
|
|
|
Some 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 configuration file format is *deprecated* and has been superseded by
|
|
*rust2rpm.toml*(5), which supports a superset of the settings that are available
|
|
in *rust2rpm.conf*.
|
|
|
|
The file format for *rust2rpm.conf* is based on the INI format as implemented in
|
|
the *configparser* module from the Python standard library. Notably, settings in
|
|
the [DEFAULT] section can be overridden by target-specific settings (i.e. with
|
|
settings under a [fedora], [mageia], or [plain] section). This rarely used
|
|
support for layered settings has not been implemented in *rust2rpm.toml*(5).
|
|
|
|
== Options
|
|
|
|
*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.
|
|
|
|
*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 a line-separated / indented list of
|
|
target architectures. If this setting is present, the "cargo build" and
|
|
"cargo test" steps in the generated spec file are wrapped with "%ifarch"
|
|
conditionals.
|
|
|
|
*all-features*::
|
|
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. This setting accepts a "bool-like" value. Setting
|
|
*all-features* to true-ish requires the *enabled-features* setting to be
|
|
unspecified or to be empty.
|
|
|
|
*enabled-features*::
|
|
This setting provides more fine-grained control for passing feature flags to
|
|
cargo calls. It accepts a line-separated / indented list of names of enabled
|
|
features. Setting *enabled-features* to a non-empty list requires the
|
|
*all-features* setting to be unspecified or to be false-ish.
|
|
|
|
*unwanted-features*::
|
|
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. It accepts a line-separated /
|
|
indented list of names of "unwanted" crate 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 "unwanted" 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.
|
|
|
|
*buildrequires*::
|
|
Additional BuildRequires for the package can be specified with this setting.
|
|
It accepts a line-separated / indented list of BuildRequires in the syntax
|
|
supported by RPM. 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.
|
|
|
|
*testrequires*::
|
|
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.requires*::
|
|
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 as both _buildrequires_ and _lib.requires_.
|
|
This setting accepts a list of line-separated / indented RPM dependencies.
|
|
|
|
*lib+foo.requires*::
|
|
This setting works just like _lib.requires_, except for adding additional
|
|
dependencies to subpackages for crate features. It can be specified multiple
|
|
times, and dependencies listed for "foo" are added to the "-devel" subpackage
|
|
for feature "foo" instead. Only valid feature names are accepted, specifying
|
|
a non-existent feature will cause a validation failure.
|
|
|
|
*bin.requires*::
|
|
For crates that include application binaries / executables, this setting can
|
|
be used to add additional dependencies for the subpackage that contains these
|
|
executables. The accepted values are line-separated / indented strings that
|
|
are valid RPM dependencies.
|
|
|
|
== Migrating to rust2rpm.toml
|
|
|
|
The *rust2rpm.toml*(5) configuration file format supports a superset of the
|
|
settings available in *rust2rpm.conf*, except that "layered" configuration is
|
|
not supported.
|
|
|
|
* *summary*: moved to the "summary" setting in the [package] table,
|
|
accepts a TOML string
|
|
* *supported-arches*: moved to the "supported-arches" setting in the [package]
|
|
table, accepts a TOML array of strings
|
|
* *all-features*: moved to the "enable-all" setting in the [features] table,
|
|
accepts a TOML boolean
|
|
* *enabled-features*: moved to the "enable" setting in the [features] table,
|
|
accepts a TOML array of strings
|
|
* *unwanted-features*: moved to the "hide" setting in the [features] table,
|
|
accepts a TOML array of strings
|
|
* *buildrequires*: moved to the "build" setting in the [requires] table,
|
|
accepts a TOML array of strings
|
|
* *testrequires*: moved to the "test" setting in the [requires] table, accepts
|
|
a TOML array of strings
|
|
* *lib.requires*: moved to the "lib" setting in the [requires] table, accepts
|
|
a TOML array of strings
|
|
* *bin.requires*: moved to the "bin" setting in the [requires] table, accepts
|
|
a TOML array of strings
|
|
* *lib+foo.requires*: moved to the "features" table in the [requires] table,
|
|
accepts a table with keys that must match feature names, and TOML arrays
|
|
of strings as values
|
|
|
|
== Examples
|
|
|
|
=== Bindings for system libraries
|
|
|
|
One typical use case for a *rust2rpm.conf* 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 from the package for "gtk4-sys" version 0.7.3 on Fedora 38, where
|
|
version 4.10 of gtk4 is available:
|
|
|
|
[source,ini]
|
|
----
|
|
[DEFAULT]
|
|
unwanted-features =
|
|
v4_12
|
|
v4_14
|
|
buildrequires =
|
|
pkgconfig(gtk4) >= 4.0.0
|
|
lib.requires =
|
|
pkgconfig(gtk4) >= 4.0.0
|
|
lib+v4_2.requires =
|
|
pkgconfig(gtk4) >= 4.2
|
|
lib+v4_4.requires =
|
|
pkgconfig(gtk4) >= 4.4
|
|
lib+v4_6.requires =
|
|
pkgconfig(gtk4) >= 4.6
|
|
lib+v4_8.requires =
|
|
pkgconfig(gtk4) >= 4.7
|
|
lib+v4_10.requires =
|
|
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.148:
|
|
|
|
[source,ini]
|
|
----
|
|
[DEFAULT]
|
|
unwanted-features =
|
|
rustc-dep-of-std
|
|
rustc-std-workspace-core
|
|
buildrequires =
|
|
glibc-devel
|
|
lib.requires =
|
|
glibc-devel
|
|
----
|
|
|
|
== Homepage
|
|
|
|
https://pagure.io/fedora-rust/rust2rpm
|
|
|
|
== See also
|
|
|
|
*rust2rpm*(1), *rust2rpm.toml*(5)
|