مرجع پرس و جو بازل

این صفحه راهنمای زبان پرس و جو Bazel است که هنگام استفاده از bazel query برای تجزیه و تحلیل وابستگی های ساخت استفاده می شود. همچنین فرمت‌های خروجی را که bazel query پشتیبانی می‌کند، توضیح می‌دهد.

برای موارد استفاده عملی، به نحوه پرس و جو Bazel مراجعه کنید.

مرجع درخواست اضافی

Bazel علاوه بر query ، که بر روی نمودار هدف فاز پس از بارگذاری اجرا می شود، شامل پرس و جو گراف عمل و پرس و جوی قابل تنظیم است.

پرس و جو نمودار اقدام

پرس و جو گراف کنش ( aquery ) بر روی نمودار هدف پیکربندی شده پس از تجزیه و تحلیل عمل می کند و اطلاعات مربوط به Actions ، مصنوعات و روابط آنها را در معرض دید قرار می دهد. aquery زمانی مفید است که به ویژگی‌های Actions/Artifacts تولید شده از نمودار هدف پیکربندی شده علاقه دارید. برای مثال، دستورات واقعی اجرا می‌شوند و ورودی‌ها، خروجی‌ها و یادداشت‌های آن‌ها.

برای جزئیات بیشتر، به مرجع استعلام مراجعه کنید.

پرس و جو قابل تنظیم

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

برای جزئیات بیشتر، به مرجع cquery مراجعه کنید.

مثال ها

مردم چگونه از bazel query استفاده می کنند؟ در اینجا نمونه های معمولی وجود دارد:

چرا درخت //foo به //bar/baz بستگی دارد؟ نشان دادن یک مسیر:

somepath(foo/..., //bar/baz:all)

تمام تست‌های foo به چه کتابخانه‌های C++ بستگی دارد که هدف foo_bin به آن وابسته نیست؟

kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin))

نشانه ها: نحو واژگانی

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

• کلمات کلیدی مانند let . کلمات کلیدی کلمات رزرو شده زبان هستند و هر یک از آنها در زیر توضیح داده شده است. مجموعه کامل کلمات کلیدی عبارتند از:

  • except

  • in

  • intersect

  • let

  • set

  • union

• کلماتی مانند " foo/... " یا " .*test rule " یا " //bar/baz:all ". اگر یک دنباله کاراکتر "نقل شده" باشد (با یک نقل قول تکی شروع و پایان می یابد یا با یک نقل قول دوگانه شروع می شود و به پایان می رسد)، یک کلمه است. اگر یک دنباله کاراکتر نقل قول نشده باشد، ممکن است همچنان به عنوان یک علامت تجزیه شود. واژه های نقل قول نشده دنباله ای از نویسه ها هستند که از حروف الفبای A-Za-z، اعداد 0-9، و نویسه های خاص */@.-_:$~[] (ستاره، اسلش جلو، در، نقطه، خط تیره، زیرخط، دو نقطه، علامت دلار، * - مربع چپ، مربع راست نام ها) ممکن است با آن شخصیت ها شروع شود.

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

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

   //foo:bar+wiz    # WRONG: scanned as //foo:bar + wiz.
   //foo:bar=wiz    # WRONG: scanned as //foo:bar = wiz.
   "//foo:bar+wiz"  # OK.
   "//foo:bar=wiz"  # OK.
  

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

  bazel query ' "//foo:bar=wiz" '   # single-quotes for shell, double-quotes for Bazel.
  

  کلمات کلیدی، هنگامی که نقل قول می شوند، به عنوان کلمات عادی در نظر گرفته می شوند. به عنوان مثال، some یک کلمه کلیدی است اما "بعضی" یک کلمه است. فوو و foo هر دو کلمه هستند.

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

  در زیر نمونه هایی از اینکه رشته پرس و جوی جاوا چه خواهد بود آورده شده است:

    'a"'a'         # WRONG: Error message: unclosed quotation.
    "a'"a"         # WRONG: Error message: unclosed quotation.
    '"a" + 'a''    # WRONG: Error message: unexpected token 'a' after query expression '"a" + '
    "'a' + "a""    # WRONG: Error message: unexpected token 'a' after query expression ''a' + '
    "a'a"          # OK.
    'a"a'          # OK.
    '"a" + "a"'    # OK
    "'a' + 'a'"    # OK
  

  ما این نحو را انتخاب کردیم تا علامت نقل قول در بیشتر موارد مورد نیاز نباشد. مثال (غیر معمول) ".*test rule" به نقل قول نیاز دارد: با نقطه شروع می شود و حاوی یک فاصله است. نقل قول "cc_library" غیر ضروری اما بی ضرر است.

• علائم نگارشی مانند واژگان () نقطه . و کاما , . کلمات حاوی علائم نگارشی (غیر از استثناهای ذکر شده در بالا) باید نقل قول شوند.

کاراکترهای فضای خالی خارج از یک کلمه نقل قول نادیده گرفته می شوند.

مفاهیم زبان پرس و جو بازل

زبان پرس و جو Bazel زبان عبارات است. هر عبارت به مجموعه ای از اهداف تا حدی مرتب شده یا به طور معادل، یک نمودار (DAG) از اهداف ارزیابی می شود. این تنها نوع داده است.

مجموعه و نمودار به یک نوع داده اشاره دارد، اما بر جنبه های مختلف آن تأکید می کند، به عنوان مثال:

• مجموعه: ترتیب جزئی اهداف جالب نیست.
• نمودار: ترتیب جزئی اهداف قابل توجه است.

چرخه ها در نمودار وابستگی

نمودارهای وابستگی ساخت باید غیر چرخه ای باشند.

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

وابستگی های ضمنی

علاوه بر ساخت وابستگی هایی که به صراحت در فایل های BUILD تعریف شده اند، Bazel وابستگی های ضمنی اضافی را به قوانین اضافه می کند. برای مثال هر قانون جاوا به طور ضمنی به JavaBuilder بستگی دارد. وابستگی های ضمنی با استفاده از ویژگی هایی ایجاد می شوند که با $ شروع می شوند و نمی توان آنها را در فایل های BUILD لغو کرد.

