फ़ाइलें बनाएं

पिछले सेक्शन में, पैकेज, टारगेट, लेबल, और बिल्ड डिपेंडेंसी ग्राफ़ के बारे में खास तौर पर बताया गया है. इस सेक्शन में, पैकेज को तय करने के लिए इस्तेमाल किए गए कंक्रीट सिंटैक्स के बारे में बताया गया है.

हर पैकेज में एक BUILD फ़ाइल होती है, जो एक छोटा प्रोग्राम होता है.

BUILD फ़ाइलों का आकलन, Starlark जैसी भाषा का इस्तेमाल करके किया जाता है.

इन्हें स्टेटमेंट की क्रम से बनी सूची के तौर पर समझा जाता है.

आम तौर पर, क्रम का फ़र्क़ पड़ता है: उदाहरण के लिए, वैरिएबल का इस्तेमाल करने से पहले, उन्हें तय करना ज़रूरी है. हालांकि, ज़्यादातर BUILD फ़ाइलों में सिर्फ़ बिल्ड के नियमों का एलान होता है और इन स्टेटमेंट का क्रम अभौतिक होता है. सिर्फ़ यह मायने रखता है कि किन नियमों को एलान किया गया था और टाइम पैकेज का आकलन पूरा होने तक, किन-किन वैल्यू का एलान किया गया था.

जब cc_library जैसे किसी बिल्ड नियम फ़ंक्शन को लागू किया जाता है, तो यह ग्राफ़ में नया टारगेट बनाता है. इस टारगेट को बाद में लेबल का इस्तेमाल करके रेफ़र किया जा सकता है.

सामान्य BUILD फ़ाइलों में, नियमों के एलान को व्यवहार में बदलाव किए बिना, फिर से व्यवस्थित किया जा सकता है.

कोड और डेटा को अलग-अलग रखने के लिए, BUILD फ़ाइलों में फ़ंक्शन की परिभाषाएं, for स्टेटमेंट या if स्टेटमेंट शामिल नहीं किए जा सकते. हालांकि, सूची के समझने और if एक्सप्रेशन की अनुमति है. इसके बजाय, .bzl फ़ाइलों में फ़ंक्शन का एलान किया जा सकता है. इसके अलावा, BUILD फ़ाइलों में *args और **kwargs आर्ग्युमेंट इस्तेमाल करने की अनुमति नहीं है. इसके बजाय, सभी आर्ग्युमेंट साफ़ तौर पर बताएं.

अहम बात यह है कि Starlark में मौजूद प्रोग्राम, मनमुताबिक I/O नहीं कर सकते. यह इन्वैरिएंट, BUILD फ़ाइलों को हर्मेटिक बनाता है — यह सिर्फ़ इनपुट के जाने-पहचाने सेट पर निर्भर करता है. इससे यह पक्का किया जा सकता है कि बिल्ड फिर से बनाए जा सकें. ज़्यादा जानकारी के लिए, Hermeticity लेख पढ़ें.

BUILD फ़ाइलों को सिर्फ़ ASCII वर्णों का इस्तेमाल करके लिखा जाना चाहिए. हालांकि, तकनीकी तौर पर, इनका विश्लेषण Latin-1 वर्ण सेट का इस्तेमाल करके किया जाता है.

जब भी बैकग्राउंड कोड की डिपेंडेंसी में बदलाव होता है, तब BUILD फ़ाइलों को अपडेट करना ज़रूरी होता है. इसलिए, आम तौर पर एक टीम के कई लोग इन फ़ाइलों को मैनेज करते हैं. BUILD फ़ाइल के लेखकों को हर बिल्ड टारगेट की भूमिका के बारे में बताने के लिए, ज़रूरत के हिसाब से टिप्पणी करनी चाहिए. भले ही, वह सार्वजनिक इस्तेमाल के लिए हो या नहीं. साथ ही, पैकेज की भूमिका के बारे में भी बताना चाहिए.

एक्सटेंशन लोड करना

बेज़ेल एक्सटेंशन ऐसी फ़ाइलें हैं जिनके आखिरी चार अंक .bzl हैं. किसी एक्सटेंशन से कोई सिंबल इंपोर्ट करने के लिए, load स्टेटमेंट का इस्तेमाल करें.

load("//foo/bar:file.bzl", "some_library")

यह कोड, foo/bar/file.bzl फ़ाइल को लोड करता है और एनवायरमेंट में some_library सिंबल जोड़ देता है. इसका इस्तेमाल नए नियम, फ़ंक्शन या कॉन्स्टेंट (उदाहरण के लिए, स्ट्रिंग या सूची) लोड करने के लिए किया जा सकता है. load को किए जाने वाले कॉल में अतिरिक्त आर्ग्युमेंट का इस्तेमाल करके, एक से ज़्यादा सिंबल इंपोर्ट किए जा सकते हैं. आर्ग्युमेंट, स्ट्रिंग लिटरल (कोई वैरिएबल नहीं) होने चाहिए और load स्टेटमेंट, सबसे ऊपर दिखने चाहिए — ये किसी फ़ंक्शन बॉडी में नहीं हो सकते.

