सामान्य नियम

7.3 · 7.2 · 7.1 · 7.0 · 6.5

नियम

• उपनाम
• config_setting
• filegroup
• genquery
• जेनरुल
• starlark_doc_extract
• test_suite

उपनाम

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

alias(name, actual, compatible_with, deprecation, features, 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, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

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

उदाहरण

नीचे दी गई चीज़ें ऐसे किसी भी बिल्ड से मेल खाती हैं जो --compilation_mode=opt या -c opt को सेट करती है (साफ़ तौर पर कमांड लाइन पर या सीधे तौर पर .baZZrc फ़ाइलों से):

  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"
      }
  )
  

नीचे दी गई चीज़ें ऐसे किसी भी बिल्ड से मेल खाती हैं जो उपयोगकर्ता के लिए तय किया गया फ़्लैग --//custom_flags:foo=1 को सेट करता है (साफ़ तौर पर कमांड लाइन पर या सीधे तौर पर .baazrc फ़ाइलों से):

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

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

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

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

नोट

• जब एक से ज़्यादा config_setting, कॉन्फ़िगरेशन की मौजूदा स्थिति से मैच करते हैं, तो क्या होता है, यह जानने के लिए चुनें देखें.
• --compilation_mode बनाम -c जैसे शॉर्टहैंड फ़ॉर्म के साथ काम करने वाले फ़्लैग के लिए, values परिभाषाओं में पूरे फ़ॉर्म का इस्तेमाल किया जाना चाहिए. ये किसी भी फ़ॉर्म का इस्तेमाल करके, अपने-आप कॉल के साथ मैच हो जाते हैं.
• अगर किसी फ़्लैग में एक से ज़्यादा वैल्यू होती हैं (जैसे कि --copt=-Da --copt=-Db या सूची के तौर पर स्टारलार्क फ़्लैग), तो 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 से मैच कर सके. (कार्रवाई करने वाले प्लैटफ़ॉर्म को यहां शामिल नहीं किया जाता.) प्लैटफ़ॉर्म पर मौजूद अन्य पाबंदियों की वैल्यू को अनदेखा कर दिया जाता है. ज़्यादा जानकारी के लिए, कॉन्फ़िगर किए जा सकने वाले बिल्ड एट्रिब्यूट देखें. अगर दो config_setting एक ही select से मैच करते हैं, तो यह तय करने के लिए कि इनमें से कोई एक config_setting, दूसरे की विशेषता है या नहीं, इस एट्रिब्यूट को ध्यान में नहीं रखा जाता. दूसरे शब्दों में, एक config_setting किसी प्लैटफ़ॉर्म से दूसरे प्लैटफ़ॉर्म से ज़्यादा मैच नहीं कर सकता.
define_values	डिक्शनरी: स्ट्रिंग -> स्ट्रिंग; nonconfigurable; डिफ़ॉल्ट {} है यह values जैसा ही है, लेकिन खास तौर पर --define फ़्लैग के लिए. --define खास है, क्योंकि इसके सिंटैक्स (--define KEY=VAL) का मतलब है कि KEY=VAL, Bazel फ़्लैग के हिसाब से वैल्यू है. इसका मतलब है कि: 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 -> स्ट्रिंग; कॉन्फ़िगर नहीं की जा सकती; डिफ़ॉल्ट रूप से {} है values की तरह ही है, लेकिन उपयोगकर्ता के तय किए गए बिल्ड फ़्लैग के लिए. यह एक अलग एट्रिब्यूट है, क्योंकि उपयोगकर्ता के तय किए गए फ़्लैग को लेबल के तौर पर दिखाया जाता है, जबकि पहले से मौजूद फ़्लैग को आर्बिट्रेरी स्ट्रिंग के तौर पर बताया जाता है.
values	डिक्शनरी: स्ट्रिंग -> स्ट्रिंग; nonconfigurable; डिफ़ॉल्ट {} है इस नियम से मेल खाने वाली कॉन्फ़िगरेशन वैल्यू का सेट (इसे बिल्ड फ़्लैग के तौर पर दिखाया जाता है) यह नियम, कॉन्फ़िगर किए गए उस टारगेट का कॉन्फ़िगरेशन इनहेरिट करता है जो select स्टेटमेंट में इसका रेफ़रंस देता है. इसे 'Baज़ल' कहते हैं, इसलिए इसे "मिलते-जुलते" तब माना जाता है, जब शब्दकोश में मौजूद हर एंट्री के लिए उसका कॉन्फ़िगरेशन, एंट्री की अनुमानित वैल्यू से मेल खाता हो. उदाहरण के लिए, values = {"compilation_mode": "opt"}, टारगेट के लिए कॉन्फ़िगर किए गए नियमों पर bazel build --compilation_mode=opt ... और bazel build -c opt ... से मैच होता है. सुविधा के लिए, कॉन्फ़िगरेशन वैल्यू को बिल्ड फ़्लैग के तौर पर दिखाया जाता है (पिछले "--" के बिना). हालांकि, ध्यान रखें कि ये दोनों एक जैसी नहीं होती हैं. ऐसा इसलिए होता है, क्योंकि एक ही बिल्ड में कई कॉन्फ़िगरेशन में टारगेट बनाए जा सकते हैं. उदाहरण के लिए, exec कॉन्फ़िगरेशन का "cpu", --cpu की वैल्यू से नहीं, बल्कि --host_cpu की वैल्यू से मैच करता है. इसलिए, एक ही config_setting के अलग-अलग इंस्टेंस, एक ही कॉल को अलग-अलग तरीके से मैच कर सकते हैं. यह इस बात पर निर्भर करता है कि उनका इस्तेमाल करने वाले नियम का कॉन्फ़िगरेशन क्या है. अगर कमांड लाइन पर कोई फ़्लैग साफ़ तौर पर सेट नहीं किया गया है, तो उसकी डिफ़ॉल्ट वैल्यू का इस्तेमाल किया जाता है. अगर कोई कीवर्ड डिक्शनरी में कई बार दिखता है, तो सिर्फ़ आखिरी इंस्टेंस का इस्तेमाल किया जाता है. अगर कोई कुंजी किसी ऐसे फ़्लैग का रेफ़रंस देती है जिसे कमांड लाइन पर कई बार सेट किया जा सकता है (उदाहरण के लिए, bazel build --copt=foo --copt=bar --copt=baz ...), तो मैच तब होता है, जब उनमें से कोई भी सेटिंग मैच करती है.

