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