Kirigami met Rust

Kirigami installeren

Alvorens te beginnen moeten we Kirigami en Rust op onze machine installeren.

ManjaroArch	sudo pacman -S cargo cmake extra-cmake-modules kirigami breeze qqc2-desktop-style
OpenSUSE	sudo zypper install cargo cmake kf6-extra-cmake-modules kf6-kirigami-devel qt6-quickcontrols2-devel kf6-qqc2-desktop-style
Fedora	sudo dnf install cargo cmake extra-cmake-modules kf6-kirigami2-devel kf6-qqc2-desktop-style

Verdere informatie voor andere distributies is hier te vinden.

Projectstructuur

Eerst maken we onze projectmap aan (u kunt de onderstaande commando's gebruiken). De onze gaan we kirigami_rust/ noemen. Dit zal de structuur van het project worden:

kirigami_rust/
├── CMakeLists.txt
├── Cargo.toml
├── build.rs
├── org.kde.kirigami_rust.desktop
└── src/
    ├── main.rs
    └── qml/
        └── Main.qml

Dit project zal CMake gebruiken om Cargo aan te roepen, die op zijn beurt het project zal bouwen.

Het project zal kirigami_rust worden genoemd en het zal een uitvoerbaar bestand genereren genaamd kirigami_hello.

org.kde.kirigami_rust.desktop

Het hoofddoel van Desktop Entry bestanden is te zorgen dat uw programma in de toepassingenstarter van Linux verschijnt. Een andere reden om ze te hebben is om bij Wayland venster-pictogrammen te hebben, omdat ze nodig zijn om de compositor te vertellen "dit venster hoort bij dit icon".

Het moet een reverse-DNS naam-schema volgen gevolgd door de .desktop extensie zoals org.kde.kirigami_rust.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

[Desktop Entry]
Name=Kirigami Tutorial in Rust
Name[ca]=Guia d'aprenentatge del Kirigami en Rust
Name[es]=Tutorial de Kirigami en Rust
Name[it]=Esercitazione di Kirigami in Rust
Name[nl]=Kirigami handleiding in Rust
Name[sl]=Učbenik Kirigami v Rustu
Name[sv]=Kirigami-handledning i Rust
Name[uk]=Підручник з Kirigami для Rust
Name[x-test]=xxKirigami Tutorial in Rustxx
Exec=kirigami_hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

CMakeLists.txt

The CMakeLists.txt file is going to be used to run Cargo and to install the necessary files together with our application. It also provides certain quality of life features, such as making sure that Kirigami is installed during compilation and to signal Linux distributions to install the necessary dependencies with the application.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

cmake_minimum_required(VERSION 3.28)

project(kirigami_rust)

find_package(ECM 6.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
include(KDEInstallDirs)
include(ECMUninstallTarget)

include(ECMFindQmlModule)
ecm_find_qmlmodule(org.kde.kirigami REQUIRED)
find_package(KF6 REQUIRED COMPONENTS QQC2DesktopStyle)

add_custom_target(kirigami_rust
    ALL
    COMMAND cargo build --target-dir ${CMAKE_CURRENT_BINARY_DIR}
)

install(
    PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/debug/kirigami_hello
    DESTINATION ${KDE_INSTALL_BINDIR}
)

install(FILES org.kde.kirigami_rust.desktop DESTINATION ${KDE_INSTALL_APPDIR})

The first thing we do is add KDE's Extra CMake Modules (ECM) to our project so we can use ecm_find_qml_module to check that Kirigami is installed when trying to build the application, and if it's not, fail immediately. Another useful ECM feature is ECMUninstallTarget, which allows to easily uninstall the application with CMake if desired.

We also use CMake's find_package() to make sure we have qqc2-desktop-style, KDE's QML style for the desktop. This is one of the two reasons we use CMake in this tutorial.

Typically Rust projects are built with Cargo, and it won't be different here. We create a target that will simply run Cargo when run, and mark it with ALL so it builds by default. Cargo will build the executable inside CMake's binary directory (typically build/).

For more information about CMake, targets, and the binary directory, see Building KDE software manually.

After this, we simply install the kirigami_rust executable generated by Cargo in the binary directory and install it to the BINDIR, which is usually /usr/bin, /usr/local/bin or ~/.local/bin. We also install the necessary desktop file to APPDIR, which is usually /usr/share/applications or ~/.local/share/applications. This is the second reason we use CMake in this tutorial.

For more information about where KDE software is installed, see Building KDE software manually: The install step.

Nu we met CMake klaar zijn, laten we kijken naar de bestanden waarmee we de meeste tijd aan gaan werken.

Cargo.toml

Next we have a very straightforward Cargo.toml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

[package]
name = "kirigami_hello"
version = "0.1.0"
authors = [ "Konqi the Konqueror <konqi@kde.org>" ]
edition = "2021"
license = "GPLv3"

[dependencies]
cxx = "1.0.95"
cxx-qt = "0.7"
cxx-qt-lib = { version="0.7", features = ["qt_full"] }
cxx-qt-lib-extras = "0.7"

[build-dependencies]
# The link_qt_object_files feature is required for statically linking Qt 6.
cxx-qt-build = { version = "0.7", features = [ "link_qt_object_files" ] }

It consists of project metadata and a list of dependencies that will be pulled automatically by Cargo, namely cxx and cxx-qt, which are necessary to run Qt applications written in Rust.

build.rs

Where in C++ you'd typically register QML elements with QML_ELEMENT and ecm_add_qml_module using declarative registration, with Rust you'll need to declare it in a build script build.rs file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use cxx_qt_build::{CxxQtBuilder, QmlModule};

fn main() {
    CxxQtBuilder::new()
        .qml_module(QmlModule {
            uri: "org.kde.tutorial",
            qml_files: &["src/qml/Main.qml"],
            rust_files: &["src/main.rs"],
            ..Default::default()
        })
        .build();
}

This is necessary to make the QML file available in the entrypoint for our application, main.rs.

src/main.rs

The file kirigami_rust/src/main.rs initializes the project and then loads the QML file, which will consist of the user interface for the application.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

#[cxx_qt::bridge]
mod ffi {
    extern "RustQt" {
        #[qobject]
        type DummyQObject = super::DummyRustStruct;
    }
}

#[derive(Default)]
pub struct DummyRustStruct;

use cxx_qt_lib::{QGuiApplication, QQmlApplicationEngine, QQuickStyle, QString, QUrl};
use cxx_qt_lib_extras::QApplication;
use std::env;

fn main() {
    let mut app = QApplication::new();
    let mut engine = QQmlApplicationEngine::new();

    // To associate the executable to the installed desktop file
    QGuiApplication::set_desktop_file_name(&QString::from("org.kde.kirigami_rust"));
    // To ensure the style is set correctly
    let style = env::var("QT_QUICK_CONTROLS_STYLE");
    if style.is_err() {
        QQuickStyle::set_style(&QString::from("org.kde.desktop"));
    }

    if let Some(engine) = engine.as_mut() {
        engine.load(&QUrl::from("qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml"));
    }

    if let Some(app) = app.as_mut() {
        app.exec();
    }
}

The first part that is marked with the #[cxx_qt::bridge] Rust macro just creates a dummy QObject out of a dummy Rust struct. This is needed just to complete the use of QmlModule in the previous build script build.rs. This will play a larger part in a future tutorial teaching how to expose Rust code to QML, but for now you can ignore it.

After this starts the important part:

Lines 12-13 import the needed Qt libraries exposed through cxx-qt.

We first create a new instance of a QApplication, then perform a few integrations in lines 20-26.

Then comes the part that actually creates the application window:

28
29
30

    if let Some(engine) = engine.as_mut() {
        engine.load(&QUrl::from("qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml"));
    }

The long URL qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml corresponds to the Main.qml file according to the Qt Resource System, and it follows this scheme: <resource_prefix><import_URI><QML_dir><file>.

In other words: the default resource prefix qrc:/qt/qml/ + the import URI org/kde/tutorial (set in build.rs, separated by slashes instead of dots) + the QML dir src/qml/ + the QML file Main.qml.

src/qml/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
    // Unique identifier to reference this object
    id: root

    width: 400
    height: 300

    // Window title
    title: "Hello World"

    // Set the first page that will be loaded when the app opens
    // This can also be set to an id of a Kirigami.Page
    pageStack.initialPage: Kirigami.Page {
        Controls.Label {
            // Center label horizontally and vertically within parent object
            anchors.centerIn: parent
            text: "Hello World!"
        }
    }
}

Hier gaan we onze frontend van de toepassing behandelen.

Als u enige Javascript kent, dan zal veel van QML u bekend voorkomen (hoewel het zijn eigen eigenaardigheden heeft). Qt's documentation heeft een uitgebreide hoeveelheid materiaal over deze taal als u zelf iets wilt proberen. Gedurende de loop van deze inleidingen zullen we veel van onze aandacht focussen op onze QML code, waar we Kirigami kunnen gebruiken om er het meeste uit te krijgen.

Laten we ons voor nu focussen op Main.qml. Eerst importeren we een aantal belangrijke modulen:

• QtQuick, de standaard bibliotheek gebruikt in QML toepassingen.
• QtQuick Controls, die een aantal standaard besturingen levert die we kunnen gebruiken om onze toepassingen interactief te maken.
• QtQuick Layouts, die hulpmiddelen voor het plaatsen van componenten in de toepassingsvensters levert.
• Kirigami, die een aantal componenten levert geschikt voor het aanmaken van toepassingen die werken over apparaten met verschillende vormen en groottes.

Daarna komen we bij ons basiselement, Kirigami.ApplicationWindow die enige basis functies levert nodig voor alle Kirigami toepassen. Dit is het venster dat elk van onze pagina's bevat, de hoofdsecties van onze UI.

Daarna zetten we de eigenschap id van het venster op 'root'. ID's zijn nuttig omdat ze ons uniek verwijzen naar een component, zelfs als we er verschillende hebben van hetzelfde type.

We zetten de titel van het venstereigenschap op "Hello World".

Daarna zetten we de eerste pagina van onze pagina stapel. De meeste Kirigami toepassingen zijn georganiseerd als een stapel pagina's, elke pagina bevat gerelateerde componenten passend bij een specifieke taak. Voor nu houden we het eenvoudig en blijven bij een enkele pagina. pageStack is een initieel lege stapel pagina's geleverd door Kirigami.ApplicationWindow en met pageStack.initialPage: Kirigami.Page {...} zetten we de eerste pagina op gepresenteerd bij het laden van de toepassing op een Kirigami.Page. Deze pagina zal al onze inhoud zal bevatten.

Tenslotte voegen we in onze pagina een Controls.Label in die ons tekst laat plaatsen op onze pagina. We gebruiken anchors.centerIn: parent om ons label horizontaal en verticaal te centreren in ons ouderelement. In dit geval is de oudercomponent van Kirigami.Page. Het laatste ding dat we moeten doen is het zetten van zijn tekst: text: "Hello World!".

De toepassing compileren en installeren

You should find the generated executable kirigami_hello under build/debug/kirigami_hello and you may run it directly or with cargo run, but it will lack a Window icon. To address this, we'll install the application first.

Voer het volgende uit:

cmake -B build --install-prefix ~/.local
cmake --build build/
cmake --install build/

With the first command, CMake will search for Kirigami and qqc2-desktop-style.

With the second command, CMake will build the kirigami_rust target, which just calls cargo build --target-dir build/. This step will take a while to complete, but the next time you repeat the second CMake command it will be faster or you will not need to compile at all.

In the third step, CMake will install the executable kirigami_hello under ~/.local/bin/kirigami_hello and the desktop file under ~/.local/share/applications, and a new entry named "Kirigami Tutorial in Rust" will appear on your menu.

Open het menu-item en voilà! Nu ziet u uw allereerste Kirigami toepassing voor uw eigen ogen verschijnen.

Om het nieuwe QML-programma in de modus mobiel op te starten, kan u QT_QUICK_CONTROLS_MOBILE=1 gebruiken:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

Als u voor een reden het project handmatig met CMake heeft gecompileerd en voor de een of andere reden het project wilt dëinstalleren, dan kan u het volgende uitvoeren:

cmake --build build/ --target uninstall