Kirigami з Rust

Встановлення Kirigami

Перш ніж почати, нам потрібно встановити Kirigami і Rust у нашій машині.

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

Подальші відомості для інших дистрибутивів наведено тут.

Структура проєкту

Спочатку ми створимо теку нашого проєкту (ви можете скористатися наведеними нижче командами). Назвемо цю теку kirigami_rust/. Ось структура проєкту:

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

У цьому проєкті використано CMake для виклику Cargo, системи, яка збере проєкт.

Проєкт називатиметься kirigami_rust, і він створюватиме виконуваний файл із назвою kirigami_hello.

org.kde.kirigami_rust.desktop

Основним призначенням файлів стільничних записів є показ вашої програми у засобі запуску програм у Linux. Іншою причиною їхнього існування є визначення піктограм вікна у Wayland, оскільки вони потрібні для надсилання повідомлення засобу композиції «піктограмою цього вікна є така».

Має виконуватися схема іменування зворотного DNS з наступним суфіксом назви .desktop, наприклад org.kde.kirigami_rust.desktop:

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

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

Файл CMakeLists.txt буде використано для запуску Cargo та встановлення необхідних файлів разом із нашою програмою. У ньому також реалізовано певні функції для зручності, такі як забезпечення встановлення Kirigami під час компіляції та надсилання команд дистрибутивам Linux про необхідність встановлення необхідних залежностей разом із програмою.

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

Перше, що ми зробимо, це додамо до нашого проєкту Додаткові модулі CMake (ECM) від KDE, щоб ми могли використовувати ecm_find_qml_module для перевірки встановлення Kirigami під час спроби зібрати програму, і якщо його не встановлено, то негайно завершити роботу. Ще однією корисною функцією ECM є ECMUninstallTarget, яка надає змогу легко вилучити програму за допомогою CMake, якщо це потрібно.

Ми також скористаємося find_package() з CMake, щоб переконатися, що у нас є qqc2-desktop-style, стиль QML KDE для стільниці. Це одна з двох причин, чому ми використовуємо CMake у цьому підручнику.

Зазвичай проєкти Rust збираються за допомогою Cargo, і тут ми теж це зробимо. Ми створюємо ціль, яка просто запускатиме Cargo під час запуску, і позначаємо її як ALL, щоб вона збиралася типово. Cargo збиратиме виконуваний файл у каталозі CMake для виконуваних файлів (зазвичай build/).

Щоб дізнатися більше про CMake, цілі та каталог виконуваних файлів, див. Збирання програмного забезпечення KDE вручну.

Після цього ми просто встановлюємо виконуваний файл kirigami_rust, створений Cargo, у каталозі виконуваних файлів та встановлюємо його до BINDIR, яким зазвичай є /usr/bin, /usr/local/bin або ~/.local/bin. Ми також встановлюємо потрібний файл desktop до APPDIR, яким зазвичай є /usr/share/applications або ~/.local/share/applications. Це друга причина, чому ми використовуємо CMake у цьому підручнику.

Щоб дізнатися більше про те, де встановлено програмне забезпечення KDE, див. Збирання програмного забезпечення KDE вручну: крок встановлення.

Тепер, коли ми подбали про CMake, погляньмо на файли, з якими ми маємо намір працювати переважний час під час розробки програми.

Cargo.toml

Далі, у нас є зрозумілий 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" ] }

Він складається з метаданих проєкту та списку залежностей, які будуть автоматично завантажені Cargo, а саме cxx та cxx-qt, необхідних для запуску Qt-програм, написаних на Rust.

build.rs

Якщо у C++ ви зазвичай реєструєте елементи QML за допомогою QML_ELEMENT та ecm_add_qml_module за допомогою декларативної реєстрації, то у Rust вам потрібно буде оголосити їх у файлі скрипту збирання 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();
}

Це необхідно для того, щоб QML-файл був доступним у точці входу для нашої програми, main.rs.

src/main.rs

Файл kirigami_rust/src/main.rs ініціалізує проєкт, а потім завантажує файл 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
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();
    }
}

Перша частина, позначена як #[cxx_qt::bridge], створює фіктивний QObject з фіктивної структури Rust. Це потрібно лише для завершення використання QmlModule у попередньому скрипті збирання build.rs. Це матиме значний вплив на решту підручника, де ми вивчатимемо, як використовувати код Rust для QML, але поки що ви можете на це не зважати.

Після цього починається важлива частина:

У рядках 12-13 імпортуємо потрібні бібліотеки Qt, які розкриваються через cxx-qt.

