इस पेज में स्टारलार्क की बुनियादी स्टाइल से जुड़े दिशा-निर्देश दिए गए हैं. साथ ही, इसमें यह जानकारी भी दी गई है मैक्रो और नियमों के बारे में जानकारी.
Starlark वह भाषा जो सॉफ़्टवेयर बनाने के तरीके को परिभाषित करती है. साथ ही, यह प्रोग्रामिंग और कॉन्फ़िगरेशन भाषा की ज़रूरत होती है.
BUILD फ़ाइलों, मैक्रो, और बिल्ड के नियम लिखने के लिए, Starlark का इस्तेमाल किया जा सकता है. मैक्रो और नियम, मुख्य रूप से मेटा-भाषाएं होती हैं - ये तय करते हैं कि BUILD फ़ाइलें कैसे लिखी जाती हैं.
BUILD फ़ाइलें आसान और बार-बार इस्तेमाल की जानी चाहिए.
सभी सॉफ़्टवेयर को लिखे जाने की तुलना में अधिक बार पढ़ा जाता है. यह बात खास तौर पर Starlark के लिए सही है, क्योंकि इंजीनियर अपने टारगेट की डिपेंडेंसी और अपने बिल्ड की जानकारी समझने के लिए, BUILD फ़ाइलें पढ़ते हैं. यह रीडिंग अक्सर पास होने में होगी,
जल्दी या किसी अन्य काम को पूरा करने के साथ-साथ. इस वजह से,
सरलता और पठनीयता बहुत महत्वपूर्ण है, ताकि उपयोगकर्ता पार्स और
BUILD फ़ाइलों को जल्दी से समझ सकते हैं.
जब कोई उपयोगकर्ता BUILD फ़ाइल खोलता है, तो वह तुरंत इसमें टारगेट की सूची जानना चाहता है
फ़ाइल; या C++ लाइब्रेरी के सोर्स की सूची देखें; या किसी आइटम को हटाने के लिए
पर निर्भर नहीं होना चाहिए. जब भी कोई एब्स्ट्रैक्शन लेयर जोड़ी जाती है, तो उपयोगकर्ता के लिए ये टास्क करना मुश्किल हो जाता है.
BUILD फ़ाइलों का विश्लेषण करने के साथ-साथ, उन्हें कई अलग-अलग टूल की मदद से अपडेट भी किया जाता है. शायद टूल ये काम न करें
अगर आपकी BUILD फ़ाइल में ऐब्स्ट्रैक्ट का इस्तेमाल किया गया है, तो उसमें बदलाव किया जा सकता है. BUILD को सेव किया जा रहा है
फ़ाइलों को आसान बनाकर बेहतर टूल का इस्तेमाल किया जा सकता है. कोड बेस के बढ़ने के साथ-साथ, किसी लाइब्रेरी को अपडेट करने या उसे साफ़ करने के लिए, कई BUILD फ़ाइलों में बदलाव करना ज़रूरी हो जाता है.
सामान्य सलाह
- Buildifier को फ़ॉर्मैटर और लिंटर के तौर पर इस्तेमाल करें.
- जांच से जुड़े दिशा-निर्देशों का पालन करें.
स्टाइल
Python स्टाइल
संदेह होने पर, जहां मुमकिन हो वहां पीईपी 8 स्टाइल गाइड. खास तौर पर, इंडेंटेशन के लिए दो के बजाय चार स्पेस का इस्तेमाल करें, ताकि Python कन्वेंशन.
Starlark, Python नहीं है. इसलिए, Python स्टाइल के कुछ पहलू लागू नहीं होते. उदाहरण के लिए, PEP 8 के मुताबिक, सिंगलटन की तुलना is से की जानी चाहिए. यह Starlark में कोई ऑपरेटर नहीं है.
डॉकस्ट्रिंग
डॉस्ट्रिंग का इस्तेमाल करके, फ़ाइलों और फ़ंक्शन के बारे में जानकारी दें.
हर .bzl फ़ाइल के सबसे ऊपर और हर सार्वजनिक फ़ंक्शन के लिए, डोकस्ट्रिंग का इस्तेमाल करें.
दस्तावेज़ के नियम और पहलू
नियमों और पहलुओं के साथ-साथ उनके एट्रिब्यूट, प्रोवाइडर, और उनके फ़ील्ड को doc आर्ग्युमेंट का इस्तेमाल करके दस्तावेज़ में शामिल किया जाना चाहिए.
नाम रखने का तरीका
- वैरिएबल और फ़ंक्शन के नामों में, अंग्रेज़ी के छोटे अक्षरों का इस्तेमाल किया जाता है. साथ ही, शब्दों को अंडरस्कोर (
[a-z][a-z0-9_]*) से अलग किया जाता है, जैसे किcc_library. - टॉप-लेवल की निजी वैल्यू, एक अंडरस्कोर से शुरू होती हैं. बेज़ल यह लागू करते हैं कि दूसरी फ़ाइलों से निजी वैल्यू का इस्तेमाल नहीं किया जा सकता. लोकल वैरिएबल में अंडरस्कोर प्रीफ़िक्स का इस्तेमाल नहीं किया जाना चाहिए.
लाइन की लंबाई
BUILD फ़ाइलों की तरह, लाइन की लंबाई की कोई सख्त सीमा नहीं है, क्योंकि लेबल लंबे हो सकते हैं.
जब भी हो सके, हर लाइन में ज़्यादा से ज़्यादा 79 वर्ण इस्तेमाल करें. ऐसा करने के लिए, Python के स्टाइल गाइड, PEP 8 का पालन करें. यह दिशा-निर्देश
सख्ती से लागू नहीं किया जाना चाहिए: संपादकों को 80 से ज़्यादा कॉलम दिखाने चाहिए,
अपने-आप होने वाले बदलावों में अक्सर लंबी लाइनें दिखती हैं. इसलिए, इंसानों को
उन लाइनों को छोटे-छोटे हिस्सों में बांटें जो पहले से पढ़ी जा सकती हैं.
कीवर्ड के ऑर्ग्युमेंट
कीवर्ड आर्ग्युमेंट में, बराबर के निशान के आस-पास स्पेस का इस्तेमाल करना बेहतर होता है:
def fct(name, srcs):
filtered_srcs = my_filter(source = srcs)
native.cc_library(
name = name,
srcs = filtered_srcs,
testonly = True,
)
बूलियन वैल्यू
बूलियन वैल्यू के लिए, 1 और 0 के बजाय True और False वैल्यू का इस्तेमाल करें. उदाहरण के लिए, नियम में बूलियन एट्रिब्यूट का इस्तेमाल करते समय.
डीबग करने के लिए सिर्फ़ प्रिंट करें का इस्तेमाल करें
प्रोडक्शन कोड में print() फ़ंक्शन का इस्तेमाल न करें. इसका इस्तेमाल सिर्फ़ डिबग करने के लिए किया जाता है. यह आपकी .bzl फ़ाइल के सभी उपयोगकर्ताओं को स्पैम भेजेगा. कॉन्टेंट बनाने
इसका अपवाद सिर्फ़ यह है कि आप print() का इस्तेमाल करने वाला कोड सबमिट कर सकते हैं, अगर वह बंद हो
डिफ़ॉल्ट रूप से होता है और इसे केवल स्रोत में बदलाव करके सक्षम किया जा सकता है -- उदाहरण के लिए, अगर सभी
print() के इस्तेमाल को if DEBUG: सुरक्षित रखता है, जहां DEBUG को हार्डकोड किया गया है
False. इस बात का ध्यान रखें कि क्या ये स्टेटमेंट सही हैं या नहीं
पढ़ने में आसानी होती है.
मैक्रो
मैक्रो एक ऐसा फ़ंक्शन होता है जो लोड होने के दौरान एक या उससे ज़्यादा नियमों को इंस्टैंशिएट करता है फ़ेज़. आम तौर पर, मैक्रो के बजाय नियमों का इस्तेमाल करें. उपयोगकर्ता को दिखने वाला बिल्ड ग्राफ़, बिल्ड के दौरान Bazel के इस्तेमाल किए गए ग्राफ़ से अलग होता है. Bazel, बिल्ड ग्राफ़ का विश्लेषण करने से पहले, मैक्रो को बड़ा कर देता है.
इस वजह से, जब कोई गड़बड़ी होती है, तो उपयोगकर्ता को यह समझना होगा कि
बनाने से जुड़ी समस्याओं के हल के लिए अपने मैक्रो को लागू करना. इसके अलावा, bazel
query के नतीजों को समझना मुश्किल हो सकता है, क्योंकि नतीजों में दिखाए गए टारगेट
मैक्रो एक्सपैंशन से. अंत में, पहलुओं को मैक्रो का पता नहीं होता, इसलिए टूलिंग
पहलुओं (आईडीई और अन्य) के आधार पर यह फ़ेल हो सकता है.
मैक्रो का सुरक्षित इस्तेमाल, अतिरिक्त टारगेट तय करने के लिए किया जाता है. इन टारगेट का रेफ़रंस, सीधे तौर पर Bazel CLI या BUILD फ़ाइलों में दिया जाता है: इस मामले में, सिर्फ़ उन टारगेट के असल उपयोगकर्ताओं को उनके बारे में पता होना चाहिए. साथ ही, मैक्रो के इस्तेमाल से होने वाली कोई भी बिल्ड समस्या, उनके इस्तेमाल से कभी भी दूर नहीं होती.
जनरेट किए गए टारगेट को तय करने वाले मैक्रो के लिए (मैक्रो के लागू करने की जानकारी जिनका सीएलआई में संदर्भ नहीं दिया जाना चाहिए या जो टारगेट पर आधारित नहीं होते हैं उस मैक्रो से इंस्टैंशिएट नहीं होने पर, इन सबसे सही तरीकों को अपनाएं:
- मैक्रो को एक
nameआर्ग्युमेंट लेना चाहिए और उस नाम का टारगेट तय करना चाहिए. वह टारगेट उस मैक्रो का मुख्य टारगेट बन जाता है. - जनरेट किए गए टारगेट, यानी मैक्रो से तय किए गए सभी अन्य टारगेट के लिए:
- उनके नाम के आगे
<name>या_<name>लगा हो. उदाहरण के लिए,name = '%s_bar' % (name)का इस्तेमाल करना. - सीमित लोगों को दिख रहा है (
//visibility:private) और - वाइल्डकार्ड टारगेट (
:all,manual...,:*वगैरह).
- उनके नाम के आगे
nameका उपयोग केवल मैक्रो है, और किसी अन्य के लिए नहीं. उदाहरण के लिए, पाने के लिए नाम का इस्तेमाल न करें एक निर्भरता या इनपुट फ़ाइल, जो मैक्रो से जनरेट नहीं होती.- मैक्रो में बनाए गए सभी टारगेट, मुख्य टारगेट से किसी तरह से जुड़े होने चाहिए.
- मैक्रो में पैरामीटर के नाम एक जैसे रखें. अगर किसी पैरामीटर को मुख्य टारगेट के लिए एट्रिब्यूट वैल्यू के तौर पर पास किया जाता है, तो उसका नाम पहले जैसा ही रखें. अगर कोई मैक्रो पैरामीटर,
depsजैसे सामान्य नियम एट्रिब्यूट के मकसद के लिए काम करता है, तो उसे एट्रिब्यूट की तरह ही नाम दें (नीचे देखें). - मैक्रो को कॉल करते समय, सिर्फ़ कीवर्ड आर्ग्युमेंट का इस्तेमाल करें. यह नियमों के मुताबिक है और इससे कॉन्टेंट को पढ़ना आसान हो जाता है.
इंजीनियर अक्सर मैक्रो लिखते हैं, जब काम के नियमों का Starlark API, उनके इस्तेमाल के उदाहरण के लिए काफ़ी नहीं होता. भले ही, नियम को Bazel में नेटिव कोड या Starlark में तय किया गया हो. अगर आपको यह समस्या आ रही है, तो नियम बनाने वाले व्यक्ति से पूछें कि क्या वह आपके लक्ष्यों को पूरा करने के लिए एपीआई को बढ़ा सकता है.
बुनियादी नियम यह है कि मैक्रो जितने ज़्यादा नियमों के समान होंगे, उतना ही बेहतर होगा.
मैक्रो भी देखें.
नियम
- नियमों, पहलुओं, और उनकी विशेषताओं के लिए लोअर_केस (लोअर_केस) नाम ("सांप") का इस्तेमाल करना चाहिए केस").
- नियम के नाम ऐसे संज्ञा होते हैं जो नियम से जनरेट होने वाले मुख्य आर्टफ़ैक्ट के बारे में बताते हैं. यह जानकारी, नियम की डिपेंडेंसी (या लीफ़ नियमों के लिए, उपयोगकर्ता) के हिसाब से दी जाती है. यह ज़रूरी नहीं है कि यह फ़ाइल का सफ़िक्स हो. उदाहरण के लिए, C++ आर्टफ़ैक्ट जनरेट करने वाले नियम को
py_extensionकहा जा सकता है. इन आर्टफ़ैक्ट का इस्तेमाल, Python एक्सटेंशन के तौर पर किया जाता है. ज़्यादातर भाषाओं के लिए, सामान्य नियमों में ये शामिल हैं:*_library- कंपाइलेशन यूनिट या "मॉड्यूल".*_binary- एक्ज़ीक्यूटेबल या डिप्लॉयमेंट यूनिट बनाने वाला टारगेट.*_test- टेस्ट टारगेट. इसमें एक से ज़्यादा टेस्ट शामिल हो सकते हैं.*_testटारगेट में मौजूद सभी जांचों के एक ही थीम के वैरिएंट होने की उम्मीद करें. उदाहरण के लिए, किसी एक लाइब्रेरी की जांच करना.*_import: पहले से कंपाइल किए गए आर्टफ़ैक्ट को कवर करने वाला टारगेट, जैसे कि.jarया.dll, जिसका इस्तेमाल कंपाइलेशन के दौरान किया जाता है.
- एट्रिब्यूट के लिए एक जैसे नाम और टाइप का इस्तेमाल करें. कुछ सामान्य रूप से लागू होते हैं
विशेषताओं में शामिल हैं:
srcs:label_list, फ़ाइलों को अनुमति दी जा रही है: सोर्स फ़ाइलें, आम तौर पर इंसानों ने लिखा है.deps:label_list, आम तौर पर फ़ाइलों को अनुमति नहीं दी जाती: कंपाइलेशन के लिए ज़रूरी फ़ाइलें.data:label_list, फ़ाइलों को अनुमति देना: डेटा फ़ाइलें, जैसे कि टेस्ट डेटा वगैरह.runtime_deps:label_list: रनटाइम डिपेंडेंसी, जिन्हें कंपाइल करने के लिए ज़रूरत नहीं होती.
- व्यवहार से जुड़ी जानकारी देने वाले किसी भी एट्रिब्यूट के लिए, जैसे कि स्ट्रिंग टेंप्लेट
विकल्प हैं या ऐसे टूल जिनका इस्तेमाल किसी खास विकल्प के साथ किया जाता है
ज़रूरी है), तो
docकीवर्ड तर्क का इस्तेमाल करके दस्तावेज़ उपलब्ध कराएं. एट्रिब्यूट का एलान करना (attr.label_list()या इससे मिलता-जुलता). - नियम लागू करने वाले फ़ंक्शन, ज़्यादातर मामलों में निजी फ़ंक्शन होने चाहिए. इनके नाम के आगे अंडरस्कोर होना चाहिए. आम तौर पर,
myruleके लिए लागू करने वाले फ़ंक्शन को_myrule_implनाम दिया जाता है. - एक अच्छी तरह से तय नियम का इस्तेमाल करके, अपने नियमों के बीच जानकारी दें provider इंटरफ़ेस के साथ ब्राउज़ करता है. जानकारी दें और दस्तावेज़ उपलब्ध कराने वाली कंपनी के बारे में बताएं फ़ील्ड.
- अपने नियम को इस तरह से डिज़ाइन करें कि उसे आगे बढ़ाया जा सके. ध्यान रखें कि हो सकता है कि अन्य नियम आपके नियम के साथ इंटरैक्ट करना चाहें, आपके सेवा देने वालों को ऐक्सेस करना चाहें, और आपकी बनाई गई कार्रवाइयों का फिर से इस्तेमाल करना चाहें.
- अपने नियमों में परफ़ॉर्मेंस से जुड़े दिशा-निर्देशों का पालन करें.