नियमों को डिप्लॉय करना

यह पेज, नियम लिखने वाले उन लोगों के लिए है जो अपने नियमों को दूसरों के लिए उपलब्ध कराना चाहते हैं.

हमारा सुझाव है कि आप नियमों का नया सेट, टेंप्लेट रिपॉज़िटरी से बनाएं: https://github.com/bazel-contrib/rules-template यह टेंप्लेट, यहां दिए गए सुझावों के मुताबिक है. इसमें एपीआई के दस्तावेज़ जनरेट करने की सुविधा शामिल है. साथ ही, यह सीआई/सीडी पाइपलाइन सेट अप करता है, ताकि नियमों के सेट को डिस्ट्रिब्यूट करना आसान हो.

होस्ट करने और नाम रखने के नियम

नए नियम, आपके संगठन के तहत अपनी GitHub रिपॉज़िटरी में होने चाहिए. अगर आपको लगता है कि आपके नियम, bazelbuild संगठन में होने चाहिए, तो GitHub पर कोई थ्रेड शुरू करें.

Bazel के नियमों के लिए रिपॉज़िटरी के नाम, इस फ़ॉर्मैट में तय किए जाते हैं: $ORGANIZATION/rules_$NAME. उदाहरण के लिए, GitHub पर जाएं. एक जैसी फ़ॉर्मैटिंग बनाए रखने के लिए, Bazel के नियमों को पब्लिश करते समय भी इसी फ़ॉर्मैट का इस्तेमाल करें.

GitHub रिपॉज़िटरी के लिए जानकारी देने वाला ब्यौरा और README.md का टाइटल इस्तेमाल करें. उदाहरण के लिए:

