लेबल

लेबल, टारगेट के लिए आइडेंटिफ़ायर होता है. किसी सामान्य लेबल अपने पूरे कैननिकल फ़ॉर्म में ऐसा दिखता है:

@@myrepo//my/app/main:app_binary

लेबल का पहला हिस्सा, @@myrepo रिपॉज़िटरी का नाम होता है. दो बार @ वाला सिंटैक्स यह दिखाता है कि यह कैननिकल रिपॉज़िटरी का नाम है. यह नाम, वर्कस्पेस में यूनीक होता है. कैननिकल रेपो नाम वाले लेबल साफ़ तौर पर टारगेट की पहचान करते हैं, चाहे वे किसी भी संदर्भ में दिख रहे हों.

अक्सर कैननिकल रेपो नेम, आर्केन स्ट्रिंग होता है, जो @@rules_java++toolchains+local_jdk की तरह दिखता है. आम तौर पर, साफ़ तौर पर दिखने वाले रिपॉज़िटरी के नाम वाले लेबल दिखते हैं. ये लेबल इस तरह के होते हैं:

@myrepo//my/app/main:app_binary

इन दोनों में सिर्फ़ एक अंतर है. रीपो के नाम के आगे दो के बजाय एक @ लगा है. यह एक ऐसे रिपो के बारे में बताता है जिसका नाम myrepo है. यह लेबल, उस संदर्भ के हिसाब से अलग हो सकता है जिसमें यह लेबल दिखता है.

आम तौर पर, अगर लेबल उसी रिपॉज़िटरी (डेटा स्टोर करने की जगह) को दिखाता है जिससे इसका इस्तेमाल किया जाता है, तो रेपो नाम वाले हिस्से को हटाया जा सकता है. इसलिए, @@myrepo में पहला लेबल आम तौर पर

//my/app/main:app_binary

लेबल का दूसरा हिस्सा, पैकेज का नाम my/app/main होता है. यह पैकेज का ऐसा नाम होता है जिसमें कोई विशेषता नहीं होती. यह नाम, रिपॉज़िटरी के रूट के हिसाब से पैकेज का पाथ होता है. डेटा स्टोर करने की जगह का नाम और अमान्य पैकेज के नाम, एक साथ पूरी तरह क्वालिफ़ाइड पैकेज का नाम @@myrepo//my/app/main बनाते हैं. जब लेबल उसी पैकेज का रेफ़र करता है जिसमें उसका इस्तेमाल किया गया है, तो पैकेज का नाम (और वैकल्पिक रूप से, कोलन) छोड़ा जा सकता है. इसलिए, @@myrepo//my/app/main के अंदर, यह लेबल इनमें से किसी एक तरीके से लिखा जा सकता है:

app_binary
:app_binary

यह एक नियम है कि फ़ाइलों के लिए कोलन का इस्तेमाल नहीं किया जाता, लेकिन नियमों के लिए किया जाता है. हालांकि, यह ज़रूरी नहीं है.

कोलन के बाद का लेबल का हिस्सा, app_binary बिना क्वालीफ़ायर वाला टारगेट नाम है. अगर यह पैकेज पाथ के आखिरी कॉम्पोनेंट से मेल खाता है, तो इसे और कोलन को छोड़ा जा सकता है. इसलिए, ये दोनों लेबल एक जैसे हैं:

//my/app/lib
//my/app/lib:lib

पैकेज की किसी सबडायरेक्ट्री में मौजूद फ़ाइल टारगेट का नाम, पैकेज रूट (BUILD फ़ाइल वाली डायरेक्ट्री) के हिसाब से फ़ाइल का पाथ होता है. इसलिए, यह फ़ाइल रिपॉज़िटरी की my/app/main/testdata सबडायरेक्ट्री में है:

//my/app/main:testdata/input.txt

