بهترین شیوه ها

این صفحه فرض می کند که شما با Bazel آشنا هستید و دستورالعمل ها و توصیه هایی در مورد ساختار پروژه های خود برای استفاده کامل از ویژگی های Bazel ارائه می دهد.

اهداف کلی عبارتند از:

• استفاده از وابستگی های ریز دانه برای اجازه موازی سازی و افزایش.
• برای اینکه وابستگی ها به خوبی محصور شوند.
• برای اینکه کد به خوبی ساختار یافته و قابل آزمایش باشد.
• برای ایجاد یک پیکربندی ساخت که به راحتی قابل درک و نگهداری باشد.

این دستورالعمل ها الزامی نیستند: پروژه های کمی قادر به رعایت همه آنها خواهند بود. همانطور که صفحه man for lint می گوید، "به اولین فردی که یک برنامه واقعی تولید می کند که با بررسی دقیق هیچ خطایی تولید نمی کند، جایزه ویژه ای ارائه می شود." با این حال، گنجاندن تا حد امکان از این اصول باید یک پروژه را خواناتر، کمتر مستعد خطا و سریع‌تر ساختن کند.

این صفحه از سطوح مورد نیاز شرح داده شده در این RFC استفاده می کند.

اجرای ساخت و تست

یک پروژه باید همیشه بتواند bazel build //... و bazel test //... را با موفقیت روی شاخه پایدار خود اجرا کند. اهدافی که ضروری هستند اما تحت شرایط خاصی ساخته نمی‌شوند (مانند نیاز به پرچم‌های ساخت خاص، عدم ساختن بر روی یک پلت فرم خاص، نیاز به موافقت‌نامه‌های مجوز) باید تا حد امکان به‌طور خاص برچسب‌گذاری شوند (مثلاً " requires-osx ") . این برچسب گذاری به اهداف اجازه می دهد تا در سطح دقیق تری نسبت به برچسب "دستی" فیلتر شوند و به شخصی که فایل BUILD را بررسی می کند اجازه می دهد تا بفهمد محدودیت های یک هدف چیست.

وابستگی های شخص ثالث

می توانید وابستگی های شخص ثالث را اعلام کنید:

• یا آنها را به عنوان مخازن راه دور در فایل WORKSPACE اعلام کنید.
• یا آنها را در دایرکتوری به نام third_party/ در زیر پوشه فضای کاری خود قرار دهید.

بسته به باینری ها

همه چیز باید در صورت امکان از منبع ساخته شود. به طور کلی این بدان معنی است که به جای وابستگی به یک کتابخانه some-library.so ، یک فایل BUILD ایجاد کرده و some-library.so را از منابع آن بسازید، سپس به آن هدف وابسته باشید.

ساختن همیشه از منبع تضمین می کند که یک ساختمان از کتابخانه ای استفاده نمی کند که با پرچم های ناسازگار یا معماری متفاوت ساخته شده است. همچنین برخی از ویژگی ها مانند پوشش، تجزیه و تحلیل استاتیک یا تجزیه و تحلیل پویا وجود دارد که فقط روی منبع کار می کند.

نسخه سازی

هر زمان که ممکن است، ساخت همه کدها را از head ترجیح دهید. وقتی باید از نسخه‌ها استفاده شود، از قرار دادن نسخه در نام هدف خودداری کنید (به عنوان مثال //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 . خود اضافه کنید.

بسته ها

هر دایرکتوری که حاوی فایل های قابل ساخت است باید یک بسته باشد. اگر یک فایل BUILD به فایل‌های زیر شاخه‌ها (مانند srcs = ["a/b/C.java"] اشاره دارد، نشانه آن است که یک فایل BUILD باید به آن زیر شاخه اضافه شود. هر چه این ساختار طولانی‌تر باشد، احتمال ایجاد وابستگی‌های دایره‌ای به طور ناخواسته بیشتر می‌شود، دامنه هدف خزش می‌کند، و تعداد فزاینده‌ای از وابستگی‌های معکوس باید به‌روزرسانی شوند.