rust2rpm.toml - Man Page

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 can be used to override the default homepage (the crate page on crates.io).

supported-arches / unsupported-arches

These settings 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). Both settings accept a TOML array of strings as value. Only one of them can be present (i.e. they are mutually exclusive). If either setting is present and non-empty, the "cargo build" and "cargo test" steps in the generated spec file are wrapped with "%ifarch" or "%ifnarch" conditionals. NOTE: This likely does not have the expected effect when used for crates that contain executable targets (i.e. "bin" compilation targets), since these are attempted to be built by "%cargo_install" if they were not already built. In this case, add ExclusiveArch or ExcludeArch tags to the spec file instead of using this setting.

suppress-cdylib-install-fixme

This setting can be used to prevent generation of a FIXME comment for projects that build a "cdylib" crate target. Usually this should be used in conjunction with the "scripts.install.post" setting to handle installation. This setting accepts boolean values. The default behaviour is equivalent to specifying false for this setting.

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.

license-files

This setting can be used to override the heuristics for detecting "%license" files of a project. It accepts either a list of strings (to override automatic detection entirely) or an object with "include" and / or "exclude" properties, both of which accept lists of strings. In both cases, all values are interpreted as paths or globs relative to the project root.

doc-files

This setting can be used to override the heuristics for detecting "%doc" files of a project. It accepts either a list of strings (to override automatic detection entirely) or an object with "include" and / or "exclude" properties, both of which accept lists of strings. In both cases, all values are interpreted as paths or globs relative to the project root.

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.

exclude-crate-files

This setting allows specifying a list of files (or directories) that should be "%exclude"d from installed crate sources in built rust-$crate-devel packages. This setting accepts a list of strings, which are all treated as paths relative to the crate root directory.

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.

package-extra

If present, the string in this setting is injected into the generated spec file verbatim after the definition of the "binary" package (if present) and before the definitions of the "-devel" subpackages (if present). This can be used to define custom additional subpackages.

bin-package-extra

If present, the string in this setting is injected into the generated spec file verbatim in the definition of the "binary" package between its License tag and its %description. This can be used to inject additional RPM metadata (i.e. Recommends, Suggests, Provides, etc.) or custom RPM scriptlets (like %post, %pre, %postun, etc.).

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.

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 boolean or a TOML array of strings (with only "lib", "bins", "bin:name", "test:name", and "doc" being accepted values) - or a single string from this list.
If this setting is not specified, the default is equivalent to true (i.e. all tests are run, no arguments are passed to "cargo test"). If the setting is set to false, 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 when the specified tests should be skipped for all run targets, or a mapping from run target names to arrays of strings.

skip-exact

This setting controls 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 when the "--exact" flag should be passed for all run targets, or a mapping from run target names to booleans when the flag should only be passed to some targets. If this setting is unspecified, the default behaviour is equivalent to setting it to 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. The comment text is automatically formatted, line-wrapped to 80 columns, and prefixed with "#". If run is set to false, the comments are added just before the disabled "check" bcond. Otherwise, the comments are added just before the "%cargo_test" macro calls. Accepts a TOML array of strings when comments should apply to all tests, or a mapping from run target names to arrays of strings when comments should get associated with specific targets.

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.

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.

In some cases, the "package.description" in crate metadata really isn’t very meaningful, or fails to automatically be shortened by the heuristics implemented in rust2rpm. In cases like this, both the Summary tag and / or the package %description can be overridden:

[package]
summary = "Very meaningful and concise package summary"
description = """\
Multi-line
pre-formatted
package
description.
"""

By default, the URL tag contains a link to the crate page on crates.io. In some cases, it might be desirable to override this with a URL to the actual project homepage:

[package]
url = "https://forge.me/org/repo"

Some Rust crates only support certain CPU architectures (or their dependencies are only available on limited architectures). For library crates, these settings can be used to limit the architectures on which the crate is built and tests are run (but the "-devel" packages with source code are still built to avoid broken dependencies):

[package]
supported-arches = ["x86_64", "aarch64"]
#unsupported-arches = ["s390x"]

Note that the package.supported-arches and package.unsupported-arches settings are mutually exclusive.

When packaging Rust crates, it’s sometimes not desirable to package source code when only built executables or shared libraries are of interest, or vice versa, to ship executables when only the library interface / source code is needed. In these cases, installation of source code or executables can be suppressed:

[package]
# not interested in shipping the library sources
cargo-install-lib = false

[package]
# not interested in shipping executables
cargo-install-bin = false

Compilation of some large Rust projects can hit memory limits during the linking stage, especially on 32-bit x86 (i686). In this case, it can be helpful to limit the verbosity of generated debug symbols:

[package]
debuginfo-level = 1

There are situations that require permanently patching Cargo.toml downstream, in which cases it can be useful to store the comments associated with that patch to ensure they’re not lost (and rust2rpm fails if comments are specified but no actual changes to Cargo.toml are applied):

[package]
cargo-toml-patch-comments = [
    "remove a bad dependency",
    "bump foo dependency from v1 to v2",
]

Determining which files in a crate archive should be marked as %license and which should be marked as %doc is based on heuristics that can be wrong. But there are settings available to override the automatically determined lists of files. Both including / excluding specific files from the automatically generated list and overriding the lists completely is possible, and all three options support globs:

[package]
doc-files.include = ["LIESMICH.txt"]
doc-files.exclude = ["requirements.txt"]
license-files = [".licenses/*"]

