فایل های پیکربندی bazelrc را بنویسید

بازل گزینه های زیادی را می پذیرد. برخی از گزینه‌ها اغلب تغییر می‌کنند (مثلاً --subcommands ) در حالی که برخی دیگر در چندین بیلد یکسان می‌مانند (مانند --package_path ). برای جلوگیری از تعیین این گزینه های بدون تغییر برای هر ساخت (و سایر دستورات)، می توانید گزینه هایی را در یک فایل پیکربندی به نام .bazelrc کنید.

فایل های .bazelrc کجا هستند؟

Bazel به دنبال فایل های پیکربندی اختیاری در مکان های زیر، به ترتیب نشان داده شده در زیر است. گزینه‌ها به این ترتیب تفسیر می‌شوند، بنابراین گزینه‌های موجود در فایل‌های بعدی می‌توانند در صورت بروز تضاد، مقداری از فایل قبلی را لغو کنند. تمام گزینه‌هایی که کنترل می‌کنند کدام یک از این فایل‌ها لود می‌شوند، گزینه‌های راه‌اندازی هستند، به این معنی که باید بعد از bazel و قبل از دستور ( build ، test و غیره) رخ دهند.

  1. فایل RC سیستم ، مگر اینکه --nosystem_rc موجود باشد.

    مسیر:

    • در Linux/macOS/Unixes: /etc/bazel.bazelrc
    • در ویندوز: %ProgramData%\bazel.bazelrc

    اگر این فایل وجود نداشته باشد، خطا نیست.

    اگر مکان مشخص دیگری از سیستم مورد نیاز است، باید یک باینری Bazel سفارشی بسازید، که مقدار BAZEL_SYSTEM_BAZELRC_PATH در //src/main/cpp:option_processor کند. مکان مشخص شده توسط سیستم ممکن است حاوی ارجاعات متغیر محیطی باشد، مانند ${VAR_NAME} در Unix یا %VAR_NAME% در Windows.

  2. فایل RC فضای کاری ، مگر اینکه --noworkspace_rc وجود داشته باشد.

    مسیر: .bazelrc در فهرست فضای کاری شما (در کنار فایل WORKSPACE اصلی).

    اگر این فایل وجود نداشته باشد، خطا نیست.

  3. فایل RC خانگی ، مگر اینکه --nohome_rc موجود باشد.

    مسیر:

    • در Linux/macOS/Unixes: $HOME/.bazelrc
    • در ویندوز: %USERPROFILE%\.bazelrc در صورت وجود، یا %HOME%/.bazelrc

    اگر این فایل وجود نداشته باشد، خطا نیست.

  4. فایل RC مشخص شده توسط کاربر ، اگر با --bazelrc= file مشخص شده باشد

    این پرچم اختیاری است اما می تواند چندین بار نیز مشخص شود.

    /dev/null نشان می دهد که تمام --bazelrc های بعدی نادیده گرفته می شوند، که برای غیرفعال کردن جستجوی فایل rc کاربر، مانند نسخه های انتشار مفید است.

    مثلا:

    --bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
    • x.rc و y.rc خوانده می شوند.
    • z.rc به دلیل /dev/null قبلی نادیده گرفته می شود.

علاوه بر این فایل پیکربندی اختیاری، Bazel به دنبال یک فایل rc جهانی است. برای جزئیات بیشتر، بخش bazelrc جهانی را ببینید.

.bazelrc نحو و معناشناسی

مانند همه فایل‌های "rc" یونیکس، فایل .bazelrc . یک فایل متنی با دستور زبان مبتنی بر خط است. خطوط خالی و خطوطی که با # شروع می شوند (نظرات) نادیده گرفته می شوند. هر خط حاوی یک دنباله از کلمات است که مطابق با قوانین پوسته Bourne نشانه گذاری می شوند.

واردات

خطوطی که با import یا try-import شروع می شوند خاص هستند: از آنها برای بارگیری سایر فایل های "rc" استفاده کنید. برای تعیین مسیری که نسبت به ریشه فضای کاری است، import %workspace%/path/to/bazelrc .

تفاوت بین import و try-import در این است که Bazel اگر فایل import 'ed گم شده باشد (یا قابل خواندن نباشد) با شکست مواجه می شود، اما برای یک فایل try-import 'ed اینطور نیست.

اولویت واردات:

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

گزینه های پیش فرض

اکثر خطوط یک bazelrc مقادیر گزینه پیش فرض را تعریف می کنند. اولین کلمه در هر خط مشخص می کند که این پیش فرض ها چه زمانی اعمال می شوند:

  • startup : گزینه های راه اندازی، که قبل از دستور قرار می گیرند و در bazel help startup_options توضیح داده شده اند.
  • common : گزینه هایی که برای همه دستورات Bazel اعمال می شوند.
  • command : دستور Bazel، مانند build یا query که گزینه ها برای آن اعمال می شود. این گزینه ها همچنین برای تمام دستوراتی که از دستور مشخص شده ارث می برند اعمال می شود. (به عنوان مثال، test ارث بری از build .)

هر یک از این خطوط ممکن است بیش از یک بار مورد استفاده قرار گیرد و آرگومان هایی که پس از کلمه اول قرار می گیرند طوری ترکیب می شوند که گویی در یک خط ظاهر شده اند. (کاربران CVS، ابزار دیگری با رابط خط فرمان "Swiss Army Knife"، نحوی شبیه به .cvsrc . را پیدا می کنند.) به عنوان مثال، خطوط:

build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar

به صورت زیر ترکیب می شوند:

build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar

