इस पेज पर यह मान लिया गया है कि आपको Bazel के बारे में जानकारी है. इसमें Bazel की सुविधाओं का पूरा फ़ायदा पाने के लिए, अपने प्रोजेक्ट को स्ट्रक्चर करने के बारे में दिशा-निर्देश और सलाह दी गई है.
कुल मिलाकर ये लक्ष्य हैं:
- पैरललिज़्म और इंक्रीमेंटैलिटी की अनुमति देने के लिए, फ़ाइन-ग्रेन्ड डिपेंडेंसी का इस्तेमाल करना.
- डिपेंडेंसी को अच्छी तरह से इनकैप्सुलेट करने के लिए.
- कोड को अच्छी तरह से स्ट्रक्चर करने और उसकी जांच करने के लिए.
- ऐसी बिल्ड कॉन्फ़िगरेशन बनाना जिसे समझना और बनाए रखना आसान हो.
ये दिशा-निर्देश ज़रूरी शर्तें नहीं हैं: कुछ प्रोजेक्ट ही इन सभी का पालन कर पाएंगे. lint के मैन पेज के मुताबिक, "सख्ती से जांच करने पर, ऐसा असली प्रोग्राम बनाने वाले पहले व्यक्ति को खास इनाम दिया जाएगा जिसमें कोई गड़बड़ी नहीं होगी." हालांकि, इन सिद्धांतों में से ज़्यादा से ज़्यादा को शामिल करने से, प्रोजेक्ट को ज़्यादा आसानी से पढ़ा जा सकेगा, उसमें गड़बड़ियां कम होंगी, और उसे तेज़ी से बनाया जा सकेगा.
इस पेज पर, इस RFC में बताए गए ज़रूरी लेवल का इस्तेमाल किया जाता है.
बिल्ड और टेस्ट चलाना
किसी प्रोजेक्ट को हमेशा अपनी स्टेबल ब्रांच पर bazel build //... और bazel test //... को सही तरीके से चलाने में सक्षम होना चाहिए. जिन टारगेट को टैग करना ज़रूरी है, लेकिन कुछ मामलों में उन्हें टैग नहीं किया जा सकता (जैसे, खास बिल्ड फ़्लैग की ज़रूरत होना, किसी प्लैटफ़ॉर्म पर बिल्ड न होना, लाइसेंस समझौते की ज़रूरत होना) उन्हें ज़्यादा से ज़्यादा खास तौर पर टैग किया जाना चाहिए (उदाहरण के लिए, "requires-osx"). इस टैगिंग से, टारगेट को "मैन्युअल" टैग की तुलना में ज़्यादा बारीकी से फ़िल्टर किया जा सकता है. साथ ही, BUILD फ़ाइल की जांच करने वाला व्यक्ति यह समझ सकता है कि किसी टारगेट पर कौनसी पाबंदियां लागू हैं.
तीसरे पक्ष की डिपेंडेंसी
तीसरे पक्ष की डिपेंडेंसी के बारे में यह जानकारी दी जा सकती है:
MODULE.bazelफ़ाइल में उन्हें रिमोट रिपॉज़िटरी के तौर पर एलान करें.- इसके अलावा, उन्हें अपने वर्कस्पेस डायरेक्ट्री में मौजूद
third_party/नाम की डायरेक्ट्री में भी रखा जा सकता है.
बाइनरी पर निर्भर करता है
जब भी मुमकिन हो, हर चीज़ को सोर्स से बनाया जाना चाहिए. आम तौर पर, इसका मतलब यह है कि लाइब्रेरी some-library.so पर निर्भर रहने के बजाय, आपको BUILD फ़ाइल बनानी होगी और उसके सोर्स से some-library.so बनाना होगा. इसके बाद, उस टारगेट पर निर्भर रहना होगा.
सोर्स से हमेशा बिल्ड करने से यह पक्का होता है कि बिल्ड ऐसी लाइब्रेरी का इस्तेमाल नहीं कर रहा है जिसे ऐसे फ़्लैग या अलग आर्किटेक्चर के साथ बनाया गया था जो काम नहीं करते. कवरेज, स्टैटिक विश्लेषण या डाइनैमिक विश्लेषण जैसी कुछ सुविधाएं भी हैं. ये सिर्फ़ सोर्स पर काम करती हैं.
वर्शन
जब भी मुमकिन हो, हेड से पूरा कोड बनाएं. जब वर्शन इस्तेमाल करने हों, तो टारगेट के नाम में वर्शन शामिल न करें. उदाहरण के लिए, //guava, //guava-20.0 नहीं. इस तरह से नाम रखने पर, लाइब्रेरी को अपडेट करना आसान हो जाता है. इसके लिए, सिर्फ़ एक टारगेट को अपडेट करना होता है. यह डायमंड डिपेंडेंसी की समस्याओं से भी ज़्यादा सुरक्षित है: अगर कोई लाइब्रेरी guava-19.0 पर निर्भर करती है और कोई लाइब्रेरी guava-20.0 पर निर्भर करती है, तो आपके पास ऐसी लाइब्रेरी हो सकती है जो दो अलग-अलग वर्शन पर निर्भर करती है.
अगर आपने दोनों टारगेट को एक guava लाइब्रेरी पर ले जाने के लिए, गुमराह करने वाला कोई एलियास बनाया है, तो BUILD फ़ाइलें गुमराह करने वाली हैं.
.bazelrc फ़ाइल का इस्तेमाल करना
प्रोजेक्ट के हिसाब से विकल्पों के लिए, अपनी workspace/.bazelrc कॉन्फ़िगरेशन फ़ाइल का इस्तेमाल करें (bazelrc फ़ॉर्मैट देखें).
अगर आपको अपने प्रोजेक्ट के लिए, हर उपयोगकर्ता के हिसाब से विकल्प उपलब्ध कराने हैं और आपको सोर्स कंट्रोल में उनकी जांच नहीं करनी है, तो यह लाइन शामिल करें:
try-import %workspace%/user.bazelrc
(या कोई अन्य फ़ाइल का नाम) में जोड़ें और .gitignore में user.bazelrc जोड़ें.workspace/.bazelrc
ओपन-सोर्स bazelrc-preset.bzl{: .external} आपकी Bazel के वर्शन से मेल खाने वाली कस्टम bazelrc फ़ाइल जनरेट करता है. साथ ही, सुझाए गए फ़्लैग का प्रीसेट उपलब्ध कराता है.
पैकेज
हर डायरेक्ट्री जिसमें बनाई जा सकने वाली फ़ाइलें मौजूद हैं, वह एक पैकेज होना चाहिए. अगर कोई BUILD फ़ाइल, सबडायरेक्ट्री में मौजूद फ़ाइलों (जैसे कि srcs = ["a/b/C.java"]) के बारे में बताती है, तो इसका मतलब है कि उस सबडायरेक्ट्री में BUILD फ़ाइल को जोड़ा जाना चाहिए. यह स्ट्रक्चर जितना पुराना होगा, उतनी ही ज़्यादा संभावना होगी कि गलती से साइक्लिक डिपेंडेंसी बन जाएंगी. साथ ही, टारगेट का स्कोप बढ़ता जाएगा और रिवर्स डिपेंडेंसी की बढ़ती संख्या को अपडेट करना होगा.