الدوال

المحتويات

• الحزمة
• package_group
• exports_files
• كرة قدم
• اختيار
• الحِزم الفرعية

طرد

package(default_deprecation, default_testonly, default_visibility, features)

تحدّد هذه الدالة البيانات الوصفية التي تنطبق على كل قاعدة لاحقة في الحزمة. ويتم استخدامها مرة واحدة على الأكثر في الحزمة (ملف BUILD).

يجب استدعاء دالة package() مباشرةً بعد جميع عباراتload() في أعلى الملف، قبل أي قاعدة.

الوسيطات

السمة	الوصف
default_visibility	List of labels; optional إذن الوصول التلقائي للقواعد في هذه الحزمة ويكون لكل قاعدة في هذه الحزمة إذن الوصول المُحدَّد في هذه السمة، ما لم يُذكر خلاف ذلك في سمة visibility للقاعدة. لمزيد من التفاصيل حول بنية هذه السمة، يمكنك الاطّلاع على مستندات مستوى العرض. ولا تنطبق إذن الوصول التلقائي للحزمة على exports_files، المتاحة للجميع بشكل تلقائي.
default_deprecation	String; optional لضبط رسالة deprecation التلقائية لجميع القواعد في هذه الحزمة.
default_testonly	Boolean; optional; default is False except as noted لضبط سمة testonly التلقائية لكل القواعد في هذه الحزمة. في الحِزم التي يقل حجمها عن javatests، تكون القيمة التلقائية 1.
features	List strings; optional لضبط علامات مختلفة تؤثر في دلالات ملف BUILD. تُستخدَم هذه الميزة بشكل أساسي من قِبل الأشخاص الذين يستخدمون نظام التصميم لوضع علامات على الحِزم التي تحتاج إلى معالجة خاصة. لا تستخدم هذه السمة إلا إذا طلبها صراحةً شخص يعمل على نظام التصميم.

أمثلة

يعلن البيان أدناه أن القواعد في هذه الحزمة مرئية فقط لأعضاء مجموعة الحزمة //foo:target. تصريحات دخول فردية على قاعدة، إن وجدت، تلغي هذه المواصفات.

package(default_visibility = ["//foo:target"])

package_group (مجموعة_الحزمة)

package_group(name, packages, includes)

تحدّد هذه الدالة مجموعة من الحِزم وتربط تصنيفًا بالمجموعة. يمكن الإشارة إلى التصنيف في سمات visibility.

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

تُعدّ أي حزمة متوفّرة في المجموعة إذا كانت تتطابق مع السمة packages أو إذا كانت مضمّنة في إحدى مجموعات الحِزم الأخرى المذكورة في السمة includes.

تُعد مجموعات الطرود استهدافات من الناحية الفنية، ولكن لا يتم إنشاؤها من خلال القواعد، ولا تتضمن هذه المجموعات أي حماية لمستوى الرؤية.

الوسيطات

