Kirigami z Rustom

Nameščanje Kirigami

Preden začnemo, bomo morali namestiti Kirigami in Rust na naš računalnik.

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

Dodatne informacije za druge distribucije najdete tukaj.

Struktura projekta

Najprej ustvarimo mapo projekta (lahko uporabite spodnje ukaze). Poimenovali jo bomo kirigami_rust/. To bo struktura projekta:

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

Ta projekt bo uporabil CMake za klic Cargo, ki bo nato zgradil projekt.

Projekt se bo imenoval kirigami_rust in ustvaril bo izvedljivo datoteko z imenom kirigami_hello.

org.kde.kirigami_rust.desktop

Glavni namen datotek za vnos namizja je prikazati vašo aplikacijo v zaganjalniku aplikacij v sistemu Linux. Drug razlog, da jih imate, so ikone oken na Waylandu, saj morajo sestavljavcu sporočiti "to okno gre s to ikono".

Slediti mora shemi poimenovanja z obratnim DNS, ki ji sledi končnica .desktop, kot je 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

Datoteka CMakeLists.txt bo uporabljena za zagon programa Cargo in namestitev potrebnih datotek skupaj z našo aplikacijo. Zagotavlja tudi določene zmožnosti za zagotavljanje kakovosti življenja, kot je zagotavljanje namestitve programa Kirigami med prevajanjem in signaliziranje distribucijam Linuxa, da namestijo potrebne odvisnosti z aplikacijo.

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

Najprej dodamo KDE-jeve Dodatne module CMake (ECM) v naš projekt, da lahko s pomočjo ecm_find_qml_module preverimo, ali je Kirigami nameščen, ko poskušamo zgraditi aplikacijo, in če ni, takoj spodleti. Druga uporabna funkcija ECM je ECMUninstallTarget, ki omogoča enostavno odstranitev aplikacije s CMake, če želimo.

Uporabljamo tudi CMake-ov find_package(), da zagotovimo, da imamo qqc2-desktop-style, KDE-jev slog QML za namizje. To je eden od dveh razlogov, zakaj v tej vadnici uporabljamo CMake.

Običajno se projekti Rust gradijo s Cargom in tukaj ne bo nič drugače. Ustvarimo cilj, ki bo ob zagonu preprosto zagnal Cargo, in ga označimo z ALL, da se bo gradi privzeto. Cargo bo zgradil izvedljivo datoteko znotraj binarnega imenika CMake (običajno build/).

Za več informacij o CMake, ciljih in binarnem imeniku glejte Ročna gradnja programske opreme KDE.

Po tem preprosto namestimo izvedljivo datoteko kirigami_rust, ki jo ustvari Cargo, v binarni imenik in jo namestimo v BINDIR, ki je običajno /usr/bin, /usr/local/bin ali ~/.local/bin. Prav tako namestimo potrebno datoteko namizja v APPDIR, ki je običajno /usr/share/applications ali ~/.local/share/applications. To je drugi razlog, zakaj v tej vadnici uporabljamo CMake.

Za več informacij o tem, kje je nameščena programska oprema KDE, glejte Ročna gradnja programske opreme KDE: korak namestitve.

Zdaj, ko je za CMake poskrbljeno, poglejmo datoteke, s katerimi bomo večino časa preživeli pri delu.

Cargo.toml

Nato imamo zelo preprost 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" ] }

Sestavljen je iz metapodatkov projekta in seznama odvisnosti, ki jih bo Cargo samodejno prevzel, in sicer cxx in cxx-qt, ki sta potrebna za zagon Qt aplikacij, napisanih v Rustu.

build.rs

Medtem ko bi v C++ elemente QML običajno registrirali z QML_ELEMENT in ecm_add_qml_module z uporabo deklarativne registracije, jih boste morali v Rustu deklarirati v datoteki 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();
}

To je potrebno, da je datoteka QML na voljo v vstopni točki za našo aplikacijo, main.rs.

src/main.rs

Datoteka kirigami_rust/src/main.rs inicializira projekt in nato naloži datoteko QML, ki bo vsebovala uporabniški vmesnik za aplikacijo.

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

Prvi del, ki je označen z #[cxx_qt::bridge], ustvari le navidezni objekt QObject iz navidezne strukture Rust. To je potrebno le za dokončanje uporabe QmlModule v prejšnjem skriptu za gradnjo build.rs. To bo imelo večjo vlogo v prihodnji vadnici, ki bo učila, kako izpostaviti kodo Rust v QML, vendar ga zaenkrat lahko prezrete.

Po tem se začne pomemben del:

Vrstici 12-13 uvozita potrebne knjižnice Qt, ki so na voljo prek cxx-qt.

