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

इस पेज पर यह मान लिया गया है कि आपको 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

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

पैकेज

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