सामान्य नियम

समस्या की शिकायत करें सोर्स देखें

नाइटली · 9.2 · 9.1 · 9.0 · 8.7 · 8.6

नियम

• alias
• config_setting
• filegroup
• genquery
• genrule
• 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 होने की स्थिति का इस्तेमाल किया जाता है. हालांकि, कुछ छोटे-मोटे अपवाद हैं:

• अगर कमांड लाइन पर उनके एलियास का ज़िक्र किया गया है, तो टेस्ट नहीं चलाए जाते हैं. रेफ़र किए गए टेस्ट को चलाने वाले एलियास को तय करने के लिए, 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)

यह फ़ंक्शन, कॉन्फ़िगर किए जा सकने वाले एट्रिब्यूट को ट्रिगर करने के लिए, कॉन्फ़िगरेशन की अनुमानित स्थिति से मेल खाता है. इसे बिल्ड फ़्लैग या प्लैटफ़ॉर्म की पाबंदियों के तौर पर दिखाया जाता है. इस नियम को इस्तेमाल करने के तरीके के बारे में जानने के लिए, 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"
      }
  )
  

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

filegroup

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

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 डायरेक्ट्री को क्रॉल करने के लिए, 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(), Blaze क्वेरी लैंग्वेज में दी गई क्वेरी को चलाता है और नतीजे को किसी फ़ाइल में डंप करता है.

क्वेरी को एक जैसा बनाए रखने के लिए, क्वेरी को सिर्फ़ 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, 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 कमांड का इस्तेमाल करके एक या उससे ज़्यादा फ़ाइलें जनरेट करता है.

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

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

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

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

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

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

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

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

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

खास मामले

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

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

Genrule Environment

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

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

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

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

सामान्य सलाह