फ़ाइलग्रुप

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

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

टारगेट के कलेक्शन को कोई आसान नाम देने के लिए, filegroup का इस्तेमाल करें. इसके बाद, इनका रेफ़रंस दूसरे नियमों से लिया जा सकता है.

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

उदाहरण

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

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

इसके अलावा, testdata डायरेक्ट्री को grovel करने के लिए, 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 में जोड़ दिए जाएंगे. जब filegroup को किसी दूसरे नियम के data एट्रिब्यूट में रेफ़र किया गया हो, तो इसके runfiles को इस नियम के runfiles में जोड़ दिया जाएगा. डेटा फ़ाइलों पर निर्भर रहने और उन्हें इस्तेमाल करने के तरीके के बारे में ज़्यादा जानकारी के लिए, डेटा डिपेंडेंसी सेक्शन और data का सामान्य दस्तावेज़ देखें.
output_group	स्ट्रिंग; डिफ़ॉल्ट तौर पर "" है वह आउटपुट ग्रुप जिससे सोर्स से आर्टफ़ैक्ट इकट्ठा करना है. अगर यह एट्रिब्यूट दिया गया है, तो डिपेंडेंसी के तय किए गए आउटपुट ग्रुप के आर्टफ़ैक्ट, डिफ़ॉल्ट आउटपुट ग्रुप के बजाय एक्सपोर्ट किए जाएंगे. "आउटपुट ग्रुप", किसी टारगेट के आउटपुट आर्टफ़ैक्ट की कैटगरी होती है. इसे नियम के लागू होने के दौरान तय किया जाता है.

Genquery

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

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

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

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

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

