सबसे अच्छे तरीके

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

कुल लक्ष्य ये हैं:

• समानता और बढ़ोतरी के लिए, सटीक डिपेंडेंसी का इस्तेमाल करना.
• डिपेंडेंसी को अच्छी तरह से कवर करने के लिए.
• कोड को अच्छी तरह से स्ट्रक्चर करने और टेस्ट करने लायक बनाने के लिए.
• ऐसा बिल्ड कॉन्फ़िगरेशन बनाने के लिए जिसे समझना और मैनेज करना आसान हो.

ये दिशा-निर्देश ज़रूरी शर्तों के मुताबिक नहीं हैं: कुछ ही प्रोजेक्ट, इन सभी का पालन कर पाएंगे. जैसा कि लिंट के लिए मैन पेज ने कहा है, "पहले व्यक्ति को एक विशेष इनाम दिया जाएगा, जो एक ऐसा असली प्रोग्राम बनाएगा, जिससे सही जाँच करने में कोई गड़बड़ी न हो." हालांकि, इनमें से ज़्यादा से ज़्यादा सिद्धांतों को शामिल करने से, किसी प्रोजेक्ट को बेहतर तरीके से पढ़ा जा सकता है, गड़बड़ी की संभावना कम होती है, और वह तेज़ी से बनता है.

इस पेज पर, इस आरएफ़सी में बताई गई ज़रूरी शर्तों के लेवल का इस्तेमाल किया जाता है.

बिल्ड और टेस्ट चलाना

कोई प्रोजेक्ट ऐसा होना चाहिए जो हमेशा bazel build //... और bazel test //... को उसकी स्थिर ब्रांच पर चला सके. ज़रूरी होने के बावजूद, कुछ मामलों में बने नहीं रहने वाले टारगेट (जैसे, किसी खास बिल्ड फ़्लैग की ज़रूरत होती है, किसी खास प्लैटफ़ॉर्म पर नहीं बनते, लाइसेंस समझौते की ज़रूरत होती है) को जितना हो सके उतना सटीक तरीके से टैग किया जाना चाहिए. उदाहरण के लिए, "requires-osx". इस टैगिंग की मदद से, टारगेट को "मैन्युअल" टैग के मुकाबले ज़्यादा बेहतर तरीके से फ़िल्टर किया जा सकता है. साथ ही, BUILD फ़ाइल की जांच करने वाले व्यक्ति को यह समझने में मदद मिलती है कि टारगेट की पाबंदियां क्या हैं.

तीसरे पक्ष की डिपेंडेंसी

तीसरे पक्ष की डिपेंडेंसी का एलान इन तरीकों से किया जा सकता है:

• इसके लिए, WORKSPACE फ़ाइल में उन्हें रिमोट रिपॉज़िटरी के तौर पर दिखाएं.
• इसके अलावा, उन्हें अपने वर्कस्पेस डायरेक्ट्री में third_party/ नाम की डायरेक्ट्री में भी रखा जा सकता है.

बाइनरी के आधार पर

जब भी हो सके, सब कुछ सोर्स से बनाया जाना चाहिए. आम तौर पर, इसका मतलब यह है कि किसी लाइब्रेरी some-library.so पर निर्भर रहने के बजाय, आपको BUILD फ़ाइल बनानी होगी और उसके सोर्स से some-library.so बनाना होगा. इसके बाद, उस टारगेट पर निर्भर रहना होगा.

हमेशा सोर्स से बनाने से यह पक्का होता है कि बिल्ड किसी ऐसी लाइब्रेरी का इस्तेमाल नहीं कर रहा है जिसे काम न करने वाले फ़्लैग या अलग आर्किटेक्चर के साथ बनाया गया हो. इनके अलावा, कवरेज, स्टैटिक विश्लेषण या डाइनैमिक विश्लेषण जैसी कुछ सुविधाएं भी सिर्फ़ सोर्स पर काम करती हैं.

वर्शन

जब भी हो सके, हेड से सभी कोड बनाना पसंद करें. जब वर्शन का इस्तेमाल करना हो, तो टारगेट के नाम में वर्शन शामिल न करें (उदाहरण के लिए, //guava, //guava-20.0 नहीं). इस नाम से लाइब्रेरी को अपडेट करना आसान हो जाता है (सिर्फ़ एक टारगेट को अपडेट करने की ज़रूरत होती है). इससे डायमंड डिपेंडेंसी से जुड़ी समस्याओं से भी बचा जा सकता है: अगर एक लाइब्रेरी guava-19.0 और दूसरी guava-20.0 पर निर्भर है, तो हो सकता है कि आपके पास ऐसी लाइब्रेरी हो जो दो अलग-अलग वर्शन पर निर्भर हो. अगर आपने दोनों टारगेट को एक guava लाइब्रेरी पर ले जाने के लिए, गुमराह करने वाला कोई उपनाम बनाया है, तो BUILD फ़ाइलें गुमराह करने वाली हैं.

.bazelrc फ़ाइल का इस्तेमाल करना

प्रोजेक्ट से जुड़े विकल्पों के लिए, अपने workspace/.bazelrc कॉन्फ़िगरेशन फ़ाइल का इस्तेमाल करें. इसके लिए, bazzrc फ़ॉर्मैट देखें.

अगर आपको अपने प्रोजेक्ट के लिए हर उपयोगकर्ता के हिसाब से, ऐसे विकल्पों का इस्तेमाल करने की सुविधा देनी है जिन्हें सोर्स कंट्रोल में शामिल नहीं करना है, तो यह लाइन शामिल करें:

try-import %workspace%/user.bazelrc

अपने workspace/.bazelrc में (या किसी दूसरे फ़ाइल नाम) और user.bazelrc को अपने .gitignore में जोड़ें.

पैकेज

जिस डायरेक्ट्री में ऐसी फ़ाइलें हों जिन्हें बिल्ड किया जा सकता है वह एक पैकेज होनी चाहिए. अगर कोई BUILD फ़ाइल, सबडायरेक्ट्री (जैसे, srcs = ["a/b/C.java"]) में मौजूद फ़ाइलों को रेफ़र करती है, तो इसका मतलब है कि उस सबडायरेक्ट्री में BUILD फ़ाइल जोड़ी जानी चाहिए. यह स्ट्रक्चर जितना लंबा होगा, इस बात की संभावना उतनी ही ज़्यादा होगी कि अनजाने में सर्कुलर डिपेंडेंसी हो जाएगी. साथ ही, टारगेट का स्कोप कम होगा और रिवर्स डिपेंडेंसी की बढ़ती हुई संख्या को अपडेट करना होगा.