Спочатку ми створюємо екземпляр QApplication, потім виконуємо декілька інтеграцій у рядках 20-26.

Потім йде частина, яка створює вікно програми:

28
29
30

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

Довга URL-адреса qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml відповідає файлу Main.qml згідно з Системою ресурсів Qt, у ній використано таку схему:<префікс_ресурсів><адреса_імпортування><каталог_QML><файл>.

Іншими словами: типовий префікс ресурсу qrc:/qt/qml/ + адреса імпортування org/kde/tutorial (встановлена у build.rs, відокремлення символами похилої риски замість крапок) + каталог QML src/qml/ + файл 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!"
        }
    }
}

Тут ми працюватимемо із оболонкою нашої програми.

Якщо ви трохи знаєте Javascript, більша частина QML видасться вам знайомою (хоча тут є свої особливості). У документації до Qt є багато матеріалу щодо цієї мови, якщо вам захочеться спробувати щось самостійно. Вивчаючи курс підручника, ми зосередимося на нашому коді QML, де ми використовуватимемо Kirigami, щоб отримати максимальні переваги від цього.

Тепер зосередимо увагу на Main.qml. Спочатку ми імпортуємо декілька важливих модулів:

• QtQuick, стандартну бібліотеку, яку використовують програми QML.
• QtQuick Controls, які забезпечують роботу декількох стандартних засобів керування, якими ми можемо скористатися для того, щоб зробити наші програми інтерактивними.
• QtQuick Layouts, які містять інструменти для розташовування компонентів у вікні програм.
• Kirigami, яка містить декілька компонентів, які пристосовано для створення програм, що можуть працювати на різних пристроях і екранах з різними формами та розмірами.

Далі, ми перейдемо до нашого базового елемента, Kirigami.ApplicationWindow, який надає певні базові можливості, потрібні для усіх програм Kirigami. Це вікно, які міститиме усі наші сторінки, основні розділи нашого інтерфейсу користувача.

Далі, ми встановимо для властивості id вікна значення 'root'. Ідентифікатори є корисними, оскільки за їх допомогою ми отримуємо унікальну прив'язку до компонента, навіть коли у нас є декілька компонентів одного типу.

Ми також встановлюємо для властивості title значення "Hello World".

Далі, ми визначаємо першу сторінку нашого стосу сторінок. Більшість програм Kirigami упорядковано як стос сторінок — кожну сторінку призначено для виконання окремого завдання. У нашому прикладі ми створимо простий стос, який складатиметься із однієї сторінки. pageStack є початково порожнім стосом сторінок, роботу якого забезпечує Kirigami.ApplicationWindow, і за допомогою pageStack.initialPage: Kirigami.Page{...} ми задаємо для першої сторінки, яку буде показано після завантаження програми, значення Kirigami.Page. Відповідна сторінка міститиме усі наші дані.

Нарешті, ми включаємо до нашої сторінки Controls.Label, яка надасть нам змогу розмістити на нашій сторінці текст. Ми використовуємо anchors.centerIn: parent для центрування нашої мітки горизонтально і вертикально у нашому батьківському елементі. У цьому випадку батьківським для компонента нашої мітки буде компонент Kirigami.Page. Нарешті, ми маємо встановити для мітки текст: text: "Hello World!".

Збирання і встановлення програми

Ви маєте знайти створений виконуваний файл kirigami_hello у build/debug/kirigami_hello, і ви можете запустити його безпосередньо або за допомогою cargo run, але в ньому не буде піктограми вікна. Щоб вирішити цю проблему, ми спочатку встановимо програму.

Віддайте такі команди:

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

За допомогою першої команди наказуємо CMake шукати Kirigami та qqc2-desktop-style.

За допомогою другої команди наказуємо CMake зібрати ціль kirigami_rust, — просто викликаємо cargo build --target-dir build/. Цей крок може бути досить тривалим, але наступного разу, коли ви повторите другу команду CMake, це буде швидше або вам взагалі не знадобиться збирання.

На третьому кроці CMake встановить виконуваний файл kirigami_hello до ~/.local/bin/kirigami_hello та файл desktop до ~/.local/share/applications, а у вашому меню з'явиться новий запис із назвою «Kirigami Tutorial in Rust».

Виберіть пункт меню, і ось і все! Тепер ви бачите перед собою вашу першу програму Kirigami вашими власними очима.

Щоб запустити нову програму QML у режимі мобільного пристрою, ви можете скористатися QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

Якщо ви зібрали проєкт вручну за допомогою CMake і з якихось причин хочете вилучити встановлений проєкт, ви можете скористатися такою командою:

cmake --build build/ --target uninstall