فایل ها را بسازید

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

طبق تعریف، هر بسته حاوی یک فایل BUILD است که یک برنامه کوتاه است. فایل های BUILD با استفاده از زبان امری، Starlark ارزیابی می شوند.

آنها به عنوان یک لیست متوالی از عبارات تفسیر می شوند.

به طور کلی، نظم مهم است: برای مثال، متغیرها باید قبل از استفاده تعریف شوند. با این حال، اکثر فایل‌های BUILD فقط از اعلان‌های قوانین ساخت تشکیل شده‌اند، و ترتیب نسبی این عبارات بی‌اهمیت است. تنها چیزی که اهمیت دارد این است که تا زمان تکمیل ارزیابی بسته، کدام قوانین و با چه مقادیری اعلام شده است.

هنگامی که یک تابع قانون ساخت، مانند cc_library ، اجرا می شود، یک هدف جدید در نمودار ایجاد می کند. این هدف را می توان بعداً با استفاده از یک برچسب ارجاع داد.

در فایل‌های ساده BUILD ، اعلان‌های قوانین می‌توانند آزادانه و بدون تغییر رفتار دوباره مرتب شوند.

برای تشویق جداسازی پاک بین کد و داده، فایل‌های BUILD نمی‌توانند شامل تعاریف تابع، for عبارات یا عبارات if (اما درک لیست و if عبارات مجاز هستند). به جای آن، توابع را می توان در فایل های .bzl . اعلام کرد. علاوه بر این، آرگومان های *args و **kwargs در فایل های BUILD مجاز نیستند. در عوض تمام آرگومان ها را به صراحت فهرست کنید.

مهم این است که برنامه ها در Starlark نمی توانند ورودی/خروجی دلخواه را انجام دهند. این تغییر ناپذیر، تفسیر فایل‌های BUILD را هرمتیک می‌کند - تنها به مجموعه‌ای از ورودی‌های شناخته شده وابسته است، که برای اطمینان از تکرارپذیری ساخت‌ها ضروری است. برای جزئیات بیشتر، Hermeticity را ببینید.

فایل های BUILD باید فقط با استفاده از کاراکترهای ASCII نوشته شوند، اگرچه از نظر فنی با استفاده از مجموعه کاراکترهای Latin-1 تفسیر می شوند.

از آنجایی که فایل‌های BUILD باید هر زمان که وابستگی‌های کد اصلی تغییر می‌کند، به‌روزرسانی شوند، معمولاً توسط چندین نفر در یک تیم نگهداری می‌شوند. نویسندگان فایل BUILD باید برای مستندسازی نقش هر هدف ساخت، خواه برای استفاده عمومی در نظر گرفته شده باشد یا نه، و برای مستندسازی نقش خود بسته، نظر آزادانه ارائه دهند.

در حال بارگیری یک برنامه افزودنی

پسوندهای Bazel فایل هایی هستند که به .bzl می شوند. از عبارت load برای وارد کردن نماد از یک برنامه افزودنی استفاده کنید.

load("//foo/bar:file.bzl", "some_library")

این کد فایل foo/bar/file.bzl را بارگیری می کند و نماد some_library را به محیط اضافه می کند. این می تواند برای بارگذاری قوانین، توابع یا ثابت های جدید (مثلاً یک رشته یا یک لیست) استفاده شود. نمادهای متعدد را می توان با استفاده از آرگومان های اضافی به فراخوانی برای load وارد کرد. آرگومان‌ها باید رشته‌ای باشند (بدون متغیر) و عبارات load باید در سطح بالا ظاهر شوند - آنها نمی‌توانند در یک بدنه تابع باشند.

اولین آرگومان load ، برچسبی است که فایل .bzl . را مشخص می کند. اگر یک برچسب نسبی باشد، با توجه به بسته (نه دایرکتوری) حاوی فایل bzl فعلی حل می شود. برچسب‌های نسبی در بیانیه‌های load باید از علامت اصلی استفاده کنند :

load همچنین از نام مستعار پشتیبانی می کند، بنابراین، می توانید نام های مختلفی را به نمادهای وارد شده اختصاص دهید.

load("//foo/bar:file.bzl", library_alias = "some_library")

شما می توانید چند نام مستعار را در یک دستور load تعریف کنید. علاوه بر این، لیست آرگومان می تواند هم نام مستعار و هم نام نمادهای معمولی را داشته باشد. مثال زیر کاملا قانونی است (لطفاً توجه داشته باشید که چه زمانی از علامت نقل قول استفاده کنید).

load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")

در یک فایل .bzl . نمادهایی که با _ شروع می شوند صادر نمی شوند و نمی توانند از فایل دیگری بارگیری شوند.

می‌توانید از قابلیت مشاهده بار برای محدود کردن افرادی که ممکن است فایل .bzl . را بارگیری کنند استفاده کنید.

انواع قوانین ساخت

اکثر قوانین ساخت در خانواده ها آمده و بر اساس زبان گروه بندی شده اند. به عنوان مثال، cc_binary ، cc_library و cc_test به ترتیب قوانین ساخت برای باینری ها، کتابخانه ها و تست های C++ هستند. زبان‌های دیگر از طرح نام‌گذاری یکسانی با پیشوند متفاوتی مانند java_* برای جاوا استفاده می‌کنند. برخی از این توابع در دایره المعارف ساخت مستند شده اند، اما برای هر کسی امکان ایجاد قوانین جدید وجود دارد.

• *_binary برنامه های اجرایی را در یک زبان مشخص می سازد. پس از ساخت، فایل اجرایی در درخت خروجی باینری ابزار ساخت در نام مربوطه برای برچسب قانون قرار می گیرد، بنابراین //my:program در (مثلا) $(BINDIR)/my/program ظاهر می شود.

  در برخی از زبان‌ها، چنین قوانینی همچنین یک فهرست راهنما ایجاد می‌کنند که حاوی تمام فایل‌های ذکر شده در یک ویژگی data متعلق به قانون، یا هر قاعده‌ای در بسته شدن گذرا از وابستگی‌ها است. این مجموعه فایل ها برای سهولت در استقرار در تولید در یک مکان جمع آوری شده اند.

• *_test تخصصی از یک قانون *_binary است که برای تست خودکار استفاده می شود. تست ها به سادگی برنامه هایی هستند که موفقیت آنها صفر است.

  مانند باینری‌ها، تست‌ها نیز دارای درخت‌های runfiles هستند و فایل‌های زیر آن تنها فایل‌هایی هستند که آزمایش ممکن است به طور قانونی در زمان اجرا باز شود. برای مثال، یک برنامه cc_test(name='x', data=['//foo:bar']) ممکن است باز شود و در حین اجرا، $TEST_SRCDIR/workspace/foo/bar را بخواند. (هر زبان برنامه نویسی تابع کاربردی خاص خود را برای دسترسی به مقدار $TEST_SRCDIR دارد، اما همه آنها معادل استفاده مستقیم از متغیر محیطی هستند.) عدم رعایت این قانون باعث می شود که تست زمانی که روی یک میزبان تست از راه دور اجرا شود با شکست مواجه شود. .

• *_library ماژول های کامپایل شده جداگانه را در زبان برنامه نویسی داده شده مشخص می کند. کتابخانه‌ها می‌توانند به کتابخانه‌های دیگر وابسته باشند، و باینری‌ها و آزمایش‌ها می‌توانند به کتابخانه‌ها، با رفتار کامپایل جداگانه مورد انتظار، وابسته باشند.