इस पेज में स्टारलार्क की बुनियादी स्टाइल से जुड़े दिशा-निर्देश दिए गए हैं. साथ ही, इसमें यह जानकारी भी दी गई है मैक्रो और नियमों के बारे में जानकारी.
स्टारलार्क वह भाषा जो सॉफ़्टवेयर बनाने के तरीके को परिभाषित करती है. साथ ही, यह प्रोग्रामिंग और कॉन्फ़िगरेशन भाषा की ज़रूरत होती है.
BUILD फ़ाइलों, मैक्रो, और बिल्ड के नियम लिखने के लिए, Starlark का इस्तेमाल किया जा सकता है. मैक्रो और
नियम ज़रूरी मेटा-भाषाएं हैं - इनसे तय होता है कि BUILD फ़ाइलों को कैसे लिखा जाएगा.
BUILD फ़ाइलें आसान और दोहराई जाने वाली हैं.
सभी सॉफ़्टवेयर को लिखे जाने की तुलना में अधिक बार पढ़ा जाता है. यह खास तौर पर उन लोगों के लिए सही है
स्टारलार्क, जहां इंजीनियर BUILD फ़ाइलों को पढ़ते हैं, ताकि उनकी डिपेंडेंसी को समझा जा सके
टारगेट और उनके बिल्ड के बारे में जानकारी दी गई है. यह रीडिंग अक्सर पास होने में होगी,
जल्दी या किसी अन्य काम को पूरा करने के साथ-साथ. इस वजह से,
सरलता और पठनीयता बहुत महत्वपूर्ण है, ताकि उपयोगकर्ता पार्स और
BUILD फ़ाइलों को जल्दी से समझ सकते हैं.
जब कोई उपयोगकर्ता BUILD फ़ाइल खोलता है, तो वह तुरंत इसमें टारगेट की सूची जानना चाहता है
फ़ाइल; या C++ लाइब्रेरी के सोर्स की सूची देखें; या किसी आइटम को हटाने के लिए
पर निर्भर नहीं होना चाहिए. हर बार ऐब्स्ट्रैक्ट की लेयर जोड़ने पर, आपको
इससे उपयोगकर्ता के लिए इन कामों को करना मुश्किल हो जाएगा.
BUILD फ़ाइलों का विश्लेषण करने के साथ-साथ, उन्हें कई अलग-अलग टूल की मदद से अपडेट भी किया जाता है. शायद टूल ये काम न करें
अगर आपकी BUILD फ़ाइल में ऐब्स्ट्रैक्ट का इस्तेमाल किया गया है, तो उसमें बदलाव किया जा सकता है. BUILD को सेव किया जा रहा है
फ़ाइलों को आसान बनाकर बेहतर टूल का इस्तेमाल किया जा सकता है. कोड बेस बढ़ने के साथ-साथ,
करने के लिए कई BUILD फ़ाइलों में बार-बार बदलाव करना पड़ता है
लाइब्रेरी अपडेट करने या क्लीनअप करने के लिए.
सामान्य सलाह
- Buildifier का इस्तेमाल करना के फ़ॉर्मैट और लिंटर के तौर पर काम करता है.
- जांच के दिशा-निर्देशों का पालन करें.
स्टाइल
Python स्टाइल
संदेह होने पर, जहां मुमकिन हो वहां पीईपी 8 स्टाइल गाइड. खास तौर पर, इंडेंटेशन के लिए दो के बजाय चार स्पेस का इस्तेमाल करें, ताकि Python कन्वेंशन.
से
Starlark, Python नहीं है,
Python स्टाइल के कुछ पहलू लागू नहीं होते. उदाहरण के लिए, पीईपी 8 सलाह देता है कि
सिंगलटन की तुलना is से की जाएगी, जो इसमें कोई ऑपरेटर नहीं है
स्टार्लार्क.
डॉकस्ट्रिंग
docstrings का इस्तेमाल करके, फ़ाइलों और फ़ंक्शन के बारे में जानकारी देना.
हर .bzl फ़ाइल में सबसे ऊपर docstring और हर सार्वजनिक फ़ाइल के लिए एक docstring का इस्तेमाल करें
फ़ंक्शन का इस्तेमाल करना होगा.
दस्तावेज़ के नियम और पहलू
नियम और पहलू और उनकी विशेषताएं, सेवा देने वाली कंपनियां, और उनके
फ़ील्ड में, 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. इस बात का ध्यान रखें कि क्या ये स्टेटमेंट सही हैं या नहीं
पढ़ने में आसानी होती है.
मैक्रो
मैक्रो एक ऐसा फ़ंक्शन होता है जो लोड होने के दौरान एक या उससे ज़्यादा नियमों को इंस्टैंशिएट करता है फ़ेज़. आम तौर पर, मैक्रो के बजाय जब भी संभव हो नियमों का इस्तेमाल करें. बिल्ड उपयोगकर्ता ने जो ग्राफ़ देखा है वह उस ग्राफ़ के समान नहीं है जिसका इस्तेमाल बेज़ल बिल्ड - Baज़ल, बिल्ड ग्राफ़ का विश्लेषण करने से पहले मैक्रो को बड़ा कर दिया जाता है.
इस वजह से, जब कोई गड़बड़ी होती है, तो उपयोगकर्ता को यह समझना होगा कि
बनाने से जुड़ी समस्याओं के हल के लिए अपने मैक्रो को लागू करना. इसके अलावा, bazel
query के नतीजों को समझना मुश्किल हो सकता है, क्योंकि नतीजों में दिखाए गए टारगेट
मैक्रो एक्सपैंशन से. अंत में, पहलुओं को मैक्रो का पता नहीं होता, इसलिए टूलिंग
पहलुओं (आईडीई और अन्य) के आधार पर यह फ़ेल हो सकता है.
मैक्रो के लिए एक सुरक्षित इस्तेमाल यह है कि वे तय किए गए अतिरिक्त टारगेट के बारे में बताएं बेज़ल सीएलआई या बिल्ड फ़ाइलों में सीधे संदर्भ दिया गया है: इस मामले में, सिर्फ़ उन लक्ष्यों के असली उपयोगकर्ताओं को उनके बारे में और बिल्ड से जुड़ी समस्याओं के बारे में जानना ज़रूरी है मैक्रो से उपलब्ध कराने की सुविधा, उनके काम की है.
जनरेट किए गए टारगेट को तय करने वाले मैक्रो के लिए (मैक्रो के लागू करने की जानकारी जिनका सीएलआई में संदर्भ नहीं दिया जाना चाहिए या जो टारगेट पर आधारित नहीं होते हैं उस मैक्रो से इंस्टैंशिएट नहीं होने पर, इन सबसे सही तरीकों को अपनाएं:
- मैक्रो को एक
nameआर्ग्युमेंट लेना चाहिए और उस नाम का टारगेट तय करना चाहिए. वह टारगेट उस मैक्रो का मुख्य टारगेट बन जाता है. - जनरेट किए गए टारगेट यानी कि मैक्रो से तय किए गए अन्य टारगेट में:
- उनके नाम से पहले
<name>या_<name>लगाएं. उदाहरण के लिए,name = '%s_bar' % (name). - सीमित लोगों को दिख रहा है (
//visibility:private) और - वाइल्डकार्ड टारगेट (
:all,manual...,:*वगैरह).
- उनके नाम से पहले
nameका उपयोग केवल मैक्रो है, और किसी अन्य के लिए नहीं. उदाहरण के लिए, पाने के लिए नाम का इस्तेमाल न करें एक निर्भरता या इनपुट फ़ाइल, जो मैक्रो से जनरेट नहीं होती.- मैक्रो में बनाए गए सभी लक्ष्य इस प्रकार जोड़े जाने चाहिए कि मुख्य टारगेट को टारगेट करना.
- आम तौर पर, मैक्रो तय करते समय,
nameपहला आर्ग्युमेंट होना चाहिए. - मैक्रो में पैरामीटर के नाम एक जैसे रखें. अगर कोई पैरामीटर पास किया जाता है
को मुख्य टारगेट के लिए एट्रिब्यूट की वैल्यू के तौर पर सबमिट करना होगा, तो उसका नाम एक जैसा रखें. अगर मैक्रो
पैरामीटर का मकसद वही है जो किसी सामान्य नियम एट्रिब्यूट का इस्तेमाल करता है, जैसे
deps, एट्रिब्यूट को जैसा नाम दें (नीचे देखें). - मैक्रो कॉल करते समय, केवल कीवर्ड तर्क का उपयोग करें. यह इसके साथ संगत है साथ ही, इससे कॉन्टेंट पढ़ना आसान हो जाता है.
इंजीनियर अक्सर मैक्रो तब लिखते हैं, जब काम के नियमों का Starlark एपीआई उनके विशिष्ट उपयोग के उदाहरण के लिए अपर्याप्त है, चाहे नियम का मतलब है, नेटिव कोड या Starlark में मौजूद. अगर आपको इस समस्या का सामना करना पड़ रहा है, कोई समस्या हो, तो नियम लेखक से पूछें कि क्या वह लक्ष्य.
बुनियादी नियम यह है कि मैक्रो जितने ज़्यादा नियमों के समान होंगे, उतना ही बेहतर होगा.
मैक्रो भी देखें.
नियम
- नियमों, पहलुओं, और उनकी विशेषताओं के लिए लोअर_केस (लोअर_केस) नाम ("सांप") का इस्तेमाल करना चाहिए केस").
- नियम के नाम संज्ञा होते हैं. ये नाम, मुख्य रूप से बनाए गए आर्टफ़ैक्ट के बारे में बताते हैं
निर्भरता के संदर्भ में (या लीफ़ रूल के लिए,
उपयोगकर्ता). यह ज़रूरी नहीं है कि यह फ़ाइल सफ़िक्स हो. उदाहरण के लिए, एक नियम जो
C++ आर्टफ़ैक्ट जनरेट करता है, जिसका इस्तेमाल Python एक्सटेंशन के नाम से किया जा सकता है
py_extension. ज़्यादातर भाषाओं के लिए, सामान्य नियमों में ये शामिल हैं:*_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 इंटरफ़ेस के साथ ब्राउज़ करता है. एलान करें और दस्तावेज़ देने वाली कंपनी का नाम बताएं फ़ील्ड.
- ज़्यादा इस्तेमाल करने की शर्तों को ध्यान में रखकर अपना नियम बनाएं. ध्यान दें कि अन्य नियम, अपने नियम के साथ इंटरैक्ट करना, अपने प्रदाताओं तक पहुंच बनाना और आपके द्वारा बनाई जाने वाली कार्रवाइयां.
- अपने नियमों में दिए गए परफ़ॉर्मेंस के दिशा-निर्देशों का पालन करें.