التصنيفات

تنتمي جميع الأهداف إلى حزمة واحدة بالضبط. ويُطلق على اسم الهدف اسم التصنيف الخاص به. يحدّد كل تصنيف هدفًا بشكل فريد. يبدو التصنيف العادي في الشكل الأساسي على النحو التالي:

@myrepo//my/app/main:app_binary

الجزء الأول من التصنيف هو اسم المستودع، @myrepo//. في الحالة النموذجية التي يشير إليها التصنيف على المستودع نفسه الذي يتم استخدامه منه، قد يتم اختصار معرّف المستودع بالتنسيق //. لذا، في الداخل @myrepo تتم كتابة هذا التصنيف عادةً على النحو التالي:

//my/app/main:app_binary

الجزء الثاني من التصنيف هو اسم الحزمة غير المؤهَّلة، my/app/main وهو المسار إلى الحزمة بالنسبة إلى جذر المستودع. معًا، يشكّل اسم المستودع واسم الحزمة غير المؤهّلة اسم الحزمة المؤهلة بالكامل.@myrepo//my/app/main وإذا كان التصنيف يشير إلى الحزمة نفسها المستخدَمة فيها، قد يتم حذف اسم الحزمة (وبشكل اختياري علامة النقطتين الرأسيتين). لذا في داخل @myrepo//my/app/main، قد تتم كتابة هذا التصنيف بأيٍّ من الطريقتَين التاليتَين:

app_binary
:app_binary

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

الجزء من التصنيف بعد النقطتين الرأسيتين هو app_binary. وعند تطابقه مع المكوِّن الأخير في مسار الحزمة، قد يتم حذفه، والنقطتين الرأسيتين. لذلك، هناك نوعان من التصنيفات متساويان:

//my/app/lib
//my/app/lib:lib

اسم الملف المستهدَف في دليل فرعي للحزمة هو مسار file's مقارنةً بجذر الحزمة (الدليل الذي يتضمّن الملف BUILD). إذن، يوجد هذا الملف في الدليل الفرعي لـ my/app/main/testdata للمستودع:

//my/app/main:testdata/input.txt

تحمل سلاسل مثل //my/app و@some_repo//my/app معانيَين حسب السياق الذي يتم استخدامهما فيه: عندما يتوقع بازل تصنيفًا، يعني ذلك //my/app:app و@some_repo//my/app:app، على التوالي. ولكن عندما تتوقّع Bazel طردًا (مثلاً في مواصفات package_group)، فإنها تشير إلى الحزمة التي تحتوي على ذلك التصنيف.

هناك خطأ شائع في ملفات BUILD وهي استخدام //my/app للإشارة إلى حزمة، أو لجميع الأهداف في حزمة، الأمر الذي لا يحدث. تجدر الإشارة إلى أنها تساوي //my/app:app، لذلك يتم تسمية الهدف app في الحزمة my/app من المستودع الحالي.

ومع ذلك، يُنصح باستخدام //my/app للإشارة إلى حزمة في مواصفات ملف package_group أو في .bzl، لأنه يوضّح بوضوح أنّ اسم الحزمة كامل وجذر في دليل المستوى الأعلى لمساحة العمل.

لا يمكن استخدام التصنيفات النسبية للإشارة إلى الاستهدافات في الحزم الأخرى، ويجب تحديد معرّف المستودع واسم الحزمة دائمًا في هذه الحالة. على سبيل المثال، إذا كان الهيكل المصدر يتضمّن كلاً من الحزمة my/app والحزمة my/app/testdata (يحتوي كل دليل من هذين الدليلين على ملف BUILD خاص به)، تحتوي الحزمة الأخيرة على ملف باسم testdepot.zip. في ما يلي طريقتان (طريقة خاطئة وأخرى صحيحة) للإشارة إلى هذا الملف ضمن //my/app:BUILD:

غير صحيحة — testdata هي حزمة مختلفة، لذا لا يمكنك استخدام مسار نسبي

testdata/testdepot.zip

صحيح: راجِع testdata بمساره الكامل

//my/app/testdata:testdepot.zip

إنّ التصنيفات التي تبدأ بـ @// هي إشارات إلى المستودع الرئيسي، الذي سيظل يعمل حتى من المستودعات الخارجية. بالتالي، تختلف السمة @//a/b/c عن السمة //a/b/c عند الإشارة إليها من مستودع خارجي. تشير الصفحة السابقة إلى المستودع الرئيسي، في حين تبحث المؤسسة الثانية عن //a/b/c في المستودع الخارجي نفسه. ويُعدّ ذلك مفيدًا على وجه الخصوص عند كتابة القواعد في المستودع الرئيسي الذي يشير إلى الأهداف في المستودع الرئيسي، وسيتم استخدامه من المستودعات الخارجية.

