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