यह पेज उन नियम लेखकों के लिए है जो अपने नियमों को दूसरों के लिए उपलब्ध कराना चाहते हैं.
होस्टिंग और नाम रखने से जुड़े नियम
नए नियम, आपके संगठन के GitHub रिपॉज़िटरी में होने चाहिए. अगर आपको लगता है कि आपके नियम bazelbuild संगठन के हैं, तो bazel-dev मेलिंग सूची से संपर्क करें.
बेज़ेल नियमों के लिए डेटा स्टोर करने की जगहों के नाम इस फ़ॉर्मैट के हिसाब से तय किए जाते हैं:
$ORGANIZATION/rules_$NAME
.
GitHub पर उदाहरण देखें.
एक जैसा फ़ॉर्मैट इस्तेमाल करने के लिए, आपको Bazel नियमों को पब्लिश करते समय भी यही फ़ॉर्मैट अपनाना होगा.
GitHub रिपॉज़िटरी की पूरी जानकारी और README.md
टाइटल का इस्तेमाल ज़रूर करें. उदाहरण के लिए:
- रिपॉज़िटरी का नाम:
bazelbuild/rules_go
- डेटा स्टोर करने की जगह की जानकारी: Basel के लिए Go के नियम
- डेटा स्टोर करने की जगह के टैग:
golang
,bazel
README.md
हेडर: Baaz के लिए नियमों का पालन करें (https://bazu.build का लिंक देखें, जो उन लोगों को सही जगह पर ले जाएगा जो Basel के बारे में नहीं जानते)
नियमों को भाषा (जैसे, Scala) या प्लैटफ़ॉर्म (जैसे, Android) के हिसाब से ग्रुप किया जा सकता है.
डेटा स्टोर करने की जगह का कॉन्टेंट
हर नियम के रिपॉज़िटरी का लेआउट एक जैसा होना चाहिए, ताकि उपयोगकर्ता नए नियमों को तुरंत समझ सकें.
उदाहरण के लिए, 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 मेलिंग सूची से संपर्क करें.
नीचे दिए गए सेक्शन में, मान लें कि डेटा स्टोर करने की जगह, baazbuild संगठन की है.
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()
अगर आपके नियम, डेटा स्टोर करने की किसी दूसरी जगह के नियमों पर निर्भर करते हैं, तो इस बात की जानकारी दें कि नियमों के दस्तावेज़ में (उदाहरण के लिए, 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
टारगेट का विश्लेषण करना होगा. 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/
डायरेक्ट्री होनी चाहिए.
टेस्ट करना
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 डेटा स्टोर करने की जगह में अपना नियम क्यों नहीं जोड़ सकते?
इसलिए, हम चाहते हैं कि ज़्यादा से ज़्यादा समय से, Basel की रिलीज़ के नियमों को अलग-अलग कैटगरी में रखा जाए. इससे यह साफ़ तौर पर पता चलता है कि अलग-अलग नियमों का मालिकाना हक किसके पास है. इससे Bazel डेवलपर पर लोड कम हो जाता है. हमारे उपयोगकर्ताओं के लिए, डिकोड करने से नियमों में बदलाव करना, उन्हें अपग्रेड करना, डाउनग्रेड करना, और बदलना आसान हो जाता है. नियमों पर निर्भर करते हुए - बेज़ल में योगदान करने के मुकाबले, नियमों में योगदान करना कम वज़न हो सकता है. इसमें संबंधित GitHub रिपॉज़िटरी का पूरा ऐक्सेस भी शामिल है. Bazel में सबमिट करने का ऐक्सेस पाना, काफ़ी मुश्किल प्रोसेस है.
हालांकि, हमारे उपयोगकर्ताओं के लिए एक बार इंस्टॉल करने की प्रक्रिया काफ़ी जटिल है. उन्हें एक नियम को कॉपी करके अपनी WORKSPACE
फ़ाइल में चिपकाना होता है, जैसा कि ऊपर README.md
सेक्शन में दिखाया गया है.
पहले हमारे सभी नियम, Bazel रिपॉज़िटरी में (//tools/build_rules
या //tools/build_defs
में) होते थे. अब भी हमारे पास कुछ नियम वहां मौजूद हैं, लेकिन हम बाकी नियमों को वहां से हटाने पर काम कर रहे हैं.