यह पेज मान लेता है कि आपको Basel की जानकारी है. साथ ही, यह आपको Basel की सुविधाओं का पूरा फ़ायदा लेने के लिए, अपने प्रोजेक्ट को व्यवस्थित करने के दिशा-निर्देश और सलाह भी देता है.
कुल लक्ष्य ये हैं:
- समानता और बढ़ोतरी के लिए, सटीक डिपेंडेंसी का इस्तेमाल करना.
- डिपेंडेंसी को अच्छी तरह से इनकैप्सुलेट करने के लिए.
- कोड को अच्छी तरह से स्ट्रक्चर करने और टेस्ट करने लायक बनाने के लिए.
- ऐसा बिल्ड कॉन्फ़िगरेशन बनाने के लिए जो समझने और बनाए रखने में आसान हो.
ये दिशा-निर्देश ज़रूरी शर्तों के मुताबिक नहीं हैं: कुछ ही प्रोजेक्ट, इन सभी का पालन कर पाएंगे. जैसा कि लिंट के लिए मैन पेज ने कहा है, "पहले व्यक्ति को एक विशेष इनाम दिया जाएगा, जो एक ऐसा असली प्रोग्राम बनाएगा, जिससे सही जाँच करने में कोई गड़बड़ी न हो." हालांकि, इनमें से ज़्यादा से ज़्यादा सिद्धांतों को शामिल करने से, किसी प्रोजेक्ट को बेहतर तरीके से पढ़ा जा सकता है, गड़बड़ी की संभावना कम होती है, और वह तेज़ी से बनता है.
इस पेज पर, इस आरएफ़सी में बताए गए ज़रूरी लेवल का इस्तेमाल किया जाता है.
बिल्ड और टेस्ट चलाना
कोई प्रोजेक्ट ऐसा होना चाहिए जो हमेशा 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 फ़ाइल को जोड़ा जाना चाहिए. यह स्ट्रक्चर जितना लंबा होगा, इस बात की संभावना उतनी ही ज़्यादा होगी कि अनजाने में सर्कुलर डिपेंडेंसी हो जाएगी. साथ ही, टारगेट का स्कोप कम होगा और रिवर्स डिपेंडेंसी की बढ़ती हुई संख्या को अपडेट करना होगा.