تفترض هذه الصفحة أنك على دراية ببازيل وتوفّر إرشادات ونصائح حول كيفية تنظيم مشاريعك للاستفادة الكاملة من ميزات بازيل.
إليك الأهداف الإجمالية:
- استخدام التبعيات الدقيقة للسماح بالتوازي والتزايد.
- للحفاظ على اعتمادية كاملة.
- لجعل الرمز منظمًا وقابلاً للاختبار.
- لإنشاء ضبط إصدار يمكن فهمه والحفاظ عليه بسهولة.
وهذه الإرشادات ليست متطلبات، لأنّه يمكن لبعض المشاريع التقيّد بها جميعًا. وكما يقول رجل في صفحة الوبر، "سيتم تقديم مكافأة خاصة لأول شخص ينتج برنامجًا حقيقيًا لا ينتج عن أي أخطاء في نظام "التحقّق الصارم". ويجب ألا يؤدّي تضمين أكبر عدد ممكن من هذه المبادئ إلى إنشاء المشروع بسهولة، وأقل عرضة للخطأ، وأسرع عملية الإنشاء.
تستخدم هذه الصفحة مستويات المتطلبات الموضحة في RFC هذا.
إصدارات واختبارات قيد التشغيل
يجب أن يتمكن المشروع دائمًا من تشغيل bazel build //... وbazel test //... في فرعه الثابت. يجب وضع علامات على الأهداف الضرورية ولكن لا يتم إنشاؤها في ظل ظروف معينة (مثل، تتطلب علامات إصدار محددة، ولا يتم إنشاؤها على نظام أساسي معين، تتطلب اتفاقيات ترخيص)
بشكل ممكن قدر الإمكان. على سبيل المثال، "requires-osx"). ويسمح وضع العلامات هذا بفلترة الأهداف على مستوى أكثر دقة من العلامة "اليدوية"، كما يسمح لشخص يفحص ملف BUILD بفهم القيود المفروضة على الهدف.
اعتماديات الجهات الخارجية
يمكنك الإعلان عن تبعيات الجهات الخارجية:
- ويمكنك تعريفها كمستودعات بعيدة في ملف
WORKSPACE. - أو يمكنك وضعها في دليل باسم
third_party/ضمن دليل مساحة العمل.
بناءً على البرامج الثنائية
يجب إنشاء كل شيء من المصدر كلما أمكن. يعني هذا بشكل عام أنّه عليك إنشاء ملف BUILD من some-library.so ومصادره استنادًا إلى المكتبة some-library.so. .
يضمن الإنشاء دائمًا من المصدر أن الإصدار لا يستخدم مكتبة تم إنشاؤها باستخدام علامات غير متوافقة أو بنية مختلفة. وهناك أيضًا بعض الميزات، مثل التغطية أو التحليل الثابت أو التحليل الديناميكي التي تعمل على المصدر فقط.
تحديد إصدارات
أفضّل إنشاء جميع الرموز من رأسك كلما أمكن. عندما يجب استخدام الإصدارات، تجنّب تضمين الإصدار في اسم الهدف (على سبيل المثال، //guava، وليس //guava-20.0). يساعد هذا التسمية في تسهيل تحديث المكتبة (يجب تحديث استهداف واحد فقط). تتميز هذه الأداة أيضًا بمرونة أكبر في ما يتعلّق باعتمادية المستوى المعيّن، وذلك إذا كانت إحدى المكتبات تعتمد على guava-19.0 وتعتمد واحدة على guava-20.0، قد ينتهي بك الأمر إلى مكتبة تحاول الاعتماد على إصدارين مختلفين.
إذا أنشأت عنوانًا بديلاً مضللاً لتوجيه كلا الموقعين المستهدفين إلى مكتبة واحدة على guava،
فستكون ملفات BUILD مضللة.
استخدام ملف .bazelrc
للحصول على خيارات خاصة بالمشاريع، يمكنك استخدام ملف الإعداد
workspace/.bazelrc (راجِع تنسيق بازيلرك).
إذا كنت تريد دعم خيارات لكل مستخدم لمشروعك، يجب تضمين السطر التالي:
try-import %workspace%/user.bazelrc
(أو أي اسم ملف آخر) في workspace/.bazelrc
وإضافة user.bazelrc إلى .gitignore.
الحِزم
يجب أن يكون كل دليل يحتوي على ملفات قابلة للإنشاء عبارة عن حزمة. إذا كان الملف BUILD
يشير إلى ملفات في الأدلة الفرعية (مثل، srcs = ["a/b/C.java"])،
فإنه علامة تفيد بإضافة ملف BUILD إلى هذا الدليل الفرعي. وكلّما طالت هذه البنية، زاد احتمال حدوث تبعيات دائرية بشكل غير مقصود، وسيزحف إلى نطاق الاستهداف، وبالتالي يجب تعديل عدد من التبعيات العكسية.