सामान्य नियम

समस्या की शिकायत करें सोर्स देखें Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

नियम

• alias
• config_setting
• filegroup
• genquery
• genrule
• starlark_doc_extract
• test_suite

उपनाम

नियम का सोर्स देखें

alias(name, actual, aspect_hints, compatible_with, deprecation, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility)

alias नियम, एक ऐसा नाम बनाता है जिससे किसी नियम को रेफ़र किया जा सकता है.

एलियासिंग की सुविधा सिर्फ़ "रेगुलर" टारगेट के लिए काम करती है. खास तौर पर, package_group और test_suite को एलियास नहीं किया जा सकता.

एलियासिंग, बड़ी रिपॉज़िटरी में काम आ सकती है. यहां किसी टारगेट का नाम बदलने के लिए, कई फ़ाइलों में बदलाव करने की ज़रूरत होती है. अगर आपको एक से ज़्यादा टारगेट के लिए, select फ़ंक्शन कॉल के लॉजिक का फिर से इस्तेमाल करना है, तो ऐलियास नियम का इस्तेमाल करके उसे सेव किया जा सकता है.

एलियास के नियम में, दिखने की स्थिति के बारे में जानकारी देने वाला अपना स्टेटमेंट होता है. अन्य सभी मामलों में, यह उस नियम की तरह काम करता है जिसका रेफ़रंस दिया गया है. उदाहरण के लिए, एलियास पर testonly को अनदेखा किया जाता है. इसके बजाय, रेफ़रंस किए गए नियम के testonly-ness का इस्तेमाल किया जाता है. हालांकि, कुछ छोटे-मोटे अपवाद हैं:

• अगर कमांड लाइन पर टेस्ट का एलियास दिया गया है, तो टेस्ट नहीं चलाए जाते. रेफ़र किए गए टेस्ट को चलाने वाले किसी एलियास को तय करने के लिए, test_suite नियम का इस्तेमाल करें. इस नियम के tests एट्रिब्यूट में सिर्फ़ एक टारगेट होना चाहिए.
• एनवायरमेंट ग्रुप तय करते समय, environment नियमों के लिए उपनामों का इस्तेमाल नहीं किया जा सकता. ये --target_environment कमांड लाइन विकल्प में भी काम नहीं करते.

उदाहरण

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

तर्क

विशेषताएं
name	नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम.
actual	लेबल; ज़रूरी है यह टारगेट, इस उपनाम से जुड़ा है. यह ज़रूरी नहीं है कि यह कोई नियम हो. यह इनपुट फ़ाइल भी हो सकती है.

config_setting

नियम का सोर्स देखें

config_setting(name, aspect_hints, constraint_values, define_values, deprecation, features, flag_values, licenses, package_metadata, tags, testonly, values, visibility)

यह कॉन्फ़िगरेशन की अनुमानित स्थिति से मेल खाता है. इसे बिल्ड फ़्लैग या प्लैटफ़ॉर्म की पाबंदियों के तौर पर दिखाया जाता है. इसका इस्तेमाल, कॉन्फ़िगर किए जा सकने वाले एट्रिब्यूट को ट्रिगर करने के लिए किया जाता है. इस नियम का इस्तेमाल कैसे करें, यह जानने के लिए select देखें. साथ ही, इस सुविधा के बारे में खास जानकारी पाने के लिए कॉन्फ़िगर किए जा सकने वाले एट्रिब्यूट देखें.

उदाहरण

नीचे दिया गया पैटर्न, --compilation_mode=opt या -c opt सेट करने वाले किसी भी बिल्ड से मेल खाता है. इन्हें कमांड लाइन में साफ़ तौर पर या .bazelrc फ़ाइलों से परोक्ष रूप से सेट किया जाता है:

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

नीचे दिया गया रेगुलर एक्सप्रेशन, ARM को टारगेट करने वाले किसी भी बिल्ड से मेल खाता है. साथ ही, यह कस्टम डिफाइन FOO=bar (उदाहरण के लिए, bazel build --cpu=arm --define FOO=bar ...) को लागू करता है:

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )
  

नीचे दिया गया पैटर्न, ऐसी किसी भी बिल्ड से मेल खाता है जो user-defined flag --//custom_flags:foo=1 सेट करता है. यह फ़्लैग, कमांड लाइन में साफ़ तौर पर या .bazelrc फ़ाइलों से इंप्लिसिट तौर पर सेट किया जाता है:

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

नीचे दिया गया उदाहरण, x86_64 आर्किटेक्चर और glibc वर्शन 2.25 वाले किसी भी प्लैटफ़ॉर्म को टारगेट करने वाले बिल्ड से मैच करता है. इसमें यह माना गया है कि constraint_value मौजूद है और उसका लेबल //example:glibc_2_25 है. ध्यान दें कि अगर कोई प्लैटफ़ॉर्म इन दो वैल्यू के अलावा, अन्य वैल्यू भी तय करता है, तो भी वह मैच करता है.

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  

इन सभी मामलों में, बिल्ड के दौरान कॉन्फ़िगरेशन में बदलाव हो सकता है. उदाहरण के लिए, अगर किसी टारगेट को उसके डिफ़ॉल्ट प्लैटफ़ॉर्म के बजाय किसी दूसरे प्लैटफ़ॉर्म के लिए बनाया जाना है. इसका मतलब है कि अगर config_setting, टॉप-लेवल के कमांड-लाइन फ़्लैग से मेल नहीं खाता है, तो भी यह कुछ बिल्ड टारगेट से मेल खा सकता है.

नोट

• जब कई config_setting, मौजूदा कॉन्फ़िगरेशन की स्थिति से मेल खाते हैं, तो क्या होता है, यह जानने के लिए select देखें.
• शॉर्टहैंड फ़ॉर्म का इस्तेमाल करने वाले फ़्लैग (जैसे, --compilation_mode बनाम -c) के लिए, values की परिभाषाओं में पूरे फ़ॉर्म का इस्तेमाल किया जाना चाहिए. ये दोनों फ़ॉर्म इस्तेमाल करके किए गए इनवॉकेशन से अपने-आप मैच हो जाते हैं.
• अगर किसी फ़्लैग की एक से ज़्यादा वैल्यू होती हैं (जैसे कि --copt=-Da --copt=-Db या सूची के टाइप वाला Starlark फ़्लैग), तो values = { "flag": "a" } तब मैच करता है, जब "a", असल सूची में कहीं भी मौजूद हो.

  values = { "myflag": "a,b" } एक ही तरह से काम करता है: यह --myflag=a --myflag=b, --myflag=a --myflag=b --myflag=c, --myflag=a,b, और --myflag=c,b,a से मेल खाता है. हर फ़्लैग का मतलब अलग-अलग होता है. उदाहरण के लिए, --copt एक ही इंस्टेंस में एक से ज़्यादा वैल्यू के साथ काम नहीं करता: --copt=a,b से ["a,b"] मिलता है, जबकि --copt=a --copt=b से ["a", "b"] मिलता है. इसलिए, values = { "copt": "a,b" } पहले वाले से मेल खाता है, लेकिन बाद वाले से नहीं. लेकिन --ios_multi_cpus (Apple के नियमों के लिए) ऐसा करता है: -ios_multi_cpus=a,b और ios_multi_cpus=a --ios_multi_cpus=b , दोनों से ["a", "b"] मिलता है. फ़्लैग की परिभाषाएं देखें और अपनी शर्तों को ध्यान से टेस्ट करें, ताकि यह पुष्टि की जा सके कि वे आपकी उम्मीदों के मुताबिक हैं.