للحصول على معلومات حول الطرق المختلفة التي يمكنك من خلالها الرجوع إلى الأهداف، يمكنك الاطّلاع على الأنماط المستهدفة.

المواصفات اللغوية للتصنيف

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

في ما يلي التفاصيل الدقيقة لأسماء الأهداف المسموح بها.

الأسماء المستهدفة — package-name:target-name

target-name هو اسم الهدف ضمن الحزمة. يكون اسم القاعدة هو قيمة السمة name في بيان القاعدة&#39؛ في ملف BUILD، ويكون اسم الملف هو اسم المسار المرتبط بالدليل الذي يحتوي على الملف BUILD.

يجب أن تتألف الأسماء المستهدفة بالكامل من أحرف مرسومة من المجموعة a–z، AوZ، 0-9، ورموز الترقيم !%-@^_"#$&'()*-+,;<=>?[]{|}~/..

يجب أن تكون أسماء الملفات أسماء مسارات نسبية بالشكل العادي، أي أنّه يجب ألا تبدأ أو تنتهي بشرطة مائلة (مثلاً، /foo وfoo/ ممنوعة) وألا تحتوي على عدة شرطات متتالية، مثل فواصل المسارات (على سبيل المثال، foo//bar). وبالمثل، يُحظر استخدام المراجع ذات المستوى الأعلى (..) والمراجع الحالية في الدليل (./).

غير صحيح - لا تستخدم `..` للإشارة إلى الملفات في حزم أخرى

صحيح - استخدِم `//package-name:filename`

من الشائع استخدام / في اسم استهداف الملف، ولكن تجنّب استخدام / في أسماء القواعد. فقد يؤدي ذلك إلى إرباك القارئ خاصةً عند استخدام شكل مختصر للتصنيف. ودائمًا ما يكون التصنيف //foo/bar/wiz اختصارًا للكلمة //foo/bar/wiz:wiz، حتى في حال عدم وجود حزمة foo/bar/wiz من هذا النوع، ولا يشير مطلقًا إلى //foo:bar/wiz، حتى في حال توفّر هذا الهدف.

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

أسماء الطرود — //package-name:target-name

اسم الحزمة هو اسم الدليل الذي يحتوي على ملف BUILD الخاص به، مقارنةً بدليل المستوى الأعلى للمستودع الذي يحتوي عليه. مثلاً: my/app

يجب أن تتألف أسماء الحزم بالكامل من أحرف مرسومة من المجموعة A-Z، a–z، 0–9، '/', '-', '.', '@', '_', ولا يمكن أن تبدأ بشرطة مائلة.

بالنسبة إلى اللغة التي لها بنية دليل مهمة لنظام الوحدات (مثل Java)، من المهم اختيار أسماء الأدلة التي تكون معرّفات صالحة في اللغة.

على الرغم من أن Bazel يدعم الأهداف في الحزمة الجذر في مساحة العمل (على سبيل المثال، //:foo)، من الأفضل ترك هذه الحزمة فارغة كي تحتوي جميع الحزم المفيدة على أسماء وصفية.

لا يجوز أن تحتوي أسماء الحِزم على السلسلة الفرعية //، ولا تنتهي بشرطة مائلة.

القواعد

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

تحدِّد ملفات BUILD الأهداف عن طريق استدعاء القواعد.

في المثال أدناه، نعرض إعلان الاستهداف my_app باستخدام القاعدة cc_binary.

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)

يحتوي كل استدعاء للقاعدة على سمة name (يجب أن تكون سمة اسم هدف صالحة) تشير إلى هدف ضمن حزمة ملف BUILD.

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

تحتوي السمة srcs المتوفّرة في عدة قواعد على النوع "قائمة التصنيفات&;; وقيمتها، إن وجدت، هي قائمة بالتصنيفات، يكون كل منها اسمًا لهدف إدخال في هذه القاعدة.

في بعض الحالات، يكون اسم نوع القاعدة عشوائيًا إلى حد ما، والمزيد من الأمور المثيرة للاهتمام هي أسماء الملفات التي تم إنشاؤها من خلال القاعدة، وينطبق ذلك على القواعد العامة. لمزيد من المعلومات، راجِع القواعد العامة: genrule.

في حالات أخرى، يكون الاسم مهمًا: بالنسبة إلى قاعدتَي *_binary و*_test، على سبيل المثال، يحدّد اسم القاعدة اسم الملف التنفيذي الذي تم إنشاؤه من خلال الإصدار.

يُسمّى هذا الرسم البياني الدائري الموجّه فوق الأهداف الرسم البياني المستهدف أو الرسم البياني للاعتمادية، وهو النطاق الذي تعمل عليه أداة طلبات بحث Bazel.

الأهداف ملفات BBILD