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

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

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

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

नए नियमों को आपके संगठन के 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
  MODULE.bazel
  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

MODULE.bazel

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

यहां दिए गए सेक्शन में, मान लें कि रिपॉज़िटरी, bazelbuild संगठन के लिए है.

module(name = "rules_mockascript")

README

टॉप लेवल पर, एक README होना चाहिए. इसमें नियमों के सेट का संक्षिप्त ब्यौरा और एपीआई के उपयोगकर्ताओं को मिलने वाली सुविधाएं शामिल होनी चाहिए.

नियम

अक्सर, आपकी रिपॉज़िटरी में कई नियम दिए जाते हैं. भाषा के नाम से कोई डायरेक्ट्री बनाएं और एंट्री पॉइंट दें. इसके लिए, 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 फ़ाइलों में प्लैटफ़ॉर्म के हिसाब से लॉजिक लागू करने के लिए इनका इस्तेमाल करेंगे. उदाहरण के लिए, select का इस्तेमाल करना. कस्टम कंस्ट्रेंट की मदद से, ऐसी भाषा तय की जाती है जिसका इस्तेमाल Bazel का पूरा इकोसिस्टम करेगा.

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

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

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

डिपेंडेंसी

आपके नियमों में बाहरी डिपेंडेंसी हो सकती हैं. आपको इन्हें अपनी MODULE.bazel फ़ाइल में तय करना होगा.

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

आपके नियम, टूलचेन भी रजिस्टर कर सकते हैं. इन्हें MODULE.bazel फ़ाइल में भी तय किया जा सकता है.

ध्यान दें कि Bazel को विश्लेषण के दौरान टूलचेन को हल करने के लिए, रजिस्टर किए गए सभी toolchain टारगेट का विश्लेषण करना होगा. Bazel को toolchain.toolchain एट्रिब्यूट से रेफ़रंस लिए गए सभी टारगेट का विश्लेषण करने की ज़रूरत नहीं होगी. अगर आपको टूलचेन रजिस्टर करने के लिए, रिपॉज़िटरी में जटिल कैलकुलेशन करनी पड़ती है, तो toolchain टारगेट वाली रिपॉज़िटरी को <LANG>_toolchain टारगेट वाली रिपॉज़िटरी से अलग करें. पहली रिपॉज़िटरी हमेशा फ़ेच की जाएगी. वहीं, दूसरी रिपॉज़िटरी सिर्फ़ तब फ़ेच की जाएगी, जब उपयोगकर्ता को <LANG> कोड बनाने की ज़रूरत होगी.

रिलीज़ स्निपेट

रिलीज़ के एलान में, एक स्निपेट शामिल करें. इसे आपके उपयोगकर्ता, अपनी MODULE.bazel फ़ाइल में कॉपी-पेस्ट कर सकते हैं. आम तौर पर, यह स्निपेट ऐसा दिखेगा:

bazel_dep(name = "rules_<LANG>", version = "<VERSION>")

जांच

ऐसे टेस्ट होने चाहिए जिनसे यह पुष्टि की जा सके कि नियम उम्मीद के मुताबिक काम कर रहे हैं. इन्हें नियमों के लिए तय की गई भाषा की स्टैंडर्ड जगह पर या टॉप लेवल पर मौजूद tests/ डायरेक्ट्री में रखा जा सकता है.

उदाहरण (ज़रूरी नहीं)

उपयोगकर्ताओं के लिए, examples/ डायरेक्ट्री काम की होती है. इससे उन्हें नियमों का इस्तेमाल करने के कुछ बुनियादी तरीकों के बारे में पता चलता है.

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

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

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

दस्तावेज़

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

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

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

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

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

हालांकि, हमारे उपयोगकर्ताओं के लिए, एक बार की जाने वाली इंस्टॉलेशन प्रोसेस थोड़ी मुश्किल होती है. उन्हें अपनी MODULE.bazel फ़ाइल में, नियमों के सेट के लिए डिपेंडेंसी जोड़नी होती है.

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