• अगर आपको ऐसी शर्तें तय करनी हैं जिन्हें बिल्ट-इन बिल्ड फ़्लैग से मॉडल नहीं किया जाता है, तो Starlark-डिफ़ाइन किए गए फ़्लैग का इस्तेमाल करें. --define का इस्तेमाल भी किया जा सकता है. हालांकि, इससे कम मदद मिलती है और इसका इस्तेमाल करने का सुझाव नहीं दिया जाता. ज़्यादा जानकारी के लिए, यहां देखें.
• अलग-अलग पैकेज में एक जैसी config_setting परिभाषाओं को दोहराने से बचें. इसके बजाय, कैननिकल पैकेज में तय किए गए सामान्य config_setting का रेफ़रंस दें.
• values, define_values, और constraint_values को एक ही config_setting में किसी भी कॉम्बिनेशन में इस्तेमाल किया जा सकता है. हालांकि, किसी भी config_setting के लिए कम से कम एक वैल्यू सेट होनी चाहिए.

तर्क

विशेषताएं
name	नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम.
constraint_values	लेबल की सूची; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट वैल्यू [] है constraint_values का वह कम से कम सेट जिसे टारगेट प्लैटफ़ॉर्म को इस config_setting से मैच करने के लिए तय करना होगा. (यहां एक्ज़ीक्यूशन प्लैटफ़ॉर्म को शामिल नहीं किया गया है.) प्लैटफ़ॉर्म पर मौजूद किसी भी अन्य पाबंदी की वैल्यू को अनदेखा कर दिया जाता है. ज़्यादा जानकारी के लिए, कॉन्फ़िगर किए जा सकने वाले बिल्ड एट्रिब्यूट देखें. अगर एक ही select में दो config_setting मेल खाते हैं और एक में दूसरे के मुकाबले ज़्यादा फ़्लैग और constraint_setting हैं, तो ज़्यादा सेटिंग वाले config_setting को चुना जाता है. इसे "स्पेशलाइज़ेशन" कहा जाता है. उदाहरण के लिए, config_setting, x86 और Linux से मैच करता है. वहीं, config_setting, x86 से मैच करता है. अगर दो config_setting मेल खाते हैं और दोनों में ऐसे constraint_value मौजूद हैं जो दूसरे में मौजूद नहीं हैं, तो यह एक गड़बड़ी है.
define_values	डिक्शनरी: String -> String; nonconfigurable; डिफ़ॉल्ट वैल्यू {} है यह values जैसा ही है, लेकिन खास तौर पर --define फ़्लैग के लिए है. --define खास है, क्योंकि इसके सिंटैक्स (--define KEY=VAL) का मतलब है कि Bazel फ़्लैग के हिसाब से KEY=VAL एक वैल्यू है. इसका मतलब है कि: config_setting( name = "a_and_b", values = { "define": "a=1", "define": "b=2", }) काम नहीं करता, क्योंकि शब्दकोश में एक ही कुंजी (define) दो बार दिखती है. यह एट्रिब्यूट इस समस्या को हल करता है: config_setting( name = "a_and_b", define_values = { "a": "1", "b": "2", }) bazel build //foo --define a=1 --define b=2 से सही तरीके से मेल खाता हो. --define को अब भी सामान्य फ़्लैग सिंटैक्स के साथ values में दिखाया जा सकता है. साथ ही, इसे इस एट्रिब्यूट के साथ आसानी से मिक्स किया जा सकता है. हालांकि, इसके लिए ज़रूरी है कि डिक्शनरी के की अलग-अलग हों.
flag_values	डिक्शनरी: label -> String; nonconfigurable; डिफ़ॉल्ट वैल्यू {} है यह values की तरह ही है, लेकिन उपयोगकर्ता के तय किए गए बिल्ड फ़्लैग के लिए. यह एक अलग एट्रिब्यूट है, क्योंकि उपयोगकर्ता के तय किए गए फ़्लैग को लेबल के तौर पर रेफ़रंस किया जाता है. वहीं, बिल्ट-इन फ़्लैग को मनमाने स्ट्रिंग के तौर पर रेफ़रंस किया जाता है.
values	डिक्शनरी: String -> String; nonconfigurable; डिफ़ॉल्ट वैल्यू {} है कॉन्फ़िगरेशन वैल्यू का वह सेट जो इस नियम से मेल खाता है. इसे बिल्ड फ़्लैग के तौर पर दिखाया जाता है यह नियम, कॉन्फ़िगर किए गए उस टारगेट के कॉन्फ़िगरेशन को इनहेरिट करता है जो select स्टेटमेंट में इसे रेफ़रंस करता है. किसी Bazel इनवोकेशन को "मिलान" वाला तब माना जाता है, जब डिक्शनरी की हर एंट्री के लिए, उसका कॉन्फ़िगरेशन, एंट्री की अनुमानित वैल्यू से मेल खाता हो. उदाहरण के लिए, values = {"compilation_mode": "opt"}, टारगेट के हिसाब से कॉन्फ़िगर किए गए नियमों के लिए bazel build --compilation_mode=opt ... और bazel build -c opt ... से मेल खाता है. आसानी के लिए, कॉन्फ़िगरेशन वैल्यू को बिल्ड फ़्लैग के तौर पर बताया गया है. इसमें "--" शामिल नहीं है. हालांकि, ध्यान रखें कि ये दोनों एक ही नहीं हैं. ऐसा इसलिए होता है, क्योंकि एक ही बिल्ड में कई कॉन्फ़िगरेशन में टारगेट बनाए जा सकते हैं. उदाहरण के लिए, किसी एक्ज़ेक कॉन्फ़िगरेशन का "cpu", --cpu की वैल्यू से नहीं, बल्कि --host_cpu की वैल्यू से मेल खाता है. इसलिए, एक ही config_setting के अलग-अलग इंस्टेंस, एक ही इनवोकेशन से अलग-अलग तरीके से मैच हो सकते हैं. यह इस बात पर निर्भर करता है कि नियम का कॉन्फ़िगरेशन कैसा है. अगर किसी फ़्लैग को कमांड लाइन पर साफ़ तौर पर सेट नहीं किया जाता है, तो उसकी डिफ़ॉल्ट वैल्यू का इस्तेमाल किया जाता है. अगर किसी डिक्शनरी में कोई कुंजी एक से ज़्यादा बार दिखती है, तो सिर्फ़ आखिरी बार दिखने वाली कुंजी का इस्तेमाल किया जाता है. अगर कोई कुंजी ऐसे फ़्लैग को रेफ़र करती है जिसे कमांड लाइन पर कई बार सेट किया जा सकता है (जैसे, bazel build --copt=foo --copt=bar --copt=baz ...), तो मिलान तब होता है, जब इनमें से कोई भी सेटिंग मेल खाती हो.

filegroup

नियम का सोर्स देखें

filegroup(name, srcs, data, aspect_hints, compatible_with, deprecation, features, licenses, output_group, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility)

filegroup का इस्तेमाल करके, एक लेबल के तहत टारगेट के सेट के आउटपुट इकट्ठा करें.

filegroup, कमांड लाइन पर या किसी अन्य नियम के एट्रिब्यूट में टारगेट की सूची बनाने का विकल्प नहीं है. ऐसा इसलिए, क्योंकि टारगेट में उनके आउटपुट के अलावा कई अन्य प्रॉपर्टी होती हैं. इन्हें एक ही तरीके से इकट्ठा नहीं किया जाता. हालांकि, यह अब भी कई मामलों में काम आता है. उदाहरण के लिए, genrule के srcs एट्रिब्यूट में या *_binary नियम के data एट्रिब्यूट में.

