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

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

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