//my/app और @@some_repo//my/app जैसी स्ट्रिंग का मतलब, इस्तेमाल के कॉन्टेक्स्ट के हिसाब से दो तरह से होता है: जब Bazel को लेबल की ज़रूरत होती है, तो इनका मतलब क्रमशः //my/app:app और @@some_repo//my/app:app होता है. हालांकि, जब Bazel को किसी पैकेज (उदाहरण के लिए, package_group स्पेसिफ़िकेशन में) की ज़रूरत होती है, तो वह उस पैकेज का रेफ़रंस देता है जिसमें वह लेबल मौजूद होता है.

BUILD फ़ाइलों में अक्सर यह गलती की जाती है कि किसी पैकेज या पैकेज के सभी टारगेट का रेफ़रंस देने के लिए, //my/app का इस्तेमाल किया जाता है. हालांकि, ऐसा नहीं करना चाहिए. याद रखें कि यह //my/app:app के बराबर है. इसलिए, यह मौजूदा रिपॉज़िटरी के my/app पैकेज में app टारगेट का नाम बताता है.

हालांकि, package_group या .bzl फ़ाइलों में, पैकेज के बारे में बताने के लिए //my/app का इस्तेमाल करने की सलाह दी जाती है, क्योंकि इससे साफ़ तौर पर पता चलता है कि पैकेज का नाम बिलकुल सटीक है और फ़ाइल फ़ोल्डर की टॉप-लेवल डायरेक्ट्री में रूट किया गया है.

रिलेटिव लेबल का इस्तेमाल, दूसरे पैकेज में मौजूद टारगेट का रेफ़रंस देने के लिए नहीं किया जा सकता. इस मामले में, हमेशा रिपॉज़िटरी आइडेंटिफ़ायर और पैकेज का नाम बताना ज़रूरी है. उदाहरण के लिए, अगर सोर्स ट्री में पैकेज my/app और पैकेज my/app/testdata, दोनों मौजूद हैं (इन दोनों डायरेक्ट्री में अपनी BUILD फ़ाइल है), तो दूसरे पैकेज में testdepot.zip नाम की फ़ाइल मौजूद है. //my/app:BUILD में इस फ़ाइल को रेफ़र करने के दो तरीके (एक गलत, एक सही) यहां दिए गए हैं:

गलत — testdata एक अलग पैकेज है, इसलिए रिलेटिव पाथ का इस्तेमाल नहीं किया जा सकता

testdata/testdepot.zip

सही — testdata को उसके पूरे पाथ के साथ देखें

//my/app/testdata:testdepot.zip

@@// से शुरू होने वाले लेबल, डेटा स्टोर करने की मुख्य जगह के रेफ़रंस होते हैं. ये लेबल, डेटा स्टोर करने की बाहरी जगहों से भी काम करेंगे. इसलिए, किसी बाहरी रिपॉज़िटरी से रेफ़रंस लेने पर, @@//a/b/c, //a/b/c से अलग होता है. पहला यूआरएल, डेटा स्टोर करने की मुख्य जगह के बारे में बताता है. वहीं, बाद वाला वैरिएंट, एक्सटर्नल रिपॉज़िटरी में //a/b/c खोजता है. यह खास तौर पर तब ज़रूरी होता है, जब मुख्य रिपॉज़िटरी में ऐसे नियम लिखे जा रहे हों जो मुख्य रिपॉज़िटरी में मौजूद टारगेट का रेफ़रंस देते हों और जिनका इस्तेमाल बाहरी रिपॉज़िटरी से किया जाएगा.

टारगेट को रेफ़र करने के अलग-अलग तरीकों के बारे में जानने के लिए, टारगेट पैटर्न देखें.

लेबल के बारे में लेक्सिकल जानकारी

लेबल सिंटैक्स, उन मेटाकैरेक्टर का इस्तेमाल करने से बचने के लिए कहता है जिनका शेल के लिए खास मतलब होता है. इससे अनजाने में होने वाली कोटेशन की समस्याओं से बचने में मदद मिलती है. साथ ही, लेबल में हेर-फेर करने वाले टूल और स्क्रिप्ट बनाने में भी आसानी होती है, जैसे कि Baez क्वेरी लैंग्वेज.

टारगेट के लिए इस्तेमाल किए जा सकने वाले नामों के बारे में यहां पूरी जानकारी दी गई है.