• यह पक्का करें कि genrule से चलने वाले टूल, डिटरमिनिस्टिक और हर्मेटिक हों. उन्हें अपने आउटपुट में टाइमस्टैंप नहीं लिखने चाहिए. साथ ही, उन्हें सेट और मैप के लिए स्टेबल ऑर्डरिंग का इस्तेमाल करना चाहिए. इसके अलावा, उन्हें आउटपुट में सिर्फ़ मिलते-जुलते फ़ाइल पाथ लिखने चाहिए, पूरे पाथ नहीं. इस नियम का पालन न करने पर, बिल्ड में अनचाहे बदलाव हो सकते हैं. जैसे, Bazel उस genrule को फिर से नहीं बनाएगा जिसे आपको फिर से बनाना था. साथ ही, इससे कैश मेमोरी की परफ़ॉर्मेंस भी खराब हो सकती है.
• आउटपुट, टूल, और सोर्स के लिए, $(location) का ज़्यादा से ज़्यादा इस्तेमाल करें. अलग-अलग कॉन्फ़िगरेशन के लिए आउटपुट फ़ाइलों को अलग-अलग करने की वजह से, genrules, हार्ड-कोड किए गए और/या ऐब्सलूट पाथ पर भरोसा नहीं कर सकते.
• अगर एक ही या मिलते-जुलते genrule का इस्तेमाल कई जगहों पर किया जाता है, तो एक सामान्य Starlark मैक्रो लिखें. अगर जनरूल जटिल है, तो उसे किसी स्क्रिप्ट में या स्टार्लार्क नियम के तौर पर लागू करें. इससे कोड को पढ़ना और टेस्ट करना आसान हो जाता है.
• पक्का करें कि एक्ज़िट कोड से, यह सही तरीके से पता चलता हो कि genrule सफल हुआ है या नहीं.
• stdout या stderr में सूचना देने वाले मैसेज न लिखें. यह डीबग करने के लिए मददगार है. हालांकि, इससे आसानी से नॉइज़ जनरेट हो सकता है. इसलिए, 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).
• सिमलिंक और डायरेक्ट्री बनाने से बचें. 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-specific "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	स्ट्रिंग; डिफ़ॉल्ट वैल्यू "" है चलाने के लिए बैश कमांड. इस एट्रिब्यूट को cmd एट्रिब्यूट के मुकाबले ज़्यादा प्राथमिकता दी जाती है. कमांड को बड़ा किया जाता है और यह cmd एट्रिब्यूट की तरह ही काम करती है.
cmd_bat	स्ट्रिंग; डिफ़ॉल्ट वैल्यू "" है Windows पर चलाने के लिए बैच कमांड. इस एट्रिब्यूट को cmd और cmd_bash एट्रिब्यूट से ज़्यादा प्राथमिकता दी जाती है. यह कमांड, cmd एट्रिब्यूट की तरह ही काम करती है. हालांकि, इन दोनों के बीच ये अंतर हैं: यह एट्रिब्यूट सिर्फ़ Windows पर लागू होता है. यह कमांड, cmd.exe /c के साथ चलती है. इसमें डिफ़ॉल्ट रूप से ये तर्क शामिल होते हैं: /S - पहले और आखिरी कोटेशन मार्क को हटा दें और बाकी सभी को वैसे ही लागू करें. /E:ON - एक्सटेंडेड कमांड सेट चालू करें. /V:ON - वैरिएबल एक्सपैंशन को कुछ समय के लिए चालू करें /D - ignore AutoRun registry entries. $(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	लाइसेंस का टाइप; डिफ़ॉल्ट रूप से ["none"] पर सेट होता है common attributes देखें
output_to_bindir	बूलियन; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट रूप से False होता है अगर इस विकल्प को 'सही है' पर सेट किया जाता है, तो आउटपुट फ़ाइलें genfiles डायरेक्ट्री के बजाय bin डायरेक्ट्री में लिखी जाती हैं.
tools	लेबल की सूची; डिफ़ॉल्ट वैल्यू [] है इस नियम के लिए, टूल की डिपेंडेंसी की सूची. ज़्यादा जानकारी के लिए, डिपेंडेंसी की परिभाषा देखें. बिल्ड सिस्टम यह पक्का करता है कि genrule कमांड चलाने से पहले, इन ज़रूरी शर्तों को पूरा किया गया हो. इन्हें exec कॉन्फ़िगरेशन का इस्तेमाल करके बनाया जाता है, क्योंकि इन टूल को बिल्ड के हिस्से के तौर पर एक्ज़ीक्यूट किया जाता है. $(location //x:y) का इस्तेमाल करके, किसी tools टारगेट //x:y का पाथ हासिल किया जा सकता है. cmd या cmd से लागू किए जाने वाले किसी भी टूल को इस सूची में दिखना चाहिए, न कि srcs में. इससे यह पक्का किया जा सकेगा कि उन्हें सही कॉन्फ़िगरेशन में बनाया गया है.*_binary

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 (डिफ़ॉल्ट आउटपुट): 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 किसी इकाई के लिए दस्तावेज़ तब ही जारी करता है, जब इकाई के क्वालिफ़ाइड नाम का हर कॉम्पोनेंट सार्वजनिक हो. दूसरे शब्दों में, क्वालिफ़ाइड नाम के हर कॉम्पोनेंट का पहला वर्ण अक्षर हो, न कि "_"); और either the symbol_names list is empty (which is the default case), or इकाई का क्वालिफ़ाइड नाम या उस स्ट्रक्चर का क्वालिफ़ाइड नाम जिसमें इकाई नेस्ट की गई है, 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", "database" या "-flaky". टैग कोई भी मान्य स्ट्रिंग हो सकते हैं. "-" वर्ण से शुरू होने वाले टैग को नेगेटिव टैग माना जाता है. "-" वर्ण को टैग का हिस्सा नहीं माना जाता. इसलिए, "-small" वाला सुइट टैग, टेस्ट के "small" साइज़ से मेल खाता है. अन्य सभी टैग को पॉज़िटिव टैग माना जाता है. अगर आपको पॉज़िटिव टैग को ज़्यादा साफ़ तौर पर दिखाना है, तो टैग "+" वर्ण से भी शुरू हो सकते हैं. हालांकि, इसे टैग के टेक्स्ट का हिस्सा नहीं माना जाएगा. इससे सिर्फ़ सकारात्मक और नकारात्मक अंतर को आसानी से पढ़ा जा सकता है. टेस्ट सुइट में सिर्फ़ वे टेस्ट नियम शामिल किए जाएंगे जो पॉज़िटिव टैग में से सभी और नेगेटिव टैग में से कोई नहीं से मेल खाते हों. ध्यान दें कि इसका मतलब यह नहीं है कि फ़िल्टर किए गए टेस्ट पर निर्भरता के लिए, गड़बड़ी की जांच को छोड़ दिया गया है.छोड़े गए टेस्ट पर निर्भरता अब भी कानूनी होनी चाहिए. उदाहरण के लिए, यह ज़रूरी है कि वे दिखने से जुड़ी पाबंदियों की वजह से ब्लॉक न हों. manual टैग किए गए कीवर्ड को ऊपर दिए गए कीवर्ड से अलग माना जाता है. ऐसा इसलिए, क्योंकि manual कमांड, वाइल्डकार्ड वाले टारगेट पैटर्न से जुड़े इनवोकेशन पर "टेस्ट सुइट एक्सपैंशन" करती है.blaze test यहां, "मैन्युअल" के तौर पर टैग किए गए 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 एट्रिब्यूट की वैल्यू नहीं दी गई है या यह खाली है, तो नियम डिफ़ॉल्ट रूप से, मौजूदा BUILD फ़ाइल में मौजूद उन सभी टेस्ट नियमों को शामिल करेगा जिन्हें manual के तौर पर टैग नहीं किया गया है. ये नियम अब भी tag फ़िल्टरिंग के दायरे में आते हैं.