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.

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::cpp_file.

External build system integration

The CxxQtBuilder automatically integrates with CMake when using CXX-Qt-CMake.

To integrate CxxQtBuilder with other build systems, you may specify a directory to output cxx-qt’s autogenerated headers by setting the QMAKE, CXX_QT_EXPORT_DIR and CXX_QT_EXPORT_CRATE_<crate-name> environment variables before calling cargo build. See also: https://kdab.github.io/cxx-qt/book/concepts/build_systems.html

Note: The exact output format in the CXX_QT_EXPORT_DIR is unstable and may change with future releases, so treat this as an experimental feature.

Implementations

impl CxxQtBuilder

pub fn new() -> Self

Create a new builder

pub fn new_qml_module(module: QmlModule) -> Self

Create a new CxxQtBuilder for building the specified QmlModule.

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 using the appropriate functions on CxxQtBuilder.

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::new("com.kdab.cxx_qt.demo").qml_files(["qml/main.qml"]))
    .files(["src/cxxqt_object.rs"])
    .build();

Note: This will automatically add the Qml Qt module to the build (see Self::qt_module).

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

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

pub fn files( self, rust_sources: impl IntoIterator<Item = impl AsRef<Path>>, ) -> Self

Specify multiple rust file paths to parse through the cxx-qt macro.

See also: Self::file

pub fn crate_include_root(self, include_dir: Option<String>) -> Self

Specify the sub-directory within the crate that should act as the root include directory of the crate. All header files under this subdirectory will be includable in C++ under this crates name. This is useful for crates that export C++ headers to be included by other crates.

For example, if your crate is called my_crate and you specify crate_include_dir(Some("include")), The file: include/my_header.h would become available as:

#include <my_crate/my_header.h>

Specify None to disable automatic inclusion of your crate as a header directory.

The default is Some("") which means that the entire crate directory is used as the include directory.

pub fn include_dir(self, dir: impl AsRef<Path>) -> Self

Specify a directory to include additional C++ headers from.

This directory will be namespaced by the crate name! So if you call include_dir("include/") a header include/my_header.h will be available as:

#include <crate_name/my_header.h>

Note that if you are trying to specify an include directory that is inside your own crate, prefer using Self::crate_include_root, which expects a path relative to the crate directory.

Also note that unlike the Self::crate_include_root method, this does not emit rerun-if-changed directives for the directory! If you need to rerun the build script when files in this directory change, you must emit appropriate rerun-if-changed directives yourself.

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

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

This is the prefix used Self::crate_include_root and Self::include_dir

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();

Note: In CMake projects, the .qrc file is typically added to the SOURCES of the target. This can be done as an alternative to using this function.

pub fn qrc_resources(self, qrc_resources: impl Into<QResources>) -> Self

Include resources (files) listed in a QResources struct into the binary with Qt’s resource system.

See QResources and QResource for details on how to specify resources.

If a QmlModule was specified when constructing the CxxQtBuilder, any resources that do not have a prefix specified will automatically be given a prefix based on the QML module’s default QML import path qrc:/qt/qml/uri/of/module/

Note: A list of strings or paths can be converted into a QResources, so it is possibly to just specify a list of strings like this:

CxxQtBuilder::new()
    .qrc_resources(["images/image.png", "images/logo.png"])
    .build();

Note: In CMake projects, the resources are typically added via qt_add_resources This can be done as an alternative to using this function.

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 exported. 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 cpp_file(self, file: impl Into<CppFile>) -> Self

Specify an additional C++ file to compile or run moc on. This allows building QObject C++ subclasses besides the ones autogenerated by cxx-qt.

Note: This function accepts anything that can be automatically converted into a CppFile, including strings:

CxxQtBuilder::new()
    .cpp_file("./test.h")
    .build();

pub fn cpp_files( self, files: impl IntoIterator<Item = impl Into<CppFile>>, ) -> Self

Specify multiple additional C++ files to compile or run moc on.

See also: Self::cpp_file

CxxQtBuilder::new()
    .cpp_files(["src/connection.cpp", "src/test.cpp"])
    .build();

pub unsafe 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 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:

unsafe {
CxxQtBuilder::new()
    .file("src/lib.rs")
    .cc_builder(|cc| {
        cc.flag_if_supported("-Wall");
    })
    .build();
}

Safety

This function is marked as unsafe because the closure has full access to the internal cc::Build instance. Misuse of the API may lead to unexpected behavior. No stability guarantees are made about the cc::Build instance between minor releases of Cxx-Qt.

pub fn build(self) -> Interface

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

Trait Implementations

impl Default for CxxQtBuilder

fn default() -> CxxQtBuilder

Returns the “default value” for a type.