डिटरमिनिस्टिक आउटपुट लागू करने के लिए, जेनक्वेरी के आउटपुट को लेक्सिकोग्राफ़िक तरीके से क्रम में लगाया जाता है. हालांकि, --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 पहले से ही, 2^20 बाइट से ज़्यादा के क्वेरी आउटपुट को अंदरूनी तौर पर कंप्रेस कर देता है. इस सेटिंग की वैल्यू चाहे जो भी हो, इससे कोई फ़र्क़ नहीं पड़ता. इसलिए, हो सकता है कि इसे True पर सेट करने से, सेव किए गए ढेर का साइज़ कम न हो. हालांकि, इससे आउटपुट फ़ाइल लिखते समय Basel को डिकंप्रेशन करने की प्रक्रिया नहीं करने का विकल्प मिलता है. इस फ़ाइल में बहुत ज़्यादा मेमोरी हो सकती है.
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, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

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

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

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

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

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

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

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

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

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

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

खास मामले

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

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

Genrule एनवायरमेंट

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

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

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

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

सामान्य सलाह

• पक्का करें कि genrule से चलाए जाने वाले टूल, डिटरमिनिस्टिक और हर्मेटिक हों. उन्हें अपने आउटपुट के लिए टाइमस्टैंप नहीं लिखने चाहिए. साथ ही, उन्हें सेट और मैप के लिए स्थायी क्रम का इस्तेमाल करना चाहिए. साथ ही, उन्हें आउटपुट के मिलते-जुलते फ़ाइल पाथ लिखने चाहिए, ऐब्सलूट पाथ का इस्तेमाल नहीं करना चाहिए. इस नियम का पालन न करने पर, बिल्ड के तरीके में कोई गड़बड़ी होगी और इससे कैश मेमोरी की परफ़ॉर्मेंस खराब होगी. साथ ही, बैज की मदद से जनरेट किया गया सामान्य नियम फिर से नहीं बनाया जाएगा.
• आउटपुट, टूल, और सोर्स के लिए, $(location) का ज़्यादा से ज़्यादा इस्तेमाल करें. अलग-अलग कॉन्फ़िगरेशन के लिए आउटपुट फ़ाइलों को अलग-अलग करने की वजह से, जेन नियम हार्ड कोड किए गए और/या ऐब्सलूट पाथ पर भरोसा नहीं कर सकते.
• अगर एक जैसे या काफ़ी मिलते-जुलते जेन नियम कई जगहों पर इस्तेमाल किए गए हों, तो एक सामान्य Starlark मैक्रो ज़रूर लिखें. अगर genrule जटिल है, तो उसे स्क्रिप्ट में या Starlark नियम के तौर पर लागू करें. इससे ऐप्लिकेशन को पढ़ना आसान होने के साथ-साथ, टेस्ट करने में आसानी होती है.
• पक्का करें कि बाहर निकलने का कोड, genrule के काम करने या न करने के बारे में सही जानकारी देता हो.
• जानकारी देने वाले मैसेज, स्टैंडआउट या स्टैंडर्ड गड़बड़ी वाले आउटपुट में न लिखें. डीबग करने के लिए यह मददगार है, लेकिन यह आसानी से ग़ैर-ज़रूरी जानकारी बन सकता है. सही genrule में कोई ग़ैर-ज़रूरी जानकारी नहीं होनी चाहिए. दूसरी ओर, काम न करने वाले 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).
• सिंबललिंक और डायरेक्ट्री बनाने से बचें. Basel, genनियमों के ज़रिए बनाई गई डायरेक्ट्री/सिमलिंक स्ट्रक्चर को कॉपी नहीं करता है. साथ ही, डायरेक्ट्री के लिए इसकी डिपेंडेंसी की जांच से जुड़ी कोई जानकारी नहीं मिलती है.
• अन्य नियमों में जेन रूल का रेफ़रंस देते समय, जेन नियम के लेबल या अलग-अलग आउटपुट फ़ाइलों के लेबल का इस्तेमाल किया जा सकता है. कभी-कभी एक तरीका ज़्यादा पढ़ने लायक होता है, कभी-कभी दूसरा: इस्तेमाल करने वाले नियम के srcs में आउटपुट को नाम से बताने से अनजाने में जेनरूल के दूसरे आउटपुट को चुनने से बचा जा सकता है, लेकिन अगर जेनरल से कई आउटपुट मिलते हैं, तो यह मुश्किल हो सकता है.

