यह पेज उन नियम लेखकों के लिए है जो अपने नियमों को दूसरों के लिए उपलब्ध कराना चाहते हैं.
होस्टिंग और नाम रखने से जुड़े नियम
नए नियम, आपके संगठन के GitHub रिपॉज़िटरी में होने चाहिए. अगर आपको लगता है कि आपके नियम bazelbuild संगठन के हैं, तो bazel-dev मेलिंग सूची से संपर्क करें.
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) के हिसाब से ग्रुप किया जा सकता है.
डेटा स्टोर करने की जगह
हर नियम के रिपॉज़िटरी का लेआउट एक जैसा होना चाहिए, ताकि उपयोगकर्ता नए नियमों को तुरंत समझ सकें.
उदाहरण के लिए, (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 संगठन के नियमों के मुताबिक होना चाहिए, तो कृपया bazel-dev मेलिंग सूची से संपर्क करें.
नीचे दिए गए सेक्शन में, मान लें कि रिपॉज़िटरी bazelbuild संगठन का है.
workspace(name = "rules_mockascript")
README
सबसे ऊपर, एक README होना चाहिए. इसमें कम से कम वह जानकारी होनी चाहिए जिसे उपयोगकर्ताओं को आपके नियम का इस्तेमाल करने के लिए, अपनी WORKSPACE फ़ाइल में कॉपी-पेस्ट करना होगा.
आम तौर पर, यह आपकी GitHub रिलीज़ पर ले जाने वाला http_archive और एक मैक्रो कॉल होगा, जो आपके नियम के लिए ज़रूरी टूल डाउनलोड/कॉन्फ़िगर करता है. उदाहरण के लिए, 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()
अगर आपके नियम किसी दूसरी रिपॉज़िटरी के नियमों पर निर्भर हैं, तो नियमों के दस्तावेज़ में इसकी जानकारी दें. उदाहरण के लिए, Sass नियमों पर निर्भर Skydoc नियम देखें. साथ ही, एक 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 का इस्तेमाल करना.
अपनी पसंद के हिसाब से कंस्ट्रेंट की मदद से, ऐसी भाषा तय की जाती है जिसे पूरा बेज़ल नेटवर्क
बताता है.
रनफ़ाइल लाइब्रेरी
अगर आपका नियम, रनफ़ाइलों को ऐक्सेस करने के लिए कोई स्टैंडर्ड लाइब्रेरी उपलब्ध कराता है, तो वह //<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/ डायरेक्ट्री का होना फ़ायदेमंद होता है. इससे उपयोगकर्ताओं को नियमों को इस्तेमाल करने के कुछ बुनियादी तरीके पता चलते हैं.
टेस्ट करना
Travis को शुरू करने के लिए दिए गए दस्तावेज़ों में बताए गए तरीके से सेट अप करें. इसके बाद, अपनी रिपॉज़िटरी में .travis.yml फ़ाइल जोड़ें. इसमें यह कॉन्टेंट शामिल करें:
dist: xenial # Ubuntu 16.04
# On trusty (or later) images, the Bazel apt repository can be used.
addons:
apt:
sources:
- sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
key_url: 'https://bazel.build/bazel-release.pub.gpg'
packages:
- bazel
script:
- bazel build //...
- bazel test //...
अगर आपकी रिपॉज़िटरी bazelbuild संगठन के तहत है, तो आपके पास ci.bazel.build में इसे जोड़ने का अनुरोध करने का विकल्प है.
दस्तावेज़
अपने नियमों पर टिप्पणी करने के तरीके के बारे में निर्देश पाने के लिए, Stardoc दस्तावेज़ देखें, ताकि दस्तावेज़ अपने-आप जनरेट हो सके.
अक्सर पूछे जाने वाले सवाल
हम Bazel के मुख्य GitHub डेटा स्टोर करने की जगह में अपना नियम क्यों नहीं जोड़ सकते?
हम Bazel रिलीज़ से नियमों को जितना हो सके उतना अलग करना चाहते हैं. इससे साफ़ तौर पर पता चलता है कि अलग-अलग नियमों का मालिक कौन होता है. इससे बेज़ल डेवलपर पर कम दबाव पड़ता है. हमारे उपयोगकर्ताओं के लिए, अलग-अलग करने की सुविधा से नियमों में बदलाव करना, उन्हें अपग्रेड करना, डाउनग्रेड करना, और बदलना आसान हो जाता है. नियमों में योगदान देना, Bazel में योगदान देने के मुकाबले आसान हो सकता है. हालांकि, यह नियमों पर निर्भर करता है. इसमें, संबंधित GitHub डेटा स्टोर करने की जगह को सबमिट करने का पूरा ऐक्सेस भी शामिल है. Bazel में सबमिट करने का ऐक्सेस पाना, काफ़ी मुश्किल प्रोसेस है.
हालांकि, इसका एक नुकसान यह है कि उपयोगकर्ताओं को एक बार इंस्टॉल करने की प्रोसेस ज़्यादा मुश्किल होती है:
उन्हें ऊपर दिए गए README.md सेक्शन में दिखाए गए तरीके के मुताबिक, अपनी WORKSPACE फ़ाइल में कोई नियम कॉपी-पेस्ट करना होता है.
पहले हमारे सभी नियम, Bazel रिपॉज़िटरी में (//tools/build_rules या //tools/build_defs में) होते थे. अब भी हमारे पास कुछ नियम वहां मौजूद हैं, लेकिन हम बाकी नियमों को वहां से हटाने पर काम कर रहे हैं.