قواعد المستودع

توضّح هذه الصفحة كيفية إنشاء قواعد المستودع وتقدّم أمثلة لالمزيد من التفاصيل.

المستودع الخارجي هو قاعدة لا يمكن استخدامها إلا في ملف WORKSPACE، وهي تفعّل التشغيل غير الزخرفي في مرحلة التحميل لميزة Bazel. وتُنشئ كل قاعدة مستودع خارجي مساحة عمل خاصة بها، مع ملفات BUILD وعناصرها الخاصة. ويمكن استخدامها للاعتماد على مكتبات الجهات الخارجية (مثل المكتبات المجمّعة في Maven)، فضلاً عن إنشاء ملفات BUILD خاصة بالمضيف الذي يجري تشغيل Bazel عليه.

إنشاء قاعدة المستودع

في ملف .bzl، يمكنك استخدام الدالة repository_rule لإنشاء قاعدة مستودع جديدة وتخزينها في متغير عام.

يمكن استخدام قاعدة مستودع مخصصة تمامًا مثل قاعدة مستودع الإعلانات الأصلية. ويحتوي العنصر على سمة name إلزامية، ويمكن الإشارة إلى كل هدف في ملفات الإصدار باسم @<name>//package:target، حيث يكون <name> هو قيمة السمة name.

يتم تحميل القاعدة عند إنشائها صراحةً، أو إذا كانت اعتمادية على الإصدار. في هذه الحالة، سينفِّذ Bazel دالة implementation. تصف هذه الدالة كيفية إنشاء المستودع ومحتواه وملفات BUILD.

السمات

السمة هي وسيطة قاعدة، مثل url أو sha256. يجب إدراج السمات وأنواعها عند تعريف قاعدة مستودع.

local_repository = repository_rule(
    implementation=_impl,
    local=True,
    attrs={"path": attr.string(mandatory=True)})

للوصول إلى سمة، استخدِم repository_ctx.attr.<attribute_name>.

تحتوي repository_rule على سمات محدّدة بشكل ضمني (مثل قواعد الإصدار). إنّ السمتَين الضمنيتَين هما name (تمامًا مثل قواعد الإصدار) و repo_mapping. يمكن الوصول إلى اسم قاعدة المستودع مع repository_ctx.name. يشير معنى repo_mapping إلى كل من قواعد المستودع الإعلاني المدمجة مع المحتوى local_repository وnew_local_repository.

إذا كان اسم السمة يبدأ بـ _، يكون خاصًا ولا يمكن للمستخدمين ضبطه.

وظيفة التنفيذ

تتطلب كل قاعدة مستودع وظيفة implementation. وتحتوي على المنطق الفعلي للقاعدة ويتم تنفيذه بصرامة في مرحلة التحميل.

تحتوي الدالة على معلمة إدخال واحدة بالضبط، repository_ctx. تعرض الدالة إما None للإشارة إلى أن القاعدة قابلة للتكرار في ظل المعلمات المحددة، أو قاعدة مع مجموعة من المعلمات لتلك القاعدة التي ستحوّل هذه القاعدة إلى قاعدة قابلة للتكرار تنشئ المستودع نفسه. على سبيل المثال، بالنسبة إلى قاعدة تتبُّع مستودع git يعني عرض معرّف إتمام محدّد بدلاً من فرع عائم تم تحديده في الأصل.

ويمكن استخدام معلّمة الإدخال repository_ctx للوصول إلى قيم السمات والدوال غير المتناسقة (العثور على برنامج ثنائي أو تنفيذ برنامج ثنائي أو إنشاء ملف في المستودع أو تنزيل ملف من الإنترنت). يمكنك الاطّلاع على المكتبة للحصول على مزيد من المعلومات. مثال:

def _impl(repository_ctx):
  repository_ctx.symlink(repository_ctx.attr.path, "")

local_repository = repository_rule(
    implementation=_impl,
    ...)

متى يتم تنفيذ وظيفة التنفيذ؟

إذا تم الإعلان عن المستودع باسم local، سيؤدي التغيير في الاعتمادية على الرسم البياني للاعتمادية (بما في ذلك ملف WORKSPACE نفسه) إلى تنفيذ دالة التنفيذ.

يمكن إعادة تشغيل دالة التنفيذ إذا كانت الاعتمادية التي تطلبها مفقودة. ستتم إعادة تنفيذ بداية دالة التنفيذ بعد حل الاعتمادية. لتجنب عمليات إعادة التشغيل غير الضرورية (التي تكون باهظة الثمن، لأنه قد يلزم تكرارها)، يتم جلب وسيطات التصنيف مسبقًا، شريطة أن يتم حل جميع وسيطات التصنيفات إلى ملف حالي. تجدر الإشارة إلى أنّ حلّ مسار من سلسلة أو تصنيف تم إنشاؤه فقط أثناء تنفيذ الدالة قد يؤدي إلى إعادة التشغيل.

وأخيرًا، بالنسبة إلى المستودعات غير التابعة لخدمة local، قد يؤدي إجراء تغيير في العناصر التابعة التالية فقط إلى إعادة التشغيل:

• يجب أن يتوفّر ملفان (.bzl) لتحديد قاعدة المستودع.
• بيان قاعدة المستودع في ملف WORKSPACE
• قيمة أي متغيّر بيئة تمّ الإعلان عنها باستخدام السمة environ للدالة repository_rule. يمكن فرض قيمة متغيّر البيئة هذا من سطر الأوامر باستخدام العلامة --action_env (ولكن هذه العلامة ستلغي صلاحية كل إجراء على الإصدار).
• محتوى أي ملف مستخدَم ويُشار إليه بتصنيف (مثل //mypkg:label.txt وليس mypkg/label.txt).

إلزام إعادة استرجاع المستودعات الخارجية

في بعض الأحيان، يمكن أن يصبح المستودع الخارجي قديمًا بدون أي تغيير في تعريفه أو تبعياته. على سبيل المثال، قد تتّبع مصادر استرجاع المستودع مستودعًا معيّنًا لمستودع تابع لطرف ثالث، وتتوفّر الالتزامات الجديدة في ذلك الفرع. في هذه الحالة، يمكنك أن تطلب من Bazel إعادة جلب جميع المستودعات الخارجية بدون شروط من خلال طلب الرقم bazel sync.

بالإضافة إلى ذلك، تفحص بعض القواعد الجهاز المحلي وقد تصبح قديمة إذا تمت ترقية الجهاز المحلي. يمكنك في هذه الصفحة أن تطلب من البازيل إعادة جلب تلك المستودعات الخارجية فقط حيث تم تحديد السمة configure repository_rule. استخدِم السمة bazel sync --configure.

أمثلة

• سلسلة أدوات تم ضبطها تلقائيًا في C++ : تستخدم قاعدة مستودع لإنشاء ملفات إعداد C++ تلقائيًا لتطبيق Bazel من خلال البحث عن برنامج التجميع C++ المحلي، والبيئة والعلامات التي يدعمها برنامج التجميع C++.

• تستخدم مستودعات Go العديد من repository_rule لتحديد قائمة التبعيات المطلوبة لاستخدام قواعد Go.

• تنشئ rules_jvm_external مستودعًا خارجيًا باسم @maven بشكل تلقائي ينشئ أهداف تصميم لكل عنصر من عناصر Maven في شجرة الاعتمادية الانتقالية.