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