قواعد النشر

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

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

يجب نقل القواعد الجديدة إلى مستودع GitHub الخاص بهم ضمن مؤسستك. يُرجى التواصل مع القائمة البريدية لـbazel-dev في حال اعتقادك بأنّ قواعدك تنتمي إلى مؤسسة bazelbuild.

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

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

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

يمكن تجميع القواعد حسب اللغة (مثل 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). يُرجى التواصل مع القائمة البريدية Babzel-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 (على سبيل المثال، باستخدام selects). بقيود مخصّصة، يمكنك تحديد اللغة التي سيتحدث بها منظومة Bazel المتكاملة.

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

إذا كانت القاعدة توفّر مكتبة عادية للوصول إلى ملفات run، يجب أن تكون على شكل هدف مكتبة يقع على //<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.

تجدر الإشارة إلى أنّه من أجل حلّ سلاسل الأدوات في مرحلة التحليل، عليك تحليل كل أهداف 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)، ولا يزال لدينا قاعدتان، ولكننا نعمل على استبعاد القواعد المتبقية.