यह पेज नियम लिखने वाले उन लोगों के लिए है जो अपने नियम दूसरों को उपलब्ध कराना चाहते हैं.
हमारा सुझाव है कि आप टेंप्लेट रिपॉज़िटरी में जाकर एक नया नियम-सेट शुरू करें: https://github.com/batz-consrib/rules-template वह टेंप्लेट नीचे दिए गए सुझावों के मुताबिक है और इसमें एपीआई डॉक्यूमेंटेशन जनरेट करना शामिल है. साथ ही, एक CI/CD पाइपलाइन सेट अप करता है, ताकि आपके नियमों को सेट करना आसान हो जाए.
होस्टिंग और नाम रखने से जुड़े नियम
नए नियम आपके संगठन के तहत, उनकी अपनी GitHub रिपॉज़िटरी में जाने चाहिए. अगर आपको लगता है कि आपके नियम baZbuild संगठन से जुड़े हैं, तो GitHub पर थ्रेड शुरू करें.
बेज़ेल नियमों के लिए डेटा स्टोर करने की जगहों के नाम इस फ़ॉर्मैट का इस्तेमाल करके तय किए गए हैं:
$ORGANIZATION/rules_$NAME.
GitHub पर उदाहरण देखें.
एक जैसा रखने के लिए, आपको अपने Basel के नियमों को पब्लिश करते समय यही फ़ॉर्मैट अपनाना चाहिए.
GitHub रिपॉज़िटरी की पूरी जानकारी और README.md टाइटल का इस्तेमाल ज़रूर करें. उदाहरण के लिए:
- डेटा स्टोर करने की जगह का नाम:
bazelbuild/rules_go - डेटा स्टोर करने की जगह की जानकारी: Basel के लिए Go के नियम
- डेटा स्टोर करने की जगह के टैग:
golang,bazel README.mdहेडर: Bazel का इस्तेमाल करने से जुड़े नियम (https://batz.build का लिंक देखें, जो उन लोगों को सही जगह पर पहुंचने के लिए गाइड करेगा जो Basel के बारे में नहीं जानते)
नियमों को भाषा (जैसे, स्काला), 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 में, आपको वह नाम तय करना होगा जिसका इस्तेमाल उपयोगकर्ता, आपके नियमों के बारे में बताने के लिए करेंगे. अगर आपके नियम bazubuild संगठन से जुड़े हैं, तो आपको rules_<lang> (जैसे कि rules_mockascript) का इस्तेमाल करना होगा. अगर ऐसा नहीं है, तो आपको डेटा स्टोर करने की जगह <org>_rules_<lang> (जैसे कि build_stack_rules_proto) का नाम रखना चाहिए. अगर आपको लगता है कि आपके नियम baazbuild संगठन के नियमों का पालन करने चाहिए, तो कृपया GitHub पर थ्रेड शुरू करें.
नीचे दिए गए सेक्शन में, मान लें कि डेटा स्टोर करने की जगह baazbuild संगठन की है.
workspace(name = "rules_mockascript")
README
सबसे ऊपर के लेवल पर, एक README होना चाहिए जिसमें (कम से कम) वह जानकारी शामिल हो जिसे आपके नियम का इस्तेमाल करने के लिए, उपयोगकर्ताओं को अपनी WORKSPACE फ़ाइल में कॉपी करके चिपकाना होगा.
आम तौर पर, यह आपकी GitHub रिलीज़ की ओर इशारा करने वाला एक http_archive होगा. साथ ही, यह एक मैक्रो कॉल होगा, जो आपके नियम के लिए ज़रूरी सभी टूल को डाउनलोड/कॉन्फ़िगर करेगा. उदाहरण के लिए,
जाएं
नियम के लिए, यह ऐसा
दिखेगा:
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
कंस्ट्रेंट
अगर आपके नियम में
toolchain से जुड़े नियम तय हैं,
तो हो सकता है कि आपको कस्टम constraint_setting और/या
constraint_value तय करने पड़ें. इन्हें //<LANG>/constraints पैकेज में डालें. आपकी डायरेक्ट्री इस तरह से दिखेगी:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
सबसे सही तरीकों के बारे में जानने के लिए, कृपया github.com/bazelbuild/platforms
कस्टम कंस्ट्रेंट को लागू करने का ध्यान रखें. आपके नियमों का इस्तेमाल करने वाले सभी लोग, अपनी BUILD फ़ाइलों में प्लैटफ़ॉर्म के हिसाब से लॉजिक लागू करने के लिए, इन कंस्ट्रेंट का इस्तेमाल करेंगे. उदाहरण के लिए, selects का इस्तेमाल करके.
अपनी पसंद के हिसाब से कंस्ट्रेंट की मदद से, ऐसी भाषा तय की जाती है जिसे पूरा बेज़ल नेटवर्क
बताता है.
रनफ़ाइल लाइब्रेरी
अगर आपका नियम रनफ़ाइल ऐक्सेस करने के लिए स्टैंडर्ड लाइब्रेरी देता है, तो वह
//<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 मैक्रो
जोड़ें.
ध्यान दें कि विश्लेषण के चरण में, टूलचेन की समस्याओं को हल करने के लिए, Basel को रजिस्टर किए गए सभी toolchain टारगेट का विश्लेषण करना होगा. Basel को toolchain.toolchain एट्रिब्यूट से रेफ़र किए गए सभी टारगेट का विश्लेषण करने की ज़रूरत नहीं होगी. अगर टूलचेन को रजिस्टर करने के लिए, आपको डेटा स्टोर करने की जगह में जटिल कंप्यूटेशन की ज़रूरत है, तो रिपॉज़िटरी को <LANG>_toolchain टारगेट वाले डेटा स्टोर करने की जगह से 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/ डायरेक्ट्री होनी चाहिए.
सीआई/सीडी
कई नियमसेट, GitHub की कार्रवाइयों का इस्तेमाल करते हैं. नियमों के टेंप्लेट रेपो में इस्तेमाल किया गया कॉन्फ़िगरेशन देखें. इसे baज़ेन-कॉन्ट्रिब संगठन में होस्ट किए गए, "फिर से इस्तेमाल किए जा सकने वाले वर्कफ़्लो" का इस्तेमाल करके आसान बनाया गया है. ci.yaml हर PR और main कॉमिट की जांच करता है और जब भी आप किसी टैग को डेटा स्टोर करने की जगह में पुश करते हैं, तो release.yaml चलता है.
ज़्यादा जानकारी के लिए, नियम टेंप्लेट रेपो में टिप्पणियां देखें.
अगर आपका डेटा स्टोर करने की जगह, bazubuild संगठन के तहत आता है, तो आप इसे ci.bazel.build में जोड़ने के लिए कहें.
दस्तावेज़
अपने नियमों पर टिप्पणी करने का तरीका जानने के लिए, Stardoc के दस्तावेज़ देखें. इससे दस्तावेज़ अपने-आप जनरेट हो पाएंगे.
नियमों के टेंप्लेट दस्तावेज़/ फ़ोल्डर में यह पक्का करने का आसान तरीका बताया गया है कि docs/ फ़ोल्डर में मौजूद Markdown कॉन्टेंट हमेशा अप-टू-डेट रहता है, क्योंकि Starlark फ़ाइलें अपडेट होती हैं.
अक्सर पूछे जाने वाले सवाल
हम अपने नियम को बेज़ल GitHub की मुख्य रिपॉज़िटरी में क्यों नहीं जोड़ सकते?
इसलिए, हम चाहते हैं कि ज़्यादा से ज़्यादा समय से, Basel की रिलीज़ के नियमों को अलग-अलग कैटगरी में रखा जाए. इससे साफ़ तौर पर पता चलता है कि अलग-अलग नियमों का मालिक कौन है. इससे बेज़ल डेवलपर पर कम लोड होता है. हमारे उपयोगकर्ताओं के लिए, डिकोड करने से नियमों में बदलाव करना, उन्हें अपग्रेड करना, डाउनग्रेड करना, और बदलना आसान हो जाता है. नियमों पर निर्भर करते हुए - बेज़ल में योगदान करने के मुकाबले, नियमों में योगदान करना कम वज़न हो सकता है. इसमें संबंधित GitHub रिपॉज़िटरी का पूरा ऐक्सेस भी शामिल है. Basel को सबमिट करने का ऐक्सेस अपने-आप में बहुत ज़्यादा शामिल होता है.
हालांकि, हमारे उपयोगकर्ताओं के लिए एक बार इंस्टॉल करने की प्रक्रिया काफ़ी जटिल है. उन्हें एक नियम को कॉपी करके अपनी WORKSPACE फ़ाइल में चिपकाना होता है, जैसा कि ऊपर README.md सेक्शन में दिखाया गया है.
पहले सभी नियम, बेज़ल रिपॉज़िटरी में (//tools/build_rules या //tools/build_defs के तहत) होते थे. हमारे पास अब भी कुछ नियम हैं, लेकिन हम बाकी नियमों को हटाने के लिए काम कर रहे हैं.