سيتم إطلاق BazelCon لعام 2022 في الفترة من 16 إلى 17 تشرين الثاني (نوفمبر) في نيويورك وعلى الإنترنت.
التسجيل اليوم

نشر القواعد

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

هذه الصفحة مخصّصة لكتّاب القواعد الذين يخطّطون لإتاحة قواعدهم للآخرين.

استضافة القواعد وتسميتها

يجب أن تظهر القواعد الجديدة في مستودع GitHub ضمن مؤسستك. تواصل مع القائمة البريدية لـ Bazel-dev إذا كنت تعتقد أن قواعدك تنتمي إلى مؤسسة bazelbuild.

يتم توحيد أسماء المستودعات لقواعد Bazel بالتنسيق التالي: $ORGANIZATION/rules_$NAME. الاطلاع على أمثلة على GitHub. للاتّساق، يجب اتّباع التنسيق نفسه عند نشر قواعد Bazel.

تأكَّد من استخدام وصف مستودع GitHub وصفي README.md، مثل:

  • اسم المستودع: bazelbuild/rules_go
  • وصف المستودع: الانتقال إلى قواعد Bazel
  • علامات المستودع: golang وbazel
  • عنوان الصفحة README.md: الانتقال إلى قواعد Bazel (لاحظ الرابط إلى https://bazel.build الذي يرشدك المستخدمين غير المعتادين عليهم بازيل إلى المكان المناسب)

يمكن تجميع القواعد حسب اللغة (مثل Scala) أو النظام الأساسي (مثل Android).

محتوى المستودع

يجب أن يكون لكل مستودع قواعد تنسيق معين حتى يتمكن المستخدمون من فهم القواعد الجديدة بسرعة.

على سبيل المثال، عند كتابة قواعد جديدة للغة (مثال) mockascript، سيكون للقاعدة البنية التالية:

/
  LICENSE
  README
  WORKSPACE
  mockascript/
    constraints/
      BUILD
    runfiles/
      BUILD
      runfiles.mocs
    BUILD
    defs.bzl
  tests/
    BUILD
    some_test.sh
    another_test.py
  examples/
    BUILD
    bin.mocs
    lib.mocs
    test.mocs

مساحة العمل

في WORKSPACE للمشروع، يجب تحديد الاسم الذي سيستخدمه المستخدمون للإشارة إلى قواعدك. إذا كانت قواعدك تنتمي إلى مؤسسة bazelbuild، عليك استخدام rules_<lang> (مثل rules_mockascript). وبخلاف ذلك، عليك تسمية مستودعك <org>_rules_<lang> (مثل build_stack_rules_proto). يُرجى التواصل مع قائمة بريدية Bazel-dev إذا كنت تعتقد أنه يجب اتّباع قواعد القواعد في مؤسسة bazelbuild.

في الأقسام التالية، لنفترض أن المستودع ينتمي إلى مؤسسة bazelbuild.

workspace(name = "rules_mockascript")

ملف README

في المستوى الأعلى، يجب أن يكون هناك README يحتوي على (على الأقل) ما سيحتاج المستخدمون إلى نسخه إلى ملف WORKSPACE لاستخدام القاعدة. بشكل عام، سيكون هذا الرمز http_archive يوجّه إلى إصدار GitHub واستدعاء ماكرو ينزّل/يضبط أي أدوات تحتاجها القاعدة. على سبيل المثال، بالنسبة إلى قواعد التنقُّل، يبدو الأمر على النحو التالي:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_go",
    urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
    sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()

إذا كانت قواعدك تعتمد على قواعد مستودع آخر، حدِّد أنه في مستندات القواعد (على سبيل المثال، راجِع قواعد Skydoc التي تعتمد على قواعد Sass)، وقدِّم وحدة ماكرو WORKSPACE ستعمل على تنزيل جميع الملفات الاعتمادية (راجِع rules_go أعلاه).

القواعد

وفي كثير من الأحيان، سيقدم مستودعك قواعد متعددة. أنشِئ دليلاً باسم اللغة وقدِّم نقطة دخول - ملف defs.bzl يُصدِّر جميع القواعد (مع تضمين ملف BUILD أيضًا حتى يكون الدليل عبارة عن حزمة). بالنسبة إلى rules_mockascript، يعني ذلك أنه سيكون هناك دليل باسم mockascript وملف BUILD وملف defs.bzl داخله:

/
  mockascript/
    BUILD
    defs.bzl

القيود

في حال تحديد القاعدة سلسلة أدوات القواعد، فمن المحتمل أن تحتاج إلى تعريفconstraint_setting و/أوconstraint_value ث ضَع هذه الملفات في حزمة //<LANG>/constraints. ستبدو بنية الدليل على النحو التالي:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

يُرجى قراءة github.com/bazelbuild/platforms للحصول على أفضل الممارسات، ولمعرفة القيود الموجودة، والمساهمة في وضع قيودك هناك إذا كانت مستقلة عن اللغات. يُرجى مراعاة القيود المخصّصة، وسيستخدمها جميع المستخدمين وفقًا لمنطقك الخاص في ملفات BUILD الخاصة بهم (على سبيل المثال، باستخدام اختيارات). عند استخدام القيود المخصّصة، يمكنك تحديد لغة يتحدث بها منظومة Bazel المتكاملة.

مكتبة ملفات الملفات

إذا كانت قاعدتك توفّر مكتبة عادية للوصول إلى ملفات التشغيل، يجب أن تكون المكتبة على شكل استهداف للمكتبة على //<LANG>/runfiles (اختصار //<LANG>/runfiles:runfiles). تُضيف عادةً استهدافات المستخدمين التي تحتاج إلى الوصول إلى العناصر التابعة لها هذا الهدف إلى السمة deps الخاصة بها.

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

تبعيات

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

أنشِئ ملفًا باسم <LANG>/repositories.bzl وأدخِل وحدة ماكرو واحدة إدخال باسم rules_<LANG>_dependencies. سيبدو الدليل على النحو التالي:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl
    repositories.bzl

تسجيل سلاسل الأدوات

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

لذلك، أضِف وحدة ماكرو WORKSPACE باسم rules_<LANG>_toolchains في ملف <LANG>/repositories.bzl.

تجدر الإشارة إلى أنه من أجل حل سلاسل الأدوات في مرحلة التحليل، يحتاج Bazel إلى تحليل جميع أهداف toolchain المسجّلة. لن يحتاج Bazel إلى تحليل جميع الأهداف التي تشير إليها سمة toolchain.toolchain. إذا أردت تسجيل سلاسل أدوات، عليك إجراء عملية حسابية معقّدة في المستودع، يمكنك تقسيم المستودع إلى أهداف toolchain من المستودع مع استهداف <LANG>_toolchain. سيتم دائمًا جلب السابق، وسيتم جلب الأخير فقط عندما يحتاج المستخدم إلى إنشاء رمز <LANG>.

إصدار المقتطف

في إعلان الإصدار، قدِّم مقتطفًا يمكن للمستخدمين نسخه ولصقه في ملف WORKSPACE. بشكل عام، سيبدو هذا المقتطف على النحو التالي:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_<LANG>",
    urls = ["<url_to_the_release.zip"],
    sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()

الفحوصات

يجب أن تكون هناك اختبارات تعمل على التحقق من عمل القواعد كما هو متوقع. ويمكن وضعها إما في الموقع الجغرافي العادي للغة التي يتم استخدامها في القواعد أو في دليل tests/ على المستوى الأعلى.

أمثلة (اختياري)

من المفيد أن يمتلك المستخدمون دليل examples/ يوضّح للمستخدمين بعض الطرق الأساسية التي يمكن من خلالها استخدام القواعد.

اختبار

عليك إعداد تطبيق Travis كما هو موضّح في مستندات البدء. بعد ذلك، أضِف ملف .travis.yml إلى المستودع الذي يتضمن المحتوى التالي:

dist: xenial  # Ubuntu 16.04

# On trusty (or later) images, the Bazel apt repository can be used.
addons:
  apt:
    sources:
    - sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
      key_url: 'https://bazel.build/bazel-release.pub.gpg'
    packages:
    - bazel

script:
  - bazel build //...
  - bazel test //...

إذا كان مستودعك ضمن مؤسسة bazelbuild، يمكنك طلب إضافته إلى ci.bazel.build.

المستندات

يُرجى الاطّلاع على مستندات Stardoc للحصول على تعليمات حول كيفية التعليق على القواعد بحيث يمكن إنشاء المستندات تلقائيًا.

الأسئلة الشائعة

لماذا لا يمكننا إضافة قاعدتنا إلى مستودع Bazel GitHub الرئيسي؟

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

الجانب السلبي هو عملية تثبيت أكثر تعقيدًا لمرة واحدة للمستخدمين: عليك نسخ قاعدة ولصقها في ملف WORKSPACE، كما هو موضّح في القسم README.md أعلاه.

في السابق، عدّلنا كل القواعد في مستودع Bazel (ضمن //tools/build_rules أو //tools/build_defs). لا تزال لدينا بعض القواعد ولكننا نعمل على نقل القواعد المتبقية إلى الخارج.