در پرس و جوی پیش فرض bazel query ، هنگام محاسبه نتیجه پرس و جو، وابستگی های ضمنی را در نظر می گیرد. این رفتار را می توان با گزینه --[no]implicit_deps تغییر داد. توجه داشته باشید که از آنجایی که پرس و جو پیکربندی ها را در نظر نمی گیرد، زنجیره های ابزار بالقوه هرگز در نظر گرفته نمی شوند.

سلامتی

عبارات زبان پرس و جو Bazel روی گراف وابستگی ساخت کار می کنند، که گرافی است که به طور ضمنی توسط همه اعلانات قوانین در همه فایل های BUILD تعریف شده است. درک این نکته مهم است که این نمودار تا حدودی انتزاعی است و توصیف کاملی از نحوه انجام تمام مراحل ساخت را تشکیل نمی دهد. برای انجام یک ساخت، یک پیکربندی نیز لازم است. برای جزئیات بیشتر به بخش تنظیمات راهنمای کاربر مراجعه کنید.

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

در مورد حفظ ترتیب نمودار

عملیات هر گونه محدودیت نظم دهی به ارث رسیده از عبارت های فرعی خود را حفظ می کند. شما می توانید این را به عنوان "قانون حفظ نظم جزئی" در نظر بگیرید. یک مثال را در نظر بگیرید: اگر یک پرس و جو برای تعیین بسته شدن گذرای وابستگی های یک هدف خاص صادر کنید، مجموعه حاصل مطابق نمودار وابستگی مرتب می شود. اگر آن مجموعه را فیلتر کنید تا فقط اهداف نوع file را شامل شود، همان رابطه ترتیب جزئی گذرا بین هر جفت هدف در زیرمجموعه حاصل برقرار می‌شود - حتی اگر هیچ یک از این جفت‌ها به طور مستقیم در گراف اصلی متصل نشده باشند. (هیچ لبه فایل-فایل در گراف وابستگی ساخت وجود ندارد).

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

deps(x) union y

ترتیب مجموعه نتیجه نهایی تضمین می شود که تمام محدودیت های ترتیب عبارت های فرعی خود را حفظ کند، یعنی اینکه تمام وابستگی های x نسبت به یکدیگر به درستی مرتب شده اند. با این حال، پرس و جو هیچ تضمینی در مورد ترتیب اهداف در y ، و نه در مورد ترتیب اهداف در deps(x) نسبت به اهداف در y (به جز آن دسته از اهداف در y که اتفاقاً در deps(x) نیز هستند) را تضمین نمی کند. .

اپراتورهایی که محدودیت‌های سفارش را معرفی می‌کنند عبارتند از: allpaths ، deps ، rdeps ، somepath ، و پکیج عام الگوی هدف package:* ، dir/... ، و غیره.

پرس و جو آسمان

Sky Query حالتی از پرس و جو است که در یک محدوده جهانی مشخص عمل می کند.

توابع ویژه فقط در SkyQuery موجود است

حالت Sky Query دارای توابع پرس و جو اضافی allrdeps و rbuildfiles است. این توابع در کل محدوده جهان عمل می کنند (به همین دلیل است که برای Query عادی معنی ندارند).

تعیین محدوده جهان

حالت Sky Query با عبور از دو پرچم زیر فعال می شود: ( --universe_scope یا --infer_universe_scope ) و --order_output=no . --universe_scope=<target_pattern1>,...,<target_patternN> به query می‌گوید بسته شدن متعدی الگوی هدف مشخص شده توسط الگوهای هدف را از قبل بارگذاری کند، که می‌تواند هم افزایشی و هم کاهشی باشد. سپس همه پرس و جوها در این "محدوده" ارزیابی می شوند. به طور خاص، allrdeps و rbuildfiles فقط نتایج این محدوده را برمی‌گردانند. --infer_universe_scope به Bazel می گوید که مقداری را برای --universe_scope از عبارت query استنتاج کند. این مقدار استنباط شده لیستی از الگوهای هدف منحصر به فرد در عبارت پرس و جو است، اما ممکن است آن چیزی نباشد که شما می خواهید. مثلا:

bazel query --infer_universe_scope --order_output=no "allrdeps(//my:target)"

لیست الگوهای هدف منحصربه‌فرد در این عبارت پرس و جو ["//my:target"] است، بنابراین Bazel با این مورد همانند فراخوان رفتار می‌کند:

bazel query --universe_scope=//my:target --order_output=no "allrdeps(//my:target)"

اما نتیجه آن پرس و جو با --universe_scope فقط //my:target ; هیچ یک از وابستگی های معکوس //my:target در جهان نیست، بر اساس ساخت! از سوی دیگر، در نظر بگیرید:

bazel query --infer_universe_scope --order_output=no "tests(//a/... + b/...) intersect allrdeps(siblings(rbuildfiles(my/starlark/file.bzl)))"

این یک فراخوانی پرس و جو معنادار است که سعی می کند اهداف آزمایشی را در بسط tests اهداف تحت برخی دایرکتوری ها محاسبه کند که به طور موقت به اهدافی که تعریف آنها از یک فایل .bzl خاص استفاده می کند بستگی دارد. در اینجا، --infer_universe_scope راحت است، به خصوص در مواردی که انتخاب --universe_scope در غیر این صورت مستلزم آن است که خودتان عبارت پرس و جو را تجزیه کنید.

بنابراین، برای عبارت‌های پرس و جو که از عملگرهایی با دامنه جهانی مانند allrdeps و rbuildfiles استفاده می‌کنند، حتماً از --infer_universe_scope فقط در صورتی استفاده کنید که رفتار آن همان چیزی باشد که شما می‌خواهید.

Sky Query در مقایسه با پرس و جوی پیش فرض دارای مزایا و معایبی است. عیب اصلی این است که نمی تواند خروجی خود را مطابق با ترتیب نمودار ترتیب دهد و بنابراین فرمت های خروجی خاصی ممنوع است. مزایای آن این است که دو عملگر ( allrdeps و rbuildfiles ) را ارائه می دهد که در کوئری پیش فرض موجود نیستند. همچنین، Sky Query کار خود را با بررسی درونی گراف Skyframe انجام می دهد، به جای ایجاد یک نمودار جدید، کاری که پیاده سازی پیش فرض انجام می دهد. بنابراین، شرایطی وجود دارد که سرعت آن بیشتر است و از حافظه کمتری استفاده می کند.

