= 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)