السمة	الوصف
name	Name; required الاسم الفريد لهذا الهدف.
packages	List of strings; optional قائمة لا تتضمن أي مواصفات لحزمة أو أكثر. يمكن أن تكون كل سلسلة لمواصفات الحزمة أحد النماذج التالية: الاسم الكامل لحزمة بدون مستودع، يبدأ بشرطة مائلة مرتين. على سبيل المثال، تحدّد الخاصية //foo/bar الحزمة التي تحمل هذا الاسم وتلك المتوفّرة في المستودع نفسه الذي تستخدمه مجموعة الحِزم. كما هو موضّح أعلاه، ولكن مع إضافة لاحقة /.... على سبيل المثال، تحدّد السمة //foo/... مجموعة //foo وجميع حُزمها الفرعية. يحدّد //... جميع الحِزم في المستودع الحالي. السلاسل public أو private، التي تحدّد على التوالي كل حزمة أو حزمة. (يتطلب هذا النموذج ضبط العلامة --incompatible_package_group_has_public_syntax.) بالإضافة إلى ذلك، قد يسبق النوعَين الأولَين من مواصفات حزمَات العلامة - أيضًا للإشارة إلى إلغاءهما. تحتوي مجموعة الحِزم على أي حزمة تتطابق مع سمة واحدة على الأقل من مواصفاتها الإيجابية ولا تتوافق مع أي من مواصفاتها السلبية. على سبيل المثال، تشمل القيمة [//foo/..., -//foo/tests/...] كل الحِزم الفرعية //foo التي لا تتضمّن أيضًا حِزم //foo/tests الفرعية. (يتم تضمين //foo نفسه بينما لا يتم تضمين //foo/tests نفسها). علاوةً على ظهور المحتوى للجميع، ما مِن طريقة لتحديد الحِزم خارج المستودع الحالي مباشرةً. وإذا لم تتوفّر هذه السمة، تتطابق هذه السمة مع ضبط السمة على قائمة فارغة، وهي أيضًا مضبوطة على قائمة تحتوي على private فقط. ملاحظة: تتميّز المواصفات //... بسلوك قديم مثل السمة public. ويتم إيقاف هذا السلوك عند تفعيل --incompatible_fix_package_group_reporoot_syntax. ملاحظة: كسلوك قديم، عندما يتم ترميز هذه السمة كجزء من bazel query --output=proto (أو --output=xml)، يتم حذف الشرطة المائلة الأولى في حال عدم تفعيل --incompatible_package_group_includes_double_slash. على سبيل المثال، سيتم إخراج //pkg/foo/... على أنه \"pkg/foo/...\".
includes	List of labels; optional مجموعات الحزم الأخرى المضمّنة في هذه الحزمة. يجب أن تشير التصنيفات في هذه السمة إلى مجموعات حزمات أخرى. يتم أخذ الحِزم في مجموعات الطرود المرجعية كجزء من مجموعة الحِزم هذه. هذه المجموعة تفاعلية، وإذا كانت مجموعة الطرود a تتضمّن مجموعة الطرود b، وكانت المجموعة b تتضمّن مجموعة الطرود c، ستكون كل حزمة في c عضوًا في a. وعند استخدام هذه السمة مع مواصفات الحزمة المُلغاة، لاحِظ أنّ مجموعة الحِزم لكل مجموعة يتم احتسابها أولاً بشكل مستقل ويتم توحيد النتائج معًا. وهذا يعني أنّ المواصفات المُلغاة في إحدى المجموعات لا تؤثّر في المواصفات في مجموعة أخرى.

أمثلة

يحدّد بيان package_group التالي مجموعة حُزم تُسمّى &"تروبيكال"تحتوي على فواكه استوائية.

package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)

تحدّد التعريفات التالية مجموعات حِزم تطبيق خيالية:

package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

package_group(
    name = "model",
    packages = ["//fooapp/database"],
)

package_group(
    name = "view",
    packages = [
        "//fooapp/swingui",
        "//fooapp/webui",
    ],
)

package_group(
    name = "controller",
    packages = ["//fooapp/algorithm"],
)

الملفات_التصديرية

exports_files([label, ...], visibility, licenses)

تحدّد الخاصية exports_files() قائمة بالملفات التي تنتمي إلى هذه الحزمة التي تم تصديرها إلى حِزم أخرى.

قد لا يشير ملف BUILD لحزمة إلى ملفات المصدر التي تنتمي إلى حزمة أخرى مباشرةً إلا إذا تم تصديرها بشكل صريح مع عبارة exports_files(). يمكنك الاطّلاع على مزيد من المعلومات عن إذن الوصول إلى الملفات.

وكالسلوك القديم، يتم أيضًا تصدير الملفات المذكورة كإدخال إلى قاعدة باستخدام إذن الوصول التلقائي إلى أن يتم قلب العلامة --incompatible_no_implicit_file_export. ومع ذلك، يجب عدم الاعتماد على هذا السلوك ونقله بعيدًا عن نطاقه.

الوسيطات

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

مثال

يتم في المثال التالي تصدير golden.txt، وهو ملف نصي من الحزمة test_data، بحيث يمكن للحزم الأخرى استخدامه، على سبيل المثال، في السمة data من الاختبارات.

# from //test_data/BUILD

exports_files(["golden.txt"])

كرة أرضية

glob(include, exclude=[], exclude_directories=1, allow_empty=True)

Glob هي وظيفة مساعِدة تبحث عن جميع الملفات التي تطابق أنماط مسارات معيّنة، وتعرض قائمة جديدة للمسارات بمسارات قابلة للترتيب. لا يبحث تطبيق Glob إلا عن الملفات في حزمته الخاصة، ويبحث فقط عن الملفات المصدر (وليس الملفات التي تم إنشاؤها أو الأهداف الأخرى).

يتم تضمين تصنيف ملف المصدر في النتيجة إذا كان مسار الملف الخاص بالحزمة يتطابق مع أي من أنماط include أو لا يطابق أيًا من أنماط exclude.