load का पहला आर्ग्युमेंट, .bzl फ़ाइल की पहचान करने वाला लेबल होता है. अगर यह मिलता-जुलता लेबल है, तो इसका समाधान मौजूदा bzl फ़ाइल वाले पैकेज (डायरेक्ट्री नहीं) के हिसाब से किया जाता है. load स्टेटमेंट में रिलेटिव लेबल के लिए, शुरुआत में : का इस्तेमाल करना चाहिए.

load में उपनामों का भी इस्तेमाल किया जा सकता है. इसलिए, इंपोर्ट किए गए सिंबल के लिए अलग-अलग नाम असाइन किए जा सकते हैं.

load("//foo/bar:file.bzl", library_alias = "some_library")

आप एक load कथन में एक से ज़्यादा उपनाम परिभाषित कर सकते हैं. इसके अलावा, तर्क सूची में उपनाम और सामान्य चिह्न के नाम, दोनों हो सकते हैं. नीचे दिया गया उदाहरण पूरी तरह से कानूनी है (कृपया ध्यान दें कि कोटेशन मार्क का इस्तेमाल कब करना चाहिए).

load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")

.bzl फ़ाइल में, _ से शुरू होने वाले सिंबल एक्सपोर्ट नहीं किए जाते और किसी दूसरी फ़ाइल से डाउनलोड नहीं किए जा सकते.

लोड दिखने की सेटिंग का इस्तेमाल करके, यह तय किया जा सकता है कि .bzl फ़ाइल को कौन लोड कर सकता है.

बिल्ड नियमों के टाइप

बिल्ड के ज़्यादातर नियम, परिवारों में आते हैं. इन्हें भाषा के हिसाब से ग्रुप में बांटा जाता है. उदाहरण के लिए, cc_binary, cc_library और cc_test, C++ बाइनरी, लाइब्रेरी, और टेस्ट के लिए बने बिल्ड नियम हैं. अन्य भाषाएं, नाम रखने के लिए इसी स्कीम का इस्तेमाल करती हैं. हालांकि, इनमें अलग प्रीफ़िक्स का इस्तेमाल किया जाता है. जैसे, Java के लिए java_*. इनमें से कुछ फ़ंक्शन, Build Encyclopedia में दस्तावेज़ के तौर पर मौजूद हैं. हालांकि, कोई भी व्यक्ति नए नियम बना सकता है.

• *_binary नियम, किसी भाषा में चलाए जा सकने वाले प्रोग्राम बनाते हैं. बाइल्ड करने के बाद, बाइनरी फ़ाइल, बाइल्ड टूल के बाइनरी आउटपुट ट्री में, नियम के लेबल के नाम से जुड़ी जगह पर रहेगी. उदाहरण के लिए, //my:program, $(BINDIR)/my/program पर दिखेगा.

  कुछ भाषाओं में, ऐसे नियम एक रनफ़ाइल डायरेक्ट्री भी बनाते हैं. इसमें, नियम से जुड़े data एट्रिब्यूट या डिपेंडेंसी के ट्रांज़िशन क्लोज़र में मौजूद किसी भी नियम में बताई गई सभी फ़ाइलें शामिल होती हैं. प्रोडक्शन में आसानी से डिप्लॉय करने के लिए, फ़ाइलों के इस सेट को एक जगह पर इकट्ठा किया जाता है.

• *_test नियम, *_binary नियम का एक खास वर्शन है. इसका इस्तेमाल, ऑटोमेटेड जांच के लिए किया जाता है. टेस्ट, ऐसे प्रोग्राम होते हैं जो सफल होने पर शून्य दिखाते हैं.

  बाइनरी की तरह ही, टेस्ट में भी रनफ़ाइल ट्री होते हैं. इनमें मौजूद फ़ाइलें ही ऐसी होती हैं जिन्हें टेस्ट, रनटाइम के दौरान सही तरीके से खोल सकता है. उदाहरण के लिए, कोई प्रोग्राम cc_test(name='x', data=['//foo:bar']), प्रोग्राम चलाने के दौरान $TEST_SRCDIR/workspace/foo/bar को खोल सकता है और पढ़ सकता है. ($TEST_SRCDIR की वैल्यू को ऐक्सेस करने के लिए, हर प्रोग्रामिंग भाषा का अपना यूटिलिटी फ़ंक्शन होता है, लेकिन वे सभी सीधे एनवायरमेंट वैरिएबल का इस्तेमाल करने के बराबर हैं.) नियम का पालन न करने पर, रिमोट टेस्टिंग होस्ट पर टेस्ट करने पर वह पूरा नहीं होगा.

• *_library नियम, दी गई प्रोग्रामिंग भाषा में अलग-अलग मॉड्यूल के बारे में बताते हैं. लाइब्रेरी अन्य लाइब्रेरी पर निर्भर हो सकती हैं. बाइनरी और टेस्ट, लाइब्रेरी पर निर्भर कर सकते हैं. ऐसा होने पर, लाइब्रेरी उम्मीद के मुताबिक अलग-अलग कंपाइलेशन हो सकती हैं.