پایگاه کد بازل

این سند شرحی از پایه کد و نحوه ساختار بازل است. این برای افرادی در نظر گرفته شده است که مایل به مشارکت در Bazel هستند، نه برای کاربران نهایی.

مقدمه

اساس کد بازل بزرگ است (کد تولید ~ 350 KLOC و کد تست ~ 260 KLOC) و هیچ کس با کل چشم انداز آشنا نیست: همه دره خاص خود را به خوبی می شناسند، اما تعداد کمی از آنها می دانند که چه چیزی بر فراز تپه ها در هر جهت نهفته است.

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

نسخه عمومی کد منبع Bazel در GitHub در github.com/bazelbuild/bazel موجود است. این «منبع حقیقت» نیست. از یک درخت منبع داخلی Google مشتق شده است که شامل عملکردهای اضافی است که در خارج از Google مفید نیست. هدف بلند مدت این است که GitHub را به منبع حقیقت تبدیل کنیم.

مشارکت‌ها از طریق مکانیسم درخواست کشش معمولی GitHub پذیرفته می‌شوند و توسط یک Googler به صورت دستی به درخت منبع داخلی وارد می‌شوند، سپس دوباره به GitHub صادر می‌شوند.

معماری کلاینت/سرور

بخش عمده ای از Bazel در یک فرآیند سرور قرار دارد که بین ساخت ها در RAM باقی می ماند. این به Bazel اجازه می دهد تا حالت بین ساخت ها را حفظ کند.

به همین دلیل است که خط فرمان Bazel دو نوع گزینه دارد: راه اندازی و فرمان. در یک خط فرمان مانند این:

    bazel --host_jvm_args=-Xmx8G build -c opt //foo:bar

برخی از گزینه ها ( --host_jvm_args= ) قبل از نام دستوری هستند که باید اجرا شوند و برخی بعد از ( -c opt ); نوع اول «گزینه راه‌اندازی» نامیده می‌شود و بر فرآیند سرور به‌عنوان یک کل تأثیر می‌گذارد، در حالی که نوع دوم، «گزینه فرمان»، تنها بر یک فرمان تأثیر می‌گذارد.

هر نمونه سرور دارای یک درخت منبع مرتبط است ("فضای کاری") و هر فضای کاری معمولاً یک نمونه سرور فعال دارد. این را می توان با تعیین یک پایه خروجی سفارشی دور زد (برای اطلاعات بیشتر به بخش "طرح دایرکتوری" مراجعه کنید).

Bazel به عنوان یک فایل اجرایی ELF که یک فایل zip. معتبر نیز می باشد توزیع می شود. هنگامی که شما bazel را تایپ می کنید، فایل اجرایی ELF بالا که در C++ پیاده سازی شده است ("مشتری") کنترل می شود. با استفاده از مراحل زیر یک فرآیند سرور مناسب را تنظیم می کند:

1. بررسی می کند که آیا قبلاً خودش را استخراج کرده است یا خیر. اگر نه، این کار را انجام می دهد. پیاده سازی سرور از اینجا می آید.
2. بررسی می‌کند که آیا یک نمونه سرور فعال وجود دارد که کار می‌کند: در حال اجرا است، گزینه‌های راه‌اندازی مناسبی دارد و از دایرکتوری فضای کاری مناسب استفاده می‌کند. سرور در حال اجرا را با نگاه کردن به دایرکتوری $OUTPUT_BASE/server که در آن یک فایل قفل با پورتی که سرور به آن گوش می دهد وجود دارد، پیدا می کند.
3. در صورت نیاز، فرآیند سرور قدیمی را از بین می برد
4. در صورت نیاز، یک فرآیند سرور جدید راه اندازی می کند

پس از آماده شدن یک فرآیند سرور مناسب، دستوری که باید اجرا شود از طریق یک رابط gRPC به آن ابلاغ می‌شود، سپس خروجی Bazel به ترمینال بازگردانده می‌شود. فقط یک فرمان می تواند همزمان اجرا شود. این با استفاده از یک مکانیسم قفل پیچیده با قطعات در C++ و قطعات در جاوا پیاده سازی شده است. زیرساخت هایی برای اجرای چند دستور به صورت موازی وجود دارد، زیرا عدم توانایی اجرای bazel version به موازات با دستور دیگری تا حدودی شرم آور است. مسدود کننده اصلی چرخه زندگی BlazeModule و برخی از وضعیت ها در BlazeRuntime است.

در پایان یک دستور، سرور Bazel کد خروجی را که کلاینت باید برگرداند، ارسال می کند. یک مشکل جالب اجرای bazel run است: وظیفه این دستور اجرای چیزی است که Bazel به تازگی ساخته است، اما نمی تواند این کار را از طریق فرآیند سرور انجام دهد زیرا ترمینال ندارد. بنابراین در عوض به مشتری می گوید که چه باینری باید ujexec() و با چه آرگومان هایی باشد.

هنگامی که Ctrl-C را فشار می دهید، مشتری آن را به یک تماس لغو در اتصال gRPC ترجمه می کند، که سعی می کند دستور را در اسرع وقت خاتمه دهد. پس از سومین Ctrl-C، مشتری به جای آن یک SIGKILL را به سرور ارسال می کند.

کد منبع کلاینت تحت src/main/cpp و پروتکل مورد استفاده برای برقراری ارتباط با سرور در src/main/protobuf/command_server.proto است.

نقطه ورود اصلی سرور BlazeRuntime.main() است و تماس های gRPC از کلاینت توسط GrpcServerImpl.run() مدیریت می شود.

طرح دایرکتوری

Bazel مجموعه ای پیچیده از دایرکتوری ها را در طول ساخت ایجاد می کند. توضیحات کامل در طرح‌بندی فهرست خروجی موجود است.

"فضای کار" درخت منبعی است که Bazel در آن اجرا می شود. معمولاً با چیزی مطابقت دارد که شما از کنترل منبع بررسی کرده اید.

Bazel تمام داده های خود را در "output user root" قرار می دهد. این معمولاً $HOME/.cache/bazel/_bazel_${USER} است، اما می‌توان با استفاده از گزینه راه‌اندازی --output_user_root آن را لغو کرد.

"پایه نصب" جایی است که Bazel به آن استخراج می شود. این کار به صورت خودکار انجام می شود و هر نسخه Bazel یک زیر شاخه بر اساس چک جمع خود در زیر پایه نصب دریافت می کند. به طور پیش فرض در $OUTPUT_USER_ROOT/install است و می توان آن را با استفاده از گزینه خط فرمان --install_base تغییر داد.

"پایه خروجی" جایی است که نمونه Bazel متصل به یک فضای کاری خاص در آن می نویسد. هر پایه خروجی حداکثر یک نمونه سرور Bazel در هر زمان دارد. معمولاً در $OUTPUT_USER_ROOT/<checksum of the path to the workspace> است. می توان آن را با استفاده از گزینه --output_base startup تغییر داد، که از جمله موارد دیگر، برای دور زدن این محدودیت مفید است که تنها یک نمونه Bazel می تواند در هر فضای کاری در هر زمان معین اجرا شود.

دایرکتوری خروجی شامل موارد زیر است:

• مخازن خارجی واکشی شده در $OUTPUT_BASE/external .
• ریشه exec، دایرکتوری که حاوی پیوندهای نمادین به تمام کد منبع برای ساخت فعلی است. در $OUTPUT_BASE/execroot واقع شده است. در طول ساخت، دایرکتوری کاری $EXECROOT/<name of main repository> است. ما قصد داریم این را به $EXECROOT تغییر دهیم، اگرچه این یک برنامه بلند مدت است زیرا یک تغییر بسیار ناسازگار است.
• فایل های ساخته شده در حین ساخت.

فرآیند اجرای یک دستور

هنگامی که سرور Bazel کنترل می شود و از دستوری که باید اجرا کند مطلع می شود، ترتیب زیر رخ می دهد:

1. BlazeCommandDispatcher در مورد درخواست جدید مطلع شده است. این تصمیم می‌گیرد که آیا دستور برای اجرا به یک فضای کاری نیاز دارد (تقریباً هر دستوری به جز دستورهایی که ربطی به کد منبع ندارند، مانند نسخه یا راهنما) و آیا دستور دیگری در حال اجرا است.

2. دستور درست پیدا می شود. هر دستور باید رابط BlazeCommand را پیاده سازی کند و باید حاشیه نویسی @Command را داشته باشد (این کمی ضد الگو است، خوب است اگر تمام ابرداده هایی که یک فرمان نیاز دارد با روش هایی در BlazeCommand توضیح داده شود)

3. گزینه های خط فرمان تجزیه می شوند. هر دستور دارای گزینه های مختلف خط فرمان است که در حاشیه نویسی @Command توضیح داده شده است.

4. یک اتوبوس رویداد ایجاد می شود. اتوبوس رویداد یک جریان برای رویدادهایی است که در طول ساخت اتفاق می افتد. برخی از این موارد تحت حمایت پروتکل Build Event به خارج از Bazel صادر می شوند تا به دنیا بگویند ساخت چگونه پیش می رود.

5. فرمان کنترل می شود. جالب ترین دستورات آنهایی هستند که یک build را اجرا می کنند: build، test، run، coverage و غیره: این قابلیت توسط BuildTool پیاده سازی شده است.

6. مجموعه الگوهای هدف در خط فرمان تجزیه می شود و عبارات عام مانند //pkg:all و //pkg/... حل می شوند. این در AnalysisPhaseRunner.evaluateTargetPatterns() پیاده سازی شده و در Skyframe به عنوان TargetPatternPhaseValue تبدیل شده است.

7. فاز بارگذاری/تحلیل برای تولید نمودار عمل (گراف غیر چرخه ای جهت دار از دستورات که باید برای ساخت اجرا شود) اجرا می شود.

8. مرحله اجرا اجرا می شود. این بدان معناست که اجرای هر اقدام مورد نیاز برای ساخت اهداف سطح بالای درخواست شده اجرا می شود.

گزینه های خط فرمان