تحتوي قائمتا include وexclude على أنماط مسارات نسبية إلى الحزمة الحالية. ويمكن أن يتألف كل نمط من جزء مسار واحد أو أكثر. وكما هو الحال مع مسارات Unix، يتم فصل هذه الشرائح باستخدام /. يمكن أن تحتوي الشرائح على حرف البدل *: يطابق أي سلسلة فرعية في شريحة المسار (حتى السلسلة الفرعية الفارغة)، باستثناء فاصل الدليل /. ويمكن استخدام حرف البدل عدة مرات ضمن شريحة مسار واحدة. إضافةً إلى ذلك، يمكن أن يتطابق حرف البدل ** مع صفر أو شرائح مسار أكثر اكتمالاً، ولكن يجب التصريح عنه كشريحة مسار مستقلة.

أمثلة:

• يطابق foo/bar.txt الملف foo/bar.txt تمامًا في هذه الحزمة
• يطابق foo/*.txt كل ملف في الدليل foo/ إذا كان الملف ينتهي بـ .txt (ما لم يكن foo/ حزمة فرعية)
• يطابق foo/a*.htm* كل ملف في الدليل foo/ يبدأ بـ a، ثم يحتوي على سلسلة عشوائية (يمكن أن تكون فارغة)، ثم يحتوي على .htm، وينتهي بسلسلة عشوائية. مثل foo/axx.htm وfoo/a.html أو foo/axxx.html
• **/a.txt يطابق كل ملف a.txt في كل دليل فرعي لهذه الحزمة
• تتطابق **/bar/**/*.txt مع كل ملف .txt في كل دليل فرعي لهذه الحزمة، إذا كان هناك دليل واحد على الأقل على المسار الناتج يُسمى bar، مثل xxx/bar/yyy/zzz/a.txt أو bar/a.txt (تذكّر أن ** يتطابق أيضًا مع صفر الشرائح) أو bar/zzz/a.txt
• ** يطابق كل ملف في كل دليل فرعي لهذه الحزمة
• foo**/a.txt هو نمط غير صالح، لأن ** يجب أن يكون مستقلًا ضمن شريحة

في حال تفعيل الوسيطة exclude_directories (تم الضبط على 1)، سيتم حذف ملفات دليل الأنواع من النتائج (القيمة التلقائية 1).

إذا تم ضبط الوسيطة allow_empty على False، سيتم رفض دالة glob إذا كانت النتيجة هي القائمة الفارغة.

هناك عدة قيود وتحذيرات مهمة:

1. بما أنّه يتم تشغيل glob() أثناء تقييم ملف BUILD، لا تتطابق glob() مع الملفات إلا في العرض التدرّجي المصدر، ولا يتم إنشاء ملفات مطلقًا. إذا كنت تنشئ هدفًا يتطلّب كلاً من الملفات المصدر والملفات التي تم إنشاؤها، عليك إلحاق قائمة صريحة بالملفات التي تم إنشاؤها على مستوى الكرة الأرضية. راجِع المثال أدناه مع :mylib و:gen_java_srcs.

2. إذا كان للقاعدة الاسم نفسه كملف مصدر مُطابِق، تكون القاعدة "تظليل"الملف.

   لفهم هذا الأمر، تذكّر أنّ glob() يعرض قائمة بالمسارات، لذا فإن استخدام السمة glob() في قواعد أخرى&#39؛ يكون للسمة (مثل srcs = glob(["*.cc"])) التأثير نفسه الذي تؤدّي إليه عملية إدراج المسارات المطابقة. على سبيل المثال، سينتج عن السمة glob() ["Foo.java", "bar/Baz.java"] ولكن هناك أيضًا قاعدة في الحزمة تُسمَّى &&;;;;oo.Foo.java" (مسموح بها، على الرغم من أن Bazel تحذّرها)، لأنّ مستهلك glob() سيستخدِم القاعدة "&&;;Foo.java" (النتائج) بدلاً من الملف "Foo.java". ولمزيد من التفاصيل، يمكنك الاطّلاع على المشكلة رقم 10395 من GitHub.

3. قد تتطابق الكرة الأرضية مع الملفات في الأدلة الفرعية. وقد يتم إدخال حرف بدل في أسماء الأدلة الفرعية. ومع ذلك...

