KDAB cxx-qt: Rust and Qt Interop Through CXX

Why cxx-qt targets mixed Rust and Qt applications

CXX-Qt addresses a specific boundary problem: an application already uses Qt, but part of its implementation is written in Rust. It is aimed at engineers who need Rust code to participate in a C++ Qt application, use CMake, or build a Rust application with Cargo. The project is also relevant to codebases that expose Rust-backed QObject subclasses through QML or JavaScript. The README explicitly describes this as bidirectional Rust and C++ binding support, rather than a standalone Qt replacement.

The project does not attempt to bind every Qt API into safe Rust. Its comparison table marks QWidgets support as limited. It explains that custom QObject subclasses implemented in Rust can be used from C++ and therefore inside QWidgets applications, but CXX-Qt and the listed Rust Qt Binding Generator do not provide Rust bindings for QWidgets APIs. A team looking for a complete Rust-side QWidgets interface should treat that boundary as a design constraint, not as a missing convenience feature.

CXX-Qt supports Qt 5.15 LTS and all versions of Qt 6. Qt versions below 5.15 are explicitly unsupported. This boundary matters when selecting a project for an existing application, especially when a workstation has multiple Qt installations or when build scripts need to choose a compiler and Qt module set.

How cxx-qt generates the Rust and C++ interface

CXX-Qt is a set of crates rather than one isolated library. The `cxx-qt-lib` crate supplies Rust bindings to common `QtCore` and `QtGui` classes, generated with CXX. The `cxx-qt` crate provides a Rust macro for code generation, while `cxx-qt-build` runs in Cargo build scripts and generates and compiles the corresponding C++ code. The `cxx-qt-gen` crate is also included in the workspace, and `qt-build-utils` supplies Qt build support.

The generated interface extends ordinary CXX bindings with attributes for Qt metadata and interactions. The README specifically identifies signals, slots, and Qt properties as areas handled by the additional code generation. This means the bridge can represent more than a plain Rust function exported through a C ABI. A Rust-defined QObject subclass can be represented as a Qt object, connected to Qt signals and slots, and consumed by QML or JavaScript according to the generated C++ interface.

The practical data flow still crosses a language boundary. Rust implementation code is parsed by the CXX-Qt macro and build tooling, C++ support code is produced for Qt, and the C++ side must compile with the selected Qt installation. Cargo and CMake can therefore appear in one project for different roles. The workspace includes Cargo-only examples as well as CMake example directories, but the README does not provide enough command-line detail to reproduce every build mode from the excerpt alone.

Qt metadata support and the boundary around QWidgets

The Qt-specific portion of CXX-Qt is most useful when the Rust object must behave like a normal Qt participant. The generated code can implement `QObject` subclasses in Rust, and those objects can be used from C++, QML, and JavaScript. Signals and slots are declared through the project's additional attributes, while the property system is supported by the same generation layer.

That approach differs from generating a broad type-safe façade over Qt from JSON descriptions or embedding C++ directly in Rust. CXX-Qt uses CXX plus additional code generation, so the resulting interface has to satisfy the requirements of CXX bridge types and Qt's object model. The documentation excerpt does not enumerate every supported type, signal signature, property form, or ownership rule. Those details need to be checked in the versioned CXX-Qt Book before a design relies on a particular API shape.

The limited QWidgets result is an architectural limitation, not merely missing documentation. A Rust-backed QObject can be used by a C++ or QML application, but CXX-Qt does not provide Rust bindings for the QWidgets APIs themselves. Applications that keep most widget construction in C++ can use the bridge at selected boundaries. Applications that want to manipulate widgets from Rust throughout their implementation may find the tool incomplete.

Installing cxx-qt and reaching the first example

The README directs users to the CXX-Qt Book for a step-by-step minimal example and to the `examples` directory for demonstrations of threading, `QQmlExtensionPlugin`, and other features. It also states that the project should work with Qt and Rust versions supported by both ecosystems. The documented build prerequisites include a C++ compiler, `clang-format`, `CMake`, Qt 5 and/or Qt 6, and the Rust toolchain.

