Safe and Idiomatic Rust Bindings for libdnf5

Warning

Depending on how this crate is received, this crate may continue development and the API may change between releases. If you use it today, please pin a commit or version and expect some breaking updates.

This workspace provides Rust bindings to the libdnf5 C++ library so your Rust code can interact with DNF's functionalities in a safe, ergonomic way. The bindings hide the unsafe C++ details behind a small set of helper C++ functions and a clean Rust facade.

Quick overview

• The low-level FFI layer is implemented with the cxx crate: small C++ helper functions (in libdnf5/src and libdnf5/include) expose the functionality we need from libdnf5 to Rust.
• The Rust side (in libdnf5/src/lib.rs and libdnf5/src/bridge.rs) wraps those cxx bindings with safe, idiomatic types and methods (Context, RepoSack, Package, PackageSet, Transaction, etc.).
• API documentation is generated from the Rust docs and is the canonical reference for the Rust API.

Getting Started

• Rust and Cargo
• A C++ toolchain capable of compiling the C++ helper sources (g++ or clang++)
• libdnf5 installed on your system and discoverable via pkg-config. See installation at the official libdnf5 documentation. If libdnf5 is installed in a non-standard path, ensure PKG_CONFIG_PATH or the compiler include/library paths are adjusted appropriately.

Generating the Rust API docs

To generate the Rust API docs for the bindings run:

cargo doc -p libdnf5 --no-deps

The generated docs are the API reference listing methods, types, and doc comments produced from the Rust facade (for example, libdnf5/src/lib.rs). We will keep libdnf5/src/lib.rs docs up to date as the API evolves.

Building and running

This repository is a Cargo workspace. From the repo root you can build individual crates or the whole workspace:

cargo build                   # builds workspace
cargo build -p libdnf5         # build the bindings crate

There are small example crates in this workspace:

• demo/ — basic usage examples and a small runnable demo
• dnf/ — cli tool that implements the libdnf5 rust bindings

How the bindings work (short)

1. We call into libdnf5's C++ API from small helper functions written in C++.
2. Those helper functions are exposed to Rust using the cxx crate and a small bridge module (libdnf5/src/bridge.rs).
3. A safe Rust facade (libdnf5/src/lib.rs) wraps the cxx types and presents idiomatic Rust types (Context, RepoSack, Package, PackageSet, Transaction, etc.) that perform checks and convert error cases into anyhow::Result.

Where to look in the repo

• libdnf5/include/: C++ header helpers for the FFI layer (C++ declarations used by the bridge)
• libdnf5/src/: C++ helper implementations and Rust facade/bridge code
  • libdnf5/src/bridge.rs: cxx bridge definitions
  • libdnf5/src/lib.rs: high-level Rust API (what you will call from Rust code)
• demo/, dnf/: example binaries
• repo_samples/: sample repo files used by demos/tests

Usage notes

• The facade methods return anyhow::Result and try to surface meaningful errors when the underlying C++ call fails.
• Many methods accept &str inputs and return owned Rust types (String, Vec, etc.) to make usage ergonomic.

Contributing

We welcome those looking to contribute, but we are particular!

• If you add new C++ helpers, update the bridge.rs cxx interface and add safe Rust wrappers in lib.rs.
• Keep public Rust API docs updated — they are the primary developer reference and are what cargo doc generates.

Acknowledgements

This project builds on libdnf5 and cxx and the work of the DNF/libdnf community. The bindings exist to make that functionality accessible from Rust while keeping the unsafe surface minimal.

Check out:

• libdnf5
• CXX