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