यह पेज उन नियम लेखकों के लिए है जो अपने नियमों को दूसरों के लिए उपलब्ध कराना चाहते हैं.
हमारा सुझाव है कि आप टेंप्लेट रिपॉज़िटरी से नया नियमों का सेट शुरू करें: 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हेडर: Baaz के लिए नियमों का पालन करें (https://bazu.build का लिंक देखें, जो उन लोगों को सही जगह पर ले जाएगा जो Basel के बारे में नहीं जानते)
नियमों को भाषा (जैसे, Scala), रनटाइम प्लैटफ़ॉर्म (जैसे, Android) या फ़्रेमवर्क (जैसे, Spring) के हिसाब से ग्रुप किया जा सकता है.
डेटा स्टोर करने की जगह
हर नियम का डेटा स्टोर करने की जगह का एक लेआउट होना चाहिए, ताकि उपयोगकर्ता नए नियमों को तुरंत समझ सकें.
उदाहरण के लिए, (make-believe)
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 का इस्तेमाल करना.
अपनी पसंद के हिसाब से कंस्ट्रेंट की मदद से, ऐसी भाषा तय की जाती है जिसे पूरा बेज़ल नेटवर्क
बताता है.
Runfiles लाइब्रेरी
अगर आपका नियम, रनफ़ाइलों को ऐक्सेस करने के लिए कोई स्टैंडर्ड लाइब्रेरी उपलब्ध कराता है, तो वह //<LANG>/runfiles (//<LANG>/runfiles:runfiles का छोटा नाम) पर मौजूद लाइब्रेरी टारगेट के तौर पर होनी चाहिए. जिन उपयोगकर्ता टारगेट को अपनी डेटा डिपेंडेंसी ऐक्सेस करनी होती है वे आम तौर पर इस टारगेट को अपने deps एट्रिब्यूट में जोड़ते हैं.
रिपॉज़िटरी के नियम
डिपेंडेंसी
आपके नियमों में बाहरी डिपेंडेंसी हो सकती हैं. आपको उन्हें अपनी MODULE.bazel फ़ाइल में बताना होगा.
टूलचेन रजिस्टर करना
आपके नियमों से टूलचेन भी रजिस्टर हो सकते हैं. इनके बारे में, MODULE.bazel फ़ाइल में भी बताया जा सकता है.
ध्यान दें कि विश्लेषण के चरण में टूलचेन को हल करने के लिए, Bazel को रजिस्टर किए गए सभी toolchain टारगेट का विश्लेषण करना होगा. Bazel को toolchain.toolchain एट्रिब्यूट से रेफ़र किए गए सभी टारगेट का विश्लेषण करने की ज़रूरत नहीं होगी. अगर टूलचेन को रजिस्टर करने के लिए, आपको डेटा स्टोर करने की जगह में जटिल कंप्यूटेशन की ज़रूरत है, तो रिपॉज़िटरी को <LANG>_toolchain टारगेट वाले डेटा स्टोर करने की जगह से toolchain टारगेट वाले डेटा में बांटें. पहला हमेशा फ़ेच किया जाएगा और दूसरा सिर्फ़ तब फ़ेच किया जाएगा, जब उपयोगकर्ता को <LANG> कोड बनाने की ज़रूरत होगी.
रिलीज़ स्निपेट
रिलीज़ के एलान में ऐसा स्निपेट दें जिसे उपयोगकर्ता अपनी MODULE.bazel फ़ाइल में कॉपी-पेस्ट कर सकें. आम तौर पर, यह स्निपेट कुछ ऐसा दिखेगा:
bazel_dep(name = "rules_<LANG>", version = "<VERSION>")
जांच
ऐसे टेस्ट होने चाहिए जिनसे यह पुष्टि की जा सके कि नियम उम्मीद के मुताबिक काम कर रहे हैं. यह
उस भाषा के लिए स्टैंडर्ड जगह पर हो सकता है जिसके लिए नियम बनाए गए हैं या फिर टॉप लेवल पर
tests/ डायरेक्ट्री हो सकती है.
उदाहरण (ज़रूरी नहीं)
अगर उपयोगकर्ताओं के पास नियमों का इस्तेमाल करने के कुछ बुनियादी तरीके हैं, तो उपयोगकर्ताओं के पास examples/ डायरेक्ट्री होनी चाहिए.
सीआई/सीडी
कई नियमों के सेट में GitHub Actions का इस्तेमाल किया जाता है. rules-template repo में इस्तेमाल किए गए कॉन्फ़िगरेशन को देखें. इन कॉन्फ़िगरेशन को आसान बनाने के लिए, bazel-contrib.org में होस्ट किए गए "फिर से इस्तेमाल किए जा सकने वाले वर्कफ़्लो" का इस्तेमाल किया गया है. ci.yaml हर एक पीआर और main कमिट पर टेस्ट चलाता है. साथ ही, release.yaml किसी टैग को रिपॉज़िटरी में पुश करने पर भी चलता है.
ज़्यादा जानकारी के लिए, rules-template repo में मौजूद टिप्पणियां देखें.
अगर आपकी रिपॉज़िटरी bazelbuild संगठन के तहत है, तो आपके पास ci.bazel.build में इसे जोड़ने का अनुरोध करने का विकल्प है.
दस्तावेज़
अपने नियमों पर टिप्पणी करने के तरीके के बारे में निर्देश पाने के लिए, Stardoc दस्तावेज़ देखें, ताकि दस्तावेज़ अपने-आप जनरेट हो सके.
rules-template docs/ फ़ोल्डर में, यह पक्का करने का एक आसान तरीका बताया गया है कि Starlark फ़ाइलों के अपडेट होने पर, docs/ फ़ोल्डर में मौजूद मार्कडाउन कॉन्टेंट हमेशा अप-टू-डेट रहे.
अक्सर पूछे जाने वाले सवाल
हम Bazel के मुख्य GitHub डेटा स्टोर करने की जगह में अपना नियम क्यों नहीं जोड़ सकते?
इसलिए, हम चाहते हैं कि ज़्यादा से ज़्यादा समय से, Basel की रिलीज़ के नियमों को अलग-अलग कैटगरी में रखा जाए. इससे यह साफ़ तौर पर पता चलता है कि अलग-अलग नियमों का मालिकाना हक किसके पास है. इससे Bazel डेवलपर पर लोड कम हो जाता है. हमारे उपयोगकर्ताओं के लिए, अलग-अलग करने की सुविधा से नियमों में बदलाव करना, उन्हें अपग्रेड करना, डाउनग्रेड करना, और बदलना आसान हो जाता है. नियमों में योगदान देना, Bazel में योगदान देने के मुकाबले आसान हो सकता है. हालांकि, यह नियमों पर निर्भर करता है. इसमें, संबंधित GitHub डेटा स्टोर करने की जगह को सबमिट करने का पूरा ऐक्सेस भी शामिल है. Bazel में सबमिट करने का ऐक्सेस पाना, काफ़ी मुश्किल प्रोसेस है.
हालांकि, इसका एक नुकसान यह है कि हमारे उपयोगकर्ताओं को एक बार में इंस्टॉल करने की प्रोसेस ज़्यादा मुश्किल होती है:
उन्हें अपनी MODULE.bazel फ़ाइल में, आपके नियमों के सेट पर डिपेंडेंसी जोड़नी होती है.
पहले सभी नियम, बेज़ल रिपॉज़िटरी में (//tools/build_rules या //tools/build_defs के तहत) होते थे. हमारे पास अब भी कुछ नियम हैं, लेकिन हम बाकी नियमों को हटाने के लिए काम कर रहे हैं.