Настройка проекта на 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-devel
Fedora	sudo dnf install cargo cmake extra-cmake-modules kf6-kirigami-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

Основное назначение файлов .desktop — показывать приложение в меню запуска приложений в Linux. Ещё одна причина их использовать — значки окон в Wayland, поскольку они нужны, чтобы сообщить композитору: «это окно соответствует этому значку».

Оно должно соответствовать схеме обратного именования DNS, за которой следует расширение .desktop, например org.kde.kirigami_rust.desktop:

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

[Desktop Entry]
Name=Kirigami Tutorial in Rust
Name[ar]=درس كيريغامي برست
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[pt_BR]=Tutorial do Kirigami em Rust
Name[ro]=Îndrumar Kirigami în Rust
Name[ru]=Учебное руководство по Kirigami на Rust
Name[sk]=Tutoriál Kirigami v Ruste
Name[sl]=Učbenik Kirigami v Rustu
Name[sv]=Kirigami-handledning i Rust
Name[tr]=Rust ile Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami для Rust
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})

Первым делом в проект добавляется Extra CMake Modules (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. Кроме того, в APPDIR, обычно /usr/share/applications или ~/.local/share/applications, устанавливается требуемый файл .desktop. Это вторая причина использования CMake в этом руководстве.

Дополнительные сведения о том, куда устанавливается программное обеспечение KDE, можно найти в разделе Сборка программного обеспечения KDE вручную: шаг установки.

Теперь, когда с CMake разобрались, рассмотрим файлы, с которыми предстоит работать большую часть времени.

Cargo.toml

Далее приведён очень простой Cargo.toml:

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

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

[dependencies]
cxx = "1.0.194" # Check the latest available version at https://crates.io/crates/cxx

# Check the latest available version of all related cxx-qt crates at https://crates.io/crates/cxx-qt
cxx-qt = "0.8.1"
cxx-qt-lib = { version="0.8.1", features = ["qt_full"] }
cxx-qt-lib-extras = "0.8.1"

[build-dependencies]
# The link_qt_object_files feature is required for statically linking Qt 6.
cxx-qt-build = { version = "0.8.1", 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

use cxx_qt_build::{CxxQtBuilder, QmlModule};

fn main() {
    CxxQtBuilder::new_qml_module(
        QmlModule::new("org.kde.tutorial")
            .qml_files(&["src/qml/Main.qml"])
    )
    .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

use cxx_qt_lib::{QGuiApplication, QQmlApplicationEngine, QQuickStyle};
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(&"org.kde.kirigami_rust".into());
    // To ensure the style is set correctly
    let style = env::var("QT_QUICK_CONTROLS_STYLE");
    if style.is_err() {
        QQuickStyle::set_style(&"org.kde.desktop".into());
    }

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

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

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

После этого начинается важная часть:

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

Сначала создаётся новый экземпляр QApplication, затем в строках 20–26 выполняются несколько интеграций.

Затем идёт часть, которая непосредственно создаёт окно приложения:

Длинный URL qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml соответствует файлу Main.qml согласно системе ресурсов Qt и следует схеме: <resource_prefix><import_URI><QML_dir><file>.

Иными словами: префикс ресурса по умолчанию qrc:/qt/qml/ + URI импорта 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