यह पेज नियम लिखने वाले उन लोगों के लिए है जो अपने नियम दूसरों को उपलब्ध कराना चाहते हैं.
हमारा सुझाव है कि आप टेंप्लेट रिपॉज़िटरी से नया नियमों का सेट शुरू करें: https://github.com/bazel-contrib/rules-template यह टेंप्लेट, यहां दिए गए सुझावों का पालन करता है. इसमें एपीआई दस्तावेज़ जनरेशन शामिल है और सीआई/सीडी पाइपलाइन सेट अप की जाती है, ताकि आपके नियमों के सेट को आसानी से डिस्ट्रिब्यूट किया जा सके.
होस्टिंग और नाम रखने से जुड़े नियम
नए नियम आपके संगठन के तहत, उनकी अपनी GitHub रिपॉज़िटरी में जाने चाहिए. अगर आपको लगता है कि आपके नियम bazubuild संगठन में हैं, तो GitHub पर थ्रेड शुरू करें.
बेज़ेल नियमों के लिए डेटा स्टोर करने की जगहों के नाम इस फ़ॉर्मैट के हिसाब से तय किए जाते हैं:
$ORGANIZATION/rules_$NAME.
GitHub पर उदाहरण देखें.
एक जैसा फ़ॉर्मैट इस्तेमाल करने के लिए, आपको Bazel नियमों को पब्लिश करते समय भी यही फ़ॉर्मैट अपनाना चाहिए.
GitHub के डेटा स्टोर करने की जगह के ब्यौरे और README.md
टाइटल में ज़्यादा जानकारी दें. उदाहरण के लिए:
- डेटा स्टोर करने की जगह का नाम:
bazelbuild/rules_go - डेटा स्टोर करने की जगह की जानकारी: Basel के लिए Go के नियम
- डेटा स्टोर करने की जगह के टैग:
golang,bazel README.mdहेडर: Bazel के लिए Go के नियम (https://bazel.build का लिंक ध्यान दें. इससे, Bazel के बारे में जानकारी न रखने वाले उपयोगकर्ताओं को सही जगह पर ले जाया जाएगा)
नियमों को भाषा (जैसे, Scala), रनटाइम प्लैटफ़ॉर्म (जैसे, Android) या फ़्रेमवर्क (जैसे, Spring) के हिसाब से ग्रुप किया जा सकता है.
डेटा स्टोर करने की जगह
हर नियम का डेटा स्टोर करने की जगह का एक लेआउट होना चाहिए, ताकि उपयोगकर्ता नए नियमों को तुरंत समझ सकें.
उदाहरण के लिए, (make-believe)
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) रखना चाहिए. अगर आपको लगता है कि आपके नियमों को bazelbuild संगठन के नियमों के मुताबिक होना चाहिए, तो कृपया 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()
अगर आपके नियम किसी दूसरी रिपॉज़िटरी के नियमों पर निर्भर हैं, तो नियमों के दस्तावेज़ में इसकी जानकारी दें. उदाहरण के लिए, Sass नियमों पर निर्भर Skydoc नियम देखें. साथ ही, एक 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 का इस्तेमाल करना.
कस्टम पाबंदियों की मदद से, एक ऐसी भाषा तय की जाती है जिसका इस्तेमाल, 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 टारगेट का विश्लेषण करना होगा. Basel को 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/ डायरेक्ट्री होनी चाहिए.
सीआई/सीडी
कई नियमसेट, GitHub की कार्रवाइयों का इस्तेमाल करते हैं. rules-template repo में इस्तेमाल किए गए कॉन्फ़िगरेशन को देखें. इन कॉन्फ़िगरेशन को आसान बनाने के लिए, bazel-contrib.org में होस्ट किए गए "फिर से इस्तेमाल किए जा सकने वाले वर्कफ़्लो" का इस्तेमाल किया गया है. ci.yaml हर एक पीआर और main कमिट पर टेस्ट चलाता है. साथ ही, release.yaml किसी टैग को रिपॉज़िटरी में पुश करने पर भी चलता है.
ज़्यादा जानकारी के लिए, rules-template repo में मौजूद टिप्पणियां देखें.
अगर आपकी रिपॉज़िटरी bazelbuild संगठन के तहत है, तो आपके पास ci.bazel.build में इसे जोड़ने का अनुरोध करने का विकल्प है.
दस्तावेज़
अपने नियमों पर टिप्पणी करने का तरीका जानने के लिए, Stardoc के दस्तावेज़ देखें. इससे दस्तावेज़ अपने-आप जनरेट हो पाएंगे.
नियमों के टेंप्लेट दस्तावेज़/ फ़ोल्डर में यह पक्का करने का आसान तरीका बताया गया है कि docs/ फ़ोल्डर में मौजूद Markdown कॉन्टेंट हमेशा अप-टू-डेट रहता है, क्योंकि Starlark फ़ाइलें अपडेट होती हैं.
अक्सर पूछे जाने वाले सवाल
हम Bazel के मुख्य GitHub डेटा स्टोर करने की जगह में अपना नियम क्यों नहीं जोड़ सकते?
इसलिए, हम चाहते हैं कि ज़्यादा से ज़्यादा समय से, Basel की रिलीज़ के नियमों को अलग-अलग कैटगरी में रखा जाए. इससे यह साफ़ तौर पर पता चलता है कि अलग-अलग नियमों का मालिकाना हक किसके पास है. इससे Bazel डेवलपर पर लोड कम हो जाता है. हमारे उपयोगकर्ताओं के लिए, डिकोड करने से नियमों में बदलाव करना, उन्हें अपग्रेड करना, डाउनग्रेड करना, और बदलना आसान हो जाता है. नियमों पर निर्भर करते हुए - बेज़ल में योगदान करने के मुकाबले, नियमों में योगदान करना कम वज़न हो सकता है. इसमें संबंधित GitHub रिपॉज़िटरी का पूरा ऐक्सेस भी शामिल है. Bazel में सबमिट करने का ऐक्सेस पाना, काफ़ी मुश्किल प्रोसेस है.
हालांकि, इसका एक नुकसान यह है कि उपयोगकर्ताओं को एक बार इंस्टॉल करने की प्रोसेस ज़्यादा मुश्किल होती है:
उन्हें ऊपर दिए गए README.md सेक्शन में दिखाए गए तरीके के मुताबिक, अपनी WORKSPACE फ़ाइल में कोई नियम कॉपी-पेस्ट करना होता है.
पहले हमारे सभी नियम, Bazel रिपॉज़िटरी में (//tools/build_rules या //tools/build_defs में) होते थे. अब भी हमारे पास कुछ नियम वहां मौजूद हैं, लेकिन हम बाकी नियमों को वहां से हटाने पर काम कर रहे हैं.