repository·dev·Indexed 41 days ago
https://github.com/qt/qtbridge-rustQtBridge enables building modern Qt Quick user interfaces with a Rust backend without writing C++ code. It uses attribute macros like #[qobject], #[qslot], #[qproperty], and #[qsignal] to expose Rust types, properties, signals, and slots directly to QML. The framework requires Qt 6.10 or higher and provides utilities for QMetaType support and C++ proxy code generation.
The qt-artifacts crate is a manifest provider that contains pre-built Qt artifact download URLs and their corresponding SHA256 checksums. It supports Windows, Linux, and macOS.
Important Note: This crate does not contain the Qt framework itself; it only provides the links and checksums required to download the prebuilt artifacts.
The qt-version crate is used to select and resolve supported Qt versions in a Rust project using Cargo features.
Important Note: This crate does not include the Qt framework itself. It only contains links to prebuilt Qt framework artifacts. You must ensure the Qt framework is available on your system or provided via other means. Using this crate does not change the licensing terms of the Qt framework used in your project.
QtBridge allows you to build modern Qt Quick user interfaces using a Rust backend without writing C++. You define Rust types and expose them to QML using attribute macros.
Core Workflow:
#[qobject] macro on an impl block for that struct. Use #[qslot], #[qproperty], and #[qsignal] to define how the Rust type appears in QML.QApp to register your types, load your QML files, and run the application.Memory Model:
All #[qobject] types are held in Rc<RefCell<_>>. This allows the Rust code, the QML engine, and QML components to share ownership. Rust objects are borrowed only for the duration of a signal, slot, or property invocation. This allows Rust code to freely take mutable borrows between QML interactions, provided no call chain is interrupted in a way that causes a RefCell conflict (which results in a panic).
use qtbridge::{qobject, QApp};
#[derive(Default)]
pub struct Backend {}
#[qobject(Singleton)]
impl Backend {
#[qslot]
fn say_hello(&self) {
println!("Hello World!")
}
}
fn main() {
QApp::new()
.register::<Backend>()
.load_qml(include_bytes!("qml/Main.qml"))
.run();
}When your local patch is ready, follow these steps to submit it for review:
git checkout -b feature-name.Task-number: or Fixes: entry in the commit footer.dev branch on Gerrit.Your change will then appear in Gerrit for review, where you can add reviewers and modify the commit message.
git add <the files you modified>
git commit
git push origin HEAD:refs/for/devTo generate documentation for the project including all available features, run the following command with Cargo:
cargo doc --features linkme,serde_json --no-depsThe repository is a Rust workspace. By default, cargo build and cargo test only build the core crates and tests. To ensure your changes are valid across the entire project, including example applications, you must run the workspace-wide commands. It is highly recommended to run the full workspace test before submitting any changes to Gerrit.
# Build core crates and tests only
cargo build
cargo test
# Build the full workspace including example apps
cargo build --workspace
cargo test --workspaceTo contribute code, you must use Gerrit instead of GitHub Pull Requests.
<name>.ssh codereview.qt-project.orgAdd qtbridge to your Cargo.toml dependencies. To enable advanced features like automatic type registration or JSON support, use the corresponding feature flags.
Available Features:
linkme: Automatically registers every type annotated with #[qobject] in the QML type system at startup (removes the need for manual .register() calls).serde_json: Allows using serde_json::Value in properties, signals, and slots. These values are exposed to QML as JSON objects.[dependencies]
qtbridge = { version = "*", features = ["linkme", "serde_json"] }Clone the repository from the official Qt source to automatically include necessary git hooks (such as the commit-msg hook required for Gerrit). After cloning, navigate to the specific language directory and checkout the dev branch.
Note: The GitHub repository is a read-only mirror. All development and code reviews must happen via Gerrit.
git clone "https://codereview.qt-project.org/qt/qtbridge-rust" && (cd "qtbridge-rust" && mkdir -p `git rev-parse --git-dir`/hooks/ && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://codereview.qt-project.org/tools/hooks/commit-msg && chmod +x `git rev-parse --git-dir`/hooks/commit-msg)
cd qtbridge-<lang>
git checkout devQtBridge requires Qt 6.10 or higher and qmake must be in your system PATH. You must also have a C++ toolchain installed.
On Fedora 43/44:
sudo dnf install qt6-qtbase-devel qt6-qtdeclarative-devel qt6-qtbase-private-develOn Ubuntu 26.04/Debian Testing:
sudo apt install -y qt6-base-dev qt6-declarative-dev qt6-base-private-devIf Qt is not in your standard path, you must update your environment variables:
Linux:
export PATH=/path/to/qtbase/bin:$PATH
export LD_LIBRARY_PATH="/path/to/qtbase/lib:$LD_LIBRARY_PATH"macOS:
export PATH=/path/to/qtbase/bin:$PATH
export DYLD_FRAMEWORK_PATH=/path/to/qtbase/lib:$DYLD_FRAMEWORK_PATHWindows (Command Prompt):
set PATH=%PATH%;C:\Qt\6.10.1\msvc2022_64\bin\Windows (PowerShell):
$env:PATH += ";C:\Qt\6.10.1\msvc2022_64\bin\"The QPropertyMember trait defines how a Rust type can be used as a property in a Qt Quick interface. It handles the conversion between Rust types and QVariant for both read (to Qt) and write (from Qt) operations, and manages property equality to determine if a notify signal should be emitted.
You do not need to implement this trait manually for standard types. Support is provided for:
boolStringVec<T> where T is a primitive or StringRc<RefCell<T>> where T implements QObjectHolder (for QObject-backed properties)Vec<Rc<RefCell<T>>> where T implements QmlElement (for lists of QML elements)Note: For custom types, support must be added via CXX/C++ bindings.
Because many operations involve raw pointers to QObject instances, the following safety rules apply:
to_qvariant / to_qvariant_view: For QObject-backed members, the returned QVariant carries an untracked raw QObject*. The caller must consume this variant and begin tracking its state immediately before any garbage collection occurs. Metaobject dispatch is designed to consume these variants within the same call stack to mitigate risk.from_qvariant: When reading a QObject-backed member from a QVariant, the caller must guarantee the variant contains a live QObject of a compatible type. Qt's type-checking during property writes helps uphold this.The TypeCategory enum classifies types into three distinct groups used during code generation:
Standard: Standard programming language types (e.g., primitives).Cxx: Native C++ types.Qt: Types belonging to the Qt framework.This classification helps the bridge determine how to handle type mapping and metadata.