डायरेक्ट्री को सीधे तौर पर रेफ़रंस करने के बजाय, filegroup का इस्तेमाल करने का सुझाव दिया जाता है. डायरेक्ट्री को सीधे तौर पर रेफ़रंस करने से बचने का सुझाव दिया जाता है. ऐसा इसलिए, क्योंकि बिल्ड सिस्टम को डायरेक्ट्री में मौजूद सभी फ़ाइलों के बारे में पूरी जानकारी नहीं होती. इसलिए, इन फ़ाइलों में बदलाव होने पर, यह उन्हें फिर से नहीं बना पाता. glob के साथ इस्तेमाल करने पर, filegroup यह पक्का कर सकता है कि सभी फ़ाइलों के बारे में बिल्ड सिस्टम को साफ़ तौर पर पता हो.

उदाहरण

दो सोर्स फ़ाइलों से मिलकर बनी filegroup बनाने के लिए,

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "//a/library:target",
        "//a/binary:target",
    ],
)

इसके अलावा, testdata डायरेक्ट्री को पूरी तरह से क्रॉल करने के लिए, glob का इस्तेमाल करें:

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

इन परिभाषाओं का इस्तेमाल करने के लिए, किसी भी नियम के लेबल के साथ filegroup को रेफ़रंस करें:

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

तर्क

विशेषताएं
name	नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम.
srcs	लेबल की सूची; डिफ़ॉल्ट वैल्यू [] है फ़ाइल ग्रुप के सदस्यों के तौर पर शामिल किए गए टारगेट की सूची. srcs एट्रिब्यूट की वैल्यू के लिए, glob एक्सप्रेशन के नतीजे का इस्तेमाल करना आम बात है.
data	लेबल की सूची; डिफ़ॉल्ट वैल्यू [] है रनटाइम के दौरान, इस नियम के लिए ज़रूरी फ़ाइलों की सूची. data एट्रिब्यूट में बताए गए टारगेट, इस filegroup नियम के runfiles में जोड़ दिए जाएंगे. जब किसी दूसरे नियम के data एट्रिब्यूट में filegroup का रेफ़रंस दिया जाता है, तो इसका runfiles, निर्भरता वाले नियम के runfiles में जोड़ दिया जाएगा. डेटा फ़ाइलों का इस्तेमाल करने और उन पर निर्भर रहने के बारे में ज़्यादा जानने के लिए, डेटा डिपेंडेंसी सेक्शन और data का सामान्य दस्तावेज़ देखें.
output_group	स्ट्रिंग; डिफ़ॉल्ट वैल्यू "" है वह आउटपुट ग्रुप जिससे सोर्स से आर्टफ़ैक्ट इकट्ठा करने हैं. अगर इस एट्रिब्यूट की वैल्यू दी जाती है, तो डिपेंडेंसी के तय किए गए आउटपुट ग्रुप के आर्टफ़ैक्ट एक्सपोर्ट किए जाएंगे. ऐसा डिफ़ॉल्ट आउटपुट ग्रुप के बजाय किया जाएगा. "आउटपुट ग्रुप", टारगेट के आउटपुट आर्टफ़ैक्ट की एक कैटगरी है. इसे उस नियम के लागू होने के तरीके में बताया जाता है.

genquery

नियम का सोर्स देखें

