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