BazelCon 2022 از 16 تا 17 نوامبر به نیویورک و آنلاین می آید. امروز ثبت نام کنید!
جدید: برای روز جامعه در 15 نوامبر به ما بپیوندید! جزئیات و ثبت نام.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

استقرار قوانین

این صفحه برای قوانین نویسانی است که قصد دارند قوانین خود را در دسترس دیگران قرار دهند.

قوانین میزبانی و نامگذاری

قوانین جدید باید به مخزن GitHub خود تحت سازمان شما وارد شوند. اگر احساس می کنید قوانین شما متعلق به سازمان bazelbuild است، با لیست پستی bazel-dev تماس بگیرید.

نام‌های مخزن برای قوانین Bazel در قالب زیر استاندارد شده‌اند: $ORGANIZATION/rules_$NAME . نمونه ها را در GitHub ببینید. برای سازگاری، هنگام انتشار قوانین Bazel خود باید از همین قالب پیروی کنید.

اطمینان حاصل کنید که از یک توصیف توصیفی مخزن GitHub و عنوان README.md استفاده کنید، به عنوان مثال:

نام مخزن: bazelbuild/rules_go
توضیحات مخزن: قوانین Go برای Bazel
برچسب‌های مخزن: golang ، bazel
سرصفحه README.md : قوانین برو برای Bazel (به لینک https://bazel.build توجه کنید که کاربرانی را که با Bazel آشنا نیستند به مکان مناسب راهنمایی می کند)

قوانین را می توان بر اساس زبان (مانند اسکالا) یا پلتفرم (مانند اندروید) گروه بندی کرد.

محتوای مخزن

هر مخزن قوانین باید طرح خاصی داشته باشد تا کاربران بتوانند به سرعت قوانین جدید را درک کنند.

به عنوان مثال، هنگام نوشتن قوانین جدید برای زبان 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 ) بگذارید. اگر احساس می کنید قوانین شما باید از کنوانسیون قوانین در سازمان bazelbuild پیروی کنند، لطفاً با لیست پستی bazel-dev تماس بگیرید.

در بخش های بعدی، فرض کنید که مخزن متعلق به سازمان bazelbuild است.

workspace(name = "rules_mockascript")

README

در سطح بالا، باید یک README وجود داشته باشد که حاوی (حداقل) مواردی باشد که کاربران برای استفاده از قانون شما باید در فایل WORKSPACE خود کپی-پیست کنند. به طور کلی، این یک http_archive است که به نسخه GitHub شما اشاره می کند و یک تماس ماکرو است که هر ابزاری را که قانون شما نیاز دارد دانلود/پیکربندی می کند. به عنوان مثال، برای قوانین Go ، به نظر می رسد:

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_value constraint_setting سفارشی را تعریف کنید. اینها را در بسته //<LANG>/constraints قرار دهید. ساختار دایرکتوری شما به شکل زیر خواهد بود:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

لطفاً github.com/bazelbuild/platforms را برای بهترین شیوه‌ها بخوانید، و ببینید چه محدودیت‌هایی در حال حاضر وجود دارد، و اگر محدودیت‌های خود را مستقل از زبان هستند، در نظر بگیرید. به معرفی محدودیت های سفارشی توجه داشته باشید، همه کاربران قوانین شما از آنها برای اجرای منطق خاص پلت فرم در فایل های BUILD خود استفاده می کنند (مثلاً با استفاده از انتخاب ها). با محدودیت های سفارشی، زبانی را تعریف می کنید که کل اکوسیستم Bazel به آن صحبت خواهد کرد.

کتابخانه Runfiles

اگر قانون شما یک کتابخانه استاندارد برای دسترسی به فایل‌های اجرا ارائه می‌کند، باید به شکل یک هدف کتابخانه واقع در //<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>_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.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 ) داشتیم. ما هنوز چند قانون در آنجا داریم، اما در حال حذف قوانین باقی مانده هستیم.