گزینه های خط فرمان برای فراخوانی Bazel در یک شی OptionsParsingResult توضیح داده شده است، که به نوبه خود حاوی نقشه ای از "کلاس های گزینه" به مقادیر گزینه ها است. یک "کلاس گزینه" یک زیر کلاس از OptionsBase و گزینه های خط فرمان را که به یکدیگر مرتبط هستند را با هم گروه بندی می کند. مثلا:

1. گزینه های مربوط به یک زبان برنامه نویسی ( CppOptions یا JavaOptions ). اینها باید یک زیر کلاس از FragmentOptions باشند و در نهایت در یک شی BuildOptions پیچیده می شوند.
2. گزینه های مربوط به نحوه اجرای عملیات Bazel ( ExecutionOptions )

این گزینه ها به گونه ای طراحی شده اند که در مرحله تجزیه و تحلیل و (از طریق RuleContext.getFragment() در جاوا یا ctx.fragments در Starlark مصرف شوند. برخی از آنها (به عنوان مثال، انجام C++ شامل اسکن یا نه) در مرحله اجرا خوانده می شوند، اما همیشه نیاز به لوله کشی صریح دارد زیرا BuildConfiguration در آن زمان در دسترس نیست. برای اطلاعات بیشتر، بخش "پیکربندی" را ببینید.

اخطار: ما دوست داریم وانمود کنیم که نمونه های OptionsBase تغییرناپذیر هستند و از آنها در این راه استفاده می کنیم (مانند بخشی از SkyKeys ). اینطور نیست و اصلاح آنها یک راه واقعا خوب برای شکستن Bazel به روش های ظریفی است که اشکال زدایی آنها سخت است. متأسفانه، تغییرناپذیر ساختن آنها یک تلاش بزرگ است. (تغییر یک FragmentOptions بلافاصله پس از ساخت، قبل از اینکه دیگران فرصتی برای حفظ ارجاع به آن پیدا کنند و قبل از فراخوانی ()quals( equals() یا hashCode() بر روی آن، اشکالی ندارد.)

Bazel در مورد کلاس های گزینه به روش های زیر می آموزد:

1. برخی از آنها به Bazel متصل شده اند ( CommonCommandOptions )
2. از حاشیه نویسی Command@ در هر دستور Bazel
3. از ConfiguredRuleClassProvider (اینها گزینه های خط فرمان مربوط به هر زبان برنامه نویسی هستند)
4. قوانین Starlark همچنین می توانند گزینه های خود را تعریف کنند ( اینجا را ببینید)

هر گزینه (به استثنای گزینه‌های تعریف‌شده توسط Starlark) یک متغیر عضو از یک زیرکلاس FragmentOptions است که دارای حاشیه‌نویسی @Option است که نام و نوع گزینه خط فرمان را به همراه متن راهنما مشخص می‌کند.

نوع جاوا مقدار یک گزینه خط فرمان معمولاً چیزی ساده است (یک رشته، یک عدد صحیح، یک بولی، یک برچسب و غیره). با این حال، ما از گزینه های پیچیده تر نیز پشتیبانی می کنیم. در این حالت، کار تبدیل از رشته خط فرمان به نوع داده به پیاده سازی com.google.devtools.common.options.Converter می افتد.

درخت سرچشمه همانطور که بازل دیده می شود

بازل در زمینه ساخت نرم افزار است که با خواندن و تفسیر کد منبع اتفاق می افتد. مجموع کد منبعی که Bazel روی آن کار می کند "فضای کاری" نامیده می شود و به صورت مخازن، بسته ها و قوانین ساختار یافته است.

مخازن

"مخزن" درخت منبعی است که توسعه دهنده روی آن کار می کند. معمولاً نشان دهنده یک پروژه واحد است. جد Bazel، Blaze، روی یک monorepo کار می‌کرد، یعنی یک درخت منبع منفرد که شامل تمام کدهای منبع مورد استفاده برای اجرای بیلد است. در مقابل، Bazel از پروژه هایی پشتیبانی می کند که کد منبع آنها چندین مخزن را در بر می گیرد. مخزنی که بازل از آن فراخوانی می‌شود، «مخزن اصلی» و بقیه «مخزن‌های خارجی» نامیده می‌شوند.

یک مخزن با فایلی به نام WORKSPACE (یا WORKSPACE.bazel ) در دایرکتوری ریشه آن مشخص می شود. این فایل حاوی اطلاعاتی است که برای کل بیلد «جهانی» است، به عنوان مثال، مجموعه ای از مخازن خارجی موجود. مانند یک فایل Starlark معمولی کار می کند که به این معنی است که می توانید سایر فایل های Starlark load() را بارگذاری کنید. این معمولاً برای کشیدن مخازن مورد نیاز مخزنی که به صراحت به آن ارجاع داده شده است استفاده می شود (ما آن را "الگوی deps.bzl " می نامیم).

کد مخازن خارجی در زیر $OUTPUT_BASE/external پیوند داده شده یا دانلود می شود.

هنگام اجرای بیلد، کل درخت منبع باید با هم ترکیب شود. این کار توسط SymlinkForest انجام می شود، که هر بسته موجود در مخزن اصلی را به $EXECROOT و هر مخزن خارجی را به $EXECROOT/external یا $EXECROOT/.. می دهد (البته اولی وجود بسته ای به نام external را در اصلی غیرممکن می کند. مخزن؛ به همین دلیل است که ما در حال مهاجرت از آن هستیم)

بسته ها

هر مخزن از بسته ها، مجموعه ای از فایل های مرتبط و مشخصاتی از وابستگی ها تشکیل شده است. اینها توسط فایلی به نام BUILD یا BUILD.bazel می شوند. اگر هر دو وجود داشته باشند، BUILD.bazel ترجیح می دهد. دلیل اینکه فایل های BUILD هنوز پذیرفته می شوند این است که جد Bazel، Blaze، از این نام فایل استفاده می کرد. با این حال، مشخص شد که این یک بخش مسیر متداول است، به خصوص در ویندوز، که در آن نام فایل‌ها به حروف بزرگ و کوچک حساس نیستند.

بسته ها مستقل از یکدیگر هستند: تغییرات در فایل BUILD یک بسته نمی تواند باعث تغییر سایر بسته ها شود. افزودن یا حذف فایل های BUILD می تواند بسته های دیگر را تغییر دهد، زیرا glob های بازگشتی در مرزهای بسته متوقف می شوند و بنابراین وجود یک فایل BUILD بازگشت را متوقف می کند.

ارزیابی یک فایل BUILD "بارگیری بسته" نامیده می شود. این در کلاس PackageFactory پیاده سازی شده است، با فراخوانی مفسر Starlark کار می کند و به دانش مجموعه ای از کلاس های قانون موجود نیاز دارد. نتیجه بارگیری بسته یک شیء Package است. این بیشتر یک نقشه از یک رشته (نام یک هدف) به خود هدف است.

بخش بزرگی از پیچیدگی در حین بارگذاری بسته به صورت globbing است: Bazel نیازی ندارد که همه فایل های منبع به صراحت فهرست شوند و در عوض می توانند glob ها را اجرا کنند (مانند glob(["**/*.java"]) ). برخلاف پوسته، از گلوب‌های بازگشتی که به زیر شاخه‌ها (اما نه در بسته‌های فرعی) فرود می‌آیند، پشتیبانی می‌کند. این نیاز به دسترسی به سیستم فایل دارد و از آنجایی که می تواند کند باشد، ما انواع ترفندها را برای اجرای موازی و تا حد امکان کارآمد اجرا می کنیم.

Globbing در کلاس های زیر اجرا می شود:

• LegacyGlobber ، یک globber سریع و شاد از Skyframe
• SkyframeHybridGlobber ، نسخه‌ای که از Skyframe استفاده می‌کند و برای جلوگیری از «راه‌اندازی مجدد Skyframe» (توضیح داده شده در زیر) به globber قدیمی برمی‌گردد.

خود کلاس Package شامل تعدادی عضو است که منحصراً برای تجزیه فایل WORKSPACE استفاده می شوند و برای بسته های واقعی معنی ندارند. این یک نقص طراحی است زیرا اشیایی که بسته‌های معمولی را توصیف می‌کنند نباید دارای فیلدهایی باشند که چیز دیگری را توصیف کنند. این شامل:

• نقشه برداری های مخزن
• زنجیره های ابزار ثبت شده
• پلت فرم های اعدام ثبت شده

در حالت ایده‌آل، بین تجزیه فایل WORKSPACE از تجزیه بسته‌های معمولی تفکیک بیشتری وجود خواهد داشت تا Package نیازی به برآوردن نیازهای هر دو نداشته باشد. متأسفانه انجام این کار دشوار است زیرا این دو کاملاً عمیقاً در هم تنیده شده اند.

برچسب ها، اهداف و قوانین

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

1. فایل ها: چیزهایی که یا ورودی یا خروجی ساخت هستند. در اصطلاح بازل به آنها مصنوعات می گوییم (در جاهای دیگر بحث شده است). همه فایل های ایجاد شده در طول ساخت، هدف نیستند. معمول است که خروجی Bazel برچسب مرتبطی نداشته باشد.
2. قوانین: این مراحل مراحل استخراج خروجی آن از ورودی های آن را شرح می دهد. آنها به طور کلی با یک زبان برنامه نویسی (مانند cc_library ، java_library یا py_library ) مرتبط هستند، اما برخی از زبان های آگنوستیک وجود دارند (مانند genrule یا filegroup )
3. گروه های بسته: در بخش Visibility بحث شده است.

نام یک هدف یک برچسب نامیده می شود. نحو برچسب ها @repo//pac/kage:name است، جایی که repo نام مخزنی است که Label در آن قرار دارد، pac/kage دایرکتوری است که فایل BUILD آن در آن قرار دارد و name مسیر فایل است (اگر برچسب به یک فایل منبع اشاره دارد) نسبت به دایرکتوری بسته. هنگام اشاره به یک هدف در خط فرمان، برخی از قسمت های برچسب را می توان حذف کرد:

1. اگر مخزن حذف شود، برچسب در مخزن اصلی در نظر گرفته می شود.
2. اگر قسمت بسته حذف شود (مانند name یا :name )، برچسب در بسته دایرکتوری کاری فعلی در نظر گرفته می شود (مسیرهای نسبی حاوی ارجاعات سطح بالا (..) مجاز نیستند)

نوعی قانون (مانند "کتابخانه C++") "کلاس قانون" نامیده می شود. کلاس‌های قانون ممکن است در Starlark (تابع rule() ) یا در جاوا (اصطلاحاً قوانین بومی، نوع RuleClass ) پیاده‌سازی شوند. در دراز مدت، هر قانون خاص زبان در Starlark پیاده‌سازی می‌شود، اما برخی از خانواده‌های قوانین قدیمی (مانند جاوا یا C++) در حال حاضر هنوز در جاوا هستند.

کلاس‌های قانون Starlark باید در ابتدای فایل‌های BUILD با استفاده از دستور load() وارد شوند، در حالی که کلاس‌های قانون جاوا به دلیل ثبت شدن در ConfiguredRuleClassProvider توسط Bazel "ذاتا" شناخته می‌شوند.

کلاس های قانون حاوی اطلاعاتی مانند:

1. ویژگی های آن (مانند srcs ، deps ): انواع، مقادیر پیش فرض، محدودیت ها و غیره.
2. انتقال‌های پیکربندی و جنبه‌های متصل به هر ویژگی، در صورت وجود
3. اجرای قاعده
4. ارائه دهندگان اطلاعات انتقالی که قانون "معمولا" ایجاد می کند

توجه اصطلاحات: در پایه کد، ما اغلب از "Rule" به معنای هدف ایجاد شده توسط یک کلاس قانون استفاده می کنیم. اما در Starlark و در مستندات رو به رو کاربر، "Rule" باید منحصراً برای اشاره به خود کلاس قانون استفاده شود. هدف فقط یک "هدف" است. همچنین توجه داشته باشید که علیرغم اینکه RuleClass دارای "کلاس" در نام خود است، هیچ رابطه ارثی جاوا بین یک کلاس قانون و اهداف از آن نوع وجود ندارد.

اسکای فریم

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

گره های موجود در نمودار SkyValue s و نام آنها SkyKey s نامیده می شوند. هر دو عمیقا تغییر ناپذیر هستند. فقط اشیاء تغییرناپذیر باید از آنها قابل دسترسی باشند. این تغییر تقریباً همیشه برقرار است، و در صورت عدم وجود (مانند کلاس‌های گزینه‌های فردی BuildOptions ، که عضوی از BuildConfigurationValue و SkyKey آن است) ما واقعاً سعی می‌کنیم آنها را تغییر ندهیم یا آنها را فقط به روش‌هایی تغییر دهیم. از بیرون قابل مشاهده نیست از این نتیجه می شود که هر چیزی که در Skyframe محاسبه می شود (مانند اهداف پیکربندی شده) نیز باید تغییر ناپذیر باشد.

راحت ترین راه برای مشاهده گراف Skyframe اجرای bazel dump --skyframe=detailed است که نمودار را، یک SkyValue در هر خط تخلیه می کند. بهتر است این کار را برای ساختمان های کوچک انجام دهید، زیرا می تواند بسیار بزرگ شود.

Skyframe در بسته com.google.devtools.build.skyframe زندگی می کند. بسته com.google.devtools.build.lib.skyframe با نام مشابه شامل اجرای Bazel در بالای Skyframe است. اطلاعات بیشتر در مورد Skyframe در اینجا موجود است.

برای ارزیابی SkyKey داده شده به SkyValue ، SkyFunction تابع Sky مربوط به نوع کلید را فراخوانی می کند. در طول ارزیابی تابع، ممکن است وابستگی های دیگری از Skyframe با فراخوانی اضافه بارهای مختلف SkyFunction.Environment.getValue() کند. این اثر جانبی ثبت آن وابستگی ها در نمودار داخلی Skyframe دارد، به طوری که Skyframe می داند که در صورت تغییر هر یک از وابستگی هایش، عملکرد را مجددا ارزیابی کند. به عبارت دیگر، حافظه پنهان و محاسبات افزایشی Skyframe با جزئیات SkyFunction s و SkyValue s کار می کند.

هر زمان که SkyFunction وابستگی غیرقابل دسترسی را درخواست کند، getValue() null برمی‌گرداند. سپس تابع باید کنترل را به Skyframe برگرداند و به خودی خود null برگرداند. در مرحله‌ای بعد، Skyframe وابستگی غیرقابل دسترس را ارزیابی می‌کند، سپس تابع را از ابتدا راه‌اندازی مجدد می‌کند - فقط این بار getValue() با یک نتیجه غیر تهی موفق خواهد شد.

نتیجه این امر این است که هر محاسباتی که قبل از راه اندازی مجدد در داخل SkyFunction انجام می شود باید تکرار شود. اما این شامل کار انجام شده برای ارزیابی وابستگی SkyValues ​​که در حافظه پنهان هستند نمی شود. بنابراین، ما معمولاً در مورد این موضوع کار می کنیم:

1. اعلان وابستگی ها در دسته (با استفاده از getValuesAndExceptions() ) برای محدود کردن تعداد راه اندازی مجدد.
2. SkyValue به قطعات جداگانه محاسبه شده توسط SkyFunction های مختلف، به طوری که آنها می توانند به طور مستقل محاسبه و ذخیره شوند. این باید به صورت استراتژیک انجام شود، زیرا پتانسیل افزایش استفاده از حافظه را دارد.
3. ذخیره سازی حالت بین راه اندازی مجدد، یا با استفاده از SkyFunction.Environment.getState() ، یا نگه داشتن یک کش استاتیک موقتی "در پشت Skyframe".

اساساً ما به این نوع راه‌حل‌ها نیاز داریم، زیرا به طور معمول صدها هزار گره Skyframe در حین پرواز داریم و جاوا از رشته‌های سبک وزن پشتیبانی نمی‌کند.

استارلارک

Starlark زبان مخصوص دامنه است که مردم برای پیکربندی و گسترش Bazel از آن استفاده می کنند. این به عنوان یک زیرمجموعه محدود از پایتون در نظر گرفته شده است که دارای انواع بسیار کمتر، محدودیت‌های بیشتر در جریان کنترل، و مهمتر از همه، تضمین‌های تغییرناپذیری قوی برای فعال کردن خواندن همزمان است. تورینگ کامل نیست، که برخی از کاربران (و نه همه) را از تلاش برای انجام وظایف برنامه نویسی عمومی در داخل زبان منع می کند.

Starlark در بسته net.starlark.java پیاده سازی شده است. همچنین یک پیاده سازی Go مستقل در اینجا دارد. پیاده سازی جاوا مورد استفاده در Bazel در حال حاضر یک مفسر است.

Starlark در زمینه های مختلفی استفاده می شود، از جمله:

1. زبان BUILD . اینجاست که قوانین جدیدی تعریف می شود. کد Starlark که در این زمینه اجرا می شود فقط به محتویات خود فایل BUILD و فایل های .bzl بارگذاری شده توسط آن دسترسی دارد.
2. تعاریف قوانین قوانین جدید (مانند پشتیبانی از زبان جدید) به این ترتیب تعریف می شوند. کد Starlark که در این زمینه اجرا می شود به پیکربندی و داده های ارائه شده توسط وابستگی های مستقیم آن دسترسی دارد (در ادامه در این مورد بیشتر توضیح خواهیم داد).
3. فایل WORKSPACE. اینجا جایی است که مخازن خارجی (کدی که در درخت منبع اصلی نیست) تعریف می شوند.
4. تعاریف قوانین مخزن اینجاست که انواع جدید مخزن خارجی تعریف می شوند. کد Starlark که در این زمینه اجرا می شود می تواند کد دلخواه را روی دستگاهی که Bazel در آن اجرا می کند اجرا کند و به خارج از فضای کاری برسد.

لهجه های موجود برای فایل های BUILD و .bzl کمی متفاوت هستند زیرا چیزهای متفاوتی را بیان می کنند. لیستی از تفاوت ها در اینجا موجود است.

اطلاعات بیشتر در مورد Starlark در اینجا موجود است.

مرحله بارگذاری/تحلیل

مرحله بارگذاری/تحلیل جایی است که Bazel تعیین می کند چه اقداماتی برای ایجاد یک قانون خاص لازم است. واحد اصلی آن یک "هدف پیکربندی شده" است که کاملا معقولانه یک جفت (هدف، پیکربندی) است.

این مرحله "فاز بارگذاری/تحلیل" نامیده می شود زیرا می توان آن را به دو بخش مجزا تقسیم کرد، که قبلاً سریالی می شدند، اما اکنون می توانند در زمان همپوشانی داشته باشند:

1. بارگیری بسته ها، یعنی تبدیل فایل های BUILD به اشیاء Package که آنها را نشان می دهد
2. تجزیه و تحلیل اهداف پیکربندی شده، یعنی اجرای اجرای قوانین برای تولید نمودار عمل

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

1. پیکربندی. ("چگونه" آن قانون را بسازیم؛ به عنوان مثال، پلتفرم هدف و همچنین مواردی مانند گزینه های خط فرمان که کاربر می خواهد به کامپایلر C++ ارسال شود)
2. وابستگی های مستقیم ارائه دهندگان اطلاعات انتقالی آنها برای قانون مورد تجزیه و تحلیل در دسترس هستند. آنها به این دلیل نامیده می شوند زیرا آنها "مجموعه ای" از اطلاعات را در بسته شدن انتقالی هدف پیکربندی شده ارائه می دهند، مانند همه فایل های jar در مسیر کلاس یا همه فایل های .o که باید به C++ پیوند داده شوند. دودویی)
3. خود هدف این نتیجه بارگیری بسته ای است که هدف در آن قرار دارد. برای قوانین، این شامل ویژگی های آن است که معمولاً مهم است.
4. اجرای هدف پیکربندی شده برای قوانین، این می تواند در Starlark یا در جاوا باشد. تمام اهداف پیکربندی شده بدون قانون در جاوا پیاده سازی می شوند.

خروجی تجزیه و تحلیل یک هدف پیکربندی شده عبارت است از:

1. ارائه دهندگان اطلاعات انتقالی که اهداف وابسته به آن را پیکربندی کرده اند، می توانند به آن دسترسی داشته باشند
2. مصنوعاتی که می تواند ایجاد کند و اقداماتی که آنها را تولید می کند.

API ارائه شده به قوانین جاوا RuleContext است که معادل آرگومان ctx قوانین Starlark است. API آن قدرتمندتر است، اما در عین حال، انجام Bad Things™ آسان‌تر است، برای مثال نوشتن کدی که پیچیدگی زمانی یا مکانی آن درجه دوم (یا بدتر از آن) باشد، برای خراب کردن سرور Bazel با استثنای جاوا یا نقض آن. متغیرها (مانند تغییر ناخواسته یک نمونه Options یا با تغییر دادن یک هدف پیکربندی شده)

الگوریتمی که وابستگی های مستقیم یک هدف پیکربندی شده را تعیین می کند در DependencyResolver.dependentNodeMap() زندگی می کند.

پیکربندی

پیکربندی ها «چگونگی» ساخت یک هدف هستند: برای چه پلتفرمی، با چه گزینه های خط فرمان و غیره.

یک هدف را می توان برای پیکربندی های متعدد در یک ساخت ایجاد کرد. این مفید است، برای مثال، زمانی که از همان کد برای ابزاری استفاده می‌شود که در حین ساخت و کد هدف اجرا می‌شود و ما در حال کامپایل متقابل هستیم یا زمانی که در حال ساختن یک برنامه اندرویدی چرب هستیم (یکی که حاوی کد بومی برای چندین CPU است. معماری ها)

از نظر مفهومی، پیکربندی یک نمونه BuildOptions است. با این حال، در عمل، BuildOptions توسط BuildConfiguration می شود که عملکردهای مختلفی را ارائه می دهد. از بالای نمودار وابستگی به پایین منتشر می شود. اگر تغییر کند، ساخت باید دوباره آنالیز شود.

این امر منجر به ناهنجاری هایی مانند تجزیه و تحلیل مجدد کل ساخت می شود اگر، برای مثال، تعداد اجرای آزمایشی درخواست شده تغییر کند، حتی اگر این فقط بر اهداف آزمایشی تأثیر بگذارد (ما برنامه هایی برای "تریم کردن" پیکربندی ها داریم تا اینطور نباشد، اما هنوز آماده نیست).

هنگامی که اجرای یک قانون به بخشی از پیکربندی نیاز دارد، باید آن را در تعریف خود با استفاده از RuleClass.Builder.requiresConfigurationFragments() اعلام کند. این هم برای جلوگیری از اشتباهات (مانند قوانین پایتون با استفاده از قطعه جاوا) و هم برای تسهیل برش پیکربندی به طوری که اگر گزینه های پایتون تغییر کند، اهداف C++ نیازی به تجزیه و تحلیل مجدد نداشته باشند.

پیکربندی یک قانون لزوماً با قانون «والد» آن یکسان نیست. فرآیند تغییر پیکربندی در لبه وابستگی را "انتقال پیکربندی" می نامند. این می تواند در دو مکان اتفاق بیفتد:

1. در لبه وابستگی این انتقال‌ها در Attribute.Builder.cfg() مشخص شده‌اند و توابعی از یک Rule (جایی که انتقال اتفاق می‌افتد) و یک BuildOptions (پیکربندی اصلی) به یک یا چند BuildOptions (پیکربندی خروجی) هستند.
2. در هر لبه ورودی به یک هدف پیکربندی شده. اینها در RuleClass.Builder.cfg() مشخص شده اند.

کلاس های مربوطه TransitionFactory و ConfigurationTransition هستند.

از انتقال های پیکربندی استفاده می شود، به عنوان مثال:

1. برای اعلام اینکه یک وابستگی خاص در طول ساخت استفاده می شود و بنابراین باید در معماری اجرا ساخته شود
2. برای اعلام اینکه یک وابستگی خاص باید برای چندین معماری ساخته شود (مانند کدهای بومی در APKهای چاق Android)

اگر یک انتقال پیکربندی منجر به پیکربندی های متعدد شود، به آن انتقال تقسیم می گویند.

انتقال های پیکربندی را می توان در Starlark نیز پیاده سازی کرد (اسناد در اینجا )

ارائه دهندگان اطلاعات انتقالی

ارائه دهندگان اطلاعات انتقالی راهی (و تنها راه) برای اهداف پیکربندی شده برای گفتن چیزهایی در مورد سایر اهداف پیکربندی شده که به آن وابسته هستند هستند. دلیل اینکه "گذرا" در نام آنها است این است که این معمولاً نوعی جمع‌بندی بسته شدن گذرای یک هدف پیکربندی شده است.

به طور کلی یک مکاتبات 1:1 بین ارائه دهندگان اطلاعات انتقالی جاوا و ارائه دهندگان Starlark وجود دارد (به استثنای DefaultInfo که ادغام FileProvider ، FilesToRunProvider و RunfilesProvider است، زیرا آن API به نظر می رسد Starlark تر از نویسه گردانی مستقیم جاوا باشد. ). کلید آنها یکی از موارد زیر است:

1. یک شی کلاس جاوا. این فقط برای ارائه دهندگانی در دسترس است که از Starlark در دسترس نیستند. این ارائه دهندگان یک زیر کلاس از TransitiveInfoProvider هستند.
2. یک رشته. این میراث است و به شدت دلسرد شده است، زیرا مستعد درگیری های نامی است. چنین ارائه دهندگان اطلاعات انتقالی زیر کلاس های مستقیم build.lib.packages.Info هستند.
3. نماد ارائه دهنده این را می توان از Starlark با استفاده از تابع provider() ایجاد کرد و راه پیشنهادی برای ایجاد ارائه دهندگان جدید است. نماد با یک نمونه Provider.Key در جاوا نشان داده می شود.

ارائه دهندگان جدید پیاده سازی شده در جاوا باید با استفاده از BuiltinProvider پیاده سازی شوند. NativeProvider منسوخ شده است (هنوز وقت نداریم آن را حذف کنیم) و زیر کلاس های TransitiveInfoProvider از Starlark قابل دسترسی نیستند.

اهداف پیکربندی شده

اهداف پیکربندی شده به عنوان RuleConfiguredTargetFactory پیاده سازی می شوند. برای هر کلاس قانون یک زیر کلاس وجود دارد که در جاوا پیاده سازی می شود. اهداف پیکربندی شده StarlarkRuleConfiguredTargetUtil.buildRule() ایجاد می شوند.

کارخانه های هدف پیکربندی شده باید از RuleConfiguredTargetBuilder برای ایجاد مقدار بازگشتی خود استفاده کنند. از موارد زیر تشکیل شده است:

1. filesToBuild آنها، مفهوم مبهم "مجموعه فایل هایی که این قانون نشان می دهد." اینها فایل هایی هستند که زمانی ساخته می شوند که هدف پیکربندی شده در خط فرمان یا در srcs یک ژانر باشد.
2. فایل های اجرا شده، معمولی و داده های آنها.
3. گروه های خروجی آنها این‌ها «مجموعه‌های دیگری از فایل‌ها» هستند که قانون می‌تواند بسازد. با استفاده از ویژگی output_group قانون filegroup در BUILD و با استفاده از ارائه دهنده OutputGroupInfo در جاوا می توان به آنها دسترسی داشت.

ران فایل ها

برخی از باینری ها برای اجرا به فایل های داده نیاز دارند. نمونه بارز تست هایی است که به فایل های ورودی نیاز دارند. این در بازل با مفهوم "رانفایل" نشان داده شده است. یک "runfiles tree" یک درخت دایرکتوری از فایل های داده برای یک باینری خاص است. در سیستم فایل به‌عنوان یک درخت سیم‌لینک با پیوندهای نمادین مجزا که به فایل‌های موجود در منبع درخت‌های خروجی اشاره می‌کنند، ایجاد می‌شود.

مجموعه ای از runfiles به عنوان یک نمونه Runfiles نمایش داده می شود. از نظر مفهومی نقشه ای از مسیر یک فایل در درخت runfiles تا نمونه Artifact است که آن را نشان می دهد. به دو دلیل کمی پیچیده تر از یک Map است:

• در اکثر مواقع، مسیر فایل های اجرا شده یک فایل با execpath آن یکسان است. ما از این برای ذخیره مقداری RAM استفاده می کنیم.
• انواع مختلفی از ورودی‌های قدیمی در درختان runfiles وجود دارد که باید نمایش داده شوند.

فایل‌های اجرا با استفاده از RunfilesProvider جمع‌آوری می‌شوند: نمونه‌ای از این کلاس، فایل‌های اجرا شده را به‌عنوان یک هدف پیکربندی شده (مانند یک کتابخانه) و نیازهای بسته شدن انتقالی آن نشان می‌دهد و مانند یک مجموعه تودرتو جمع‌آوری می‌شوند (در واقع، آنها با استفاده از مجموعه‌های تودرتو در زیر پوشش پیاده‌سازی می‌شوند) : هر هدف فایل های اجرائی وابستگی های خود را متحد می کند، تعدادی از خود را اضافه می کند، سپس مجموعه به دست آمده را در نمودار وابستگی به سمت بالا می فرستد. یک نمونه RunfilesProvider شامل دو نمونه Runfiles است، یکی برای زمانی که قانون از طریق ویژگی "data" به آن وابسته است و دیگری برای هر نوع وابستگی ورودی دیگر. این به این دلیل است که یک هدف گاهی اوقات زمانی که از طریق یک ویژگی داده به آن وابسته است، فایل های اجرا متفاوتی را ارائه می دهد. این رفتار میراثی نامطلوب است که ما هنوز به حذف آن نپرداخته ایم.

فایل های باینری به عنوان نمونه ای از RunfilesSupport می شوند. این با Runfiles متفاوت است زیرا RunfilesSupport قابلیت ساخت واقعی را دارد (برخلاف Runfiles که فقط یک نقشه برداری است). این امر به اجزای اضافی زیر نیاز دارد:

• فایل های اجرائی ورودی آشکار می شوند. این یک توصیف سریالی از درخت runfiles است. این به عنوان یک پروکسی برای محتویات درخت runfiles استفاده می شود و Bazel فرض می کند که درخت runfiles تغییر می کند اگر و فقط در صورتی که محتوای مانیفست تغییر کند.
• فایل های خروجی آشکار می شوند. این مورد توسط کتابخانه‌های زمان اجرا که درختان فایل‌های اجرا را مدیریت می‌کنند، به‌ویژه در ویندوز، که گاهی از پیوندهای نمادین پشتیبانی نمی‌کنند، استفاده می‌شود.
• واسطه runfiles. برای اینکه یک درخت runfiles وجود داشته باشد، باید درخت symlink و مصنوع را که symlinks به آن اشاره می کند بسازید. In order to decrease the number of dependency edges, the runfiles middleman can be used to represent all these.
• Command line arguments for running the binary whose runfiles the RunfilesSupport object represents.

Aspects

Aspects are a way to "propagate computation down the dependency graph". They are described for users of Bazel here . A good motivating example is protocol buffers: a proto_library rule should not know about any particular language, but building the implementation of a protocol buffer message (the “basic unit” of protocol buffers) in any programming language should be coupled to the proto_library rule so that if two targets in the same language depend on the same protocol buffer, it gets built only once.

Just like configured targets, they are represented in Skyframe as a SkyValue and the way they are constructed is very similar to how configured targets are built: they have a factory class called ConfiguredAspectFactory that has access to a RuleContext , but unlike configured target factories, it also knows about the configured target it is attached to and its providers.

The set of aspects propagated down the dependency graph is specified for each attribute using the Attribute.Builder.aspects() function. There are a few confusingly-named classes that participate in the process:

1. AspectClass is the implementation of the aspect. It can be either in Java (in which case it's a subclass) or in Starlark (in which case it's an instance of StarlarkAspectClass ). It's analogous to RuleConfiguredTargetFactory .
2. AspectDefinition is the definition of the aspect; it includes the providers it requires, the providers it provides and contains a reference to its implementation, such as the appropriate AspectClass instance. It's analogous to RuleClass .
3. AspectParameters is a way to parametrize an aspect that is propagated down the dependency graph. It's currently a string to string map. A good example of why it's useful is protocol buffers: if a language has multiple APIs, the information as to which API the protocol buffers should be built for should be propagated down the dependency graph.
4. Aspect represents all the data that's needed to compute an aspect that propagates down the dependency graph. It consists of the aspect class, its definition and its parameters.
5. RuleAspect is the function that determines which aspects a particular rule should propagate. It's a Rule -> Aspect function.

A somewhat unexpected complication is that aspects can attach to other aspects; for example, an aspect collecting the classpath for a Java IDE will probably want to know about all the .jar files on the classpath, but some of them are protocol buffers. In that case, the IDE aspect will want to attach to the ( proto_library rule + Java proto aspect) pair.

The complexity of aspects on aspects is captured in the class AspectCollection .

Platforms and toolchains

Bazel supports multi-platform builds, that is, builds where there may be multiple architectures where build actions run and multiple architectures for which code is built. These architectures are referred to as platforms in Bazel parlance (full documentation here )

A platform is described by a key-value mapping from constraint settings (such as the concept of "CPU architecture") to constraint values (such as a particular CPU like x86_64). We have a "dictionary" of the most commonly used constraint settings and values in the @platforms repository.

The concept of toolchain comes from the fact that depending on what platforms the build is running on and what platforms are targeted, one may need to use different compilers; for example, a particular C++ toolchain may run on a specific OS and be able to target some other OSes. Bazel must determine the C++ compiler that is used based on the set execution and target platform (documentation for toolchains here ).

In order to do this, toolchains are annotated with the set of execution and target platform constraints they support. In order to do this, the definition of a toolchain are split into two parts:

1. A toolchain() rule that describes the set of execution and target constraints a toolchain supports and tells what kind (such as C++ or Java) of toolchain it is (the latter is represented by the toolchain_type() rule)
2. A language-specific rule that describes the actual toolchain (such as cc_toolchain() )

This is done in this way because we need to know the constraints for every toolchain in order to do toolchain resolution and language-specific *_toolchain() rules contain much more information than that, so they take more time to load.

Execution platforms are specified in one of the following ways:

1. In the WORKSPACE file using the register_execution_platforms() function
2. On the command line using the --extra_execution_platforms command line option

The set of available execution platforms is computed in RegisteredExecutionPlatformsFunction .

The target platform for a configured target is determined by PlatformOptions.computeTargetPlatform() . It's a list of platforms because we eventually want to support multiple target platforms, but it's not implemented yet.

The set of toolchains to be used for a configured target is determined by ToolchainResolutionFunction . It is a function of:

• The set of registered toolchains (in the WORKSPACE file and the configuration)
• The desired execution and target platforms (in the configuration)
• The set of toolchain types that are required by the configured target (in UnloadedToolchainContextKey)
• The set of execution platform constraints of the configured target (the exec_compatible_with attribute) and the configuration ( --experimental_add_exec_constraints_to_targets ), in UnloadedToolchainContextKey

Its result is an UnloadedToolchainContext , which is essentially a map from toolchain type (represented as a ToolchainTypeInfo instance) to the label of the selected toolchain. It's called "unloaded" because it does not contain the toolchains themselves, only their labels.

Then the toolchains are actually loaded using ResolvedToolchainContext.load() and used by the implementation of the configured target that requested them.

We also have a legacy system that relies on there being one single "host" configuration and target configurations being represented by various configuration flags, such as --cpu . We are gradually transitioning to the above system. In order to handle cases where people rely on the legacy configuration values, we have implemented platform mappings to translate between the legacy flags and the new-style platform constraints. Their code is in PlatformMappingFunction and uses a non-Starlark "little language".

Constraints

Sometimes one wants to designate a target as being compatible with only a few platforms. Bazel has (unfortunately) multiple mechanisms to achieve this end:

• Rule-specific constraints
• environment_group() / environment()
• Platform constraints

Rule-specific constraints are mostly used within Google for Java rules; they are on their way out and they are not available in Bazel, but the source code may contain references to it. The attribute that governs this is called constraints= .

environment_group() and environment()

These rules are a legacy mechanism and are not widely used.

All build rules can declare which "environments" they can be built for, where a "environment" is an instance of the environment() rule.

There are various ways supported environments can be specified for a rule:

1. Through the restricted_to= attribute. This is the most direct form of specification; it declares the exact set of environments the rule supports for this group.
2. Through the compatible_with= attribute. This declares environments a rule supports in addition to "standard" environments that are supported by default.
3. Through the package-level attributes default_restricted_to= and default_compatible_with= .
4. Through default specifications in environment_group() rules. Every environment belongs to a group of thematically related peers (such as "CPU architectures", "JDK versions" or "mobile operating systems"). The definition of an environment group includes which of these environments should be supported by "default" if not otherwise specified by the restricted_to= / environment() attributes. A rule with no such attributes inherits all defaults.
5. Through a rule class default. This overrides global defaults for all instances of the given rule class. This can be used, for example, to make all *_test rules testable without each instance having to explicitly declare this capability.

environment() is implemented as a regular rule whereas environment_group() is both a subclass of Target but not Rule ( EnvironmentGroup ) and a function that is available by default from Starlark ( StarlarkLibrary.environmentGroup() ) which eventually creates an eponymous target. This is to avoid a cyclic dependency that would arise because each environment needs to declare the environment group it belongs to and each environment group needs to declare its default environments.

A build can be restricted to a certain environment with the --target_environment command line option.

The implementation of the constraint check is in RuleContextConstraintSemantics and TopLevelConstraintSemantics .

Platform constraints

The current "official" way to describe what platforms a target is compatible with is by using the same constraints used to describe toolchains and platforms. It's under review in pull request #10945 .

Visibility

If you work on a large codebase with a lot of developers (like at Google), you want to take care to prevent everyone else from arbitrarily depending on your code. Otherwise, as per Hyrum's law , people will come to rely on behaviors that you considered to be implementation details.

Bazel supports this by the mechanism called visibility : you can declare that a particular target can only be depended on using the visibility attribute. This attribute is a little special because, although it holds a list of labels, these labels may encode a pattern over package names rather than a pointer to any particular target. (Yes, this is a design flaw.)

This is implemented in the following places:

• The RuleVisibility interface represents a visibility declaration. It can be either a constant (fully public or fully private) or a list of labels.
• Labels can refer to either package groups (predefined list of packages), to packages directly ( //pkg:__pkg__ ) or subtrees of packages ( //pkg:__subpackages__ ). This is different from the command line syntax, which uses //pkg:* or //pkg/... .
• Package groups are implemented as their own target ( PackageGroup ) and configured target ( PackageGroupConfiguredTarget ). We could probably replace these with simple rules if we wanted to. Their logic is implemented with the help of: PackageSpecification , which corresponds to a single pattern like //pkg/... ; PackageGroupContents , which corresponds to a single package_group 's packages attribute; and PackageSpecificationProvider , which aggregates over a package_group and its transitive includes .
• The conversion from visibility label lists to dependencies is done in DependencyResolver.visitTargetVisibility and a few other miscellaneous places.
• The actual check is done in CommonPrerequisiteValidator.validateDirectPrerequisiteVisibility()

Nested sets

Oftentimes, a configured target aggregates a set of files from its dependencies, adds its own, and wraps the aggregate set into a transitive info provider so that configured targets that depend on it can do the same. Examples:

• The C++ header files used for a build
• The object files that represent the transitive closure of a cc_library
• The set of .jar files that need to be on the classpath for a Java rule to compile or run
• The set of Python files in the transitive closure of a Python rule

If we did this the naive way by using, for example, List or Set , we'd end up with quadratic memory usage: if there is a chain of N rules and each rule adds a file, we'd have 1+2+...+N collection members.

In order to get around this problem, we came up with the concept of a NestedSet . It's a data structure that is composed of other NestedSet instances and some members of its own, thereby forming a directed acyclic graph of sets. They are immutable and their members can be iterated over. We define multiple iteration order ( NestedSet.Order ): preorder, postorder, topological (a node always comes after its ancestors) and "don't care, but it should be the same each time".

The same data structure is called depset in Starlark.

Artifacts and Actions

The actual build consists of a set of commands that need to be run to produce the output the user wants. The commands are represented as instances of the class Action and the files are represented as instances of the class Artifact . They are arranged in a bipartite, directed, acyclic graph called the "action graph".

Artifacts come in two kinds: source artifacts (ones that are available before Bazel starts executing) and derived artifacts (ones that need to be built). Derived artifacts can themselves be multiple kinds:

1. **Regular artifacts. **These are checked for up-to-dateness by computing their checksum, with mtime as a shortcut; we don't checksum the file if its ctime hasn't changed.
2. Unresolved symlink artifacts. These are checked for up-to-dateness by calling readlink(). Unlike regular artifacts, these can be dangling symlinks. Usually used in cases where one then packs up some files into an archive of some sort.
3. Tree artifacts. These are not single files, but directory trees. They are checked for up-to-dateness by checking the set of files in it and their contents. They are represented as a TreeArtifact .
4. Constant metadata artifacts. Changes to these artifacts don't trigger a rebuild. This is used exclusively for build stamp information: we don't want to do a rebuild just because the current time changed.

There is no fundamental reason why source artifacts cannot be tree artifacts or unresolved symlink artifacts, it's just that we haven't implemented it yet (we should, though -- referencing a source directory in a BUILD file is one of the few known long-standing incorrectness issues with Bazel; we have an implementation that kind of works which is enabled by the BAZEL_TRACK_SOURCE_DIRECTORIES=1 JVM property)

A notable kind of Artifact are middlemen. They are indicated by Artifact instances that are the outputs of MiddlemanAction . They are used to special-case some things:

• Aggregating middlemen are used to group artifacts together. This is so that if a lot of actions use the same large set of inputs, we don't have N*M dependency edges, only N+M (they are being replaced with nested sets)
• Scheduling dependency middlemen ensure that an action runs before another. They are mostly used for linting but also for C++ compilation (see CcCompilationContext.createMiddleman() for an explanation)
• Runfiles middlemen are used to ensure the presence of a runfiles tree so that one does not separately need to depend on the output manifest and every single artifact referenced by the runfiles tree.

Actions are best understood as a command that needs to be run, the environment it needs and the set of outputs it produces. The following things are the main components of the description of an action:

• The command line that needs to be run
• The input artifacts it needs
• The environment variables that need to be set
• Annotations that describe the environment (such as platform) it needs to run in \

There are also a few other special cases, like writing a file whose content is known to Bazel. They are a subclass of AbstractAction . Most of the actions are a SpawnAction or a StarlarkAction (the same, they should arguably not be separate classes), although Java and C++ have their own action types ( JavaCompileAction , CppCompileAction and CppLinkAction ).

We eventually want to move everything to SpawnAction ; JavaCompileAction is pretty close, but C++ is a bit of a special-case due to .d file parsing and include scanning.

The action graph is mostly "embedded" into the Skyframe graph: conceptually, the execution of an action is represented as an invocation of ActionExecutionFunction . The mapping from an action graph dependency edge to a Skyframe dependency edge is described in ActionExecutionFunction.getInputDeps() and Artifact.key() and has a few optimizations in order to keep the number of Skyframe edges low:

• Derived artifacts do not have their own SkyValue s. Instead, Artifact.getGeneratingActionKey() is used to find out the key for the action that generates it
• Nested sets have their own Skyframe key.

Shared actions

Some actions are generated by multiple configured targets; Starlark rules are more limited since they are only allowed to put their derived actions into a directory determined by their configuration and their package (but even so, rules in the same package can conflict), but rules implemented in Java can put derived artifacts anywhere.

This is considered to be a misfeature, but getting rid of it is really hard because it produces significant savings in execution time when, for example, a source file needs to be processed somehow and that file is referenced by multiple rules (handwave-handwave). This comes at the cost of some RAM: each instance of a shared action needs to be stored in memory separately.

If two actions generate the same output file, they must be exactly the same: have the same inputs, the same outputs and run the same command line. This equivalence relation is implemented in Actions.canBeShared() and it is verified between the analysis and execution phases by looking at every Action. This is implemented in SkyframeActionExecutor.findAndStoreArtifactConflicts() and is one of the few places in Bazel that requires a "global" view of the build.

The execution phase

This is when Bazel actually starts running build actions, such as commands that produce outputs.

The first thing Bazel does after the analysis phase is to determine what Artifacts need to be built. The logic for this is encoded in TopLevelArtifactHelper ; roughly speaking, it's the filesToBuild of the configured targets on the command line and the contents of a special output group for the explicit purpose of expressing "if this target is on the command line, build these artifacts".

The next step is creating the execution root. Since Bazel has the option to read source packages from different locations in the file system ( --package_path ), it needs to provide locally executed actions with a full source tree. This is handled by the class SymlinkForest and works by taking note of every target used in the analysis phase and building up a single directory tree that symlinks every package with a used target from its actual location. An alternative would be to pass the correct paths to commands (taking --package_path into account). This is undesirable because:

• It changes action command lines when a package is moved from a package path entry to another (used to be a common occurrence)
• It results in different command lines if an action is run remotely than if it's run locally
• It requires a command line transformation specific to the tool in use (consider the difference between such as Java classpaths and C++ include paths)
• Changing the command line of an action invalidates its action cache entry
• --package_path is slowly and steadily being deprecated

Then, Bazel starts traversing the action graph (the bipartite, directed graph composed of actions and their input and output artifacts) and running actions. The execution of each action is represented by an instance of the SkyValue class ActionExecutionValue .

Since running an action is expensive, we have a few layers of caching that can be hit behind Skyframe:

• ActionExecutionFunction.stateMap contains data to make Skyframe restarts of ActionExecutionFunction cheap
• The local action cache contains data about the state of the file system
• Remote execution systems usually also contain their own cache

The local action cache

This cache is another layer that sits behind Skyframe; even if an action is re-executed in Skyframe, it can still be a hit in the local action cache. It represents the state of the local file system and it's serialized to disk which means that when one starts up a new Bazel server, one can get local action cache hits even though the Skyframe graph is empty.

This cache is checked for hits using the method ActionCacheChecker.getTokenIfNeedToExecute() .

Contrary to its name, it's a map from the path of a derived artifact to the action that emitted it. The action is described as:

1. The set of its input and output files and their checksum
2. Its "action key", which is usually the command line that was executed, but in general, represents everything that's not captured by the checksum of the input files (such as for FileWriteAction , it's the checksum of the data that's written)

There is also a highly experimental “top-down action cache” that is still under development, which uses transitive hashes to avoid going to the cache as many times.

Input discovery and input pruning

Some actions are more complicated than just having a set of inputs. Changes to the set of inputs of an action come in two forms:

• An action may discover new inputs before its execution or decide that some of its inputs are not actually necessary. The canonical example is C++, where it's better to make an educated guess about what header files a C++ file uses from its transitive closure so that we don't heed to send every file to remote executors; therefore, we have an option not to register every header file as an "input", but scan the source file for transitively included headers and only mark those header files as inputs that are mentioned in #include statements (we overestimate so that we don't need to implement a full C preprocessor) This option is currently hard-wired to "false" in Bazel and is only used at Google.
• An action may realize that some files were not used during its execution. In C++, this is called ".d files": the compiler tells which header files were used after the fact, and in order to avoid the embarrassment of having worse incrementality than Make, Bazel makes use of this fact. This offers a better estimate than the include scanner because it relies on the compiler.

These are implemented using methods on Action:

1. Action.discoverInputs() is called. It should return a nested set of Artifacts that are determined to be required. These must be source artifacts so that there are no dependency edges in the action graph that don't have an equivalent in the configured target graph.
2. The action is executed by calling Action.execute() .
3. At the end of Action.execute() , the action can call Action.updateInputs() to tell Bazel that not all of its inputs were needed. This can result in incorrect incremental builds if a used input is reported as unused.

When an action cache returns a hit on a fresh Action instance (such as created after a server restart), Bazel calls updateInputs() itself so that the set of inputs reflects the result of input discovery and pruning done before.

Starlark actions can make use of the facility to declare some inputs as unused using the unused_inputs_list= argument of ctx.actions.run() .

Various ways to run actions: Strategies/ActionContexts

Some actions can be run in different ways. For example, a command line can be executed locally, locally but in various kinds of sandboxes, or remotely. The concept that embodies this is called an ActionContext (or Strategy , since we successfully went only halfway with a rename...)

The life cycle of an action context is as follows:

1. When the execution phase is started, BlazeModule instances are asked what action contexts they have. This happens in the constructor of ExecutionTool . Action context types are identified by a Java Class instance that refers to a sub-interface of ActionContext and which interface the action context must implement.
2. The appropriate action context is selected from the available ones and is forwarded to ActionExecutionContext and BlazeExecutor .
3. Actions request contexts using ActionExecutionContext.getContext() and BlazeExecutor.getStrategy() (there should really be only one way to do it…)

Strategies are free to call other strategies to do their jobs; this is used, for example, in the dynamic strategy that starts actions both locally and remotely, then uses whichever finishes first.

One notable strategy is the one that implements persistent worker processes ( WorkerSpawnStrategy ). The idea is that some tools have a long startup time and should therefore be reused between actions instead of starting one anew for every action (This does represent a potential correctness issue, since Bazel relies on the promise of the worker process that it doesn't carry observable state between individual requests)

If the tool changes, the worker process needs to be restarted. Whether a worker can be reused is determined by computing a checksum for the tool used using WorkerFilesHash . It relies on knowing which inputs of the action represent part of the tool and which represent inputs; this is determined by the creator of the Action: Spawn.getToolFiles() and the runfiles of the Spawn are counted as parts of the tool.

More information about strategies (or action contexts!):

• Information about various strategies for running actions is available here .
• Information about the dynamic strategy, one where we run an action both locally and remotely to see whichever finishes first is available here .
• Information about the intricacies of executing actions locally is available here .

The local resource manager

Bazel can run many actions in parallel. The number of local actions that should be run in parallel differs from action to action: the more resources an action requires, the less instances should be running at the same time to avoid overloading the local machine.

This is implemented in the class ResourceManager : each action has to be annotated with an estimate of the local resources it requires in the form of a ResourceSet instance (CPU and RAM). Then when action contexts do something that requires local resources, they call ResourceManager.acquireResources() and are blocked until the required resources are available.

A more detailed description of local resource management is available here .

The structure of the output directory

Each action requires a separate place in the output directory where it places its outputs. The location of derived artifacts is usually as follows:

$EXECROOT/bazel-out/<configuration>/bin/<package>/<artifact name>

How is the name of the directory that is associated with a particular configuration determined? There are two conflicting desirable properties:

1. If two configurations can occur in the same build, they should have different directories so that both can have their own version of the same action; otherwise, if the two configurations disagree about such as the command line of an action producing the same output file, Bazel doesn't know which action to choose (an "action conflict")
2. If two configurations represent "roughly" the same thing, they should have the same name so that actions executed in one can be reused for the other if the command lines match: for example, changes to the command line options to the Java compiler should not result in C++ compile actions being re-run.

So far, we have not come up with a principled way of solving this problem, which has similarities to the problem of configuration trimming. A longer discussion of options is available here . The main problematic areas are Starlark rules (whose authors usually aren't intimately familiar with Bazel) and aspects, which add another dimension to the space of things that can produce the "same" output file.

The current approach is that the path segment for the configuration is <CPU>-<compilation mode> with various suffixes added so that configuration transitions implemented in Java don't result in action conflicts. In addition, a checksum of the set of Starlark configuration transitions is added so that users can't cause action conflicts. It is far from perfect. This is implemented in OutputDirectories.buildMnemonic() and relies on each configuration fragment adding its own part to the name of the output directory.

Tests

Bazel has rich support for running tests. It supports:

• Running tests remotely (if a remote execution backend is available)
• Running tests multiple times in parallel (for deflaking or gathering timing data)
• Sharding tests (splitting test cases in same test over multiple processes for speed)
• Re-running flaky tests
• Grouping tests into test suites

Tests are regular configured targets that have a TestProvider, which describes how the test should be run:

• The artifacts whose building result in the test being run. This is a "cache status" file that contains a serialized TestResultData message
• The number of times the test should be run
• The number of shards the test should be split into
• Some parameters about how the test should be run (such as the test timeout)

Determining which tests to run

Determining which tests are run is an elaborate process.

First, during target pattern parsing, test suites are recursively expanded. The expansion is implemented in TestsForTargetPatternFunction . A somewhat surprising wrinkle is that if a test suite declares no tests, it refers to every test in its package. This is implemented in Package.beforeBuild() by adding an implicit attribute called $implicit_tests to test suite rules.

Then, tests are filtered for size, tags, timeout and language according to the command line options. This is implemented in TestFilter and is called from TargetPatternPhaseFunction.determineTests() during target parsing and the result is put into TargetPatternPhaseValue.getTestsToRunLabels() . The reason why rule attributes which can be filtered for are not configurable is that this happens before the analysis phase, therefore, the configuration is not available.

This is then processed further in BuildView.createResult() : targets whose analysis failed are filtered out and tests are split into exclusive and non-exclusive tests. It's then put into AnalysisResult , which is how ExecutionTool knows which tests to run.

In order to lend some transparency to this elaborate process, the tests() query operator (implemented in TestsFunction ) is available to tell which tests are run when a particular target is specified on the command line. It's unfortunately a reimplementation, so it probably deviates from the above in multiple subtle ways.

Running tests

The way the tests are run is by requesting cache status artifacts. This then results in the execution of a TestRunnerAction , which eventually calls the TestActionContext chosen by the --test_strategy command line option that runs the test in the requested way.

Tests are run according to an elaborate protocol that uses environment variables to tell tests what's expected from them. A detailed description of what Bazel expects from tests and what tests can expect from Bazel is available here . At the simplest, an exit code of 0 means success, anything else means failure.

In addition to the cache status file, each test process emits a number of other files. They are put in the "test log directory" which is the subdirectory called testlogs of the output directory of the target configuration:

• test.xml , a JUnit-style XML file detailing the individual test cases in the test shard
• test.log , the console output of the test. stdout and stderr are not separated.
• test.outputs , the "undeclared outputs directory"; this is used by tests that want to output files in addition to what they print to the terminal.

There are two things that can happen during test execution that cannot during building regular targets: exclusive test execution and output streaming.

Some tests need to be executed in exclusive mode, for example not in parallel with other tests. This can be elicited either by adding tags=["exclusive"] to the test rule or running the test with --test_strategy=exclusive . Each exclusive test is run by a separate Skyframe invocation requesting the execution of the test after the "main" build. This is implemented in SkyframeExecutor.runExclusiveTest() .

Unlike regular actions, whose terminal output is dumped when the action finishes, the user can request the output of tests to be streamed so that they get informed about the progress of a long-running test. This is specified by the --test_output=streamed command line option and implies exclusive test execution so that outputs of different tests are not interspersed.

This is implemented in the aptly-named StreamedTestOutput class and works by polling changes to the test.log file of the test in question and dumping new bytes to the terminal where Bazel rules.

Results of the executed tests are available on the event bus by observing various events (such as TestAttempt , TestResult or TestingCompleteEvent ). They are dumped to the Build Event Protocol and they are emitted to the console by AggregatingTestListener .

Coverage collection

Coverage is reported by the tests in LCOV format in the files bazel-testlogs/$PACKAGE/$TARGET/coverage.dat .

To collect coverage, each test execution is wrapped in a script called collect_coverage.sh .

This script sets up the environment of the test to enable coverage collection and determine where the coverage files are written by the coverage runtime(s). It then runs the test. A test may itself run multiple subprocesses and consist of parts written in multiple different programming languages (with separate coverage collection runtimes). The wrapper script is responsible for converting the resulting files to LCOV format if necessary, and merges them into a single file.

The interposition of collect_coverage.sh is done by the test strategies and requires collect_coverage.sh to be on the inputs of the test. This is accomplished by the implicit attribute :coverage_support which is resolved to the value of the configuration flag --coverage_support (see TestConfiguration.TestOptions.coverageSupport )

Some languages do offline instrumentation, meaning that the coverage instrumentation is added at compile time (such as C++) and others do online instrumentation, meaning that coverage instrumentation is added at execution time.

Another core concept is baseline coverage . This is the coverage of a library, binary, or test if no code in it was run. The problem it solves is that if you want to compute the test coverage for a binary, it is not enough to merge the coverage of all of the tests because there may be code in the binary that is not linked into any test. Therefore, what we do is to emit a coverage file for every binary which contains only the files we collect coverage for with no covered lines. The baseline coverage file for a target is at bazel-testlogs/$PACKAGE/$TARGET/baseline_coverage.dat . It is also generated for binaries and libraries in addition to tests if you pass the --nobuild_tests_only flag to Bazel.

Baseline coverage is currently broken.

We track two groups of files for coverage collection for each rule: the set of instrumented files and the set of instrumentation metadata files.

The set of instrumented files is just that, a set of files to instrument. For online coverage runtimes, this can be used at runtime to decide which files to instrument. It is also used to implement baseline coverage.

The set of instrumentation metadata files is the set of extra files a test needs to generate the LCOV files Bazel requires from it. In practice, this consists of runtime-specific files; for example, gcc emits .gcno files during compilation. These are added to the set of inputs of test actions if coverage mode is enabled.

Whether or not coverage is being collected is stored in the BuildConfiguration . This is handy because it is an easy way to change the test action and the action graph depending on this bit, but it also means that if this bit is flipped, all targets need to be re-analyzed (some languages, such as C++ require different compiler options to emit code that can collect coverage, which mitigates this issue somewhat, since then a re-analysis is needed anyway).

The coverage support files are depended on through labels in an implicit dependency so that they can be overridden by the invocation policy, which allows them to differ between the different versions of Bazel. Ideally, these differences would be removed, and we standardized on one of them.

We also generate a "coverage report" which merges the coverage collected for every test in a Bazel invocation. This is handled by CoverageReportActionFactory and is called from BuildView.createResult() . It gets access to the tools it needs by looking at the :coverage_report_generator attribute of the first test that is executed.

The query engine

Bazel has a little language used to ask it various things about various graphs. The following query kinds are provided:

• bazel query is used to investigate the target graph
• bazel cquery is used to investigate the configured target graph
• bazel aquery is used to investigate the action graph

Each of these is implemented by subclassing AbstractBlazeQueryEnvironment . Additional additional query functions can be done by subclassing QueryFunction . In order to allow streaming query results, instead of collecting them to some data structure, a query2.engine.Callback is passed to QueryFunction , which calls it for results it wants to return.

The result of a query can be emitted in various ways: labels, labels and rule classes, XML, protobuf and so on. These are implemented as subclasses of OutputFormatter .

A subtle requirement of some query output formats (proto, definitely) is that Bazel needs to emit _all _the information that package loading provides so that one can diff the output and determine whether a particular target has changed. As a consequence, attribute values need to be serializable, which is why there are only so few attribute types without any attributes having complex Starlark values. The usual workaround is to use a label, and attach the complex information to the rule with that label. It's not a very satisfying workaround and it would be very nice to lift this requirement.

The module system

Bazel can be extended by adding modules to it. Each module must subclass BlazeModule (the name is a relic of the history of Bazel when it used to be called Blaze) and gets information about various events during the execution of a command.

They are mostly used to implement various pieces of "non-core" functionality that only some versions of Bazel (such as the one we use at Google) need:

• Interfaces to remote execution systems
• New commands

The set of extension points BlazeModule offers is somewhat haphazard. Don't use it as an example of good design principles.

The event bus

The main way BlazeModules communicate with the rest of Bazel is by an event bus ( EventBus ): a new instance is created for every build, various parts of Bazel can post events to it and modules can register listeners for the events they are interested in. For example, the following things are represented as events:

• The list of build targets to be built has been determined ( TargetParsingCompleteEvent )
• The top-level configurations have been determined ( BuildConfigurationEvent )
• A target was built, successfully or not ( TargetCompleteEvent )
• A test was run ( TestAttempt , TestSummary )

Some of these events are represented outside of Bazel in the Build Event Protocol (they are BuildEvent s). This allows not only BlazeModule s, but also things outside the Bazel process to observe the build. They are accessible either as a file that contains protocol messages or Bazel can connect to a server (called the Build Event Service) to stream events.

This is implemented in the build.lib.buildeventservice and build.lib.buildeventstream Java packages.

External repositories

Whereas Bazel was originally designed to be used in a monorepo (a single source tree containing everything one needs to build), Bazel lives in a world where this is not necessarily true. "External repositories" are an abstraction used to bridge these two worlds: they represent code that is necessary for the build but is not in the main source tree.

The WORKSPACE file

The set of external repositories is determined by parsing the WORKSPACE file. For example, a declaration like this:

    local_repository(name="foo", path="/foo/bar")

Results in the repository called @foo being available. Where this gets complicated is that one can define new repository rules in Starlark files, which can then be used to load new Starlark code, which can be used to define new repository rules and so on…

To handle this case, the parsing of the WORKSPACE file (in WorkspaceFileFunction ) is split up into chunks delineated by load() statements. The chunk index is indicated by WorkspaceFileKey.getIndex() and computing WorkspaceFileFunction until index X means evaluating it until the Xth load() statement.

Fetching repositories

Before the code of the repository is available to Bazel, it needs to be fetched . This results in Bazel creating a directory under $OUTPUT_BASE/external/<repository name> .

Fetching the repository happens in the following steps:

1. PackageLookupFunction realizes that it needs a repository and creates a RepositoryName as a SkyKey , which invokes RepositoryLoaderFunction
2. RepositoryLoaderFunction forwards the request to RepositoryDelegatorFunction for unclear reasons (the code says it's to avoid re-downloading things in case of Skyframe restarts, but it's not a very solid reasoning)
3. RepositoryDelegatorFunction finds out the repository rule it's asked to fetch by iterating over the chunks of the WORKSPACE file until the requested repository is found
4. The appropriate RepositoryFunction is found that implements the repository fetching; it's either the Starlark implementation of the repository or a hard-coded map for repositories that are implemented in Java.

There are various layers of caching since fetching a repository can be very expensive:

1. There is a cache for downloaded files that is keyed by their checksum ( RepositoryCache ). This requires the checksum to be available in the WORKSPACE file, but that's good for hermeticity anyway. This is shared by every Bazel server instance on the same workstation, regardless of which workspace or output base they are running in.
2. A "marker file" is written for each repository under $OUTPUT_BASE/external that contains a checksum of the rule that was used to fetch it. If the Bazel server restarts but the checksum does not change, it's not re-fetched. This is implemented in RepositoryDelegatorFunction.DigestWriter .
3. The --distdir command line option designates another cache that is used to look up artifacts to be downloaded. This is useful in enterprise settings where Bazel should not fetch random things from the Internet. This is implemented by DownloadManager .

Once a repository is downloaded, the artifacts in it are treated as source artifacts. This poses a problem because Bazel usually checks for up-to-dateness of source artifacts by calling stat() on them, and these artifacts are also invalidated when the definition of the repository they are in changes. Thus, FileStateValue s for an artifact in an external repository need to depend on their external repository. This is handled by ExternalFilesHelper .

Managed directories

Sometimes, external repositories need to modify files under the workspace root (such as a package manager that houses the downloaded packages in a subdirectory of the source tree). This is at odds with the assumption Bazel makes that source files are only modified by the user and not by itself and allows packages to refer to every directory under the workspace root. In order to make this kind of external repository work, Bazel does two things:

1. Allows the user to specify subdirectories of the workspace Bazel is not allowed to reach into. They are listed in a file called .bazelignore and the functionality is implemented in BlacklistedPackagePrefixesFunction .
2. We encode the mapping from the subdirectory of the workspace to the external repository it is handled by into ManagedDirectoriesKnowledge and handle FileStateValue s referring to them in the same way as those for regular external repositories.

Repository mappings

It can happen that multiple repositories want to depend on the same repository, but in different versions (this is an instance of the "diamond dependency problem"). For example, if two binaries in separate repositories in the build want to depend on Guava, they will presumably both refer to Guava with labels starting @guava// and expect that to mean different versions of it.

Therefore, Bazel allows one to re-map external repository labels so that the string @guava// can refer to one Guava repository (such as @guava1// ) in the repository of one binary and another Guava repository (such as @guava2// ) the the repository of the other.

Alternatively, this can also be used to join diamonds. If a repository depends on @guava1// , and another depends on @guava2// , repository mapping allows one to re-map both repositories to use a canonical @guava// repository.

The mapping is specified in the WORKSPACE file as the repo_mapping attribute of individual repository definitions. It then appears in Skyframe as a member of WorkspaceFileValue , where it is plumbed to:

• Package.Builder.repositoryMapping which is used to transform label-valued attributes of rules in the package by RuleClass.populateRuleAttributeValues()
• Package.repositoryMapping which is used in the analysis phase (for resolving things like $(location) which are not parsed in the loading phase)
• BzlLoadFunction for resolving labels in load() statements

JNI bits

The server of Bazel is_ mostly _written in Java. The exception is the parts that Java cannot do by itself or couldn't do by itself when we implemented it. This is mostly limited to interaction with the file system, process control and various other low-level things.

The C++ code lives under src/main/native and the Java classes with native methods are:

• NativePosixFiles and NativePosixFileSystem
• ProcessUtils
• WindowsFileOperations and WindowsFileProcesses
• com.google.devtools.build.lib.platform

Console output

Emitting console output seems like a simple thing, but the confluence of running multiple processes (sometimes remotely), fine-grained caching, the desire to have a nice and colorful terminal output and having a long-running server makes it non-trivial.

Right after the RPC call comes in from the client, two RpcOutputStream instances are created (for stdout and stderr) that forward the data printed into them to the client. These are then wrapped in an OutErr (an (stdout, stderr) pair). Anything that needs to be printed on the console goes through these streams. Then these streams are handed over to BlazeCommandDispatcher.execExclusively() .

Output is by default printed with ANSI escape sequences. When these are not desired ( --color=no ), they are stripped by an AnsiStrippingOutputStream . In addition, System.out and System.err are redirected to these output streams. This is so that debugging information can be printed using System.err.println() and still end up in the terminal output of the client (which is different from that of the server). Care is taken that if a process produces binary output (such as bazel query --output=proto ), no munging of stdout takes place.

Short messages (errors, warnings and the like) are expressed through the EventHandler interface. Notably, these are different from what one posts to the EventBus (this is confusing). Each Event has an EventKind (error, warning, info, and a few others) and they may have a Location (the place in the source code that caused the event to happen).

Some EventHandler implementations store the events they received. This is used to replay information to the UI caused by various kinds of cached processing, for example, the warnings emitted by a cached configured target.

Some EventHandler s also allow posting events that eventually find their way to the event bus (regular Event s do _not _appear there). These are implementations of ExtendedEventHandler and their main use is to replay cached EventBus events. These EventBus events all implement Postable , but not everything that is posted to EventBus necessarily implements this interface; only those that are cached by an ExtendedEventHandler (it would be nice and most of the things do; it's not enforced, though)

Terminal output is mostly emitted through UiEventHandler , which is responsible for all the fancy output formatting and progress reporting Bazel does. It has two inputs:

• The event bus
• The event stream piped into it through Reporter

The only direct connection the command execution machinery (for example the rest of Bazel) has to the RPC stream to the client is through Reporter.getOutErr() , which allows direct access to these streams. It's only used when a command needs to dump large amounts of possible binary data (such as bazel query ).

Profiling Bazel

Bazel is fast. Bazel is also slow, because builds tend to grow until just the edge of what's bearable. For this reason, Bazel includes a profiler which can be used to profile builds and Bazel itself. It's implemented in a class that's aptly named Profiler . It's turned on by default, although it records only abridged data so that its overhead is tolerable; The command line --record_full_profiler_data makes it record everything it can.

It emits a profile in the Chrome profiler format; it's best viewed in Chrome. It's data model is that of task stacks: one can start tasks and end tasks and they are supposed to be neatly nested within each other. Each Java thread gets its own task stack. TODO: How does this work with actions and continuation-passing style?

The profiler is started and stopped in BlazeRuntime.initProfiler() and BlazeRuntime.afterCommand() respectively and attempts to be live for as long as possible so that we can profile everything. To add something to the profile, call Profiler.instance().profile() . It returns a Closeable , whose closure represents the end of the task. It's best used with try-with-resources statements.

We also do rudimentary memory profiling in MemoryProfiler . It's also always on and it mostly records maximum heap sizes and GC behavior.

Testing Bazel

Bazel has two main kinds of tests: ones that observe Bazel as a "black box" and ones that only run the analysis phase. We call the former "integration tests" and the latter "unit tests", although they are more like integration tests that are, well, less integrated. We also have some actual unit tests, where they are necessary.

Of integration tests, we have two kinds:

1. Ones implemented using a very elaborate bash test framework under src/test/shell
2. Ones implemented in Java. These are implemented as subclasses of BuildIntegrationTestCase

BuildIntegrationTestCase is the preferred integration testing framework as it is well-equipped for most testing scenarios. As it is a Java framework, it provides debuggability and seamless integration with many common development tools. There are many examples of BuildIntegrationTestCase classes in the Bazel repository.

Analysis tests are implemented as subclasses of BuildViewTestCase . There is a scratch file system you can use to write BUILD files, then various helper methods can request configured targets, change the configuration and assert various things about the result of the analysis.