• रिपॉज़िटरी का नाम: bazelbuild/rules_go
• रिपॉज़िटरी का ब्यौरा: Bazel के लिए Go के नियम
• रिपॉज़िटरी के टैग: golang, bazel
• README.md हेडर: Bazel के लिए Go के नियम (https://bazel.build का लिंक शामिल करें. इससे Bazel के बारे में जानकारी न रखने वाले उपयोगकर्ताओं को सही जगह पर पहुंचने में मदद मिलेगी)

नियमों को भाषा (जैसे, Scala), रनटाइम प्लैटफ़ॉर्म (जैसे, Android) या फ़्रेमवर्क (जैसे, Spring) के हिसाब से ग्रुप किया जा सकता है.

रिपॉज़िटरी का कॉन्टेंट

हर नियम की रिपॉज़िटरी का लेआउट एक जैसा होना चाहिए, ताकि उपयोगकर्ता नए नियमों को आसानी से समझ सकें.

उदाहरण के लिए, (काल्पनिक) 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

प्रोजेक्ट के WORKSPACE में, वह नाम तय करें जिसका इस्तेमाल उपयोगकर्ता आपके नियमों को रेफ़र करने के लिए करेंगे. अगर आपके नियम, bazelbuild संगठन के हैं, तो आपको rules_<lang> (जैसे, rules_mockascript) का इस्तेमाल करना होगा. इसके अलावा, आपको अपनी रिपॉज़िटरी का नाम <org>_rules_<lang> (जैसे, build_stack_rules_proto) रखना होगा. अगर आपको लगता है कि आपके नियमों के लिए, bazelbuild संगठन के नियमों के लिए तय किए गए कन्वेंशन का इस्तेमाल किया जाना चाहिए, तो कृपया GitHub पर कोई थ्रेड शुरू करें.

यहां दिए गए सेक्शन में, मान लें कि रिपॉज़िटरी, 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_setting और/या constraint_value तय करने पड़ें. इन्हें //<LANG>/constraints पैकेज में डालें. आपकी डायरेक्ट्री का स्ट्रक्चर ऐसा दिखेगा:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

सबसे सही तरीकों के बारे में जानने और यह देखने के लिए कि कौनसे कंस्ट्रेंट पहले से मौजूद हैं, कृपया github.com/bazelbuild/platforms पर जाएं. साथ ही, अगर आपके कंस्ट्रेंट, भाषा पर निर्भर नहीं हैं, तो उन्हें वहां सबमिट करने पर विचार करें. कस्टम कंस्ट्रेंट लागू करते समय सावधानी बरतें. आपके नियमों के सभी उपयोगकर्ता, अपनी BUILD फ़ाइलों में प्लैटफ़ॉर्म के हिसाब से लॉजिक लागू करने के लिए इनका इस्तेमाल करेंगे. उदाहरण के लिए, selects का इस्तेमाल करना. कस्टम कंस्ट्रेंट की मदद से, आप एक ऐसी भाषा तय करते हैं जिसका इस्तेमाल Bazel का पूरा इकोसिस्टम करेगा.

रनफ़ाइल लाइब्रेरी

अगर आपका नियम, रनफ़ाइल ऐक्सेस करने के लिए स्टैंडर्ड लाइब्रेरी उपलब्ध कराता है, तो यह //<LANG>/runfiles पर मौजूद लाइब्रेरी टारगेट के फ़ॉर्म में होनी चाहिए. यह //<LANG>/runfiles:runfiles का संक्षिप्त रूप है. जिन उपयोगकर्ता टारगेट को अपने डेटा डिपेंडेंसी को ऐक्सेस करना है वे आम तौर पर इस टारगेट को अपने deps एट्रिब्यूट में जोड़ेंगे.

रिपॉज़िटरी के नियम

डिपेंडेंसी

आपके नियमों में बाहरी डिपेंडेंसी हो सकती हैं. आपके नियमों पर निर्भर रहना आसान बनाने के लिए, कृपया एक WORKSPACE मैक्रो उपलब्ध कराएं, जो उन बाहरी डिपेंडेंसी पर डिपेंडेंसी का एलान करेगा. वहां जांचों की डिपेंडेंसी का एलान न करें. सिर्फ़ उन डिपेंडेंसी का एलान करें जिनकी ज़रूरत नियमों को काम करने के लिए होती है. डेवलपमेंट डिपेंडेंसी को WORKSPACE फ़ाइल में डालें.

<LANG>/repositories.bzl नाम की एक फ़ाइल बनाएं और एक एंट्री पॉइंट मैक्रो नाम rules_<LANG>_dependencies उपलब्ध कराएं. हमारी डायरेक्ट्री ऐसी दिखेगी:

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

टूलचेन रजिस्टर करना

आपके नियम, टूलचेन भी रजिस्टर कर सकते हैं. कृपया एक अलग WORKSPACE मैक्रो उपलब्ध कराएं, जो इन टूलचेन को रजिस्टर करेगा. इस तरह, उपयोगकर्ता पिछले मैक्रो को छोड़ सकते हैं और डिपेंडेंसी को मैन्युअल तरीके से कंट्रोल कर सकते हैं. साथ ही, उन्हें टूलचेन रजिस्टर करने की अनुमति भी मिलती है.

इसलिए, <LANG>/repositories.bzl फ़ाइल में rules_<LANG>_toolchains नाम का एक WORKSPACE मैक्रो जोड़ें.

ध्यान दें कि विश्लेषण के चरण में टूलचेन को हल करने के लिए, 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/ डायरेक्ट्री होना फ़ायदेमंद है. इससे उन्हें नियमों का इस्तेमाल करने के कुछ बुनियादी तरीके पता चलते हैं.

सीआई (CI)/सीडी (CD)

नियमों के कई सेट, GitHub Actions का इस्तेमाल करते हैं. rules-template रिपो में इस्तेमाल किया गया कॉन्फ़िगरेशन देखें. इसे bazel-contrib org में होस्ट किए गए "reusable workflow" का इस्तेमाल करके आसान बनाया गया है. ci.yaml, हर पीआर और main कमिट पर टेस्ट चलाता है. वहीं, release.yaml, रिपॉज़िटरी में कोई टैग पुश करने पर चलता है. ज़्यादा जानकारी के लिए, rules-template रिपो में मौजूद टिप्पणियां देखें.

अगर आपकी रिपॉज़िटरी, bazelbuild संगठन के तहत है, तो उसे ci.bazel.build में ci.bazel.build.

दस्तावेज़

अपने नियमों पर टिप्पणी करने के तरीके के बारे में जानने के लिए, Stardoc के दस्तावेज़ देखें, ताकि दस्तावेज़ अपने-आप जनरेट हो सकें.

rules-template docs/ folder rules-template के docs/ फ़ोल्डर में, यह पक्का करने का आसान तरीका दिखाया गया है कि docs/ फ़ोल्डर में मौजूद Markdown कॉन्टेंट हमेशा अप-टू-डेट रहे, क्योंकि Starlark फ़ाइलें अपडेट की जाती हैं.

अक्सर पूछे जाने वाले सवाल

हम अपने नियम को Bazel की मुख्य GitHub रिपॉज़िटरी में क्यों नहीं जोड़ सकते?

हम नियमों को Bazel की रिलीज़ से जितना हो सके उतना अलग करना चाहते हैं. इससे यह साफ़ हो जाता है कि अलग-अलग नियमों का मालिकाना हक किसके पास है. साथ ही, Bazel के डेवलपर पर पड़ने वाला लोड कम हो जाता है. हमारे उपयोगकर्ताओं के लिए, नियमों को अलग करने से उनमें बदलाव करना, उन्हें अपग्रेड करना, डाउनग्रेड करना, और बदलना आसान हो जाता है. नियमों में योगदान देना, Bazel में योगदान देने से कम मुश्किल हो सकता है. यह नियमों पर निर्भर करता है. इसमें, GitHub की संबंधित रिपॉज़िटरी में सबमिट करने का पूरा ऐक्सेस शामिल है. Bazel में सबमिट करने का ऐक्सेस पाना, एक ज़्यादा मुश्किल प्रोसेस है.

हालांकि, हमारे उपयोगकर्ताओं के लिए, एक बार की इंस्टॉलेशन प्रोसेस ज़्यादा मुश्किल होती है. उन्हें किसी नियम को अपनी WORKSPACE फ़ाइल में कॉपी-पेस्ट करना पड़ता है. जैसा कि ऊपर README.md सेक्शन में दिखाया गया है.

पहले, हमारे पास सभी नियम, Bazel की रिपॉज़िटरी में मौजूद थे. ये नियम //tools/build_rules या //tools/build_defs में मौजूद थे. अब भी वहां कुछ नियम मौजूद हैं, लेकिन हम बाकी नियमों को वहां से हटाने पर काम कर रहे हैं.