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
16

[Desktop Entry]
Name=Kirigami Tutorial in Rust
Name[ca]=Guia d'aprenentatge del Kirigami en Rust
Name[es]=Tutorial de Kirigami en Rust
Name[fr]=Tutoriel pour 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

Het bestand CMakeLists.txt wordt gebruikt om Cargo uit te voeren en om de benodigde bestanden te installeren samen met onze toepassing. Het levert ook bepaalde functies voor een kwaliteit van leven, zoals het verzekeren dat Kirigami geïnstalleerd is gedurende compilatie en om aan Linux distributies te signaleren om de benodigde afhankelijkheden met de toepassing te installeren.

 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})

Het eerste wat we doen is Extra CMake modules (ECM) van KDE toe te voegen aan ons project zodat we ecm_find_qml_module kunnen gebruiken om te controleren dat Kirigami geïnstalleerd is bij het proberen om de toepassing te bouwen, en zo niet, onmiddellijk te mislukken. Een andere nuttige ECM functie is ECMUninstallTarget, die het gemakkelijk maak de installatie ongedaan te maken van de toepassing met CMake indien gewenst.

We gebruiken ook find_package() van CMake om te verzekeren dat we qqc2-desktop-style hebben, de QML stijl van KDE voor het bureaublad. Dat is een van de twee redenen dat we CMake gebruiken in deze handleiding.

Rust projecten worden typisch gebouwd met Cargo en het zal hier niet anders zijn. We maken een doel aan dat eenvoudig Cargo zal uitvoeren bij uitvoeren en het markeren met ALL zodat het standaard wordt gebouwd. Cargo zal het uitvoerbare bestand binnen de binaire map van CMake bouwen (typisch build/).

Voor meer informatie over CMake, doelen en de binaire map, zie KDE software handmatig bouwen.

Hierna installeren we eenvoudig het uitvoerbare bestand kirigami_rust gegenereerd door Cargo in de binaire map en installeren het in de BINDIR, wat gewoonlijk /usr/bin, /usr/local/bin of ~/.local/bin is. We installeren ook het benodigde desktop-bestand in APPDIR, wat gewoonlijk /usr/share/applications of ~/.local/share/applications is. Dit is de tweede reden dat we CMake in deze handleiding gebruiken.

Voor meer informatie over waar KDE software wordt geïnstalleerd, zie KDE software handmatig bouwen: de installatiestap.

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

Cargo.toml

Als volgende hebben we een erg rechttoe-rechtaan 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" ] }

Het bestaat uit project-metadata en een lijst met afhankelijkheden die automatisch door Cargo ingehaald zullen worden, namelijk cxx en cxx-qt, die nodig zijn om Qt toepassingen geschreven in Rust uit te voeren.

build.rs

Waar in C++ u typisch QML elementen registreert met QML_ELEMENT en ecm_add_qml_module met gebruik van declarative registration, met Rust moet u het declareren in een bestand build script build.rs:

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

Dit is noodzakelijk om het QML-bestand beschikbaar te maken in het ingangspunt van onze toepassing, main.rs.

src/main.rs

Het bestand kirigami_rust/src/main.rs initialiseert het project en laadt daarna het QML-bestand, die zal bestaan uit het gebruikersinterface van de toepassing.

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

Het eerst deel dat gemarkeerd is met de Rust macro #[cxx_qt::bridge] maakt eenvoudig een dummy QObject an uit een dummy Rust struct. Dit is gewoon nodig om het gebruik van QmlModule compleet te maken in het vorige bouwscript build.rs. Dit zal een groter rol spelen in een toekomstige handleiding die onderwijst hoe Rust code aan QML bloot te stellen, maar voor nu kunt u het negeren.

Hierna begint het belangrijke gedeelte:

De regels 12-13 importeren de benodigde Qt-bibliotheken blootgesteld via cxx-qt.

We maken eerst een nieuw exemplaar van een QApplication, daarna voeren we een paar integraties uit in de regels 20-26.

Daarna komt het gedeelte dat werkelijk het toepassingsvenster aanmaakt:

28
29
30

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

De lange URL qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml komt overeen met het bestand Main.qml volgens het Qt-hulpbronsysteem en het volgt dit schema: <resource_prefix><import_URI><QML_dir><file>.

In andere woorden: de standaard hulpbronprefix qrc:/qt/qml/ + de import URI org/kde/tutorial (ingezet in build.rs, gescheiden door slashes in plaats van punten) + de QML-map src/qml/ + het QML-bestand 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 handleidingen 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

U zou het gegenereerde uitvoerbare bestand kirigami_hello moeten vinden onder build/debug/kirigami_hello en u zou het direct kunnen uitvoeren of met cargo run, maar er zal geen vensterpictogram zijn. Om dat aan te pakken zullen we de toepassing eerst installeren.

Voer het volgende uit:

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

Met het eerst commando zal CMake zoeken naar Kirigami en qqc2-desktop-style.

Met het tweede commando zal CMake het doel kirigami_rust douwen, die eenvoudig cargo build --target-dir build/ aanroept. Deze stap zal even duren om te voltooien, maar de volgende keer dat u het tweede CMake commando herhaalt zal het sneller zijn of het zal helemaal niet nodig zijn om te compileren.

In de derde stap zal CMake het uitvoerbare bestand kirigami_hello onder ~/.local/bin/kirigami_hello installeren en het desktop-bestand onder ~/.local/share/applications en een nieuw item genaamd "Kirigami Tutorial in Rust" zal in uw menu verschijnen.

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