Struct CxxQtBuilder

pub struct CxxQtBuilder { /* private fields */ }

Run cxx-qt’s C++ code generator on Rust modules marked with the cxx_qt::bridge macro, compile the code, and link to Qt. This is the complement of the cxx_qt::bridge macro, which the Rust compiler uses to generate the corresponding Rust code. No dependencies besides Qt, a C++17 compiler, and Rust toolchain are required.

For example, if your cxx_qt::bridge module is in a file called src/lib.rs within your crate, put this in your build.rs:

use cxx_qt_build::CxxQtBuilder;

CxxQtBuilder::new()
    .file("src/lib.rs")
    .build();

If you have multiple major versions of Qt installed (for example, 5 and 6), you can tell CxxQtBuilder which one to use by setting the QT_VERSION_MAJOR environment variable to when running cargo build. Otherwise CxxQtBuilder prefers the newer version by default.

To use CxxQtBuilder for a library to link with a C++ application, specify a directory to output cxx-qt’s autogenerated headers by having the C++ build system set the CXX_QT_EXPORT_DIR environment variable before calling cargo build. Then, add the same directory path to the C++ include paths. Also, set the QMAKE environment variable to the path of the qmake executable for the Qt installation found by the C++ build system. This ensures that the C++ build system and CxxQtBuilder link to the same installation of Qt.

Under the hood, CxxQtBuilder uses cc::Build, which allows compiling aditional C++ files as well. Refer to CxxQtBuilder::cc_builder for details.

In addition to autogenerating and building QObject C++ subclasses, manually written QObject subclasses can be parsed by moc and built using CxxQtBuilder::qobject_header.

Implementations

impl CxxQtBuilder

pub fn new() -> Self

Create a new builder

pub fn library(interface_definition: Interface) -> Self

Create a new builder that is set up to create a library crate that is meant to be included by later dependencies.

The headers generated for this crate will be specified

pub fn file(self, rust_source: impl AsRef<Path>) -> Self

Specify rust file paths to parse through the cxx-qt marco Relative paths are treated as relative to the path of your crate’s Cargo.toml file

pub fn qrc(self, qrc_file: impl AsRef<Path>) -> Self

Include files listed in a .qrc file into the binary with Qt’s resource system.

CxxQtBuilder::new()
    .file("src/cxxqt_module.rs")
    .qrc("src/my_resources.qrc")
    .build();

⚠️ In CMake projects, the .qrc file is typically added to the SOURCES of the target. Prefer this to adding the qrc file through cxx-qt-build. When using CMake, the qrc file will not be built by cxx-qt-build!

pub fn qt_module(self, module: &str) -> Self

Link additional Qt modules. Specify their names without the Qt prefix, for example "Widgets". The Core module and any modules from dependencies are linked automatically; there is no need to specify them.

Note that any qt_module you specify here will be enabled for all downstream dependencies as well if this crate is built as a library with CxxQtBuilder::library. It is therefore best practice to specify features on your crate that allow downstream users to disable any qt modules that are optional.

pub fn include_prefix(self, prefix: &str) -> Self

Instead of generating files under the crate name, generate files under the given prefix.

pub fn qml_module<A: AsRef<Path>, B: AsRef<Path>>( self, qml_module: QmlModule<'_, A, B>, ) -> CxxQtBuilder

Register a QML module at build time. The rust_files of the QmlModule struct should contain #[cxx_qt::bridge] modules with QObject types annotated with #[qml_element].

The QmlModule struct’s qml_files are registered with the Qt Resource System in the default QML import path qrc:/qt/qml/uri/of/module/. Additional resources such as images can be added to the Qt resources for the QML module by specifying the qrc_files field.

When using Qt 6, this will run qmlcachegen to compile the specified .qml files ahead-of-time.

use cxx_qt_build::{CxxQtBuilder, QmlModule};

CxxQtBuilder::new()
    .qml_module(QmlModule {
        uri: "com.kdab.cxx_qt.demo",
        rust_files: &["src/cxxqt_object.rs"],
        qml_files: &["qml/main.qml"],
        ..Default::default()
    })
    .build();

pub fn qobject_header(self, opts: impl Into<QObjectHeaderOpts>) -> Self

Specify a C++ header containing a Q_OBJECT macro to run moc on. This allows building QObject C++ subclasses besides the ones autogenerated by cxx-qt.

pub fn cc_builder(self, callback: impl FnMut(&mut Build)) -> Self

Use a closure to run additional customization on CxxQtBuilder’s internal cc::Build before calling CxxQtBuilder::build. This allows to add extra include paths, compiler flags, or anything else available via cc::Build’s API. For example, to add an include path for manually written C++ headers located in a directory called include within your crate:

CxxQtBuilder::new()
    .file("src/lib.rs")
    .cc_builder(|cc| {
        cc.include("include");
    })
    .build();

pub fn build(self)

Generate and compile cxx-qt C++ code, as well as compile any additional files from CxxQtBuilder::qobject_header and CxxQtBuilder::cc_builder.

Trait Implementations

impl Default for CxxQtBuilder

fn default() -> CxxQtBuilder

Returns the “default value” for a type.