Najprej ustvarimo nov pojavek QApplication, nato pa v vrsticah 20–26 izvedemo nekaj integracij.

Nato pride del, ki dejansko ustvari okno aplikacije:

28
29
30

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

Dolgi URL qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml ustreza datoteki Main.qml v skladu s Qt Resource System in sledi tej shemi: <resource_prefix><import_URI><QML_dir><file>.

Z drugimi besedami: privzeta predpona vira qrc:/qt/qml/ + uvozni URI org/kde/tutorial (nastavljen v build.rs, ločen s poševnicami namesto s pikami) + imenik QML src/qml/ + datoteka QML 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!"
        }
    }
}

Tukaj bomo delali na ospredju naše aplikacije.

Če poznate nekaj Javascripta, se vam bo večina QML zdela znana (čeprav ima svoje posebnosti). Dokumentacija Qt vsebuje obsežno količino gradiva o tem jeziku, če želite nekaj poskusiti sami. Med temi učbenki bomo veliko pozornosti namenili naši kodi QML, kjer lahko uporabimo Kirigami, da ga kar najbolje izkoristimo.

Za zdaj se osredotočimo na Main.qml. Najprej uvozimo številne pomembne module:

• QtQuick je standardna knjižnica, ki se uporablja v aplikacijah QML.
• QtQuick Controls, ki zagotavlja številne standardne kontrole, s katerimi lahko naše aplikacije naredimo interaktivne.
• QtQuick Layouts, ki ponuja orodja za postavitev komponent v okno aplikacij.
• Kirigami, ki ponuja številne komponente, primerne za ustvarjanje aplikacij, ki delujejo na napravah različnih oblik in velikosti.

Nato pridemo do našega osnovnega elementa, Kirigami.ApplicationWindow, ki ponuja nekaj osnovnih zmožnosti, potrebnih za vse Kirigami aplikacije. To je okno, ki bo vsebovalo vse naše strani, glavne dele našega uporabniškega vmesnika.

Nato določimo lastnost okna določilnik 'id' na 'root'. Določilniki so uporabni, ker nam dovolijo edinstveno sklicevanje na komponento, tudi če jih imamo več iste vrste.

Nastavili smo tudi lastnost okna title na "Hello World".

Nato nastavimo prvo stran našega sklada strani. Večina Kirigami aplikacij je organiziranih kot sklad strani, pri čemer vsaka stran vsebuje povezane komponente, primerne za določeno nalogo. Zaenkrat bomo ohranili preprostost in se držali ene same strani. pageStack je začetno prazen sklad strani, ki ga zagotavlja Kirigami.ApplicationWindow, in s pageStack.initialPage: Kirigami.Page {...} nastavimo prvo stran, ki se prikaže ob nalaganju aplikacije, na Kirigami.Page. Ta stran bo vsebovala vso našo vsebino.

Nazadnje na našo stran vključimo element Controls.Label, ki nam omogoča, da na stran postavimo besedilo. Za vodoravno in navpično centriranje oznake znotraj nadrejenega elementa uporabimo anchors.centerIn: parent. V tem primeru je nadrejena komponenta naše oznake Kirigami.Page. Zadnja stvar, ki jo moramo storiti, je nastaviti njeno besedilo: text: "Hello World!".

Prevajanje in namestitev aplikacije

Ustvarjeno izvedljivo datoteko kirigami_hello bi morali najti v mapi build/debug/kirigami_hello in jo lahko zaženete neposredno ali z ukazom cargo run, vendar ne bo imela ikone okna. Da bi to odpravili, bomo najprej namestili aplikacijo.

Poženite naslednje:

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

S prvim ukazom bo CMake poiskal Kirigami in qqc2-desktop-style.

Z drugim ukazom bo CMake zgradil cilj kirigami_rust, ki preprosto pokliče cargo build --target-dir build/. Ta korak bo trajal nekaj časa, vendar bo naslednjič, ko boste ponovili drugi ukaz CMake, hitrejši ali pa vam ga sploh ne bo treba prevajati.

V tretjem koraku bo CMake namestil izvedljivo datoteko kirigami_hello pod ~/.local/bin/kirigami_hello in datoteko namizja pod ~/.local/share/applications, v vašem meniju pa se bo pojavil nov vnos z imenom "Kirigami Tutorial in Rust" .

Odprite vnos v meni in voilà! Zdaj boste videli svojo prvo aplikacijo Kirigami, ki se bo pojavila pred vašimi očmi.

Za zagon nove aplikacije QML v mobilnem načinu lahko uporabite QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

Če ste projekt prevedli ročno s CMake in bi iz nekega razloga želeli odstraniti projekt, lahko zaženete:

cmake --build build/ --target uninstall