सामान्य नियम

किसी समस्या की शिकायत करें सोर्स देखें Nightly · 7.4 . 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 सेट करने वाले किसी भी बिल्ड से मेल खाता है. ऐसा, कमांड-लाइन पर साफ़ तौर पर या .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"
      }
  )
  

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

  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 या सूची टाइप वाला 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 से मैच करने वाला config_setting, x86 से मैच करने वाले config_setting के लिए खास तौर पर बनाया गया है.Linux अगर दो config_setting मैच करते हैं और दोनों में ऐसे constraint_value मौजूद हैं जो एक में नहीं हैं, तो यह गड़बड़ी है.
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 स्टेटमेंट में इसके बारे में बताता है. किसी Bazel invocation से "मैच" होने का मतलब है कि डिक्शनरी में मौजूद हर एंट्री के लिए, उसका कॉन्फ़िगरेशन, एंट्री की उम्मीद की गई वैल्यू से मैच करता हो. उदाहरण के लिए, 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, कमांड लाइन पर या किसी दूसरे नियम के एट्रिब्यूट में टारगेट को सूची में शामिल करने का विकल्प नहीं है. इसकी वजह यह है कि टारगेट के आउटपुट के अलावा, उनमें कई ऐसी प्रॉपर्टी होती हैं जिन्हें एक ही तरह से इकट्ठा नहीं किया जाता. हालांकि, यह अब भी कुछ मामलों में काम आता है. उदाहरण के लिए, जनरेटिव नियम के srcs एट्रिब्यूट या *_बाइनरी नियम के data एट्रिब्यूट में.

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

उदाहरण

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

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

इसके अलावा, टेस्ट डेटा डायरेक्ट्री को पूरी तरह क्रॉल करने के लिए, 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, 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/..."] का इस्तेमाल नहीं किया जा सकता.

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 पर सेट करने से, सेव किए गए ढेर का साइज़ कम न हो. हालांकि, इससे आउटपुट फ़ाइल लिखते समय 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 अगर यह सही है, तो जिन टारगेट की क्वेरी उनके दायरे के ट्रांज़िशन क्लोज़र से बाहर निकलती हैं वे बिल्ड नहीं हो पाएंगी. गलत होने पर, Basel एक चेतावनी प्रिंट करेगा. साथ ही, उस क्वेरी पाथ को छोड़ देगा जो क्वेरी पाथ को स्कोप से बाहर ले जाता है. ऐसा करते समय, बाकी क्वेरी को पूरा किया जाता है.

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_* के मौजूदा नियमों का पालन करें, क्योंकि आपके लिए पहले से ही सभी ज़रूरी काम कर लिए गए हैं.

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

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

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

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

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

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

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

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

genrule में deps एट्रिब्यूट का इस्तेमाल नहीं किया जाता है. ऐसा जान-बूझकर किया जाता है: पहले से मौजूद अन्य नियम, भाषा पर निर्भर मेटा जानकारी का इस्तेमाल करते हैं. यह जानकारी, नियमों के बीच भेजी जाती है, ताकि यह अपने-आप तय किया जा सके कि भाषा पर निर्भर नियमों को कैसे मैनेज किया जाए. हालांकि, genrule के लिए इस लेवल का ऑटोमेशन नहीं किया जा सकता. 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 को चलाने से पहले, वह ज़रूरी पैरंट डायरेक्ट्री बना देता है. गड़बड़ी होने पर, आउटपुट वाली सभी फ़ाइलें भी हटा दी जाएंगी.

सामान्य सलाह

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

उदाहरण

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

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

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

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

तर्क