عبارات: نحو و معناشناسی دستور زبان

این گرامر زبان پرس و جو Bazel است که با نماد EBNF بیان می شود:

expr ::= word
       | let name = expr in expr
       | (expr)
       | expr intersect expr
       | expr ^ expr
       | expr union expr
       | expr + expr
       | expr except expr
       | expr - expr
       | set(word *)
       | word '(' int | word | expr ... ')'

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

الگوهای هدف

expr ::= word

از نظر نحوی، یک الگوی هدف فقط یک کلمه است. این به عنوان مجموعه ای (نامرتب) از اهداف تفسیر می شود. ساده ترین الگوی هدف یک برچسب است که یک هدف واحد (فایل یا قانون) را مشخص می کند. به عنوان مثال، الگوی هدف //foo:bar به مجموعه ای شامل یک عنصر، هدف، قانون bar ارزیابی می شود.

الگوهای هدف، برچسب‌ها را تعمیم می‌دهند تا حروف عام را روی بسته‌ها و اهداف قرار دهند. به عنوان مثال، foo/...:all (یا فقط foo/... ) یک الگوی هدف است که به مجموعه‌ای شامل تمام قوانین موجود در هر بسته به صورت بازگشتی در زیر دایرکتوری foo ارزیابی می‌شود. bar/baz:all یک الگوی هدف است که به مجموعه‌ای شامل تمام قوانین بسته bar/baz ، اما نه بسته‌های فرعی آن، ارزیابی می‌شود.

به طور مشابه، foo/...:* یک الگوی هدف است که به مجموعه‌ای شامل تمام اهداف (قوانین و فایل‌ها) در هر بسته به صورت بازگشتی در زیر دایرکتوری foo ارزیابی می‌شود. bar/baz:* به مجموعه‌ای ارزیابی می‌کند که شامل تمام اهداف در بسته bar/baz است، اما نه بسته‌های فرعی آن.

از آنجایی که عام :* با فایل ها و همچنین قوانین مطابقت دارد، اغلب برای پرس و جوها از :all مفیدتر است. برعکس، علامت :all (ضمنی در الگوهای هدف مانند foo/... ) معمولاً برای ساخت‌ها مفیدتر است.

الگوهای هدف bazel query مانند اهداف ساخت bazel build کار می کنند. برای جزئیات بیشتر، الگوهای هدف را ببینید یا bazel help target-syntax تایپ کنید.

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

همه گره‌ها در نتیجه یک عبارت الگوی هدف به درستی نسبت به یکدیگر مطابق با رابطه وابستگی مرتب شده‌اند. بنابراین، نتیجه foo:* فقط مجموعه ای از اهداف در بسته foo نیست، بلکه نمودار روی آن اهداف نیز می باشد. (هیچ تضمینی در مورد ترتیب نسبی گره های نتیجه در برابر سایر گره ها وجود ندارد.) برای جزئیات بیشتر، به بخش ترتیب نمودار مراجعه کنید.

متغیرها

expr ::= let name = expr1 in expr2
       | $name

زبان پرس و جو Bazel اجازه تعاریف و ارجاع به متغیرها را می دهد. نتیجه ارزیابی یک عبارت let مانند expr ₂ است، با تمام رخدادهای آزاد name متغیر با مقدار expr ₁ جایگزین می شود.

