المادة 5: المغامرة من libs.versions.toml مشارك
Publié le 27 September 2025
مقدمة
في سعينا لإنشاء الإضافة`site-baker`سعينا للحفاظ على قاعدة كود نظيفة ومركزية. إحدى أفضل الممارسات في نظام Gradle الحديث هو استخدامقائمة الإصدارات(
)libs.versions.toml) لإدارة التبعيات. لكن ماذا يحدث عندما يصبح مشروعك أكثر تعقيدًا، مثلبناء مركبأين يجب أن يُدرج بناء مستقل (الإضافة الخاصة بنا) في آخر؟
هذا هو المكان الذي اتخذت فيه مغامرتنا منعطفًا غير متوقع. كنا نريد أن يكون مكوّننا`site-baker`, الذي هو نفسه مشروع Gradle، يستخدم نفس كتالوج الإصدارات مثل مشروعنا الرئيسي. هذه المقالة، وهي الخامسة في سلسلتنا، تروي كيف حللنا هذا التحدي.
1. كتالوج الإصدارات (libs.versions.toml) : تذكير
الملف`gradle/libs.versions.toml`هذه ميزة في Gradle تسمح بتركيز الإصدارات والإحداثيات للاعتماديات في مشروعك. عادةً ما يُنظَّم في أربعة أقسام :
-
[versions]: يُعرّف أسماء مستعارة لأرقام الإصدارات (مثال:`kotlin = "1.9.20"`). -
[libraries]: يحدد الأسماء المستعارة للاعتمادات الكاملة، باستخدام الإصدارات المعرفة أعلاه (مثل:`kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }`). -
[bundles]`جمع عدة مكتبات تحت اسم مستعار واحد (مثال:`jackson = ["jackson-core", "jackson-databind"]). -
[plugins]: يحدد أسماء مستعارة للمكوّنات الإضافية Gradle.
بمجرد تعريفه، يولد Gradle تلقائيًا مُساعِدات مكتوبة بشكل ثابت، مما يجعل عملك`build.gradle.kts`أكثر قابلية للقراءة :
dependencies {
// Au lieu de : implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.20")
implementation(libs.kotlin.stdlib)
}تدفق بيانات كتالوج الإصدارات
2. المشكلة: بناء مركب وعالمين منفصلين
هيكل مشروعنا هوبناء مركب. المشروع الرئيسي (thymeleaf.cheroliv.com) يشمل مشروع الإضافة (site-baker) عبر الأمر`includeBuild("site-baker")في الملف`settings.gradle.kts.
المشكلة هي أنه، بشكل افتراضي، فإن بناء مضمن هوعالم منفصل. له تكوينه الخاص، ودورة حياته الخاصة، ولا يرى الملف`libs.versions.toml`من النسخة principales. لنا`plugin/build.gradle.kts`كان يحاول استخدام`libs.plugins.kotlin.jvm`, لكن الكائن`libs`لم يتم إنشاؤه من ملف TOML الصحيح، مما يتسبب في حدوث أخطاء في البناء.
3. الحل : مشاركة حلّ التبعيات
بعد عدة أبحاث، تبين أن الحل هو ميزة في Gradle مصممة خصيصًا لهذا الحالة :`dependencyResolutionManagement`.
في الملف`settings.gradle.kts` du ابن شاملة(site-baker/settings.gradle.kts), يمكننا إخبار Gradle حيث يجب أن يبحث عن كتالوج الإصدارات لاستخدامه.
هذه هي التكوين الذي أضفناه إلى`site-baker/settings.gradle.kts`:
// site-baker/settings.gradle.kts
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
gradlePluginPortal()
mavenCentral()
}
versionCatalogs {
create("libs") {
from(files("../gradle/libs.versions.toml"))
}
}
}
rootProject.name = "site-baker"
include("plugin")نحلل الجزء الحاسم:
versionCatalogs {
create("libs") { // Crée un catalogue nommé 'libs'
from(files("../gradle/libs.versions.toml")) // En utilisant ce fichier
}
}-
create("libs"): نحن نعلن عن كتالوج الإصدارات الذي سيكون قابلًا للوصول عبر اللقب`libs`. -
from(files("../gradle/libs.versions.toml")): هذا هو السحر. نحن نخبر Gradle أن مصدر هذا الكتالوج هو ملف TOML الموجود في الدليل`gradle` du المشروع الأصل(../).
مع هذه الإعدادات، البناء`site-baker`يعرف الآن أنه يجب أن يستخدم كتالوج إصدارات المشروع الرئيسي. الكائن`libs`يتم إنشاؤه بشكل صحيح، ويتم حل الاعتمادات كما هو متوقع.
4. الخاتمة: قوة عمليات التجميع المركبة التي يتم إدارتها بشكل جيد
كانت هذه التجربة غنية بالدروس. كتالوج الإصدارات هو أداة رائعة للصيانة، لكن سلوكه في سيناريوهات builds المركبة ليس دائمًا بديهيًا.
المفتاح هو أن نتذكر أن البناء المضمن يبقى بناءًا مستقلاً. لمشاركة التكوينات مثل كتالوج الإصدارات، يجب استخدام الآليات الصريحة المقدمة من Gradle، مثل الكتلة`dependencyResolutionManagement`في`settings.gradle.kts`.
من خلال حل هذه المشكلة، لم نقم فقط بجعل بناءنا أنظف، بل أيضًا عززنا تماسك مشروعنا من خلال التأكد من أن الإضافة ومشروعها الرئيسي يشاركان مصدرًا واحدًا للحقيقة لتوابعهما.
في المقال القادم، سنستمر في إثراء المكون الإضافي بإضافة مهام أكثر تعقيدًا، الآن بعد أن أصبحت إدارة الاعتمادات قوية ومركزية.