टारगेट के नाम — package-name:target-name

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

टारगेट के नाम, a–z, A–Z, 0–9 सेट में मौजूद वर्णों और विराम चिह्नों !%-@^_"#$&'()*-+,;<=>?[]{|}~/. से ही बनाए जाने चाहिए.

फ़ाइल नाम, सामान्य रूप में मिलते-जुलते पाथनेम होने चाहिए. इसका मतलब है कि वे न तो स्लैश से शुरू होने चाहिए और न ही खत्म होने चाहिए (उदाहरण के लिए, /foo और foo/ अनुमति नहीं है) और न ही पाथ सेपरेटर के तौर पर लगातार कई स्लैश होने चाहिए (उदाहरण के लिए, foo//bar). इसी तरह, अप-लेवल के रेफ़रंस (..) और मौजूदा डायरेक्ट्री के रेफ़रंस (./) इस्तेमाल करने की भी अनुमति नहीं है.

गलत — अन्य पैकेज में मौजूद फ़ाइलों का रेफ़रंस देने के लिए, .. का इस्तेमाल न करें

सही — //package-name:filename का इस्तेमाल करें

हालांकि, फ़ाइल टारगेट के नाम में / का इस्तेमाल करना आम बात है, लेकिन नियमों के नाम में / का इस्तेमाल करने से बचें. खास तौर पर, जब किसी लेबल के शॉर्टहैंड फ़ॉर्म का इस्तेमाल किया जाता है, तो इससे रीडर को भ्रम हो सकता है. लेबल //foo/bar/wiz हमेशा //foo/bar/wiz:wiz के लिए कम शब्दों में लिखा गया होता है. भले ही, कोई ऐसा पैकेज foo/bar/wiz न हो. यह //foo:bar/wiz का रेफ़रंस कभी नहीं देता, भले ही वह टारगेट मौजूद हो.

हालांकि, कुछ मामलों में स्लैश का इस्तेमाल करना आसान होता है या कभी-कभी ज़रूरी भी होता है. उदाहरण के लिए, कुछ नियमों का नाम, उनकी मुख्य सोर्स फ़ाइल से मेल खाना चाहिए. यह फ़ाइल, पैकेज की सबडायरेक्ट्री में हो सकती है.

पैकेज के नाम — //package-name:target-name

किसी पैकेज का नाम, उस डायरेक्ट्री का नाम होता है जिसमें उसकी BUILD फ़ाइल मौजूद होती है. यह नाम, उस डायरेक्ट्री के टॉप-लेवल डायरेक्ट्री के हिसाब से होता है जिसमें पैकेज मौजूद होता है. उदाहरण के लिए: my/app.

तकनीकी लेवल पर, Bazel इन चीज़ों को लागू करता है:

• पैकेज के नाम में ये वर्ण इस्तेमाल किए जा सकते हैं: अंग्रेज़ी के छोटे अक्षर a से z, अंग्रेज़ी के बड़े अक्षर A से Z, अंक 0 से 9, वर्ण ! \"#$%&'()*+,-.;<=>?@[]^_`{|} (हां, इसमें स्पेस वर्ण भी है!), और फ़ॉरवर्ड स्लैश / (क्योंकि यह डायरेक्ट्री को अलग करने वाला वर्ण है).
• पैकेज के नाम, फ़ॉरवर्ड स्लैश कैरेक्टर / से शुरू या खत्म नहीं हो सकते.
• पैकेज के नाम में // सबस्ट्रिंग नहीं हो सकती. इससे कोई मतलब नहीं होगा---इससे जुड़ा डायरेक्ट्री पाथ क्या होगा?
• पैकेज के नामों में /./ या /../ या /.../ वगैरह शामिल नहीं हो सकता. नीति उल्लंघन ठीक करने के इस तरीके का इस्तेमाल, किसी लॉजिकल पैकेज के नाम और फ़िज़िकल डायरेक्ट्री के नाम के बीच अनुवाद करते समय, भ्रम की स्थिति से बचने के लिए किया जाता है. पाथ स्ट्रिंग में डॉट कैरेक्टर का सिमैंटिक मतलब दिया जाता है.

व्यावहारिक तौर पर:

• किसी ऐसी भाषा के लिए जिसका डायरेक्ट्री स्ट्रक्चर, उसके मॉड्यूल सिस्टम (जैसे, Java) के लिए अहम है, यह ज़रूरी है कि डायरेक्ट्री के ऐसे नाम चुने जाएं जो भाषा में मान्य आइडेंटिफ़ायर हों. उदाहरण के लिए, एट्रिब्यूट के नाम को अंकों से शुरू न करें. साथ ही, खास वर्णों, खास तौर पर अंडरस्कोर और हाइफ़न का इस्तेमाल न करें.
• Bazel, वर्कस्पेस के रूट पैकेज (उदाहरण के लिए, //:foo) में टारगेट के साथ काम करता है. हालांकि, उस पैकेज को खाली छोड़ना सबसे अच्छा होता है, ताकि सभी काम के पैकेज के नाम जानकारी देने वाले हों.

नियम

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

BUILD फ़ाइलें, नियम लागू करके टारगेट तय करती हैं.

नीचे दिए गए उदाहरण में, cc_binary नियम का इस्तेमाल करके टारगेट my_app के एलान को देखा जा सकता है.

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)

हर नियम के लागू होने पर, name एट्रिब्यूट का इस्तेमाल किया जाता है. यह एट्रिब्यूट, BUILD फ़ाइल के पैकेज में मौजूद टारगेट की जानकारी देता है. यह एट्रिब्यूट, टारगेट का मान्य नाम होना चाहिए.

हर नियम में एट्रिब्यूट का एक सेट होता है. किसी नियम पर लागू होने वाले एट्रिब्यूट और हर एट्रिब्यूट का महत्व और सिमैंटिक, नियम के हिसाब से ही होते हैं. नियमों और उनसे जुड़े एट्रिब्यूट की सूची देखने के लिए, बिल्ड एनसाइक्लोपीडिया देखें. हर एट्रिब्यूट का एक नाम और एक टाइप होता है. किसी एट्रिब्यूट के कुछ सामान्य टाइप ये हो सकते हैं: पूर्णांक, लेबल, लेबल की सूची, स्ट्रिंग, स्ट्रिंग की सूची, आउटपुट लेबल, आउटपुट लेबल की सूची. हर नियम में सभी एट्रिब्यूट के बारे में बताना ज़रूरी नहीं है. इस तरह, एट्रिब्यूट एक डिक्शनरी बनाते हैं, जिसमें कुंजियों (नामों) से लेकर वैकल्पिक, टाइप की गई वैल्यू तक शामिल होती हैं.

कई नियमों में मौजूद srcs एट्रिब्यूट का टाइप "लेबल की सूची" होता है. अगर इसकी वैल्यू मौजूद है, तो यह लेबल की सूची होती है. हर लेबल, इस नियम के इनपुट के तौर पर काम करने वाले टारगेट का नाम होता है.

कुछ मामलों में, नियम के टाइप का नाम कुछ हद तक मनमुताबिक होता है. साथ ही, नियम से जनरेट की गई फ़ाइलों के नाम ज़्यादा दिलचस्प होते हैं. यह बात genrules के लिए भी सही है. ज़्यादा जानकारी के लिए, सामान्य नियम: genन्या देखें.

अन्य मामलों में, नाम का ज़्यादा महत्व होता है: उदाहरण के लिए, *_binary और *_test नियमों के लिए, नियम के नाम से यह तय होता है कि बिल्ड से तैयार किए गए, रन किए जा सकने वाले प्रोग्राम का नाम क्या होगा.

टारगेट पर आधारित इस डायरेक्टेड ऐसाइक्लिक ग्राफ़ को टारगेट ग्राफ़ या बिल्ड डिपेंडेंसी ग्राफ़ कहा जाता है. यह वह डोमेन है जिस पर Bazel क्वेरी टूल काम करता है.