उदाहरण

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

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

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

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	नाम; यह ज़रूरी है इस टारगेट के लिए यूनीक नाम. आप इस नियम को srcs या BUILD के अन्य नियमों के deps सेक्शन में नाम दे सकते हैं. अगर नियम सोर्स फ़ाइलें जनरेट करता है, तो आपको srcs एट्रिब्यूट का इस्तेमाल करना चाहिए.
srcs	लेबल की सूची; डिफ़ॉल्ट [] है इस नियम के लिए इनपुट की सूची, जैसे कि प्रोसेस की जाने वाली सोर्स फ़ाइलें. यह एट्रिब्यूट, cmd से चलाए जाने वाले टूल की सूची बनाने के लिए सही नहीं है. इसके बजाय, tools एट्रिब्यूट का इस्तेमाल करें. बिल्ड सिस्टम यह पक्का करता है कि genrule कमांड को चलाने से पहले, ये ज़रूरी शर्तें पूरी कर ली गई हों. इन्हें उसी कॉन्फ़िगरेशन का इस्तेमाल करके बनाया जाता है जिसका इस्तेमाल ओरिजनल बिल्ड रिक्वेस्ट के लिए किया गया था. इन ज़रूरी शर्तों की फ़ाइलों के नाम, कमांड में, $(SRCS) में स्पेस से अलग की गई सूची के तौर पर उपलब्ध हैं. इसके अलावा, किसी srcs टारगेट //x:y का पाथ, $(location //x:y) या $< का इस्तेमाल करके भी पाया जा सकता है. हालांकि, इसके लिए ज़रूरी है कि srcs में सिर्फ़ यही एंट्री हो.
outs	फ़ाइल नाम की सूची; कॉन्फ़िगर नहीं की जा सकती; ज़रूरी है इस नियम से जनरेट हुई फ़ाइलों की सूची. आउटपुट फ़ाइलें, पैकेज की सीमाओं से ज़्यादा नहीं होनी चाहिए. आउटपुट फ़ाइल नामों को पैकेज के हिसाब से समझा जाता है. अगर executable फ़्लैग सेट है, तो outs में सिर्फ़ एक लेबल होना चाहिए. जेनरूल कमांड से हर आउटपुट फ़ाइल को पहले से तय जगह पर बनाया जाता है. जगह की जानकारी, cmd में उपलब्ध है. इसके लिए, genrule के हिसाब से "Make" वैरिएबल ($@, $(OUTS), $(@D) या $(RULEDIR)) का इस्तेमाल करें या $(location) सबस्टिट्यूशन का इस्तेमाल करें.
cmd	स्ट्रिंग; डिफ़ॉल्ट रूप से "" चलाया जाने वाला निर्देश. $(location) और "Make" वैरिएबल के बदले जाने के अधीन है. $(location label) और $(locations label) की सभी वैल्यू को बदल दिया गया है. साथ ही, इससे जुड़े वैरिएबल execpath, execpaths, rootpath, और rootpaths का इस्तेमाल करके बनाए गए ऐसे ही कंस्ट्रक्शन को बदलकर, पहला $(location) बदलाव लागू कर दिया गया है. इसके बाद, "Make" वैरिएबल को बड़ा किया जाता है. ध्यान दें कि पहले से तय वैरिएबल $(JAVA), $(JAVAC), और $(JAVABASE), exec कॉन्फ़िगरेशन के तहत बड़े हो जाते हैं. इसलिए, बिल्ड चरण के हिस्से के तौर पर चलने वाले Java invocatio, शेयर की गई लाइब्रेरी और अन्य डिपेंडेंसी को सही तरीके से लोड कर सकते हैं. आखिर में, Bash शेल का इस्तेमाल करके, नतीजे के तौर पर मिला कमांड चलाया जाता है. अगर इसका एग्ज़िट कोड शून्य नहीं है, तो माना जाता है कि निर्देश फ़ेल हो गया है. अगर इनमें से कोई भी लागू नहीं होता है, तो यह cmd_bash, cmd_ps, और cmd_bat का फ़ॉलबैक है. अगर कमांड लाइन की लंबाई, प्लैटफ़ॉर्म की सीमा (Linux/macOS पर 64K, Windows पर 8K) से ज़्यादा हो जाती है, तो gen दवा, स्क्रिप्ट में कमांड लिख देगा और उस स्क्रिप्ट को लागू करने के लिए उसे लागू कर देगा. यह सभी cmd एट्रिब्यूट (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" वैरिएबल के बदले, पाथ को विंडोज़ स्टाइल पाथ (बैकस्लैश के साथ) में बड़ा किया जाएगा.
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 कमांड का इस्तेमाल करके चलाया जा सकता है. इस मामले में, जेनरूल से सिर्फ़ एक आउटपुट मिलना चाहिए. अगर यह एट्रिब्यूट सेट है, तो run फ़ाइल को चलाने की कोशिश करेगा, फिर चाहे उसमें कोई कॉन्टेंट हो या नहीं. जनरेट की गई एक्ज़ीक्यूटेबल फ़ाइल के लिए, डेटा डिपेंडेंसी का एलान नहीं किया जा सकता.
local	बूलियन; डिफ़ॉल्ट False है अगर इस विकल्प को 'सही है' पर सेट किया जाता है, तो यह genrule को "स्थानीय" रणनीति का इस्तेमाल करके चलाने के लिए मजबूर करता है. इसका मतलब है कि रिमोट से कोई प्रोसेस नहीं की जाएगी, सैंडबॉक्सिंग नहीं की जाएगी, और न ही लगातार काम करने वाले वर्कर्स का इस्तेमाल किया जाएगा. यह टैग (tags=["local"]) के तौर पर 'local' देने के बराबर है.
message	स्ट्रिंग; डिफ़ॉल्ट रूप से "" प्रोग्रेस का मैसेज. प्रोग्रेस मैसेज, जो बिल्ड के इस चरण को पूरा करने पर प्रिंट किया जाएगा. डिफ़ॉल्ट रूप से, आपको "आउटपुट जनरेट हो रहा है" (या इतना ही साफ़ तौर पर कुछ गड़बड़ी दिख रही है) मिलता है, लेकिन आप ज़्यादा सटीक मैसेज दे सकते हैं. अपने cmd कमांड में echo या प्रिंट करने के अन्य स्टेटमेंट के बजाय, इस एट्रिब्यूट का इस्तेमाल करें. इससे, बिल्ड टूल यह कंट्रोल कर सकता है कि प्रगति के ऐसे मैसेज प्रिंट किए जाएं या नहीं.
output_licenses	लाइसेंस का टाइप, ["none"] डिफ़ॉल्ट तौर पर सेट है common attributes देखें
output_to_bindir	बूलियन; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट है False अगर इस विकल्प को 'सही है' पर सेट किया जाता है, तो इस विकल्प की वजह से आउटपुट फ़ाइलें genfiles डायरेक्ट्री के बजाय bin डायरेक्ट्री में लिखी जाएंगी.
tools	लेबल की सूची; डिफ़ॉल्ट [] है इस नियम के लिए, टूल की डिपेंडेंसी की सूची. ज़्यादा जानकारी के लिए, डिपेंडेंसी की परिभाषा देखें. बिल्ड सिस्टम यह पक्का करता है कि genrule कमांड चलाने से पहले, ये ज़रूरी शर्तें पूरी हो गई हों; इन्हें exec कॉन्फ़िगरेशन का इस्तेमाल करके बनाया जाता है, क्योंकि इन टूल को बिल्ड के हिस्से के तौर पर चलाया जाता है. किसी एक tools टारगेट //x:y का पाथ, $(location //x:y) का इस्तेमाल करके पाया जा सकता है. cmd से चलाया जाने वाला कोई भी *_binary या टूल इस सूची में दिखना चाहिए, न कि srcs में. इससे यह पक्का होता है कि वे सही कॉन्फ़िगरेशन में बनाए गए हैं.

starlark_doc_extract

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

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

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

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

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

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

तर्क

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

test_suite

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

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

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

उदाहरण

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

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