[package]
doc-files = ["README.md"]
license-files.exclude = ["**/*.rs"]

In some cases it’s necessary to include additional Source or Patch files in source packages, for example, when test input data is supplied by an additional tarball, or when there are additional downstream patches needed to build a package. Both cases can be automated with settings:

[[package.extra-sources]]
number = 2
file = "https://example.forge/org/project/archive/v1.0.2/extra-test-data-1.0.2.tar.gz"
comments = ["upstream archive that contains additional data for tests"]

[[package.extra-sources]]
number = 3
file = "foo.1"
comments = ["hand-written manual page"]

[[package.extra-patches]]
number = 2
file = "0001-dynamically-link-sqlite.patch"
comments = ["force dynamically linking with system sqlite"]

The Source and Patch file number is required to be specified, because in most cases, these files will also need to be referenced by number in RPM scriplets (i.e. when unpacking / installing additional sources, or when applying patches).

In some cases, files need to be excluded from packages for "crate" sources, but submitting a patch to the upstream project to exclude them from published crates isn’t desirable (for example, files that are necessary during testing only). For this purpose, files that are to be excluded from packages for Rust crates can be specified in settings:

[package]
exclude-crate-files = ["tests/gen.py"]

It’s possible that the default executable name shipped by Rust crates conflicts with other packages that are already available. In this case, it’s easy to cause these programs to get renamed in packaging to avoid conflicts:

[package.bin-renames]
cp = "uu_cp"

It is not feasible for rust2rpm to support controlling all aspects and features of RPM spec files, so there is a simple way to inject additional metadata (or even entire subpackage definitions) into generated spec files:

[package]
package-extra = """\
%package     -n %{crate}-devel
Summary:        %{summary}

Requires:       %{crate}%{?_isa} = %{version}-%{release}

%description -n %{crate}-devel %{_description}

This package contains libraries and header files for developing applications
that use the "%{crate}" crate via a C API.

%files       -n %{crate}-devel
%{_includedir}/foo/foo.h
%{_libdir}/%{crate}.so
%{_libdir}/pkgconfig/%{crate}.pc\
"""

For cases where additional RPM metadata needs to be associated with the automatically generated subpackage for built executables, this can be handled with a setting too:

[package]
bin-package-extra = """\
# additionally provide the upstream name
Provides:       %{crate} = %{version}-%{release}
"""

If a package requires any additional steps as part of the build process (the prep, build, install, and check scriptlets), this can easily be automated with the "scripts" group of settings:

[scripts]
prep.pre = [
    "# drop vendored C library sources",
    "rm -rf foo-1.2.3/",
]
prep.post = [
    "echo hello",
]
build.pre = [
    "# export version for build script",
    "export FOO_VERSION=%{version}",
]
build.post = [
    "# generate shell completions",
    "target/rpm/foo completions bash > foo.bash",
]
install.pre = [
    # no idea what could happen here
]
install.post = [
    "# install shell completions",
    "install -Dpm0644 foo.bash %{buildroot}/%{bash_completions_dir}/foo.bash",
]
check.pre = [
    "# unpack additional test sources",
    "tar -xzvf foo",
]
check.post = [
    # not sure what could happen here either, but hey, it's here if you need it
]

It’s also possible to inject dynamically generated BuildRequires, when statically defining them as BuildRequires is not possible:

[scripts]
genbr.post = [
    "pushd xtask >/dev/null",
    "%cargo_generate_buildrequires",
    "popd >/dev/null",
]

In many cases, not all tests that are run by "cargo test" can be run in build environments for various common reasons:

• Tests introduce additional, unpackaged dependencies.
• Tests require hardware or internet access.
• Tests require data files that are not included in published crates.
• Tests expect to be run in the project’s pre-publishing workspace directory layout.

There are settings to enable or disable tests on both fine-grained and coarse levels:

[tests]
# run no tests
run = false
comments = ["tests require "]

Skip one specific test by exact name match:

[tests]
skip = ["test_internet_access"]
skip-exact = true
comments = ["skip one test that requires internet access"]

Skip groups of tests by name substring match:

[tests]
skip = ["test_privileged_"]
comments = ["skip tests that require elevated privileges"]

Only run specific kinds of tests:

[tests]
# run only unit tests, doctests, and the "foo" integration tests
run = ["lib", "test:foo"]
comments = ["doctests can only be compiled and run from within the whole workspace"]

Most settings can be combined freely:

[tests]
# skip some unit and integration tests, but run all doctests
run = ["lib", "doc", "test:foo"]

skip.lib = ["test_priv_"]
comments.lib = ["skip running tests that require elevated privileges"]

skip.'test:foo' = ["test_poke_hardware"]
skip-exact.'test:foo' = true
comments.'test:foo' = ["skip running tests that require hardware access"]

Sometimes it is necessary to build Rust crates with additional (i.e. not enabled by default) feature flags - for example, when building applications with additional features, or when running tests for the full feature set of a library.

Enable additional feature flags:

[features]
enable = ["foo", "bar"]

Enable all features:

[features]
enable-all = true

In some cases, generating subpackages for some crate feature flags is unwanted or unnecessary (for example, when those features are "development only" or would pull in additional dependencies):

[features]
hide = [
    "nightly",
    "unstable",
    "__internal_test_only",
]

When packaging Rust crates that contain bindings for C/C++ libraries it’s frequently necessary to associate additional dependencies with the package and / or specific subpackages:

[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"]