विशेषताएं
name	नाम; यह ज़रूरी है इस टारगेट के लिए यूनीक नाम.
deps	लेबल की सूची; डिफ़ॉल्ट [] है Starlark फ़ाइलों को रैप करने वाले टारगेट की सूची, जिन्हें load() ने src के ज़रिए load() किया है. आम तौर पर, इन टारगेट को bzl_library टारगेट होना चाहिए, लेकिन starlark_doc_extract नियम ऐसा नहीं करता. साथ ही, वह ऐसे किसी भी टारगेट को स्वीकार करता है जो अपने DefaultInfo में Starlark फ़ाइलें उपलब्ध कराता है. ध्यान दें कि रैप की गई Starlark फ़ाइलें सोर्स ट्री में मौजूद फ़ाइलें होनी चाहिए. Basel, जनरेट की गई फ़ाइलों को load() नहीं कर सकता.
src	लेबल; ज़रूरी है वह Starlark फ़ाइल जिससे दस्तावेज़ निकालना है. ध्यान दें कि यह सोर्स ट्री में मौजूद फ़ाइल होनी चाहिए. Bazel, load() जनरेट की गई फ़ाइलों को इस्तेमाल नहीं कर सकता.
render_main_repo_name	बूलियन; डिफ़ॉल्ट False है अगर यह सही है, तो रिपॉज़िटरी कॉम्पोनेंट के साथ, रिलीज़ किए गए दस्तावेज़ में मुख्य रिपॉज़िटरी में लेबल रेंडर करें (दूसरे शब्दों में, //foo:bar.bzl को @main_repo_name//foo:bar.bzl के तौर पर रिलीज़ किया जाएगा). मुख्य डेटा स्टोर करने की जगह के लिए इस्तेमाल किया जाने वाला नाम, डेटा स्टोर करने की मुख्य जगह की MODULE.bazel फ़ाइल (अगर Bzlmod चालू है) में module(name = ...) से या मुख्य डेटा संग्रह स्थान की WORKSPACE फ़ाइल में workspace(name = ...) से लिया जाता है. इस एट्रिब्यूट को False पर सेट किया जाना चाहिए, जब सिर्फ़ एक ही रिपॉज़िटरी में इस्तेमाल की जाने वाली Starlark फ़ाइलों के लिए दस्तावेज़ जनरेट किए जा रहे हों. साथ ही, इस एट्रिब्यूट को True पर सेट किया जाना चाहिए, जब दूसरी रिपॉज़िटरी से इस्तेमाल की जाने वाली Starlark फ़ाइलों के लिए दस्तावेज़ जनरेट किए जा रहे हों.
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, टेस्ट के ऐसे सेट के बारे में बताता है जिसे इंसानों के लिए "काम का" माना जाता है. इससे प्रोजेक्ट को टेस्ट के सेट तय करने की अनुमति मिलती है. जैसे, "चेक इन करने से पहले आपको जो टेस्ट करने होंगे", "हमारे प्रोजेक्ट के स्ट्रेस टेस्ट" या "सभी छोटे टेस्ट." 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" वाला सुइट टैग, टेस्ट के "small" साइज़ से मैच होता है. बाकी सभी टैग को पॉज़िटिव टैग माना जाता है. इसके अलावा, पॉज़िटिव टैग को ज़्यादा साफ़ तौर पर दिखाने के लिए, टैग की शुरुआत "+" वर्ण से भी की जा सकती है. इसका आकलन, टैग के टेक्स्ट के तौर पर नहीं किया जाएगा. इससे, पॉज़िटिव और नेगेटिव रेटिंग को आसानी से पढ़ा जा सकता है. टेस्ट सुइट में सिर्फ़ वे टेस्ट नियम शामिल किए जाएंगे जो सभी पॉज़िटिव टैग और किसी भी नेगेटिव टैग से मैच करते हैं. ध्यान दें कि इसका मतलब यह नहीं है कि फ़िल्टर किए गए टेस्ट पर निर्भरता के लिए, गड़बड़ी की जांच छोड़ दी जाती है. फ़िल्टर किए गए टेस्ट पर निर्भरता अब भी कानूनी होनी चाहिए. उदाहरण के लिए, उन्हें दिखने से जुड़ी पाबंदियों से ब्लॉक नहीं किया जाना चाहिए. manual टैग कीवर्ड को ऊपर दिए गए कीवर्ड से अलग माना जाता है. ऐसा, bazel test कमांड के ज़रिए किए गए "test_suite एक्सपैंशन" की वजह से होता है. यह कमांड, वाइल्डकार्ड वाले टारगेट पैटर्न वाले इनवोकेशन पर काम करता है. वहां, "मैन्युअल" के तौर पर टैग किए गए 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 फ़िल्टर लागू होता है.