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

इस पेज पर यह मान लिया गया है कि आपको 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 और user.bazelrc को .gitignore में जोड़ें.

ओपन-सोर्स bazelrc-preset.bzl{: .external} आपके Bazel वर्शन से मेल खाने वाली कस्टम bazelrc फ़ाइल जनरेट करता है. साथ ही, सुझाए गए फ़्लैग का प्रीसेट उपलब्ध कराता है.

पैकेज

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