4. لا يُسمح للتصنيفات بعبور حدود الحزمة ولا يتطابق الملف glob مع الملفات في الحزم الفرعية.

   على سبيل المثال، لا يتضمّن تعبير glob **/*.cc في الحزمة x x/y/z.cc إذا كان x/y متوفرًا كحزمة (إما x/y/BUILD أو في مكان آخر على مسار الحزمة). وهذا يعني أن نتيجة التعبير glob في الواقع تعتمد على وجود ملفات BUILD. وبالتالي، سيتضمن تعبير glob نفسه x/y/z.cc إذا لم تكن هناك حزمة باسم x/y أو تم وضع علامة عليها على أنها محذوفة باستخدام العلامة --delete_packages.

5. ويسري القيد أعلاه على جميع تعبيرات الكرة الأرضية، بغض النظر عن أحرف البدل التي يستخدمونها.
6. تتم مطابقة ملف مخفي باسم الملف الذي يبدأ بـ . تمامًا مع حرفَي البدل ** و*. إذا كنت تريد مطابقة ملف مخفي مع نمط مركّب، يجب أن يبدأ النقش بعلامة .. على سبيل المثال، * و.*.txt ستطابق .foo.txt، ولكن *.txt لن تتطابق. تتم مطابقة الأدلة المخفية أيضًا بالطريقة نفسها. قد تتضمن الأدلة المخفية ملفات غير مطلوبة كإدخالات، ويمكن أن تزيد من عدد الملفات غير الضرورية واستهلاك الذاكرة. لاستبعاد الأدلة المخفية، أضِفها إلى وسيطة القائمة "exclude".
7. تتضمّن حرف البدل "&&;;##"quot;شرطًا واحدًا": لا يتطابق النمط "**" مع مسار الدليل الخاص بالحزمة's. ويعني ذلك أنّ glob(["**"], exclude_directories = 0) يطابق جميع الملفات والأدلة بشكلٍ عابر ضمن الدليل الحالي الخاص بالحزمة (ولكن بدون توجيه بالطبع إلى أدلة الحزم الفرعية، يُرجى الاطّلاع على الملاحظة السابقة حول ذلك).

بوجه عام، يجب محاولة تقديم إضافة مناسبة (مثل *.html) بدلاً من استخدام عارية و#39;*' لنمط كرات أرضية. يساعد الاسم الأكثر وضوحًا على التوثيق الذاتي ويضمن عدم تطابقك مع ملفات الاحتفاظ بنسخة احتياطية من الملفات أو ملفات emacs/vi/ تلقائيًا.

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

أمثلة على الكرة الأرضية

يمكنك إنشاء مكتبة Java من جميع ملفات java في هذا الدليل، وجميع الملفات التي تم إنشاؤها بواسطة قاعدة :gen_java_srcs.

java_library(
    name = "mylib",
    srcs = glob(["*.java"]) + [":gen_java_srcs"],
    deps = "...",
)

genrule(
    name = "gen_java_srcs",
    outs = [
        "Foo.java",
        "Bar.java",
    ],
    ...
)

أدرِج جميع ملفات txt في بيانات اختبار الدليل باستثناء beta.txt. يُرجى ملاحظة أنه لن يتم تضمين الملفات في الأدلة الفرعية لبيانات الاختبار. وإذا كنت تريد تضمين هذه الملفات، استخدِم الكرة الأرضية المتكرّرة (**).

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

أمثلة على الكرة الأرضية المتكررة

يعتمد الاختبار على جميع ملفات txt في دليل اختبار البيانات وعلى أي أدلة فرعية له (وأدلّته الفرعية وغيرها). يتم تجاهل الأدلة الفرعية التي تحتوي على ملف BUILD. (اطّلِع على القيود والتنبيهات أعلاه).

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)

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

java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)

أمثلة على الكرة الأرضية الموسّعة

أنشئ قاعدة عامة لـ *_test.cc في الدليل الحالي تحسب عدد الأسطر في الملف.

# Conveniently, the build language supports list comprehensions.
[genrule(
    name = "count_lines_" + f[:-3],  # strip ".cc"
    srcs = [f],
    outs = ["%s-linecount.txt" % f[:-3]],
    cmd = "wc -l $< >$@",
 ) for f in glob(["*_test.cc"])]

إذا كان ملف BUILD أعلاه في الحزمة //foo وكانت الحزمة تحتوي على ثلاثة ملفات مطابقة، a_test.cc، وb_test.cc وc_test.cc قيد التشغيل، وسيدرج bazel query '//foo:all' جميع القواعد التي تم إنشاؤها:

$ bazel query '//foo:all' | sort
//foo:count_lines_a_test
//foo:count_lines_b_test
//foo:count_lines_c_test

اختيار

select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)

select() هي الدالة المساعدة التي تجعل سمة القاعدة قابلة للضبط. ويمكن أن تحلّ محلّ السمة المخصّصة لأي سمة معيّنة لسمة تقريبًا، وبالتالي تعتمد قيمتها على علامات Bazel لسطر الأوامر. يمكنك استخدام هذا، على سبيل المثال، لتحديد تبعيات متعلقة بالنظام الأساسي أو تضمين موارد مختلفة اعتمادًا على ما إذا كانت القاعدة مضمّنة في "quot;developer" مقابل &"release".

إليك معلومات الاستخدام الأساسية:

sh_binary(
    name = "mytarget",
    srcs = select({
        ":conditionA": ["mytarget_a.sh"],
        ":conditionB": ["mytarget_b.sh"],
        "//conditions:default": ["mytarget_default.sh"]
    })
)

ويؤدي ذلك إلى جعل السمة srcs قابلة للإعداد sh_binary من خلال استبدال عملية تخصيص قائمة التصنيفات العادية باستدعاء select يربط شروط الضبط بالقيم المطابقة. يمثّل كل شرط مرجعًا إلى config_setting أو constraint_value، وهو "match;matches&quot، إذا كان ضبط target&#39s يتطابق مع مجموعة متوقّعة من القيم. تصبح قيمة mytarget#srcs بعد ذلك أي قائمة تصنيف تطابق الاستدعاء الحالي.

ملاحظات:

• يتم اختيار شرط واحد بالضبط في أي استدعاء.
• إذا تطابقت عدة شروط مع تخصص شرط آخر، تكون الأولوية للتخصص. يُعتبر الشرط (ب) تخصصًا للشرط "أ" إذا كان يتضمن العلامة "أ" نفسه لكل العلامات وعلامات القيد نفسها التي تشتمل عليها "أ" بالإضافة إلى بعض العلامات الإضافية أو قيم القيد. وهذا يعني أيضًا أن دقة التخصص ليست مصمّمة لإنشاء ترتيب كما هو موضّح في المثال 2 أدناه.
• في حال تطابُق عدة شروط مع عدم تخصص شرط واحد لجميع الشروط الأخرى، سيتعذّر تنفيذ Bazel بسبب حدوث خطأ.
• يتم اعتبار التصنيف الزائف //conditions:default مطابقًا إذا لم يتطابق أي شرط آخر. أما إذا تمّ استبعاد هذه الحالة، يجب أن تتطابق بعض القواعد الأخرى لتجنّب حدوث خطأ.
• يمكن تضمين select داخل مهمة دراسية أكبر. وبالتالي، فإنّ srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...}) و srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]}) تعبيران صالحان.
• تعمل السمة select مع معظم السمات وليس جميعها. تم وضع علامة nonconfigurable على السمات غير المتوافقة في مستنداتها.

  الحِزم الفرعية

  subpackages(include, exclude=[], allow_empty=True)

  subpackages() هي وظيفة داعمة، مثل glob()، تسرد الحِزم الفرعية بدلاً من الملفات والأدلة. ويستخدم العنصر أنماط المسار نفسها مثل glob() ويمكن أن يتطابق مع أي حزمة فرعية تابعة مباشرة لملف BUILD الذي يتم تحميله حاليًا. راجِع السمة glob للحصول على شرح تفصيلي وأمثلة على أنماط الإدراج والاستثناء.

  إنّ قائمة الطرود الفرعية المعروضة مرتَّبة وتحتوي على مسارات مرتبطة بحزمة التحميل الحالية التي تتطابق مع الأنماط المحدّدة في include وليس مع exclude.

  مثال

  يعرض المثال التالي كل الحِزم الفرعية المباشرة للحزمة foo/BUILD

  # The following BUILD files exist:
  # foo/BUILD
  # foo/bar/baz/BUILD
  # foo/sub/BUILD
  # foo/sub/deeper/BUILD
  #
  # In foo/BUILD a call to
  subs = subpackages(include = ["**"])
  
  # results in subs == ["sub", "bar/baz"]
  #
  # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
  # 'foo'
  

  وبوجهٍ عام، من المفضّل أن يستخدم المستخدمون و##39;subpackages' وحدة skylib مباشرةً بدلاً من استدعاء هذه الدالة مباشرةً.