به عنوان مثال، let v = foo/... in allpaths($v, //common) intersect $v است با allpaths(foo/...,//common) intersect foo/... .

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

در تولیدات گرامر فوق، name مانند کلمه است ، اما با محدودیت اضافی که یک شناسه قانونی در زبان برنامه نویسی C باشد. ارجاع به متغیر باید با کاراکتر "$" اضافه شود.

هر عبارت let فقط یک متغیر منفرد را تعریف می کند، اما شما می توانید آنها را تودرتو کنید.

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

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

عبارات پرانتز شده

expr ::= (expr)

پرانتزها عبارت‌های فرعی را به هم مرتبط می‌کنند تا ترتیب ارزیابی را وادار کنند. یک عبارت پرانتز شده ارزش آرگومان خود را ارزیابی می کند.

عملیات مجموعه جبری: تقاطع، اتحاد، اختلاف مجموعه

expr ::= expr intersect expr
       | expr ^ expr
       | expr union expr
       | expr + expr
       | expr except expr
       | expr - expr

این سه عملگر عملیات مجموعه معمولی را روی آرگومان های خود محاسبه می کنند. هر عملگر دو شکل دارد، یک شکل اسمی، مانند intersect ، و یک شکل نمادین، مانند ^ . هر دو شکل معادل هستند. فرم های نمادین سریعتر تایپ می شوند. (برای وضوح، بقیه این صفحه از فرم های اسمی استفاده می کند.)

مثلا،

foo/... except foo/bar/...

به مجموعه اهدافی که با foo/... مطابقت دارند ارزیابی می کند اما foo/bar/... را ندارد.

می توانید همان پرس و جو را بنویسید:

foo/... - foo/bar/...

عملیات intersect ( ^ ) و union ( + ) جابجایی (متقارن) هستند. except ( - ) نامتقارن است. تجزیه کننده هر سه عملگر را به عنوان سمت چپ و دارای اولویت یکسان در نظر می گیرد، بنابراین ممکن است پرانتز بخواهید. به عنوان مثال، دو مورد اول از این عبارت معادل هستند، اما سومی معادل نیست:

x intersect y union z
(x intersect y) union z
x intersect (y union z)

خواندن اهداف از منبع خارجی: تنظیم کنید

expr ::= set(word *)

عملگر set( a b c ...) اتحاد مجموعه ای از الگوهای هدف صفر یا بیشتر را محاسبه می کند که با فاصله سفید (بدون کاما) از هم جدا شده اند.

در ارتباط با ویژگی $(...) پوسته Bourne، set() وسیله ای برای ذخیره نتایج یک پرس و جو در یک فایل متنی معمولی، دستکاری آن فایل متنی با استفاده از برنامه های دیگر (مانند ابزارهای پوسته استاندارد یونیکس) و سپس نتیجه را به عنوان یک مقدار برای پردازش بیشتر به ابزار پرس و جو معرفی کنید. مثلا:

bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo
bazel query "kind(cc_binary, set($(<foo)))"

در مثال بعدی، kind(cc_library, deps(//some_dir/foo:main, 5)) با فیلتر کردن مقادیر maxrank با استفاده از یک برنامه awk محاسبه می‌شود.

bazel query 'deps(//some_dir/foo:main)' --output maxrank | awk '($1 < 5) { print $2;} ' > foo
bazel query "kind(cc_library, set($(<foo)))"

در این مثال‌ها، $(<foo) $(cat foo) است، اما دستورات پوسته‌ای غیر از cat نیز ممکن است استفاده شوند - مانند دستور awk قبلی.

کارکرد

expr ::= word '(' int | word | expr ... ')'

زبان پرس و جو چندین تابع را تعریف می کند. نام تابع تعداد و نوع آرگومان های مورد نیاز آن را تعیین می کند. توابع زیر در دسترس هستند:

• allpaths
• attr
• buildfiles
• rbuildfiles
• deps
• filter
• kind
• labels
• loadfiles
• rdeps
• allrdeps
• same_pkg_direct_rdeps
• siblings
• some
• somepath
• tests
• visible

بسته شدن انتقالی وابستگی ها: deps

expr ::= deps(expr)
       | deps(expr, depth)

عملگر deps( x ) نموداری را که با بسته شدن گذرای وابستگی های مجموعه آرگومان x تشکیل شده است ارزیابی می کند. به عنوان مثال، مقدار deps(//foo) نمودار وابستگی است که در گره تکی foo ، شامل تمام وابستگی‌های آن ریشه دارد. مقدار deps(foo/...) گراف‌های وابستگی است که ریشه‌های آن‌ها همه قوانین در هر بسته زیر دایرکتوری foo هستند. در این زمینه، "وابستگی ها" فقط به معنای قوانین و اهداف فایل است، بنابراین فایل های BUILD و Starlark مورد نیاز برای ایجاد این اهداف در اینجا گنجانده نشده اند. برای این کار باید از عملگر buildfiles استفاده کنید.

نمودار حاصل بر اساس رابطه وابستگی مرتب می شود. برای جزئیات بیشتر، به بخش ترتیب نمودار مراجعه کنید.

عملگر deps آرگومان دوم اختیاری را می پذیرد، که یک عدد صحیح واقعی است که کران بالایی را در عمق جستجو مشخص می کند. بنابراین deps(foo:*, 0) همه اهداف موجود در بسته foo را برمی‌گرداند، در حالی که deps(foo:*, 1) شامل پیش‌نیازهای مستقیم هر هدف در بسته foo می‌شود و deps(foo:*, 2) بیشتر شامل می‌شود. گره‌هایی که مستقیماً از گره‌های موجود در عمق قابل دسترسی هستند deps(foo:*, 1) و غیره. (این اعداد با رتبه های نشان داده شده در قالب خروجی minrank .) اگر پارامتر depth حذف شود، جستجو نامحدود است: بسته شدن گذرای بازتابی پیش نیازها را محاسبه می کند.

بسته شدن موقت وابستگی های معکوس: rdeps

expr ::= rdeps(expr, expr)
       | rdeps(expr, expr, depth)

rdeps( u , x ) وابستگی های معکوس آرگومان مجموعه x را در بسته شدن انتقالی مجموعه u ارزیابی می کند.

نمودار حاصل بر اساس رابطه وابستگی مرتب می شود. برای جزئیات بیشتر به بخش ترتیب نمودار مراجعه کنید.

عملگر rdeps آرگومان سوم اختیاری را می پذیرد، که یک عدد صحیح واقعی است که کران بالایی را در عمق جستجو مشخص می کند. نمودار حاصل فقط شامل گره هایی در فاصله ای از عمق مشخص شده از هر گره در مجموعه آرگومان است. بنابراین rdeps(//foo, //common, 1) به همه گره‌هایی در بسته شدن انتقالی //foo که مستقیماً به //common بستگی دارند ارزیابی می‌کند. (این اعداد با رتبه های نشان داده شده در قالب خروجی minrank .) اگر پارامتر depth حذف شود، جستجو نامحدود است.

بسته شدن گذرا همه وابستگی های معکوس: allrdeps

expr ::= allrdeps(expr)
       | allrdeps(expr, depth)

عملگر allrdeps درست مانند عملگر rdeps رفتار می کند، با این تفاوت که "جهت مجموعه" به جای اینکه به طور جداگانه مشخص شود، هر چیزی است که پرچم --universe_scope به آن ارزیابی می شود. بنابراین، اگر --universe_scope=//foo/... تصویب شد، آنگاه allrdeps(//bar) معادل rdeps(//foo/..., //bar) است.

وابستگی های معکوس مستقیم در همان بسته: same_pkg_direct_rdeps

expr ::= same_pkg_direct_rdeps(expr)

same_pkg_direct_rdeps( x ) مجموعه کاملی از اهداف را ارزیابی می‌کند که در همان بسته هدف در مجموعه آرگومان قرار دارند و مستقیماً به آن بستگی دارند.

برخورد با بسته هدف: خواهر و برادر

expr ::= siblings(expr)

عملگر siblings siblings( x ) به مجموعه کامل اهدافی که در همان بسته هدف در مجموعه آرگومان قرار دارند، ارزیابی می کند.

انتخاب خودسرانه: برخی

expr ::= some(expr)
       | some(expr, count )

عملگر some( x , k ) حداکثر k هدف را به طور دلخواه از مجموعه آرگومان x خود انتخاب می کند و مجموعه ای را که فقط شامل آن اهداف است ارزیابی می کند. پارامتر k اختیاری است. در صورت عدم وجود، نتیجه یک مجموعه تک تنه خواهد بود که فقط یک هدف را به صورت دلخواه انتخاب کرده است. اگر اندازه مجموعه آرگومان x کوچکتر از k ، کل مجموعه آرگومان x برگردانده می شود.

برای مثال، عبارت some(//foo:main union //bar:baz) به مجموعه‌ای تک‌تنه‌ای شامل //foo:main یا //bar:baz ارزیابی می‌شود – هرچند کدام یک تعریف نشده است. عبارت some(//foo:main union //bar:baz, 2) یا some(//foo:main union //bar:baz, 3) هر دو //foo:main و //bar:baz را برمی گرداند.

اگر آرگومان تکی باشد، some تابع هویت را محاسبه می‌کنند: some(//foo:main) معادل //foo:main است.

اگر مجموعه آرگومان مشخص شده خالی باشد، مانند عبارت some(//foo:main intersect //bar:baz) یک خطا است.

عملگرهای مسیر: somepath، allpaths

expr ::= somepath(expr, expr)
       | allpaths(expr, expr)

عملگرهای Somepath(S somepath( S , E ) و allpaths( S , E ) مسیرهای بین دو مجموعه هدف را محاسبه می کنند. هر دو پرس و جو دو آرگومان را می پذیرند، یک مجموعه S از نقاط شروع و یک مجموعه E از نقاط پایانی. somepath گراف گره‌ها را در مسیر دلخواه از یک هدف در S به یک هدف در E برمی‌گرداند. allpaths نمودار گره‌ها را در تمام مسیرها از هر هدف در S به هر هدف در E برمی‌گرداند.

نمودارهای به دست آمده بر اساس رابطه وابستگی مرتب شده اند. برای جزئیات بیشتر به بخش ترتیب نمودار مراجعه کنید.

نوع هدف فیلترینگ: نوع

expr ::= kind(word, expr)

عملگر kind( pattern , input ) یک فیلتر را برای مجموعه‌ای از اهداف اعمال می‌کند و اهدافی را که از نوع مورد انتظار نیستند دور می‌اندازد. پارامتر pattern مشخص می کند که چه نوع هدفی باید مطابقت داشته باشد.

به عنوان مثال، انواع چهار هدف تعریف شده توسط فایل BUILD (برای بسته p ) نشان داده شده در زیر در جدول نشان داده شده است:

        genrule(
            name = "a",
            srcs = ["a.in"],
            outs = ["a.out"],
            cmd = "...",
        )
      

بنابراین، kind("cc_.* rule", foo/...) به مجموعه همه cc_library ، cc_binary و غیره، اهداف قانون زیر foo و kind("source file", deps(//foo)) ارزیابی می‌کند. به مجموعه ای از تمام فایل های منبع در بسته شدن انتقالی وابستگی های هدف //foo .

نقل قول pattern آرگومان اغلب مورد نیاز است زیرا بدون آن، بسیاری از عبارات منظم ، مانند source file و .*_test ، توسط تجزیه کننده کلمات در نظر گرفته نمی شوند.

هنگام تطبیق برای package group ، اهدافی که به :all ختم می شوند ممکن است هیچ نتیجه ای نداشته باشند. به جای آن از :all-targets استفاده کنید.

فیلتر نام هدف: فیلتر

expr ::= filter(word, expr)

عملگر filter( pattern , input ) یک فیلتر را برای مجموعه‌ای از اهداف اعمال می‌کند و اهدافی را که برچسب‌های آنها (به صورت مطلق) با الگو مطابقت ندارد، دور می‌اندازد. آن را به زیر مجموعه ای از ورودی خود ارزیابی می کند.

اولین آرگومان، pattern ، کلمه ای است که شامل یک عبارت منظم روی نام هدف است. یک عبارت filter به مجموعه ای شامل تمام اهداف x ارزیابی می شود به طوری که x عضوی از input مجموعه است و برچسب (به شکل مطلق، مانند //foo:bar ) x حاوی یک تطابق (بدون پیوست) برای pattern عبارت منظم است. . از آنجایی که همه نام‌های هدف با // شروع می‌شوند، ممکن است به عنوان جایگزینی برای لنگر عبارت منظم ^ استفاده شود.

این عملگر اغلب یک جایگزین بسیار سریعتر و قوی تر برای عملگر intersect ارائه می دهد. به عنوان مثال، برای مشاهده تمام وابستگی های bar هدف //foo:foo ، می توان ارزیابی کرد

deps(//foo) intersect //bar/...

با این حال، این عبارت به تجزیه همه فایل‌های BUILD در درخت bar نیاز دارد، که کند و مستعد خطا در فایل‌های BUILD نامربوط خواهد بود. یک جایگزین خواهد بود:

filter(//bar, deps(//foo))

که ابتدا مجموعه وابستگی های //foo را محاسبه می کند و سپس فقط اهدافی را که با الگوی ارائه شده مطابقت دارند فیلتر می کند - به عبارت دیگر، اهدافی با نام های حاوی //bar به عنوان یک رشته فرعی.

یکی دیگر از کاربردهای متداول عملگر filter( pattern , expr ) فیلتر کردن فایل های خاص با نام یا پسوند آنهاست. مثلا،

filter("\.cc$", deps(//foo))

لیستی از تمام فایل های .cc مورد استفاده برای ساخت //foo را ارائه می دهد.

فیلتر کردن ویژگی قانون: attr

expr ::= attr(word, word, expr)

عملگر attr( name , pattern , input ) یک فیلتر را روی مجموعه‌ای از اهداف اعمال می‌کند، و اهدافی را که قانون نیستند، اهداف قوانینی که name مشخصه ندارند یا اهداف قانون را که در آن مقدار مشخصه با استاندارد ارائه شده مطابقت ندارد، کنار می‌گذارد . pattern بیان ; آن را به زیر مجموعه ای از ورودی خود ارزیابی می کند.

اولین آرگومان، name نام ویژگی قانون است که باید با الگوی عبارت منظم ارائه شده مطابقت داشته باشد. آرگومان دوم، pattern یک عبارت منظم بر روی مقادیر ویژگی است. یک عبارت attr به مجموعه‌ای که شامل تمام اهداف x است، ارزیابی می‌کند، به طوری که x عضوی از input مجموعه است، یک قانون با name مشخصه تعریف‌شده است و مقدار مشخصه حاوی یک تطابق (بدون لنگر) برای pattern عبارت منظم است. اگر name یک ویژگی اختیاری است و قانون آن را به صراحت مشخص نمی کند، از مقدار ویژگی پیش فرض برای مقایسه استفاده می شود. مثلا،

attr(linkshared, 0, deps(//foo))

همه وابستگی های //foo را که مجاز به داشتن یک ویژگی linkshared هستند (مانند cc_binary rule) انتخاب می کند و آن را به صراحت روی 0 تنظیم می کند یا اصلاً آن را تنظیم نمی کند اما مقدار پیش فرض 0 است (مانند قوانین cc_binary ).

ویژگی‌های نوع فهرست (مانند srcs ، data ، و غیره) به رشته‌هایی به شکل [value<sub>1</sub>, ..., value<sub>n</sub>] تبدیل می‌شوند که با یک [ شروع می‌شود. براکت که با یک براکت ] ختم می شود و از " , " (کاما، فاصله) برای محدود کردن چند مقدار استفاده می کند. برچسب ها با استفاده از شکل مطلق برچسب به رشته تبدیل می شوند. برای مثال، یک ویژگی deps=[":foo", "//otherpkg:bar", "wiz"] به رشته [//thispkg:foo, //otherpkg:bar, //thispkg:wiz] . براکت ها همیشه وجود دارند، بنابراین لیست خالی از مقدار رشته [] برای اهداف تطبیق استفاده می کند. مثلا،

attr("srcs", "\[\]", deps(//foo))

در حالی که تمام قوانین را از میان وابستگی های //foo که دارای ویژگی srcs خالی هستند انتخاب می کند

attr("data", ".{3,}", deps(//foo))

همه قوانین را از میان وابستگی های //foo که حداقل یک مقدار را در ویژگی data مشخص می کنند انتخاب می کند (هر برچسب به دلیل // و : حداقل 3 کاراکتر طول دارد).

برای انتخاب همه قوانین از میان وابستگی های //foo با یک value خاص در یک ویژگی لیست نوع، استفاده کنید

attr("tags", "[\[ ]value[,\]]", deps(//foo))

این کار به این دلیل است که کاراکتر قبل از value [ یا یک فاصله و کاراکتر بعد از value یک کاما یا ] خواهد بود.

فیلتر قابلیت مشاهده قانون: قابل مشاهده است

expr ::= visible(expr, expr)

عملگر visible( predicate , input ) یک فیلتر را برای مجموعه ای از اهداف اعمال می کند و اهداف را بدون دید مورد نیاز دور می اندازد.

آرگومان اول، predicate ، مجموعه ای از اهداف است که همه اهداف در خروجی باید برای آنها قابل مشاهده باشند. یک عبارت visible برای مجموعه حاوی تمام اهداف x ارزیابی می شود به طوری که x عضوی از input مجموعه است و برای همه اهداف y در predicate x برای y قابل مشاهده است. مثلا:

visible(//foo, //bar:*)

تمام اهداف موجود در بسته //bar را انتخاب می کند که //foo می تواند بدون نقض محدودیت های دید به آنها وابسته باشد.

ارزیابی ویژگی های قانون نوع برچسب: برچسب

expr ::= labels(word, expr)

عملگر labels( attr_name , inputs ) مجموعه ای از اهداف مشخص شده در ویژگی attr_name از نوع "label" یا "list of label" را در برخی قوانین در inputs های مجموعه برمی گرداند.

به عنوان مثال، labels(srcs, //foo) مجموعه ای از اهداف ظاهر شده در ویژگی srcs قانون //foo foo را برمی گرداند. اگر چندین قانون با ویژگی‌های srcs در مجموعه inputs وجود داشته باشد، اتحادیه srcs آنها برگردانده می‌شود.

بسط و فیلتر test_suites: تست ها

expr ::= tests(expr)

عملگر tests( x ) مجموعه‌ای از قوانین تست را در مجموعه x برمی‌گرداند، قوانین test_suite را در مجموعه تست‌های فردی که به آن‌ها ارجاع می‌دهند گسترش می‌دهد و فیلتر کردن بر اساس tag و size را اعمال می‌کند.

به‌طور پیش‌فرض، ارزیابی پرس و جو، اهداف غیر آزمایشی را در همه قوانین test_suite نادیده می‌گیرد. این را می توان با گزینه --strict_test_suite به خطا تغییر داد.

به عنوان مثال، query kind(test, foo:*) تمام قوانین *_test و test_suite را در بسته foo فهرست می کند. همه نتایج (طبق تعریف) اعضای بسته foo هستند. در مقابل، tests(foo:*) همه تست‌های فردی را که توسط bazel test foo:* : این ممکن است شامل تست‌های متعلق به بسته‌های دیگر باشد که به‌طور مستقیم یا غیرمستقیم از طریق قوانین test_suite .

فایل های تعریف بسته: فایل های ساخت

expr ::= buildfiles(expr)

buildfiles( x ) مجموعه ای از فایل ها را برمی گرداند که بسته های هر هدف را در مجموعه x تعریف می کنند. به عبارت دیگر، برای هر بسته، فایل BUILD آن، به علاوه هر فایل .bzl که از طریق load به آن ارجاع می دهد. توجه داشته باشید که با این کار فایل‌های BUILD بسته‌های حاوی این فایل‌های ویرایش load شده را نیز برمی‌گرداند.

این عملگر معمولاً هنگام تعیین اینکه چه فایل‌ها یا بسته‌هایی برای ساختن یک هدف مشخص مورد نیاز هستند، اغلب در ارتباط با گزینه --output package در زیر استفاده می‌شود. مثلا،

bazel query 'buildfiles(deps(//foo))' --output package

مجموعه ای از تمام بسته هایی که //foo به طور گذرا به آنها بستگی دارد را برمی گرداند.

فایل های تعریف بسته: rbuildfiles

expr ::= rbuildfiles(word, ...)

عملگر rbuildfiles فهرستی از قطعات مسیر جدا شده با کاما را می گیرد و مجموعه ای از فایل های BUILD را که به صورت گذرا به این قطعات مسیر وابسته هستند، برمی گرداند. برای مثال، اگر //foo یک بسته باشد، آنگاه rbuildfiles(foo/BUILD) هدف //foo:BUILD را برمی گرداند. اگر فایل foo/BUILD دارای load('//bar:file.bzl'... ) باشد، آنگاه rbuildfiles(bar/file.bzl) هدف //foo:BUILD و همچنین اهداف هر موردی را برمی گرداند. سایر فایل های BUILD که //bar:file.bzl بارگیری می شوند

دامنه rbuildfiles عملگر جهانی است که با پرچم --universe_scope مشخص شده است. فایل‌هایی که مستقیماً با فایل‌های BUILD و فایل‌های .bzl . مطابقت ندارند، روی نتایج تأثیری ندارند. برای مثال، فایل‌های منبع (مانند foo.cc ) نادیده گرفته می‌شوند، حتی اگر به صراحت در فایل BUILD ذکر شده باشند. با این حال، پیوندهای نمادین محترم هستند، به طوری که اگر foo/BUILD یک پیوند نمادین به bar/BUILD باشد، سپس rbuildfiles(bar/BUILD) //foo:BUILD را در نتایج خود شامل می شود.

عملگر rbuildfiles تقریباً از نظر اخلاقی معکوس عملگر buildfiles است. با این حال، این وارونگی اخلاقی در یک جهت قوی‌تر است: خروجی‌های rbuildfiles دقیقاً مانند ورودی‌های buildfiles . اولی فقط حاوی اهداف فایل BUILD در بسته ها خواهد بود و دومی ممکن است شامل چنین اهدافی باشد. در جهت دیگر، مکاتبات ضعیف تر است. خروجی های اپراتور buildfiles اهداف مربوط به تمام بسته ها و . فایل های bzl مورد نیاز یک ورودی داده شده است. با این حال، ورودی های اپراتور rbuildfiles آن اهداف نیستند، بلکه قطعات مسیری هستند که با آن اهداف مطابقت دارند.

فایل های تعریف بسته: loadfiles

expr ::= loadfiles(expr)

loadfiles( x ) مجموعه ای از فایل های Starlark را که برای بارگیری بسته های هر هدف در مجموعه x مورد نیاز است، برمی گرداند. به عبارت دیگر، برای هر بسته، فایل‌های bzl. را که از فایل‌های BUILD آن ارجاع داده شده‌اند، برمی‌گرداند.

فرمت های خروجی

bazel query یک نمودار ایجاد می کند. شما محتوا، قالب و ترتیبی را که bazel query این نمودار را ارائه می‌کند با استفاده از گزینه --output خط فرمان مشخص می‌کنید.

هنگام اجرا با Sky Query ، فقط فرمت‌های خروجی که با خروجی نامرتب سازگار هستند مجاز هستند. به طور خاص، فرمت‌های خروجی graph ، minrank و maxrank ممنوع هستند.

برخی از فرمت های خروجی گزینه های اضافی را می پذیرند. نام هر گزینه خروجی با فرمت خروجی که برای آن اعمال می شود پیشوند است، بنابراین --graph:factored فقط زمانی اعمال می شود که --output=graph استفاده می شود. اگر از یک فرمت خروجی غیر از graph استفاده شود، تأثیری ندارد. به طور مشابه، --xml:line_numbers فقط زمانی اعمال می شود که --output=xml استفاده می شود.

در مورد ترتیب نتایج

اگرچه عبارات پرس و جو همیشه از " قانون بقای ترتیب نمودار " پیروی می کنند، ارائه نتایج ممکن است به صورت وابستگی یا بدون ترتیب انجام شود. این روی اهداف در مجموعه نتیجه یا نحوه محاسبه پرس و جو تأثیری ندارد . این فقط بر نحوه چاپ نتایج در stdout تأثیر می گذارد. Moreover, nodes that are equivalent in the dependency order may or may not be ordered alphabetically. The --order_output flag can be used to control this behavior. (The --[no]order_results flag has a subset of the functionality of the --order_output flag and is deprecated.)

The default value of this flag is auto , which prints results in lexicographical order . However, when somepath(a,b) is used, the results will be printed in deps order instead.

When this flag is no and --output is one of build , label , label_kind , location , package , proto , or xml , the outputs will be printed in arbitrary order. This is generally the fastest option . It is not supported though when --output is one of graph , minrank or maxrank : with these formats, Bazel always prints results ordered by the dependency order or rank.

When this flag is deps , Bazel prints results in some topological order—that is, dependencies first. However, nodes that are unordered by the dependency order (because there is no path from either one to the other) may be printed in any order.

When this flag is full , Bazel prints nodes in a fully deterministic (total) order. First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a post-order depth-first search in which outgoing edges to unvisited nodes are traversed in alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order in which they were visited.

Printing nodes in this order may be slower, so it should be used only when determinism is important.

Print the source form of targets as they would appear in BUILD

--output build

With this option, the representation of each target is as if it were hand-written in the BUILD language. All variables and function calls (such as glob, macros) are expanded, which is useful for seeing the effect of Starlark macros. Additionally, each effective rule reports a generator_name and/or generator_function ) value, giving the name of the macro that was evaluated to produce the effective rule.

Although the output uses the same syntax as BUILD files, it is not guaranteed to produce a valid BUILD file.

Print the label of each target

--output label

With this option, the set of names (or labels ) of each target in the resulting graph is printed, one label per line, in topological order (unless --noorder_results is specified, see notes on the ordering of results ). (A topological ordering is one in which a graph node appears earlier than all of its successors.) Of course there are many possible topological orderings of a graph ( reverse postorder is just one); which one is chosen is not specified.

When printing the output of a somepath query, the order in which the nodes are printed is the order of the path.

Caveat: in some corner cases, there may be two distinct targets with the same label; for example, a sh_binary rule and its sole (implicit) srcs file may both be called foo.sh . If the result of a query contains both of these targets, the output (in label format) will appear to contain a duplicate. When using the label_kind (see below) format, the distinction becomes clear: the two targets have the same name, but one has kind sh_binary rule and the other kind source file .

Print the label and kind of each target

--output label_kind

Like label , this output format prints the labels of each target in the resulting graph, in topological order, but it additionally precedes the label by the kind of the target.

Print the label of each target, in rank order

--output minrank --output maxrank

Like label , the minrank and maxrank output formats print the labels of each target in the resulting graph, but instead of appearing in topological order, they appear in rank order, preceded by their rank number. These are unaffected by the result ordering --[no]order_results flag (see notes on the ordering of results ).

There are two variants of this format: minrank ranks each node by the length of the shortest path from a root node to it. "Root" nodes (those which have no incoming edges) are of rank 0, their successors are of rank 1, etc. (As always, edges point from a target to its prerequisites: the targets it depends upon.)

maxrank ranks each node by the length of the longest path from a root node to it. Again, "roots" have rank 0, all other nodes have a rank which is one greater than the maximum rank of all their predecessors.

All nodes in a cycle are considered of equal rank. (Most graphs are acyclic, but cycles do occur simply because BUILD files contain erroneous cycles.)

These output formats are useful for discovering how deep a graph is. If used for the result of a deps(x) , rdeps(x) , or allpaths query, then the rank number is equal to the length of the shortest (with minrank ) or longest (with maxrank ) path from x to a node in that rank. maxrank can be used to determine the longest sequence of build steps required to build a target.

For example, the graph on the left yields the outputs on the right when --output minrank and --output maxrank are specified, respectively.

minrank 0 //c:c 1 //b:b 1 //a:a 2 //b:b.cc 2 //a:a.cc

maxrank 0 //c:c 1 //b:b 2 //a:a 2 //b:b.cc 3 //a:a.cc

Print the location of each target

--output location

Like label_kind , this option prints out, for each target in the result, the target's kind and label, but it is prefixed by a string describing the location of that target, as a filename and line number. The format resembles the output of grep . Thus, tools that can parse the latter (such as Emacs or vi) can also use the query output to step through a series of matches, allowing the Bazel query tool to be used as a dependency-graph-aware "grep for BUILD files".

The location information varies by target kind (see the kind operator). For rules, the location of the rule's declaration within the BUILD file is printed. For source files, the location of line 1 of the actual file is printed. For a generated file, the location of the rule that generates it is printed. (The query tool does not have sufficient information to find the actual location of the generated file, and in any case, it might not exist if a build has not yet been performed.)

Print the set of packages

--output package

This option prints the name of all packages to which some target in the result set belongs. The names are printed in lexicographical order; duplicates are excluded. Formally, this is a projection from the set of labels (package, target) onto packages.

Packages in external repositories are formatted as @repo//foo/bar while packages in the main repository are formatted as foo/bar .

In conjunction with the deps(...) query, this output option can be used to find the set of packages that must be checked out in order to build a given set of targets.

Display a graph of the result

--output graph

This option causes the query result to be printed as a directed graph in the popular AT&T GraphViz format. Typically the result is saved to a file, such as .png or .svg . (If the dot program is not installed on your workstation, you can install it using the command sudo apt-get install graphviz .) See the example section below for a sample invocation.

This output format is particularly useful for allpaths , deps , or rdeps queries, where the result includes a set of paths that cannot be easily visualized when rendered in a linear form, such as with --output label .

By default, the graph is rendered in a factored form. That is, topologically-equivalent nodes are merged together into a single node with multiple labels. This makes the graph more compact and readable, because typical result graphs contain highly repetitive patterns. For example, a java_library rule may depend on hundreds of Java source files all generated by the same genrule ; in the factored graph, all these files are represented by a single node. This behavior may be disabled with the --nograph:factored option.

--graph:node_limit n

The option specifies the maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 disables truncation. Due to the factored form in which graphs are usually printed, the node labels may be very long. GraphViz cannot handle labels exceeding 1024 characters, which is the default value of this option. This option has no effect unless --output=graph is being used.

--[no]graph:factored

By default, graphs are displayed in factored form, as explained above . When --nograph:factored is specified, graphs are printed without factoring. This makes visualization using GraphViz impractical, but the simpler format may ease processing by other tools (such as grep). This option has no effect unless --output=graph is being used.

XML

--output xml

This option causes the resulting targets to be printed in an XML form. The output starts with an XML header such as this

  <?xml version="1.0" encoding="UTF-8"?>
  <query version="2">

and then continues with an XML element for each target in the result graph, in topological order (unless unordered results are requested), and then finishes with a terminating

</query>

Simple entries are emitted for targets of file kind:

  <source-file name='//foo:foo_main.cc' .../>
  <generated-file name='//foo:libfoo.so' .../>

But for rules, the XML is structured and contains definitions of all the attributes of the rule, including those whose value was not explicitly specified in the rule's BUILD file.

Additionally, the result includes rule-input and rule-output elements so that the topology of the dependency graph can be reconstructed without having to know that, for example, the elements of the srcs attribute are forward dependencies (prerequisites) and the contents of the outs attribute are backward dependencies (consumers).

rule-input elements for implicit dependencies are suppressed if --noimplicit_deps is specified.

  <rule class='cc_binary rule' name='//foo:foo' ...>
    <list name='srcs'>
      <label value='//foo:foo_main.cc'/>
      <label value='//foo:bar.cc'/>
      ...
    </list>
    <list name='deps'>
      <label value='//common:common'/>
      <label value='//collections:collections'/>
      ...
    </list>
    <list name='data'>
      ...
    </list>
    <int name='linkstatic' value='0'/>
    <int name='linkshared' value='0'/>
    <list name='licenses'/>
    <list name='distribs'>
      <distribution value="INTERNAL" />
    </list>
    <rule-input name="//common:common" />
    <rule-input name="//collections:collections" />
    <rule-input name="//foo:foo_main.cc" />
    <rule-input name="//foo:bar.cc" />
    ...
  </rule>

Every XML element for a target contains a name attribute, whose value is the target's label, and a location attribute, whose value is the target's location as printed by the --output location .

--[no]xml:line_numbers

By default, the locations displayed in the XML output contain line numbers. When --noxml:line_numbers is specified, line numbers are not printed.

--[no]xml:default_values

By default, XML output does not include rule attribute whose value is the default value for that kind of attribute (for example, if it were not specified in the BUILD file, or the default value was provided explicitly). This option causes such attribute values to be included in the XML output.

Regular expressions

Regular expressions in the query language use the Java regex library, so you can use the full syntax for java.util.regex.Pattern .

Querying with external repositories

If the build depends on rules from external repositories (defined in the WORKSPACE file) then query results will include these dependencies. For example, if //foo:bar depends on //external:some-lib and //external:some-lib is bound to @other-repo//baz:lib , then bazel query 'deps(//foo:bar)' will list both @other-repo//baz:lib and //external:some-lib as dependencies.

External repositories themselves are not dependencies of a build. That is, in the example above, //external:other-repo is not a dependency. It can be queried for as a member of the //external package, though, for example:

  # Querying over all members of //external returns the repository.
  bazel query 'kind(http_archive, //external:*)'
  //external:other-repo

  # ...but the repository is not a dependency.
  bazel query 'kind(http_archive, deps(//foo:bar))'
  INFO: Empty results