rust2rpm/README.md

# rust2rpm

rust2rpm is a tool for automatically generating RPM spec files for Rust crates.

## `rust2rpm.conf`

If it is present, a `rust2rpm.conf` configuration file is read
by rust2rpm to override some aspects of the automatic spec file generation.

This file can be committed to dist-git to ensure that these settings
will be applied for future updates of a crate package, as well.

The file follows a slightly modified `ini` syntax. It supports sections for
default settings (`[DEFAULT]`) and target-specific settings (i.e. `[fedora]`).

These configuration options are available right now:

- `summary`: override the generated summary for the RPM package for cases where
  generating a summary from the crate's description fails
- `supported-arches`: conditionally build and run tests only on specific
  architectures (mostly useful for libraries with limited cross-platform
  support - applications need to use `ExcludeArch` or `ExclusiveArch` instead)
- `all-features`: enable all cargo features when generating `BuildRequires`,
  building the crate, and running cargo tests (defaults to `false`; setting this
  value to `true` is equivalent to supplying the `--all-features` CLI flag)
- `unwanted-features`: features or optional dependencies for which no
  `+feature` subpackage should be generated (for example, dependencies on Rust
  compiler internals for crates that are also bundled with Rust itself)
- `enabled-features`: features or optional dependencies which should be enabled
  when generating `BuildRequires` and building the crate
- `buildrequires`: additional build dependencies that must be installed for the
  package to build correctly (i.e., `pkgconfig(foo)` for the `foo-sys` crate)
- `testrequires`: additional build dependencies that must be installed for the
  package's tests to build and / or run correctly (treated like `buildrequires`,
  but wrapped in an `%if %{with check}` conditional in the generated spec)
- `lib.requires`: additional build dependencies that must be installed for the
  crate to build correctly as a dependency of another crate (usually, this
  contains the same values as the `buildrequires` option)
- `lib+foo.requires`: additional build dependencies that must be installed for
  the crate to build correctly as a dependency of another crate if it has
  enabled the optional `foo` feature
- `bin.requires`: additional runtime dependencies of the binary application that
  is built from this crate

```ini
[DEFAULT]
unwanted-features =
  compiler_builtins
  rustc-dep-of-std
enabled-features =
  important
buildrequires =
  pkgconfig(foo) >= 1.2.3
lib.requires =
  pkgconfig(foo) >= 1.2.3

[fedora]
bin.requires =
  findutils
buildrequires =
lib.requires =
lib+default.requires =
  pkgconfig(bar) >= 2.0.0
```

Note that features and optional dependencies that are marked as
`unwanted-features` must not be dependencies of other Cargo features that are
not marked "unwanted" as well. Failing to consider transitive dependencies will
lead to broken dependencies of generated `rust-foo+bar-devel` packages and / or
errors when generating spec files with rust2rpm.

Specifying a non-empty list of `enabled-features` and setting `all-features` to
`true` at the same time is not allowed.

## Testing

Invoking `tox` will automatically run the test suite on all python versions
that should be supported.

Use `python -m pytest -v` or `PYTHONPATH=. pytest -v` in the source tree
(possibly within a virtualenv) to run the tests manually.