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