इस पेज पर यह माना गया है कि आपको Bazel के बारे में पता है. साथ ही, इसमें Bazel की सुविधाओं का पूरा फ़ायदा पाने के लिए, अपने प्रोजेक्ट को व्यवस्थित करने के दिशा-निर्देश और सलाह दी गई है.
कुल लक्ष्य ये हैं:
- पैरलल प्रोसेसिंग और इंक्रीमेंटल प्रोसेसिंग की अनुमति देने के लिए, बेहतर तरीके से डिपेंडेंसी का इस्तेमाल करने के लिए.
- डिपेंडेंसी को अच्छी तरह से कवर करने के लिए.
- कोड को बेहतर तरीके से व्यवस्थित करने और उसकी जांच करने के लिए.
- ऐसा बिल्ड कॉन्फ़िगरेशन बनाने के लिए जिसे समझना और मैनेज करना आसान हो.
ये दिशा-निर्देश ज़रूरी शर्तें नहीं हैं: कुछ ही प्रोजेक्ट इन सभी दिशा-निर्देशों का पालन कर पाएंगे. lint के मैन पेज के मुताबिक, "कड़ी जांच के बाद भी कोई गड़बड़ी न दिखाने वाला पहला प्रोग्राम बनाने वाले व्यक्ति को एक खास इनाम दिया जाएगा." हालांकि, इनमें से ज़्यादा से ज़्यादा सिद्धांतों को शामिल करने से, प्रोजेक्ट को पढ़ना आसान हो जाता है. साथ ही, प्रोजेक्ट में गड़बड़ियां कम होती हैं और उसे तेज़ी से बनाया जा सकता है.
इस पेज पर, इस आरएफ़सी में बताई गई ज़रूरी शर्तों के लेवल का इस्तेमाल किया जाता है.
बिल्ड और टेस्ट चलाना
किसी प्रोजेक्ट को हमेशा अपनी स्टेबल शाखा पर, 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
पैकेज
जिस डायरेक्ट्री में ऐसी फ़ाइलें हों जिन्हें बिल्ड किया जा सकता है वह एक पैकेज होनी चाहिए. अगर कोई BUILD फ़ाइल, सबडायरेक्ट्री (जैसे, srcs = ["a/b/C.java"]) में मौजूद फ़ाइलों को रेफ़र करती है, तो इसका मतलब है कि उस सबडायरेक्ट्री में BUILD फ़ाइल को जोड़ा जाना चाहिए. यह स्ट्रक्चर जितना ज़्यादा समय तक मौजूद रहेगा, अनजाने में सर्कुलर डिपेंडेंसी बनने की संभावना उतनी ही ज़्यादा होगी. साथ ही, टारगेट का दायरा बढ़ेगा और ज़्यादा से ज़्यादा रिवर्स डिपेंडेंसी को अपडेट करना पड़ेगा.