برچسب ها

همه اهداف دقیقاً به یک بسته تعلق دارند. نام یک هدف، برچسب آن نامیده می شود. هر برچسب به طور منحصر به فرد یک هدف را مشخص می کند. یک برچسب معمولی به شکل متعارف به نظر می رسد:

@myrepo//my/app/main:app_binary

اولین قسمت برچسب، نام مخزن، @myrepo// است. در حالت معمولی که یک برچسب به همان مخزنی که از آن استفاده می شود اشاره دارد، شناسه مخزن ممکن است به صورت اختصاری // باشد. بنابراین، در @myrepo این برچسب معمولاً به صورت نوشته می‌شود

//my/app/main:app_binary

قسمت دوم برچسب، نام بسته بدون واجد شرایط my/app/main است، مسیر بسته نسبت به ریشه مخزن. با هم، نام مخزن و نام بسته غیرمجاز، نام بسته کاملاً واجد شرایط @myrepo//my/app/main تشکیل می‌دهند. وقتی برچسب به همان بسته ای اشاره می کند که در آن استفاده می شود، نام بسته (و در صورت اختیاری، دو نقطه) ممکن است حذف شود. بنابراین، در داخل @myrepo//my/app/main ، این برچسب ممکن است به یکی از روش‌های زیر نوشته شود:

app_binary
:app_binary

این یک موضوع قراردادی است که کولون برای فایل‌ها حذف می‌شود، اما برای قوانین حفظ می‌شود، اما در غیر این صورت مهم نیست.

بخشی از برچسب بعد از کولون، app_binary نام هدف نامشخص است. هنگامی که با آخرین مؤلفه مسیر بسته مطابقت دارد، ممکن است آن و کولون حذف شوند. بنابراین، این دو برچسب معادل هستند:

//my/app/lib
//my/app/lib:lib

نام هدف فایل در زیر شاخه بسته، مسیر فایل نسبت به ریشه بسته (دایرکتوری حاوی فایل BUILD ) است. بنابراین، این فایل در زیر شاخه my/app/main/testdata مخزن قرار دارد:

//my/app/main:testdata/input.txt

رشته‌هایی مانند //my/app و @some_repo//my/app بسته به زمینه‌ای که در آن استفاده می‌شود دو معنی دارند: وقتی Bazel انتظار یک برچسب را دارد، به معنی //my/app:app و @some_repo//my/app:app ، به ترتیب. اما، زمانی که Bazel انتظار یک بسته را دارد (به عنوان مثال در مشخصات package_group )، آنها به بسته ای که حاوی آن برچسب است ارجاع می دهند.

یک اشتباه رایج در فایل‌های BUILD استفاده از //my/app برای ارجاع به یک بسته یا به تمام اهداف موجود در یک بسته است - اینطور نیست. به یاد داشته باشید، معادل //my/app:app است، بنابراین هدف app را در بسته my/app مخزن فعلی نام‌گذاری می‌کند.

با این حال، استفاده از //my/app برای ارجاع به یک بسته در مشخصات یک package_group یا در فایل‌های .bzl . تشویق می‌شود، زیرا به وضوح نشان می‌دهد که نام بسته مطلق است و در دایرکتوری سطح بالای فضای کاری ریشه دارد. .

برچسب های نسبی را نمی توان برای اشاره به اهداف در بسته های دیگر استفاده کرد. شناسه مخزن و نام بسته همیشه باید در این مورد مشخص شود. به عنوان مثال، اگر درخت منبع حاوی هر دو بسته my/app و بسته my/app/testdata (هر یک از این دو دایرکتوری فایل BUILD خود را دارند)، بسته دوم حاوی فایلی به نام testdepot.zip است. در اینجا دو راه (یکی اشتباه، یکی صحیح) برای مراجعه به این فایل در //my/app:BUILD وجود دارد:

اشتباه - testdata بسته متفاوتی است، بنابراین نمی‌توانید از یک مسیر نسبی استفاده کنید

testdata/testdepot.zip

صحیح - به داده testdata با مسیر کامل آن مراجعه کنید

//my/app/testdata:testdepot.zip

برچسب‌هایی که با @// شروع می‌شوند، ارجاعاتی به مخزن اصلی هستند که حتی از مخازن خارجی نیز کار می‌کنند. بنابراین @//a/b/c با //a/b/c زمانی که از یک مخزن خارجی ارجاع داده می شود متفاوت است. اولی به مخزن اصلی برمی گردد، در حالی که دومی //a/b/c را در خود مخزن خارجی جستجو می کند. این امر مخصوصاً هنگام نوشتن قوانین در مخزن اصلی که به اهداف موجود در مخزن اصلی اشاره می‌کنند مرتبط است و از مخازن خارجی استفاده خواهد شد.

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