For a local copy of the project and its documentation, the README gives these commands. On Windows, it first requires symlink support in Git because the repository contains symbolic links. The clone command below creates the repository checkout; the book command serves the documentation and opens it in a browser when run from the `book` folder.

git config --global core.symlinks true

The Windows-specific command enables symlinks in Git and avoids requiring administrator privileges during cloning, according to the README.

git clone https://github.com/KDAB/cxx-qt.git

This creates a checkout of `KDAB/cxx-qt`.

mdbook serve --open

Run that command from the repository's `book` directory. The README says it opens the local documentation and, if another browser is needed, identifies `http://localhost:3000`.

The README points to the Book's getting-started example. The Book is also the source for the latest-release behavior, while repository examples are the next reference for threading, plugins, and multi-crate arrangements.

Supported platforms and the cost of tracking releases

The README states that CXX-Qt is tested in CI on Linux, Windows, macOS, and WebAssembly. It says the project should work on other platforms where both Qt and Rust support them, but those other platforms are not tested regularly. That distinction matters for adoption: the named CI platforms have explicit coverage, while other targets rely on the compatibility of Qt and Rust.

The current supported Qt range is Qt 5.15 LTS and all Qt 6 versions. Versions below Qt 5.15 are explicitly unsupported. CXX-Qt can therefore fit both a Qt 5.15 LTS maintenance line and a Qt 6 application, but an older Qt dependency needs to be resolved before integration begins.

The repository was not archived, and the last push was on 2026-09-29. Recent releases include `v0.10.0` on 2026-08-24, `v0.9.1` on 2026-07-03, and `v0.9.0` on 2026-06-23. At the same time, the README labels the project early-stage and says the API changes frequently. Maintenance activity and API stability are separate questions: a recent push does not remove the upgrade work caused by changing interfaces. Teams should expect to review release notes and regenerated bindings when moving between versions.

The SPDX headers and the repository badge identify the licensing terms as `MIT OR Apache-2.0`. The repository contains `LICENSES/`, and the workspace package metadata repeats `license = "MIT OR Apache-2.0"`. This describes the project license declaration, not an interpretation of how a particular application or distribution should be configured.

CXX-Qt compared with other Rust Qt bridge designs

CXX-Qt is not the only approach to exposing Rust to Qt, and the README's comparison highlights materially different designs. `qmetaobject-rs` uses the `cpp` macro to write C++ inline in Rust, along with Rust macros to create `QObject` subclasses. It supports safe Rust and QML according to the table, but it is listed as not integrating into a C++ codebase. That makes it more directly tied to Rust-side declaration of Qt objects.

The Rust Qt Binding Generator is another C++ integration option. According to the table, it integrates into a C++ codebase, supports safe Rust and QML, and can implement custom `QObject` subclasses in Rust. Its described mechanism is generating Rust traits and C++ bindings from a JSON description of a `QObject` subclass. CXX-Qt instead uses CXX plus additional Qt code generation. The choice therefore depends on whether the project prefers CXX-style Rust/C++ bridging or a JSON-driven binding generator.

`rust-qt` takes a different route through Ritual, generating unsafe Rust bindings from C++ headers. The table lists it as supporting QML and QWidgets, but not safe Rust or direct integration into an existing C++ codebase. `qml-rust`, `qmlrs`, `qmlrsng`, and `rust-qml` are listed as QML-oriented alternatives with different C wrapper, engine, or `libqmlbind` approaches. The comparison is useful because CXX-Qt's safe Rust and C++ integration are paired with limited QWidgets API coverage.

Editorial conclusion

CXX-Qt fits teams that need to place Rust inside an existing C++ or CMake application while preserving QObject-based QML integration. It is a poor fit for projects requiring complete Rust bindings for QWidgets APIs or for teams unwilling to track frequent API changes. Evaluate the current book against the intended Qt version first, then confirm that the required QObject, signal, slot, and property behavior is documented for that release.

Frequently asked questions

Official sources

1. Issues
2. KDAB/cxx-qt on GitHub
3. Project website
4. README
5. Releases