الإعداد مع Rust

تنصيب كيريغامي

قبل البدء، سنحتاج إلى تثبيت كيريغامي و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-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

الغرض الأساسي من ملفات إدخال سطح المكتب هو عرض تطبيقك على مشغل التطبيقات في لينكس. سبب آخر لامتلاكها هو الحصول على أيقونات النوافذ على 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

[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[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 ولتثبيت الملفات الضرورية مع تطبيقنا. كما يوفر ميزات معينة لتحسين جودة الحياة، مثل التأكد من تثبيت كيريغامي أثناء التجميع ولإشارة توزيعات لينكس إلى تثبيت التبعيات الضرورية مع التطبيق.

 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) إلى مشروعنا حتى نتمكن من استخدام ecm_find_qml_module للتحقق من تثبيت كيريغامي عند محاولة بناء التطبيق، وإذا لم يكن مثبتًا، نفشل فورًا. ميزة أخرى مفيدة في ECM هي ECMUninstallTarget، والتي تسمح بإلغاء تثبيت التطبيق بسهولة باستخدام CMake إذا رغبت.

نستخدم أيضًا find_package() من CMake للتأكد من وجود qqc2-desktop-style، نمط QML لسطح المكتب من كيدي. هذا أحد السببين لاستخدامنا CMake في هذا الدليل.

عادةً تُبنى مشاريع Rust باستخدام Cargo، ولن يختلف الأمر هنا. ننشئ هدفًا سيشغّل Cargo ببساطة عند تشغيله، ونعلّمه بـ ALL ليُبنى افتراضيًا. سيبني Cargo الملف القابل للتنفيذ داخل دليل CMake الثنائي (عادةً build/).

لمزيد من المعلومات حول CMake والأهداف ودليل الثنائيات، راجع بناء برمجيات كيدي يدويًا.

بعد ذلك، نُثبّت ببساطة الملف التنفيذي kirigami_rust الذي يولّده Cargo في دليل الثنائيات ونُثبّته في BINDIR، وهو عادةً /usr/bin أو /usr/local/bin أو ~/.local/bin. ونُثبّت أيضًا ملف سطح المكتب الضروري في APPDIR، وهو عادةً /usr/share/applications أو ~/.local/share/applications. وهذا هو السبب الثاني لاستخدامنا CMake في هذا الدليل.

لمزيد من المعلومات حول مكان تثبيت برمجيات كيدي، راجع بناء برمجيات كيدي يدويًا: خطوة التثبيت.

والآن بعد أن عُولج أمر 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، ويتبع هذا المخطط: <بادئة_المورد><URI_الاستيراد><دليل_QML><ملف>.

بعبارة أخرى: بادئة المورد المبدئية 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 وملف سطح المكتب تحت ~/.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