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

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

हमारा सुझाव है कि आप टेंप्लेट रिपॉज़िटरी से नया नियम सेट शुरू करें: 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
  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) रखना चाहिए. अगर आपको लगता है कि आपके नियमों को bazelbuild संगठन के नियमों के लिए तय किए गए तरीके का पालन करना चाहिए, तो कृपया GitHub पर एक थ्रेड शुरू करें.

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

Runfiles लाइब्रेरी

अगर आपके नियम में रनफ़ाइलें ऐक्सेस करने के लिए स्टैंडर्ड लाइब्रेरी दी गई है, तो यह //<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 में होस्ट किए गए "reusable workflow" का इस्तेमाल करके आसान बनाया गया है. ci.yaml हर पीआर और main कमिट पर टेस्ट चलाता है. साथ ही, release.yaml जब भी रिपॉज़िटरी में कोई टैग पुश किया जाता है, तब चलता है. ज़्यादा जानकारी के लिए, नियमों के टेंप्लेट वाली रिपॉज़िटरी में मौजूद टिप्पणियां देखें.

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

दस्तावेज़

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

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

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

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

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

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

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