rust2rpm/docs/rust2rpm.toml.5.asciidoc

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

*url*::
  This setting allows specifying the homepage of the packaged project which is
  used as the value of the "URL" tag in the generated spec file. This setting is
  only valid for non-crate and workspace projects and can be used when the
  upstream project does not specify a homepage or repository URL in its
  metadata.

*source-url*::
  This setting allows specifying the download URL for the source code of the
  packaged project. It is used as the value of the "Source" tag in the generated
  spec file. This setting is only valid for non-crate and workspace projects and
  can be used for persisting the download URL which cannot be known in advance
  for non-crate and workspace projects.

*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-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".

*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".

*debuginfo-level*::
  This setting allows setting the level of debuginfo that is generated by rustc.
  Valid choices are the numbers 0, 1, and 2, corresponding to the debuginfo
  levels that are supported by rustc. The default is 2. Setting a lower level
  can be a workaround for builds running out of available memory.

*cargo-toml-patch-comments*::
  This setting allows persisting comments that are associated with manually
  created patches for Cargo.toml (i.e. by running "rust2rpm -p"). The setting
  accepts a list of strings. Elements of the array are treated as individual
  comments, and individual comments are formatted and line-wrapped to 80
  characters.

*extra-sources*::
  This setting can be used to specify additional Sources to be included in the
  generated spec file. The expected value for this key is an array of objects
  with three properties - "number", "file", and "comments". The integer "number"
  is used to set a predictable number of the Source file in the spec, the "file"
  is expected to be a string that contains an URL or a plain file name, and
  "comments" is an array of strings that are formatted in the same way as the
  "cargo-toml-patch-comments" setting.

*extra-patches*::
  This setting is similar to "extra-sources" but allows specifying additional
  Patch files instead of Source files.

*extra-files*::
  This setting allows injecting additional files into the "%files" section of
  the "binary" subpackage in the generated spec file (if it exists). The value
  is expected to be an array of strings, where each element of the array will
  end up on a separate line in the "%files" list. Specifying "extra-files" for
  a library-only Rust crate has no effect.

*bin-renames*::
  This nested table can be used to specify a re-mapping of executable names
  to avoid conflicts with other packages. To cause a rename of an existing
  "bin" target with name "foo" to a new name "bar", add a key-value pair
  like foo = "bar" to this table.

=== [scripts] table

This table contains settings which allow injecting additional commands into the
"%prep", "%build", "%install", and "%check" scriptlets, both before and after
the respective "%cargo_*" macro.

There is a corresponding nested table for each of these scriptlets ("prep",
"build", "install", "check"), with two properties each ("pre" and "post") - both
of which accept an array of strings as value. Each element of these arrays is
injected as a separate line into the spec file.

=== [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".

*disable-default*::
  When enabled, this setting causes the "-n" / "--no-default-features" flag to
  be passed to all cargo calls. This should only be used in circumstances where
  applications need to be built with non-default features (for example,
  switching from the default crypto backend to OpenSSL). This setting MUST NOT
  be enabled when building library crates, since the resulting packages might
  build, but the built packages will likely fail to install.

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