1RUST2RPM.TOML(5) rust2rpm RUST2RPM.TOML(5)
2
6 rust2rpm.toml - package-specific configuration file for *rust2rpm*
7
9 Many aspects of rust2rpm(1) can be configured by setting
10 package-specific preferences in a rust2rpm.conf file. If a file with
11 this name is present in the current working directory when running
12 rust2rpm, it is loaded automatically. This is especially useful for
13 changes that need to be permanently applied to generated spec files.
14
16 The settings in rust2rpm.toml are split into different sections
17 ("tables").
18 [package] table
20 This table contains settings that affect RPM metadata.
21 summary
23 This setting is used to override the value of the RPM "Summary" tag
24 and can be used if the summary generated from crate metadata based
25 on heuristics is not good enough. Accepts a TOML string.
26 description
28 This setting is used to override the value of the RPM %description.
29 Accepts a TOML string (for longer / multi-line descriptions,
30 triple-quoted multi-line strings can be used).
31 supported-arches
33 This setting can be used to specify that the crate only has support
34 for limited architectures (i.e. not all CPU architectures that are
35 supported by the distribution). This setting accepts TOML array of
36 strings. If this setting is present, the "cargo build" and "cargo
37 test" steps in the generated spec file are wrapped with "%ifarch"
38 conditionals.
39 [tests] table
41 This table contains settings that control which tests are run. If any
42 settings that restrict which tests are run are present, the comments
43 setting should also be added with an explanation of why the tests are
44 disabled.
45 run
47 Specific (or all) tests can be turned off with this setting. It
48 accepts a TOML array of strings (with only "none", "all", "lib",
49 "bin", "doc", "bins", and "tests" being accepted values). Neither
50 "none" or "all" can be used in combination with other settings, but
51 other settings can be combined freely.
52 If this setting is not specified, the default is equivalent to
53 "all" (i.e. all tests are run, no arguments are passed to "cargo
54 test"). If the setting is set to "none", the "check" bcond is
55 turned off. The other options specify that only some parts of the
56 cargo test suite are run.
57 skip
59 This setting can be used to skip specific tests. They are passed as
60 "--skip" arguments to the cargo test harness. Accepts a TOML array
61 of strings.
62 skip-exact
64 This setting contols whether tests are skipped based on substring
65 match (the default) or only on exact match. Unless there is a large
66 number of skipped tests, it is recommended to enable this setting
67 to avoid skipping too many / unrelated tests. Accepts a TOML
68 boolean. If this setting is unspecified, the default behaviour is
69 equivalent to setting it to "false".
70 comments
72 Whenever any tests (or kinds of tests) are skipped or disabled, it
73 is strongly recomemended to add short comments (or links to
74 upstream issues) that explain why that is the case. Accepts a TOML
75 array of strings. The comment text is automatically formatted,
76 line-wrapped to 80 columns, and prefixed with "#". If run is set to
77 ["none"], the comments are added just before the disabled "check"
78 bcond. Otherwise, the comments are added just before the
79 "%cargo_test" macro calls.
80 [features] table
82 The [features] table wraps settings that pertain to crate "features"
83 and feature flags that are passed to cargo.
84 enable-all
86 When enabled, this setting causes the "-a" / "--all-features" flag
87 to be passed to all cargo calls. This can be used for crates where
88 running tests requires optional features to be enabled, or for
89 applications where enabling all features is desirable. Accepts a
90 TOML boolean. Setting enable-all to "true" requires the enable
91 setting to be unspecified or to be an empty array. The default
92 behaviour if this setting is not specified is equivalent to setting
93 it to "false".
94 enable
96 This setting provides more fine-grained control for passing feature
97 flags to cargo calls. Accepts a TOML array of strings that must be
98 valid feature names. Setting enable to a non-empty array requires
99 the enable-all setting to be unspecified or to be "false".
100 hide
102 This setting can be used to prevent subpackages for crate features
103 and implicit features for optional dependencies from being
104 generated in the spec file. For example, this can be useful for
105 crates that have unused non-default features which pull in
106 additional dependencies. Accepts a TOML array of strings that must
107 be valid feature names / names of optional dependencies with
108 associated implicit features.
109 NOTE: Care needs to be taken to only "hide" features / optional
110 dependencies that are not dependencies of other "non-hidden"
111 features, otherwise the subpackages for the dependent features will
112 have unsatisfiable dependencies. All features that are marked as
113 "hidden" by this setting must be "unreachable" via feature
114 dependencies from any feature subpackages that are still present in
115 the generated spec file. In some circumstances, the only way to
116 cleanly handle removal of unused non-default features is to patch
117 Cargo.toml instead.
118 [requires] table
120 Additional RPM dependencies (Requires) for different types of
121 subpackages can be specified with settings in the [requires] table.
122 build
124 Additional BuildRequires for the package can be specified with this
125 setting. Accepts a TOML array of strings that must be valid RPM
126 dependency identifiers. The BuildRequires included in this setting
127 are either added in the %generare_buildrequires scriptlet for
128 targets where this is enabled, or as plain BuildRequires for
129 targets without dynamically generated BuildRequires.
130 test
132 This setting allows specifying additional BuildRequires that are
133 only needed when running a project’s test suite (i.e. "cargo
134 test"). It works the same as the setting for additional
135 BuildRequires, except that all entries are wrapped in an "%if
136 %{with check}" conditional.
137 lib
139 With this setting, additional dependencies (Requires) for the main
140 "-devel" subpackage of a "library crate" can be specified. For
141 example, many "-sys" bindings require the development headers for
142 the wrapped C library to be present during both build time of the
143 package for the crate itself and when building a package that
144 depends on this crate. In these cases, the same dependency often
145 needs to be added in both requires.build and requires.lib. Accepts
146 a TOML array of strings that must be valid RPM dependency
147 identifiers.
148 bin
150 For crates that include application binaries / executables, this
151 setting can be used to add additional dependencies for the
152 subpackage that contains these executables. Accepts a TOML array of
153 strings that must be valid RPM dependency identifiers.
154 features
156 This nested table can be used to specify additional dependencies
157 for "feature subpackages". The keys in this table must be valid
158 names of crate features or names of optional dependencies with
159 associated implicit features, and values are expected to be TOML
160 arrays of strings that must be valid RPM dependency identifiers.
161
163 The manual page for rust2rpm.conf(5) contains simple guide for
164 migrating old configuration files to TOML.
165
167 Bindings for system libraries
168 One typical use case for a rust2rpm.toml file are in packages for
169 crates that contain bindings for system libraries, especially if crate
170 features are used to control which APIs of the library are made
171 available.
172 Example file equivalent to the rust2rpm.conf example for "gtk4-sys"
174 version 0.7.3 on Fedora 38, where version 4.10 of gtk4 is available:
175 [features]
177 hide = ["v4_12", "v4_14"]
178 [requires]
180 build = ["pkgconfig(gtk4) >= 4.0.0"]
181 lib = ["pkgconfig(gtk4) >= 4.0.0"]
182 [requires.features]
184 v4_2 = ["pkgconfig(gtk4) >= 4.2"]
185 v4_4 = ["pkgconfig(gtk4) >= 4.4"]
186 v4_6 = ["pkgconfig(gtk4) >= 4.6"]
187 v4_8 = ["pkgconfig(gtk4) >= 4.7"]
188 v4_10 = ["pkgconfig(gtk4) >= 4.10"]
189 External dependencies of the Rust standard library
191 The Rust standard library depends on some crates that are also
192 published separately, and a "hack" is used when building these crates
193 as part of "std". The crate features and optional dependencies that are
194 used for this purpose are useless in other situations.
195 Example file from the package for "libc" version 0.2.149:
197 [features]
199 hide = [
200 "rustc-dep-of-std",
201 "rustc-std-workspace-core",
202 ]
203 [requires]
205 build = ["glibc-devel"]
206 lib = ["glibc-devel"]
207
209 https://pagure.io/fedora-rust/rust2rpm
210
212 rust2rpm(1), rust2rpm.conf(5)
213rust2rpm 2023-12-08 RUST2RPM.TOML(5)