यह पेज, नियम लिखने वाले उन लोगों के लिए है जो अपने नियमों को दूसरों के लिए उपलब्ध कराना चाहते हैं.
हमारा सुझाव है कि नियमों का नया सेट बनाने के लिए, टेंप्लेट रिपॉज़िटरी का इस्तेमाल करें: 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) रखना चाहिए. अगर आपको लगता है कि आपके नियमों को
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 फ़ाइलों में प्लैटफ़ॉर्म के हिसाब से लॉजिक लागू करने के लिए इनका इस्तेमाल करेंगे. उदाहरण के लिए,
'चुने गए' का इस्तेमाल करना.
कस्टम कंस्ट्रेंट की मदद से, ऐसी भाषा तय की जाती है जिसका इस्तेमाल 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/ folder
rules-template के docs/ फ़ोल्डर में, यह पक्का करने का आसान तरीका बताया गया है कि docs/ फ़ोल्डर में मौजूद Markdown कॉन्टेंट हमेशा अप-टू-डेट रहे.
इसके लिए, Starlark फ़ाइलें अपडेट की जाती हैं.
अक्सर पूछे जाने वाले सवाल
हम अपने नियम को Bazel के मुख्य GitHub रिपॉज़िटरी में क्यों नहीं जोड़ सकते?
हम नियमों को Bazel की रिलीज़ से अलग करना चाहते हैं. इससे यह साफ़ तौर पर पता चलता है कि अलग-अलग नियमों का मालिकाना हक किसके पास है. इससे Bazel के डेवलपर पर पड़ने वाला लोड कम हो जाता है. हमारे उपयोगकर्ताओं के लिए, नियमों को अलग करने से उनमें बदलाव करना, उन्हें अपग्रेड करना, डाउनग्रेड करना, और बदलना आसान हो जाता है. नियमों में योगदान देना, Bazel में योगदान देने से कम मुश्किल हो सकता है. यह नियमों पर निर्भर करता है. इसमें, GitHub की संबंधित रिपॉज़िटरी में सबमिट करने का पूरा ऐक्सेस शामिल है. Bazel में सबमिट करने का ऐक्सेस पाना, एक मुश्किल प्रोसेस है.
हालांकि, हमारे उपयोगकर्ताओं के लिए, एक बार की इंस्टॉलेशन प्रोसेस ज़्यादा मुश्किल होती है. उन्हें अपनी MODULE.bazel फ़ाइल में, नियमों के सेट के लिए डिपेंडेंसी जोड़नी होती है.
पहले, Bazel की रिपॉज़िटरी में सभी नियम मौजूद थे. ये नियम, //tools/build_rules या //tools/build_defs में मौजूद थे. अब भी यहां कुछ नियम मौजूद हैं, लेकिन हम बाकी नियमों को यहां से हटाने पर काम कर रहे हैं.