بنابراین پرچم های موثر --verbose_failures و --test_tmpdir=/tmp/bar هستند.

تقدم گزینه:

  • گزینه های موجود در خط فرمان همیشه بر گزینه های موجود در فایل های rc اولویت دارند. برای مثال، اگر یک فایل rc می گوید build -c opt اما پرچم خط فرمان -c dbg است، پرچم خط فرمان اولویت دارد.

  • در فایل rc، اولویت توسط ویژگی کنترل می شود: خطوط برای یک دستور خاص تر بر خطوط برای یک دستور کمتر خاص اولویت دارند.

    ویژگی با وراثت تعریف می شود. برخی از دستورات گزینه‌هایی را از دستورات دیگر به ارث می‌برند و فرمان ارث بری را از دستور پایه خاص‌تر می‌کنند. برای مثال test از دستور build به ارث می‌رسد، بنابراین همه پرچم‌های bazel build bazel برای bazel test معتبر هستند، و همه خطوط build برای bazel test نیز اعمال می‌شوند، مگر اینکه یک خط test برای همان گزینه وجود داشته باشد. اگر فایل rc می گوید:

    test -c dbg --test_env=PATH
build -c opt --verbose_failures

    سپس bazel build //foo از -c opt --verbose_failures و bazel test //foo از --verbose_failures -c dbg --test_env=PATH استفاده خواهد کرد.

    نمودار وراثت (ویژگی) به صورت زیر است:

    • هر فرمان از common به ارث می برد
    • دستورات زیر از build (و خاص تر از) به ارث برده می شوند: test , run , clean , mobile-install , info , print_action , config , cquery و aquery
    • coverage از test به ارث می رسد

  • دو خط که گزینه‌های یک فرمان را با مشخصات برابر مشخص می‌کنند، به ترتیبی که در فایل ظاهر می‌شوند، تجزیه می‌شوند.

  • از آنجایی که این قانون اولویت با ترتیب فایل مطابقت ندارد، اگر ترتیب اولویت را در فایل‌های rc دنبال کنید به خوانایی کمک می‌کند: با گزینه‌های common در بالا شروع کنید و با خاص‌ترین دستورات در پایین فایل پایان دهید. به این ترتیب ترتیب خواندن گزینه ها با ترتیب اعمال آنها یکی است که شهودی تر است.

آرگومان های مشخص شده در یک خط از فایل rc ممکن است شامل آرگومان هایی باشد که گزینه نیستند، مانند نام اهداف ساخت و غیره. اینها، مانند گزینه‌های مشخص‌شده در همان فایل‌ها، اولویت کمتری نسبت به خواهر و برادرشان در خط فرمان دارند و همیشه به فهرست صریح آرگومان‌های غیرگزینه اضافه می‌شوند.

--config

علاوه بر تنظیم پیش‌فرض گزینه‌ها، از فایل rc می‌توان برای گروه‌بندی گزینه‌ها و ارائه مختصر برای گروه‌بندی‌های رایج استفاده کرد. این کار با افزودن پسوند :name به دستور انجام می شود. این گزینه‌ها به‌طور پیش‌فرض نادیده گرفته می‌شوند، اما زمانی که گزینه --config= name وجود دارد، چه در خط فرمان یا در یک فایل .bazelrc .، به صورت بازگشتی، حتی در داخل یک تعریف پیکربندی دیگر، شامل می‌شوند. گزینه های مشخص شده توسط command:name فقط برای دستورات قابل اجرا، به ترتیب اولویت که در بالا توضیح داده شده است، گسترش خواهند یافت.

--config=foo به گزینه‌های تعریف‌شده در فایل‌های rc "در محل" گسترش می‌یابد تا گزینه‌های تعیین‌شده برای پیکربندی همان اولویتی را داشته باشند که گزینه --config=foo داشت.

این نحو به استفاده از startup برای تنظیم گزینه های راه اندازی گسترش نمی یابد. تنظیم startup:config-name --some_startup_option در bazelrc. نادیده گرفته خواهد شد.

مثال

در اینجا یک نمونه فایل ~/.bazelrc است:

# Bob's Bazel option defaults

startup --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --show_timestamps --keep_going --jobs 600
build --color=yes
query --keep_going

# Definition of --config=memcheck
build:memcheck --strip=never --test_timeout=3600

سایر پرونده های حاکم بر رفتار بازل

.bazelignore

می‌توانید دایرکتوری‌هایی را در فضای کاری مشخص کنید که می‌خواهید Bazel نادیده بگیرد، مانند پروژه‌های مرتبطی که از سیستم‌های ساخت دیگر استفاده می‌کنند. فایلی به نام .bazelignore را در ریشه فضای کاری قرار دهید و دایرکتوری هایی را که می خواهید Bazel نادیده بگیرد، در هر خط اضافه کنید. ورودی ها نسبت به ریشه فضای کاری هستند.

فایل bazelrc جهانی

Bazel فایل های bazelrc اختیاری را به این ترتیب می خواند: - فایل rc سیستم واقع در etc/bazel.bazelrc . - فایل rc فضای کاری واقع در $workspace/tools/bazel.rc . - فایل rc صفحه اصلی در $HOME/.bazelrc

هر فایل bazelrc لیست شده در اینجا دارای یک پرچم مربوطه است که می تواند برای غیرفعال کردن آنها استفاده شود (به عنوان مثال --nosystem_rc ، --noworkspace_rc ، --nohome_rc ). همچنین می توانید با عبور از گزینه --ignore_all_rc_files startup همه bazelrc ها را نادیده بگیرید.