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

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

हर पैकेज में एक 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 फ़ाइल के लेखकों को हर बिल्ड टारगेट की भूमिका के बारे में बताने के लिए, ज़रूरत के हिसाब से टिप्पणी करनी चाहिए. भले ही, वह सार्वजनिक इस्तेमाल के लिए हो या नहीं. साथ ही, पैकेज की भूमिका के बारे में भी बताना चाहिए.

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

Bazel एक्सटेंशन, .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 नियम, किसी प्रोग्रामिंग भाषा में अलग-अलग तौर पर कॉम्पाइल किए गए मॉड्यूल के बारे में बताते हैं. लाइब्रेरी, दूसरी लाइब्रेरी पर निर्भर हो सकती हैं. साथ ही, बाइनरी और टेस्ट, लाइब्रेरी पर निर्भर हो सकते हैं. हालांकि, इनके अलग-अलग कंपाइल होने की उम्मीद की जाती है.