genquery(name, deps, data, aspect_hints, compatible_with, compressed_output, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, expression, features, licenses, opts, package_metadata, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery(), Bazel क्वेरी लैंग्वेज में दी गई क्वेरी को चलाता है और नतीजे को किसी फ़ाइल में डंप करता है.

क्वेरी को एक जैसा बनाए रखने के लिए, क्वेरी को सिर्फ़ scope एट्रिब्यूट में बताए गए टारगेट के ट्रांज़िटिव क्लोज़र पर जाने की अनुमति है. इस नियम का उल्लंघन करने वाली क्वेरी, एक्ज़ीक्यूट नहीं की जा सकेंगी. ऐसा तब होगा, जब strict की वैल्यू तय नहीं की गई है या 'सही है' पर सेट है. अगर strict की वैल्यू 'गलत है' पर सेट है, तो स्कोप से बाहर के टारगेट को सिर्फ़ चेतावनी के साथ स्किप कर दिया जाएगा. यह पक्का करने का सबसे आसान तरीका है कि ऐसा न हो. इसके लिए, स्कोप में वही लेबल शामिल करें जो क्वेरी एक्सप्रेशन में शामिल हैं.

यहां और कमांड लाइन पर इस्तेमाल की जा सकने वाली क्वेरी में सिर्फ़ यह अंतर है कि यहां वाइल्डकार्ड टारगेट स्पेसिफ़िकेशन (जैसे, //pkg:* या //pkg:all) वाली क्वेरी इस्तेमाल नहीं की जा सकतीं. इसके दो कारण हैं: पहला, genquery को स्कोप तय करना होता है, ताकि क्वेरी के ट्रांज़िटिव क्लोज़र से बाहर के टारगेट, इसके आउटपुट पर असर न डालें.दूसरा, BUILD फ़ाइलें वाइल्डकार्ड डिपेंडेंसी के साथ काम नहीं करती हैं. उदाहरण के लिए, deps=["//a/..."] की अनुमति नहीं है.

genquery के आउटपुट को लेक्सिकोग्राफ़िक क्रम में लगाया जाता है, ताकि आउटपुट को तय किया जा सके. हालांकि, --output=graph|minrank|maxrank या somepath को टॉप-लेवल फ़ंक्शन के तौर पर इस्तेमाल करने पर ऐसा नहीं किया जाता.

आउटपुट फ़ाइल का नाम, नियम का नाम होता है.

उदाहरण

इस उदाहरण में, बताए गए टारगेट के ट्रांज़िटिव क्लोज़र में मौजूद लेबल की सूची को किसी फ़ाइल में लिखा जाता है.

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

तर्क

विशेषताएं
name	नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम.
compressed_output	बूलियन; डिफ़ॉल्ट वैल्यू False है अगर True है, तो क्वेरी का आउटपुट GZIP फ़ाइल फ़ॉर्मैट में लिखा जाता है. इस सेटिंग का इस्तेमाल, क्वेरी का आउटपुट बड़ा होने पर Bazel की मेमोरी के इस्तेमाल में होने वाली अचानक बढ़ोतरी से बचने के लिए किया जा सकता है. Bazel, 2^20 बाइट से ज़्यादा के क्वेरी आउटपुट को पहले से ही कंप्रेस कर देता है. भले ही, इस सेटिंग की वैल्यू कुछ भी हो. इसलिए, इसे True पर सेट करने से, बनाए रखे गए हीप में कमी नहीं आ सकती. हालांकि, इससे Bazel को आउटपुट फ़ाइल लिखते समय डीकंप्रेशन को स्किप करने की अनुमति मिलती है. इससे मेमोरी का इस्तेमाल ज़्यादा हो सकता है.
expression	स्ट्रिंग; ज़रूरी है वह क्वेरी जिसे एक्ज़ीक्यूट करना है. BUILD फ़ाइलों में कमांड लाइन और अन्य जगहों के मुकाबले, यहां लेबल को वर्कस्पेस की रूट डायरेक्ट्री के हिसाब से हल किया जाता है. उदाहरण के लिए, फ़ाइल a/BUILD में मौजूद इस एट्रिब्यूट में दिया गया लेबल :b, टारगेट //:b को रेफ़र करेगा.
opts	स्ट्रिंग की सूची; डिफ़ॉल्ट वैल्यू [] है क्वेरी इंजन को पास किए गए विकल्प. ये कमांड-लाइन विकल्पों के मुताबिक होते हैं. इन्हें bazel query को पास किया जा सकता है. यहां कुछ क्वेरी विकल्पों का इस्तेमाल नहीं किया जा सकता: --keep_going, --query_file, --universe_scope, --order_results, और --order_output. यहां नहीं दिए गए विकल्पों की डिफ़ॉल्ट वैल्यू, bazel query की कमांड लाइन पर मौजूद वैल्यू की तरह ही होंगी.
scope	लेबल की सूची; ज़रूरी है क्वेरी का स्कोप. क्वेरी को इन टारगेट के ट्रांज़िटिव क्लोज़र से बाहर के टारगेट को ऐक्सेस करने की अनुमति नहीं है.
strict	बूलियन; डिफ़ॉल्ट वैल्यू True है अगर यह विकल्प चुना जाता है, तो उन टारगेट को नहीं बनाया जा सकेगा जिनकी क्वेरी, स्कोप के ट्रांज़िटिव क्लोज़र से बाहर हैं. गलत होने पर, Bazel एक चेतावनी दिखाएगा और क्वेरी के उस पाथ को छोड़ देगा जिसकी वजह से वह स्कोप से बाहर चला गया था. हालांकि, वह क्वेरी के बाकी हिस्से को पूरा करेगा.

genrule

नियम का सोर्स देखें

genrule(name, srcs, outs, aspect_hints, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule, उपयोगकर्ता की तय की गई Bash कमांड का इस्तेमाल करके एक या उससे ज़्यादा फ़ाइलें जनरेट करता है.

Genrules, सामान्य बिल्ड नियम होते हैं. अगर किसी टास्क के लिए कोई खास नियम नहीं है, तो इनका इस्तेमाल किया जा सकता है. उदाहरण के लिए, Bash की एक लाइन का कोड चलाया जा सकता है. हालांकि, अगर आपको C++ फ़ाइलों को कंपाइल करने की ज़रूरत है, तो मौजूदा cc_* नियमों का पालन करें. ऐसा इसलिए, क्योंकि आपके लिए पहले ही सभी ज़रूरी काम कर दिया गया है.

ध्यान दें कि genrule को कमांड आर्ग्युमेंट को समझने के लिए, शेल की ज़रूरत होती है. PATH पर उपलब्ध किसी भी प्रोग्राम का रेफ़रंस देना भी आसान है. हालांकि, इससे कमांड नॉन-हर्मेटिक हो जाती है और हो सकता है कि इसे फिर से न बनाया जा सके. अगर आपको सिर्फ़ एक टूल चलाना है, तो इसके बजाय run_binary का इस्तेमाल करें.

हर दूसरी कार्रवाई की तरह, जनरूल से बनाई गई कार्रवाई को अपनी वर्किंग डायरेक्ट्री के बारे में कुछ भी नहीं मानना चाहिए. Bazel सिर्फ़ यह गारंटी देता है कि उनके एलान किए गए इनपुट, उस पाथ पर उपलब्ध होंगे जो $(location) उनके लेबल के लिए दिखाता है. उदाहरण के लिए, अगर कोई कार्रवाई सैंडबॉक्स या रिमोट तरीके से की जाती है, तो सैंडबॉक्स या रिमोट तरीके से कार्रवाई करने की प्रोसेस से यह तय होगा कि वर्किंग डायरेक्ट्री कौनसी है. अगर इसे सीधे तौर पर (standalone रणनीति का इस्तेमाल करके) चलाया जाता है, तो वर्किंग डायरेक्ट्री, एक्ज़ीक्यूशन रूट होगी. इसका मतलब है कि यह bazel info execution_root का नतीजा होगी.

टेस्ट चलाने के लिए, genrule का इस्तेमाल न करें. जांच और जांच के नतीजों के लिए, खास छूट दी जाती है. इनमें कैश मेमोरी से जुड़ी नीतियां और एनवायरमेंट वैरिएबल शामिल हैं. आम तौर पर, टेस्ट को बिल्ड पूरा होने के बाद और टारगेट आर्किटेक्चर पर चलाना होता है. वहीं, जनरूल को बिल्ड के दौरान और एक्ज़ेक आर्किटेक्चर पर लागू किया जाता है. ये दोनों अलग-अलग हो सकते हैं. अगर आपको सामान्य मकसद के लिए टेस्टिंग का नियम बनाना है, तो sh_test का इस्तेमाल करें.

क्रॉस-कंपाइलेशन से जुड़ी ज़रूरी बातें

क्रॉस-कंपाइलेशन के बारे में ज़्यादा जानकारी के लिए, उपयोगकर्ता मैन्युअल देखें.

genrules, बिल्ड के दौरान चलते हैं. हालांकि, इनके आउटपुट का इस्तेमाल अक्सर बिल्ड के बाद, डिप्लॉयमेंट या टेस्टिंग के लिए किया जाता है. माइक्रोकंट्रोलर के लिए C कोड कंपाइल करने का उदाहरण देखें: कंपाइलर, C सोर्स फ़ाइलों को स्वीकार करता है और ऐसा कोड जनरेट करता है जो माइक्रोकंट्रोलर पर चलता है. जनरेट किया गया कोड, उस सीपीयू पर नहीं चल सकता जिसका इस्तेमाल इसे बनाने के लिए किया गया था. हालांकि, C कंपाइलर (अगर सोर्स से कंपाइल किया गया है) को ऐसा करना होगा.

बिल्ड सिस्टम, exec कॉन्फ़िगरेशन का इस्तेमाल करके उन मशीनों के बारे में बताता है जिन पर बिल्ड चलता है. साथ ही, टारगेट कॉन्फ़िगरेशन का इस्तेमाल करके उन मशीनों के बारे में बताता है जिन पर बिल्ड का आउटपुट चलना चाहिए. यह इनमें से हर एक को कॉन्फ़िगर करने के विकल्प देता है. साथ ही, यह टकराव से बचने के लिए, इससे जुड़ी फ़ाइलों को अलग-अलग डायरेक्ट्री में बांटता है.

genrules के लिए, बिल्ड सिस्टम यह पक्का करता है कि डिपेंडेंसी को सही तरीके से बनाया गया हो: srcs को target कॉन्फ़िगरेशन के लिए बनाया गया है (अगर ज़रूरी हो), tools को exec कॉन्फ़िगरेशन के लिए बनाया गया है, और आउटपुट को target कॉन्फ़िगरेशन के लिए माना जाता है. यह "मेक" वैरिएबल भी उपलब्ध कराता है. इन्हें genrule कमांड, संबंधित टूल को पास कर सकती हैं.

यह जान-बूझकर किया गया है कि genrule, deps एट्रिब्यूट को तय नहीं करता: अन्य बिल्ट-इन नियम, नियमों के बीच पास की गई भाषा के हिसाब से मेटा जानकारी का इस्तेमाल करते हैं, ताकि यह अपने-आप तय किया जा सके कि निर्भर नियमों को कैसे हैंडल करना है. हालांकि, genrules के लिए इस तरह का ऑटोमेशन मुमकिन नहीं है. Genrules, सिर्फ़ फ़ाइल और runfiles लेवल पर काम करते हैं.

खास मामले

Exec-exec कंपाइलेशन: कुछ मामलों में, बिल्ड सिस्टम को genrules चलाने की ज़रूरत होती है, ताकि बिल्ड के दौरान आउटपुट को भी एक्ज़ीक्यूट किया जा सके. उदाहरण के लिए, अगर कोई genrule कुछ कस्टम कंपाइलर बनाता है और बाद में इसका इस्तेमाल कोई दूसरा genrule करता है, तो पहले वाले genrule को exec कॉन्फ़िगरेशन के लिए अपना आउटपुट जनरेट करना होगा. ऐसा इसलिए, क्योंकि कंपाइलर दूसरे genrule में इसी कॉन्फ़िगरेशन के तहत चलेगा. इस मामले में, बिल्ड सिस्टम अपने-आप सही काम करता है: यह टारगेट कॉन्फ़िगरेशन के बजाय, एक्ज़ेक कॉन्फ़िगरेशन के लिए पहले जनरूल का srcs और outs बनाता है. ज़्यादा जानकारी के लिए, उपयोगकर्ता मैन्युअल देखें.

JDK और C++ टूलिंग: JDK या C++ कंपाइलर सुइट के किसी टूल का इस्तेमाल करने के लिए, बिल्ड सिस्टम इस्तेमाल करने के लिए वैरिएबल का एक सेट उपलब्ध कराता है. ज़्यादा जानकारी के लिए, "Make" वैरिएबल देखें.

Genrule Environment

genrule कमांड को Bash शेल से एक्ज़ीक्यूट किया जाता है. इसे इस तरह कॉन्फ़िगर किया जाता है कि जब कोई कमांड या पाइपलाइन set -e -o pipefail का इस्तेमाल करके फ़ेल हो जाती है, तो यह भी फ़ेल हो जाए.

बिल्ड टूल, बैश कमांड को सैनिटाइज़ किए गए प्रोसेस एनवायरमेंट में एक्ज़ीक्यूट करता है. यह सिर्फ़ मुख्य वैरिएबल तय करता है, जैसे कि PATH, PWD, TMPDIR, और कुछ अन्य. यह पक्का करने के लिए कि बिल्ड को फिर से बनाया जा सके, उपयोगकर्ता के शेल एनवायरमेंट में तय किए गए ज़्यादातर वैरिएबल को genrule के कमांड में पास नहीं किया जाता है. हालांकि, Bazel (Blaze नहीं) उपयोगकर्ता के PATH एनवायरमेंट वैरिएबल की वैल्यू को पास करता है. PATH की वैल्यू में कोई भी बदलाव होने पर, Bazel अगले बिल्ड पर कमांड को फिर से लागू करेगा.

genrule कमांड को नेटवर्क ऐक्सेस नहीं करना चाहिए. हालांकि, यह नियम फ़िलहाल लागू नहीं है. इस नियम के तहत, सिर्फ़ उन प्रोसेस को नेटवर्क ऐक्सेस करने की अनुमति है जो कमांड की चाइल्ड प्रोसेस हैं.

बिल्ड सिस्टम, मौजूदा आउटपुट फ़ाइलों को अपने-आप मिटा देता है. हालांकि, genrule चलाने से पहले, ज़रूरी पैरंट डायरेक्ट्री बना देता है. अगर कोई गड़बड़ी होती है, तो यह आउटपुट फ़ाइलों को भी हटा देता है.

सामान्य सलाह

• यह पक्का करें कि जनरूल से चलने वाले टूल, डिटरमिनिस्टिक और हर्मेटिक हों. उन्हें अपने आउटपुट में टाइमस्टैंप नहीं लिखने चाहिए. साथ ही, उन्हें सेट और मैप के लिए स्टेबल ऑर्डरिंग का इस्तेमाल करना चाहिए. इसके अलावा, उन्हें आउटपुट में सिर्फ़ मिलते-जुलते फ़ाइल पाथ लिखने चाहिए, पूरे पाथ नहीं. इस नियम का पालन न करने पर, बिल्ड में अनचाहे बदलाव हो सकते हैं. जैसे, Bazel उस genrule को फिर से नहीं बनाएगा जिसे आपको फिर से बनाना था. साथ ही, इससे कैश मेमोरी की परफ़ॉर्मेंस भी खराब हो सकती है.
• आउटपुट, टूल, और सोर्स के लिए, $(location) का ज़्यादा से ज़्यादा इस्तेमाल करें. अलग-अलग कॉन्फ़िगरेशन के लिए आउटपुट फ़ाइलों को अलग-अलग करने की वजह से, genrules, हार्ड-कोड किए गए और/या पूरे पाथ पर भरोसा नहीं कर सकते.
• अगर एक ही या मिलते-जुलते genrule का इस्तेमाल कई जगहों पर किया जाता है, तो एक सामान्य Starlark मैक्रो लिखें. अगर जनरूल जटिल है, तो उसे किसी स्क्रिप्ट में या Starlark नियम के तौर पर लागू करें. इससे कोड को पढ़ना और टेस्ट करना आसान हो जाता है.
• पक्का करें कि एक्ज़िट कोड से, यह सही तरीके से पता चलता हो कि genrule सफल हुआ है या नहीं.
• stdout या stderr पर सूचना देने वाले मैसेज न लिखें. यह डीबग करने के लिए मददगार है. हालांकि, इससे आसानी से नॉइज़ जनरेट हो सकती है. इसलिए, जनरूल को साइलेंट होना चाहिए. दूसरी ओर, genrule के फ़ेल होने पर, गड़बड़ी के मैसेज सही तरीके से दिखने चाहिए.
• $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x).
• सिमलिंक और डायरेक्ट्री बनाने से बचें. Bazel, genrules से बनाई गई डायरेक्ट्री/सिमलिंक स्ट्रक्चर को कॉपी नहीं करता है. साथ ही, डायरेक्ट्री की डिपेंडेंसी की जांच करने का तरीका सही नहीं है.
• अन्य नियमों में genrule का रेफ़रंस देते समय, genrule के लेबल या अलग-अलग आउटपुट फ़ाइलों के लेबल का इस्तेमाल किया जा सकता है. कभी-कभी एक तरीका ज़्यादा आसानी से समझ में आता है, तो कभी-कभी दूसरा तरीका: इस्तेमाल किए जा रहे नियम के srcs में नाम के हिसाब से आउटपुट का रेफ़रंस देने से, genrule के अन्य आउटपुट को गलती से चुनने से बचा जा सकेगा. हालांकि, अगर genrule कई आउटपुट जनरेट करता है, तो यह तरीका मुश्किल हो सकता है.

उदाहरण

इस उदाहरण में, foo.h जनरेट किया गया है. कोई सोर्स नहीं है, क्योंकि कमांड कोई इनपुट नहीं लेती है. कमांड से चलने वाला "बाइनरी", genrule के तौर पर एक ही पैकेज में मौजूद पर्ल स्क्रिप्ट है.

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

यहां दिए गए उदाहरण में, filegroup और किसी अन्य genrule के आउटपुट को इस्तेमाल करने का तरीका दिखाया गया है. ध्यान दें कि साफ़ तौर पर बताए गए $(location) निर्देशों के बजाय $(SRCS) का इस्तेमाल करने से भी काम हो जाएगा. इस उदाहरण में, दिखाने के लिए बाद वाले का इस्तेमाल किया गया है.

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

तर्क

विशेषताएं
name	नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम. इस नियम को, अन्य BUILD नियमों के srcs या deps सेक्शन में नाम से रेफ़र किया जा सकता है. अगर नियम से सोर्स फ़ाइलें जनरेट होती हैं, तो आपको srcs एट्रिब्यूट का इस्तेमाल करना चाहिए.
srcs	लेबल की सूची; डिफ़ॉल्ट वैल्यू [] है इस नियम के लिए इनपुट की सूची, जैसे कि प्रोसेस करने के लिए सोर्स फ़ाइलें. यह एट्रिब्यूट, cmd की मदद से लागू किए गए टूल को लिस्ट करने के लिए सही नहीं है. इसके बजाय, उनके लिए tools एट्रिब्यूट का इस्तेमाल करें. बिल्ड सिस्टम यह पक्का करता है कि genrule कमांड चलाने से पहले, इन ज़रूरी शर्तों को पूरा किया गया हो. इन्हें ओरिजनल बिल्ड अनुरोध के तौर पर ही कॉन्फ़िगर किया जाता है. इन ज़रूरी शर्तों की फ़ाइलों के नाम, कमांड के लिए उपलब्ध होते हैं. ये नाम, स्पेस से अलग की गई सूची के तौर पर $(SRCS) में उपलब्ध होते हैं. इसके अलावा, किसी srcs टारगेट //x:y का पाथ, $(location //x:y) का इस्तेमाल करके या $< का इस्तेमाल करके पाया जा सकता है. हालांकि, ऐसा तब ही किया जा सकता है, जब srcs में सिर्फ़ एक एंट्री हो.
outs	फ़ाइल के नामों की सूची; कॉन्फ़िगर नहीं किया जा सकता; ज़रूरी है इस नियम से जनरेट की गई फ़ाइलों की सूची. आउटपुट फ़ाइलें, पैकेज की सीमाओं से बाहर नहीं होनी चाहिए. आउटपुट फ़ाइलों के नाम, पैकेज के हिसाब से तय किए जाते हैं. अगर executable फ़्लैग सेट है, तो outs में सिर्फ़ एक लेबल होना चाहिए. genrule कमांड से, हर आउटपुट फ़ाइल को पहले से तय की गई जगह पर बनाने की उम्मीद की जाती है. जगह की जानकारी, cmd में उपलब्ध है. इसके लिए, genrule के हिसाब से "Make" वैरिएबल ($@, $(OUTS), $(@D) या $(RULEDIR)) या $(location) सब्स्टिट्यूशन का इस्तेमाल किया जाता है.
cmd	स्ट्रिंग; डिफ़ॉल्ट वैल्यू "" है कमांड चलाने के लिए. $(location) और "मेक" वैरिएबल के हिसाब से बदलाव किया जा सकता है. सबसे पहले, $(location) को बदला जाता है. इससे $(location label) और $(locations label) (और execpath, execpaths, rootpath, और rootpaths जैसे मिलते-जुलते वैरिएबल का इस्तेमाल करके बनाए गए अन्य कंस्ट्रक्शन) की सभी जगहों पर बदलाव हो जाता है. इसके बाद, "मेक" वैरिएबल को बड़ा किया जाता है. ध्यान दें कि पहले से तय किए गए वैरिएबल $(JAVA), $(JAVAC), और $(JAVABASE), exec कॉन्फ़िगरेशन में दिखते हैं. इसलिए, बिल्ड स्टेप के हिस्से के तौर पर चलने वाले Java इनवोकेशन, शेयर की गई लाइब्रेरी और अन्य डिपेंडेंसी को सही तरीके से लोड कर सकते हैं. आखिर में, Bash शेल का इस्तेमाल करके, नतीजे के तौर पर मिली कमांड को लागू किया जाता है. अगर इसका एग्ज़िट कोड शून्य नहीं है, तो माना जाता है कि कमांड काम नहीं कर रही है. अगर इनमें से कोई भी लागू नहीं होता है, तो यह cmd_bash, cmd_ps, और cmd_bat का फ़ॉलबैक है. अगर कमांड लाइन की लंबाई प्लैटफ़ॉर्म की सीमा से ज़्यादा है (Linux/macOS पर 64K, Windows पर 8K), तो genrule, कमांड को स्क्रिप्ट में लिखेगा और उस स्क्रिप्ट को एक्ज़ीक्यूट करेगा. यह सभी सीएमडी एट्रिब्यूट (cmd, cmd_bash, cmd_ps, cmd_bat) पर लागू होता है.
cmd_bash	स्ट्रिंग; डिफ़ॉल्ट वैल्यू "" है Bash कमांड चलाने के लिए. इस एट्रिब्यूट को cmd एट्रिब्यूट से ज़्यादा प्राथमिकता दी जाती है. कमांड को बड़ा किया जाता है और यह cmd एट्रिब्यूट की तरह ही काम करती है.
cmd_bat	स्ट्रिंग; डिफ़ॉल्ट वैल्यू "" है Windows पर चलाने के लिए बैच कमांड. इस एट्रिब्यूट को cmd और cmd_bash एट्रिब्यूट से ज़्यादा प्राथमिकता दी जाती है. यह कमांड, cmd एट्रिब्यूट की तरह ही काम करती है. हालांकि, इसमें ये अंतर होते हैं: यह एट्रिब्यूट सिर्फ़ Windows पर लागू होता है. यह कमांड, cmd.exe /c के साथ चलती है. इसमें डिफ़ॉल्ट रूप से ये तर्क शामिल होते हैं: /S - पहले और आखिरी कोटेशन मार्क को हटा दें और बाकी सभी को वैसे ही लागू करें. /E:ON - एक्सटेंडेड कमांड सेट चालू करें. /V:ON - वैरिएबल एक्सपैंशन को कुछ समय के लिए चालू करें /D - AutoRun रजिस्ट्री एंट्री को अनदेखा करें. $(location) और "Make" वैरिएबल को बदलने के बाद, पाथ को Windows स्टाइल के पाथ (बैकस्लैश के साथ) में बदल दिया जाएगा.
cmd_ps	स्ट्रिंग; डिफ़ॉल्ट वैल्यू "" है Windows पर चलाने के लिए Powershell कमांड. इस एट्रिब्यूट को cmd, cmd_bash, और cmd_bat एट्रिब्यूट के मुकाबले ज़्यादा प्राथमिकता दी जाती है. यह कमांड, cmd एट्रिब्यूट की तरह ही काम करती है. हालांकि, इसमें ये अंतर हैं: यह एट्रिब्यूट सिर्फ़ Windows पर लागू होता है. यह निर्देश powershell.exe /c के साथ काम करता है. Powershell का इस्तेमाल आसान बनाने और इसमें कम से कम गड़बड़ियां होने के लिए, हम यहां दिए गए निर्देशों को चलाते हैं. इससे genrule में Powershell निर्देश को लागू करने से पहले, एनवायरमेंट सेट अप हो जाता है. Set-ExecutionPolicy -Scope CurrentUser RemoteSigned - बिना हस्ताक्षर वाली स्क्रिप्ट चलाने की अनुमति देता है. $errorActionPreference='Stop' - अगर एक से ज़्यादा कमांड को ; से अलग किया गया है, तो Powershell CmdLet के काम न करने पर कार्रवाई तुरंत बंद हो जाती है. हालांकि, यह बाहरी कमांड के लिए काम नहीं करता. $PSDefaultParameterValues['*:Encoding'] = 'utf8' - डिफ़ॉल्ट एन्कोडिंग को utf-16 से बदलकर utf-8 करें.
executable	बूलियन; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट वैल्यू False है आउटपुट को एक्ज़ीक्यूट करने लायक घोषित करें. इस फ़्लैग को 'सही है' पर सेट करने का मतलब है कि आउटपुट एक एक्ज़ीक्यूटेबल फ़ाइल है और इसे run कमांड का इस्तेमाल करके चलाया जा सकता है. इस मामले में, genrule को सिर्फ़ एक आउटपुट जनरेट करना होगा. अगर यह एट्रिब्यूट सेट किया जाता है, तो run फ़ाइल के कॉन्टेंट पर ध्यान दिए बिना उसे चलाने की कोशिश करेगा. जनरेट किए गए एक्ज़ीक्यूटेबल के लिए, डेटा डिपेंडेंसी का एलान करने की सुविधा उपलब्ध नहीं है.
local	बूलियन; डिफ़ॉल्ट वैल्यू False है अगर इसे 'सही है' पर सेट किया जाता है, तो यह विकल्प इस genrule को "स्थानीय" रणनीति का इस्तेमाल करके चलाने के लिए मजबूर करता है. इसका मतलब है कि कोई रिमोट एक्ज़ीक्यूशन नहीं होगा, कोई सैंडबॉक्सिंग नहीं होगी, और कोई परसिस्टेंट वर्कर नहीं होगा. यह 'local' को टैग (tags=["local"]) के तौर पर देने के बराबर है.
message	स्ट्रिंग; डिफ़ॉल्ट वैल्यू "" है प्रोग्रेस मैसेज. प्रोग्रेस मैसेज, जिसे इस बिल्ड स्टेप के पूरा होने पर प्रिंट किया जाएगा. डिफ़ॉल्ट रूप से, मैसेज "आउटपुट जनरेट किया जा रहा है" (या इसी तरह का कोई और मैसेज) होता है. हालांकि, आपके पास ज़्यादा जानकारी देने वाला मैसेज उपलब्ध कराने का विकल्प होता है. अपनी cmd कमांड में echo या अन्य प्रिंट स्टेटमेंट के बजाय, इस एट्रिब्यूट का इस्तेमाल करें. इससे बिल्ड टूल को यह कंट्रोल करने की अनुमति मिलती है कि इस तरह के प्रोग्रेस मैसेज प्रिंट किए जाएं या नहीं.
output_licenses	स्ट्रिंग की सूची; डिफ़ॉल्ट वैल्यू [] है common attributes देखें
output_to_bindir	बूलियन; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट वैल्यू False है अगर इस विकल्प को 'सही है' पर सेट किया जाता है, तो आउटपुट फ़ाइलें bin डायरेक्ट्री के बजाय genfiles डायरेक्ट्री में लिखी जाती हैं.
toolchains	लेबल की सूची; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट वैल्यू [] है टारगेट का वह सेट जिनके Make variables को यह जनरूल ऐक्सेस कर सकता है या toolchain_type टारगेट जिन्हें यह जनरूल ऐक्सेस करेगा. toolchain_type के ज़रिए ऐक्सेस की गई टूलचेन को TemplateVariableInfo प्रोवाइडर भी उपलब्ध कराना होगा. टारगेट इसका इस्तेमाल करके, टूलचेन की जानकारी ऐक्सेस कर सकता है.
tools	लेबल की सूची; डिफ़ॉल्ट वैल्यू [] है इस नियम के लिए, टूल की डिपेंडेंसी की सूची. ज़्यादा जानकारी के लिए, डिपेंडेंसी की परिभाषा देखें. बिल्ड सिस्टम यह पक्का करता है कि genrule कमांड चलाने से पहले, ये ज़रूरी शर्तें पूरी हो गई हों. इन्हें exec कॉन्फ़िगरेशन का इस्तेमाल करके बनाया जाता है, क्योंकि इन टूल को बिल्ड के हिस्से के तौर पर एक्ज़ीक्यूट किया जाता है. $(location //x:y) का इस्तेमाल करके, किसी व्यक्ति के tools टारगेट //x:y का पाथ पाया जा सकता है. cmd की मदद से लागू किए जाने वाले किसी भी *_binary या टूल को इस सूची में शामिल किया जाना चाहिए, न कि srcs में. इससे यह पक्का किया जा सकेगा कि उन्हें सही कॉन्फ़िगरेशन में बनाया गया है.

starlark_doc_extract

नियम का सोर्स देखें

starlark_doc_extract(name, deps, src, data, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, package_metadata, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract(), नियमों, फ़ंक्शन (मैक्रो सहित), पहलुओं, और किसी .bzl या .scl फ़ाइल में तय किए गए या फिर से एक्सपोर्ट किए गए प्रोवाइडर के लिए दस्तावेज़ निकालता है. इस नियम का आउटपुट, ModuleInfo बाइनरी प्रोटो है. इसे Bazel के सोर्स ट्री में stardoc_output.proto में तय किया गया है.

इंप्लिसिट आउटपुट टारगेट

• name.binaryproto (डिफ़ॉल्ट आउटपुट): A ModuleInfo बाइनरी प्रोटो.
• name.textproto (सिर्फ़ तब बनाया जाता है, जब साफ़ तौर पर अनुरोध किया गया हो): name.binaryproto का टेक्स्ट प्रोटो वर्शन.

चेतावनी: इस नियम के आउटपुट फ़ॉर्मैट के स्थिर होने की कोई गारंटी नहीं है. इसका इस्तेमाल मुख्य रूप से Stardoc के कर्मचारी करते हैं.

तर्क

विशेषताएं
name	नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम.
deps	लेबल की सूची; डिफ़ॉल्ट वैल्यू [] है यह उन टारगेट की सूची होती है जिनमें Starlark फ़ाइलें शामिल होती हैं. इन फ़ाइलों को src ने load() किया है. सामान्य तौर पर, इन टारगेट को टारगेट bzl_library होना चाहिए. हालांकि, starlark_doc_extract नियम इसे लागू नहीं करता है. साथ ही, यह ऐसे किसी भी टारगेट को स्वीकार करता है जो अपने DefaultInfo में Starlark फ़ाइलें उपलब्ध कराता है. ध्यान दें कि रैप की गई Starlark फ़ाइलें, सोर्स ट्री में मौजूद फ़ाइलें होनी चाहिए. Bazel, load() जनरेट की गई फ़ाइलों को रैप नहीं कर सकता.
src	लेबल; ज़रूरी है वह Starlark फ़ाइल जिससे दस्तावेज़ निकालना है. ध्यान दें कि यह फ़ाइल, सोर्स ट्री में होनी चाहिए. Bazel, load() जनरेट की गई फ़ाइलों को प्रोसेस नहीं कर सकता.
render_main_repo_name	बूलियन; डिफ़ॉल्ट वैल्यू False है अगर यह वैल्यू सही है, तो मुख्य रिपॉज़िटरी में मौजूद लेबल, रिपॉज़िटरी कॉम्पोनेंट के साथ जारी किए गए दस्तावेज़ में रेंडर किए जाएंगे. दूसरे शब्दों में, //foo:bar.bzl को @main_repo_name//foo:bar.bzl के तौर पर जारी किया जाएगा. मुख्य रिपॉज़िटरी के लिए इस्तेमाल किया जाने वाला नाम, मुख्य रिपॉज़िटरी की MODULE.bazel फ़ाइल में मौजूद module(name = ...) से मिलता है. ऐसा तब होता है, जब Bzlmod चालू हो. इसके अलावा, यह नाम मुख्य रिपॉज़िटरी की WORKSPACE फ़ाइल में मौजूद workspace(name = ...) से भी मिलता है. इस एट्रिब्यूट को False पर सेट किया जाना चाहिए, जब एक ही रिपॉज़िटरी में इस्तेमाल की जाने वाली Starlark फ़ाइलों के लिए दस्तावेज़ जनरेट किए जा रहे हों. साथ ही, इसे True पर सेट किया जाना चाहिए, जब अन्य रिपॉज़िटरी में इस्तेमाल की जाने वाली Starlark फ़ाइलों के लिए दस्तावेज़ जनरेट किए जा रहे हों.
symbol_names	स्ट्रिंग की सूची; डिफ़ॉल्ट वैल्यू [] है एक्सपोर्ट किए गए फ़ंक्शन, नियम, प्रोवाइडर या पहलुओं (या जिनमें वे नेस्ट किए गए हैं) के क्वालिफ़ाइड नामों की एक वैकल्पिक सूची. इससे दस्तावेज़ निकाला जा सकता है. यहां, क्वालिफ़ाइड नेम का मतलब उस नाम से है जिसके तहत किसी इकाई को मॉड्यूल के उपयोगकर्ता के लिए उपलब्ध कराया जाता है. इसमें वे सभी स्ट्रक्चर शामिल हैं जिनमें नेमस्पेसिंग के लिए इकाई को नेस्ट किया गया है. starlark_doc_extract किसी इकाई के लिए दस्तावेज़ तब ही जारी करता है, जब इकाई के क्वालिफ़ाइड नाम का हर कॉम्पोनेंट सार्वजनिक हो. दूसरे शब्दों में कहें, तो क्वालिफ़ाइड नाम के हर कॉम्पोनेंट का पहला वर्ण अक्षर हो, न कि "_"; और या तो symbol_names सूची खाली है (यह डिफ़ॉल्ट केस है), या इकाई का क्वालिफ़ाइड नाम या उस स्ट्रक्चर का क्वालिफ़ाइड नाम जिसमें इकाई नेस्ट की गई है, symbol_names सूची में है.

test_suite

नियम का सोर्स देखें

test_suite(name, aspect_hints, compatible_with, deprecation, features, licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

test_suite, टेस्ट का एक ऐसा सेट होता है जिसे इंसानों के लिए "काम का" माना जाता है. इससे प्रोजेक्ट को टेस्ट के सेट तय करने की अनुमति मिलती है. जैसे, "चेकइन से पहले किए जाने वाले टेस्ट", "हमारे प्रोजेक्ट के स्ट्रेस टेस्ट" या "सभी छोटे टेस्ट." bazel test कमांड, इस तरह के संगठन का पालन करती है: bazel test //some/test:suite जैसे इनवोकेशन के लिए, Bazel पहले //some/test:suite टारगेट में ट्रांज़िटिव तरीके से शामिल किए गए सभी टेस्ट टारगेट की गिनती करता है. इसे "test_suite एक्सपैंशन" कहा जाता है. इसके बाद, Bazel उन टारगेट को बनाता है और उनकी जांच करता है.

उदाहरण

यह टेस्ट सुइट, मौजूदा पैकेज में मौजूद सभी छोटे टेस्ट चलाने के लिए होता है.

test_suite(
    name = "small_tests",
    tags = ["small"],
)

यह एक टेस्ट सुइट है, जो टेस्ट के तय किए गए सेट को चलाता है:

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

यह एक टेस्ट सुइट है. इसका इस्तेमाल, मौजूदा पैकेज में मौजूद उन सभी टेस्ट को चलाने के लिए किया जाता है जो फ़्लेकी नहीं हैं.

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

तर्क

विशेषताएं
name	नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम.
tags	स्ट्रिंग की सूची; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट वैल्यू [] है टेक्स्ट टैग की सूची. जैसे, "small" या "database" या "-flaky". टैग कोई भी मान्य स्ट्रिंग हो सकते हैं. "-" वर्ण से शुरू होने वाले टैग को नेगेटिव टैग माना जाता है. "-" वर्ण को टैग का हिस्सा नहीं माना जाता. इसलिए, "-small" वाला सुइट टैग, टेस्ट के "small" साइज़ से मेल खाता है. अन्य सभी टैग को पॉज़िटिव टैग माना जाता है. अगर आपको पॉज़िटिव टैग को ज़्यादा साफ़ तौर पर दिखाना है, तो टैग "+" वर्ण से भी शुरू हो सकते हैं. हालांकि, इन्हें टैग के टेक्स्ट का हिस्सा नहीं माना जाएगा. इससे सिर्फ़ पॉज़िटिव और नेगेटिव नोट को आसानी से पढ़ा जा सकता है. टेस्ट सुइट में सिर्फ़ वे नियम शामिल किए जाएंगे जो पॉज़िटिव टैग में से सभी और नेगेटिव टैग में से कोई नहीं से मेल खाते हों. ध्यान दें कि इसका मतलब यह नहीं है कि फ़िल्टर किए गए टेस्ट पर निर्भरता के लिए, गड़बड़ी की जांच को छोड़ दिया जाता है.छोड़े गए टेस्ट पर निर्भरता अब भी कानूनी होनी चाहिए. उदाहरण के लिए, यह दिखने से जुड़ी पाबंदियों की वजह से ब्लॉक नहीं होनी चाहिए. manual टैग किए गए कीवर्ड को ऊपर दिए गए कीवर्ड से अलग तरीके से ट्रीट किया जाता है. ऐसा manual कमांड की मदद से "टेस्ट सुइट एक्सपैंशन" की वजह से होता है. यह कमांड, वाइल्डकार्ड वाले टारगेट पैटर्न से जुड़े इनवोकेशन पर काम करती है.bazel test यहां, "मैन्युअल" के तौर पर टैग किए गए test_suite टारगेट को फ़िल्टर कर दिया जाता है. इसलिए, इन्हें बढ़ाया नहीं जाता. यह तरीका, bazel build और bazel test के वाइल्डकार्ड टारगेट पैटर्न को हैंडल करने के तरीके के मुताबिक है. ध्यान दें कि यह bazel query 'tests(E)' के काम करने के तरीके से अलग है. ऐसा इसलिए, क्योंकि सुइट को हमेशा tests क्वेरी फ़ंक्शन से बड़ा किया जाता है. इससे कोई फ़र्क़ नहीं पड़ता कि manual टैग कौन-सा है. ध्यान दें कि फ़िल्टर करने के लिए, किसी टेस्ट के size को टैग माना जाता है. अगर आपको ऐसा test_suite चाहिए जिसमें एक-दूसरे से अलग टैग वाले टेस्ट शामिल हों (जैसे, सभी छोटे और मीडियम टेस्ट), तो आपको तीन test_suite नियम बनाने होंगे: एक सभी छोटे टेस्ट के लिए, एक सभी मीडियम टेस्ट के लिए, और एक जिसमें पिछले दो टेस्ट शामिल हों.
tests	लेबल की सूची; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट वैल्यू [] है किसी भी भाषा की टेस्ट सुइट और टेस्ट टारगेट की सूची. यहां किसी भी *_test को स्वीकार किया जाता है, भले ही वह किसी भी भाषा में हो. नहीं *_binary टारगेट स्वीकार नहीं किए जाते. भले ही, वे कोई टेस्ट चला रहे हों. बताए गए tags के हिसाब से फ़िल्टर करने की सुविधा, सिर्फ़ उन टेस्ट के लिए उपलब्ध है जो सीधे तौर पर इस एट्रिब्यूट में शामिल हैं. अगर इस एट्रिब्यूट में test_suite शामिल हैं, तो उनमें मौजूद टेस्ट को इस test_suite से फ़िल्टर नहीं किया जाएगा. ऐसा इसलिए, क्योंकि उन्हें पहले से ही फ़िल्टर किया गया माना जाता है. अगर tests एट्रिब्यूट की वैल्यू नहीं दी गई है या यह खाली है, तो नियम डिफ़ॉल्ट रूप से, मौजूदा BUILD फ़ाइल में मौजूद उन सभी टेस्ट नियमों को शामिल करेगा जिन्हें manual के तौर पर टैग नहीं किया गया है. इन नियमों पर अब भी tag फ़िल्टरिंग लागू होती है.