مشخصات لغوی یک برچسب

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

جزئیات دقیق اسامی هدف مجاز در زیر آمده است.

نام‌های هدف - نام package-name :target-name

target-name نام هدف درون بسته است. نام یک قانون، مقدار ویژگی name در اعلان قانون در یک فایل BUILD است. نام یک فایل، نام مسیر آن نسبت به دایرکتوری حاوی فایل BUILD است.

نام‌های هدف باید کاملاً از کاراکترهایی تشکیل شده باشند که از مجموعه a – z ، A – Z ، 0 – 9 ، و علامت‌های نقطه‌گذاری !%-@^_"#$&'()*- ,;<=>?[]{|}~/. .

نام فایل ها باید نام مسیرهای نسبی به شکل معمولی باشند، به این معنی که نه باید با یک اسلش شروع شوند و نه به پایان برسند (مثلاً /foo و foo/ ممنوع هستند) و یا حاوی چندین اسلش متوالی به عنوان جداکننده مسیر باشند (مثلا foo//bar ). به طور مشابه، مراجع سطح بالا ( .. ) و مراجع دایرکتوری فعلی ( ./ ) ممنوع هستند.

اشتباه - از «..» برای ارجاع به فایل های موجود در بسته های دیگر استفاده نکنید

درست - از «// package-name : filename » استفاده کنید

در حالی که استفاده از / در نام هدف فایل رایج است، از استفاده از / در نام قوانین اجتناب کنید. مخصوصاً زمانی که از شکل کوتاه یک برچسب استفاده می شود، ممکن است خواننده را سردرگم کند. برچسب //foo/bar/wiz همیشه مخفف //foo/bar/wiz:wiz است، حتی اگر چنین بسته ای وجود نداشته باشد foo/bar/wiz . هرگز به //foo:bar/wiz اشاره نمی کند، حتی اگر آن هدف وجود داشته باشد.

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

نام بسته - //package-name: target-name

نام یک بسته، نام دایرکتوری حاوی فایل BUILD آن، نسبت به دایرکتوری سطح بالای مخزن حاوی است. به عنوان مثال: my/app .

نام بسته‌ها باید کاملاً از نویسه‌هایی تشکیل 9 باشد که از مجموعه A - Z , a - z , 0 , ' / ', ' - ',' گرفته شده‌اند . '، ' @ '، و ' _ '، و نمی تواند با اسلش شروع شود.

برای زبانی با ساختار دایرکتوری که برای سیستم ماژول آن مهم است (به عنوان مثال جاوا)، انتخاب نام دایرکتوری‌هایی که شناسه‌های معتبر در زبان هستند، مهم است.

اگرچه Bazel از اهداف در بسته ریشه فضای کاری پشتیبانی می کند (به عنوان مثال، //:foo )، بهتر است آن بسته را خالی بگذارید تا همه بسته های معنی دار دارای نام های توصیفی باشند.

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

قوانین

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

فایل های BUILD با احضار قوانین اهداف را اعلام می کنند.

در مثال زیر، اعلان هدف my_app را با استفاده از قانون cc_binary می کنیم.

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)

هر فراخوانی قانون یک ویژگی name دارد (که باید یک نام هدف معتبر باشد)، که یک هدف را در بسته فایل BUILD اعلام می کند.

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

ویژگی srcs موجود در بسیاری از قوانین دارای نوع "list of labels" است. مقدار آن، در صورت وجود، فهرستی از برچسب ها است که هر کدام نام هدفی است که ورودی این قانون است.

در برخی موارد، نام نوع قانون تا حدودی دلخواه است و جالب تر، نام فایل های تولید شده توسط قانون است و این در مورد ژانرها صادق است. برای اطلاعات بیشتر، به قوانین عمومی مراجعه کنید: genrule .

در موارد دیگر، نام مهم است: به عنوان مثال، برای قوانین *_binary و *_test ، نام قانون، نام فایل اجرایی تولید شده توسط ساخت را تعیین می کند.

این گراف غیر چرخه ای جهت دار روی اهداف، گراف هدف یا گراف وابستگی ساخت نامیده می شود و دامنه ای است که ابزار پرس و جو Bazel بر روی آن کار می کند.