नियम
उपनाम
नियम का सोर्स देखेंalias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
alias
नियम एक दूसरा नाम बनाता है, जिसे नियम कहा जा सकता है.
एलियासिंग सिर्फ़ "सामान्य" टारगेट के लिए काम करती है. खास तौर पर, package_group
और test_suite
को उपनाम नहीं दिया जा सकता.
एलियासिंग, बड़े डेटा स्टोर करने की जगहों में मदद कर सकती है, जहां टारगेट का नाम बदलने के लिए बहुत सी फ़ाइलों में बदलाव करने की ज़रूरत होती है. अगर आपको कई टारगेट के लिए उस लॉजिक का फिर से इस्तेमाल करना है, तो select फ़ंक्शन कॉल को स्टोर करने के लिए उपनाम नियम का इस्तेमाल किया जा सकता है.
उपनाम नियम का अपना खुद का 'किसको दिखे' का एलान होता है. दूसरे सभी मामलों में, यह उस नियम की तरह काम करता है जिसके बारे में बताया गया है (उदाहरण के लिए, सिर्फ़ अन्य नाम पर टेस्ट करने के लिए इस्तेमाल नहीं किया जाता; इसके बजाय, बताए गए नियम की 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 से मैच कर सके. (लागू करने के प्लैटफ़ॉर्म के बारे में यहां नहीं बताया गया है.) प्लैटफ़ॉर्म को ध्यान में रखकर बनाई गई किसी भी अतिरिक्त कंस्ट्रेंट वैल्यू को अनदेखा किया जाता है. ज़्यादा जानकारी के लिए,
बिल्ड एट्रिब्यूट देखें. यह कॉन्फ़िगरेशन करने लायक है.
ऐसे मामले में जहां दो |
define_values
|
डिक्शनरी: स्ट्रिंग -> स्ट्रिंग; कॉन्फ़िगर नहीं की जा सकती; डिफ़ॉल्ट तौर पर values के जैसा है, लेकिन
खास तौर पर --define फ़्लैग के लिए है.
इसका मतलब है: config_setting( name = "a_and_b", values = { "define": "a=1", "define": "b=2", }) काम नहीं करती, क्योंकि शब्दकोश में एक ही कुंजी ( config_setting( name = "a_and_b", define_values = { "a": "1", "b": "2", })
|
flag_values
|
डिक्शनरी: लेबल -> स्ट्रिंग; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट तौर पर यह values के जैसा है, लेकिन
उपयोगकर्ता के तय किए गए बिल्ड फ़्लैग के लिए.
यह एक अलग एट्रिब्यूट है, क्योंकि उपयोगकर्ता के तय किए गए फ़्लैग को लेबल के तौर पर रेफ़र किया जाता है, जबकि पहले से मौजूद फ़्लैग को आर्बिट्रेरी स्ट्रिंग के तौर पर इस्तेमाल किया जाता है. |
values
|
डिक्शनरी: स्ट्रिंग -> स्ट्रिंग; कॉन्फ़िगर नहीं की जा सकती; डिफ़ॉल्ट तौर पर यह नियम, कॉन्फ़िगर किए गए टारगेट का कॉन्फ़िगरेशन इनहेरिट करता है जो
आपकी सुविधा के लिए, कॉन्फ़िगरेशन वैल्यू को बिल्ड फ़्लैग के तौर पर बताया गया है (पिछले अगर कमांड लाइन पर कोई फ़्लैग साफ़ तौर पर सेट नहीं किया गया है, तो उसकी डिफ़ॉल्ट वैल्यू का इस्तेमाल किया जाता है.
अगर कोई कुंजी शब्दकोश में कई बार दिखती है, तो सिर्फ़ आखिरी इंस्टेंस का इस्तेमाल किया जाता है.
अगर कोई कुंजी ऐसे फ़्लैग का रेफ़रंस देती है जिसे कमांड लाइन पर कई बार सेट किया जा सकता है (जैसे कि
|
फ़ाइलग्रुप
नियम का सोर्स देखेंfilegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)
टारगेट के कलेक्शन को एक आसान नाम देने के लिए, filegroup
का इस्तेमाल करें.
इसके बाद, इन्हें दूसरे नियमों से रेफ़र किया जा सकता है.
सीधे डायरेक्ट्री का इस्तेमाल करने के बजाय, filegroup
का इस्तेमाल करने की सलाह दी जाती है.
बाद वाली फ़ाइल सही नहीं है, क्योंकि बिल्ड सिस्टम को डायरेक्ट्री के नीचे मौजूद सभी फ़ाइलों की पूरी जानकारी नहीं है. इसलिए, हो सकता है कि इन फ़ाइलों के बदलने पर यह फिर से न बने. ग्लोब के साथ इस्तेमाल किए जाने पर, filegroup
यह पक्का कर सकता है कि सभी फ़ाइलों की जानकारी, बिल्ड सिस्टम को साफ़ तौर पर मिल जाए.
उदाहरण
दो सोर्स फ़ाइलों वाला filegroup
बनाने के लिए, यह करें
filegroup( name = "mygroup", srcs = [ "a_file.txt", "some/subdirectory/another_file.txt", ], )
इसके अलावा, टेस्टडेटा डायरेक्ट्री को इकट्ठा करने के लिए, 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
|
लेबल की सूची;
आम तौर पर, |
data
|
लेबल की सूची;
|
output_group
|
स्ट्रिंग; "आउटपुट ग्रुप", किसी टारगेट के आउटपुट आर्टफ़ैक्ट की ऐसी कैटगरी है जिसकी जानकारी उस नियम को लागू करने में दी जाती है. |
जेनक्वेरी
नियम का सोर्स देखें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
|
बूलियन; डिफ़ॉल्ट मान True है, तो क्वेरी आउटपुट GZIP फ़ाइल फ़ॉर्मैट में लिखा जाता है. इस सेटिंग का इस्तेमाल करके,
क्वेरी का आउटपुट बड़ा होने पर, Bazel की मेमोरी के इस्तेमाल में अचानक होने वाली बढ़ोतरी से बचा जा सकता है. Bazel
पहले से ही अंदरूनी तौर पर, 220 बाइट से ज़्यादा के क्वेरी आउटपुट को कंप्रेस करता है. इस बात से कोई फ़र्क़ नहीं पड़ता कि इस सेटिंग की वैल्यू क्या है.
इसलिए, हो सकता है कि इसे 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
|
बूलियन; डिफ़ॉल्ट मान |
जेनरूल
नियम का सोर्स देखें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
, उपयोगकर्ता के तय किए गए बैश कमांड का इस्तेमाल करके, एक या उससे ज़्यादा फ़ाइलें जनरेट करता है.
जेन रूल, बिल्ड के सामान्य नियम होते हैं. इनका इस्तेमाल तब किया जा सकता है, जब टास्क के लिए कोई खास नियम न हो.
उदाहरण के लिए, बैश वन-लाइनर चलाया जा सकता है. अगर आपको C++ फ़ाइलों को कंपाइल करना है, तो
cc_*
के मौजूदा नियमों का पालन करें. ऐसा इसलिए, क्योंकि आपने सारा काम पहले ही कर दिया है.
ध्यान दें कि कमांड तर्क की व्याख्या करने के लिए, gen फ़्रेम को शेल की ज़रूरत होती है. पाथ पर मौजूद आर्बिट्रेरी प्रोग्राम का रेफ़रंस देना भी आसान है. हालांकि, इससे यह निर्देश मिलता है, जो हर्मेटिक नहीं होता और हो सकता है कि इसे फिर से जनरेट न किया जा सके. अगर आपको सिर्फ़ एक टूल चलाना है, तो इसके बजाय run_binary का इस्तेमाल करें.
जांच करने के लिए जेनरूल का इस्तेमाल न करें. टेस्ट और टेस्ट
के नतीजों के लिए खास शर्तें हैं. इनमें कैश मेमोरी में सेव करने की नीतियां और एनवायरमेंट वैरिएबल शामिल हैं. आम तौर पर, टेस्ट पूरा होने के बाद और टारगेट आर्किटेक्चर पर चलाए जाते हैं. वहीं, बिल्ड के दौरान और
एक्ज़ीक्यूटेबल आर्किटेक्चर पर, जेन रूल लागू किए जाते हैं (दोनों अलग-अलग हो सकते हैं). अगर आपको अलग-अलग कामों के लिए जांच के नियम की ज़रूरत है, तो sh_test
का इस्तेमाल करें.
क्रॉस-कंपाइलेशन के लिए ध्यान देने वाली बातें
क्रॉस-कंपिलेशन के बारे में ज़्यादा जानने के लिए, इस्तेमाल के लिए गाइड देखें.
हालांकि, जनरेटिव प्रोसेस के दौरान जनरेट किए गए जेनक्यूल, बिल्ड के बाद डिप्लॉयमेंट या टेस्टिंग के लिए इस्तेमाल किए जाते हैं. माइक्रोकंट्रोलर के लिए C कोड को कंपाइल करने का उदाहरण देखें: कंपाइलर, C सोर्स फ़ाइलों को स्वीकार करता है और माइक्रोकंट्रोलर पर चलने वाला कोड जनरेट करता है. साफ़ तौर पर, जनरेट किया गया कोड उस सीपीयू पर नहीं चल सकता जिसका इस्तेमाल उसे बनाने में किया गया था. हालांकि, सी कंपाइलर (अगर सोर्स से इकट्ठा किया गया हो) को खुद ही चलाना होगा.
बिल्ड सिस्टम, exec कॉन्फ़िगरेशन का इस्तेमाल उन मशीन के बारे में बताने के लिए करता है जिन पर बिल्ड चलता है. साथ ही, टारगेट कॉन्फ़िगरेशन का इस्तेमाल उस मशीन (उन) की जानकारी देने के लिए होता है जिस पर बिल्ड का आउटपुट चलना चाहिए. यह इनमें से हर एक को कॉन्फ़िगर करने के विकल्प देता है और यह समस्याओं से बचने के लिए, संबंधित फ़ाइलों को अलग-अलग डायरेक्ट्री में बांट देता है.
जनरेट किए गए नियमों के लिए, बिल्ड सिस्टम यह पक्का करता है कि डिपेंडेंसी सही तरीके से बनाई गई हो:
target कॉन्फ़िगरेशन के लिए srcs
(अगर ज़रूरी हो),
tools
को exec कॉन्फ़िगरेशन के लिए बनाया गया हो, और आउटपुट
target कॉन्फ़िगरेशन के लिए बनाया गया हो. इससे
"Make" वैरिएबल भी मिलते हैं जिन्हें जनरेट करने के निर्देश, उनसे जुड़े टूल को पास कर सकते हैं.
यह सोच-समझकर इस्तेमाल किया जाता है कि जनरेटिव ने कोई deps
एट्रिब्यूट नहीं बताया: अन्य पहले से मौजूद नियम, नियमों के बीच पास की गई भाषा पर आधारित मेटा जानकारी का इस्तेमाल करते हैं.
इससे यह तय होता है कि डिपेंडेंट नियमों को कैसे मैनेज किया जाए. हालांकि,
इस तरह के ऑटोमेशन की सुविधा, नियमों के हिसाब से काम नहीं करती. जेन नियम,
फ़ाइल और रनफ़ाइल लेवल पर पूरी तरह से काम करते हैं.
खास मामले
Exec-exec कंपाइलेशन: कुछ मामलों में, बिल्ड सिस्टम को genrules चलाने की ज़रूरत होती है, ताकि बिल्ड के दौरान आउटपुट को भी चलाया जा सके. उदाहरण के लिए, अगर कोई जेनरूल कुछ कस्टम कंपाइलर बनाता है,
जिसका इस्तेमाल बाद में कोई दूसरा जेनरूल इस्तेमाल करता है, तो पहले वाले को exec कॉन्फ़िगरेशन के लिए अपना आउटपुट
जनरेट करना होगा, क्योंकि वहीं, कंपाइलर दूसरे जेनरूल में चलेगा. इस मामले में,
बिल्ड सिस्टम अपने-आप सही काम करता है: यह टारगेट कॉन्फ़िगरेशन के बजाय, exec कॉन्फ़िगरेशन के लिए पहले जनरेट किए गए जेनरूल के srcs
और
outs
को बनाता है. ज़्यादा जानकारी के लिए, इस्तेमाल के लिए गाइड देखें.
JDK और C++ टूलिंग: JDK या C++ कंपाइलर सुइट के टूल का इस्तेमाल करने के लिए, बिल्ड सिस्टम इस्तेमाल करने के लिए वैरिएबल का एक सेट उपलब्ध कराता है. ज़्यादा जानकारी के लिए, "बनाएं" वैरिएबल देखें.
जेनरूल एनवायरमेंट
जेनरूल निर्देश, बैश शेल से चलाया जाता है, जिसे set -e -o pipefail
का इस्तेमाल करके, किसी निर्देश
या पाइपलाइन के काम नहीं करने पर कॉन्फ़िगर किया जाता है.
बिल्ड टूल, सैनिटाइज़्ड प्रोसेस एनवायरमेंट में बैश कमांड एक्ज़ीक्यूट करता है. यह
सिर्फ़ PATH
, PWD
, TMPDIR
जैसे कोर वैरिएबल के बारे में बताता है. साथ ही, कुछ अन्य वैरिएबल के बारे में बताता है.
यह पक्का करने के लिए कि बिल्ड फिर से जनरेट किए जा सकें, उपयोगकर्ता के शेल एनवायरमेंट में तय किए गए ज़्यादातर वैरिएबल, जेनरूल के निर्देश से पास नहीं किए जाते. हालांकि, Bazel (इसमें Blaze नहीं है), उपयोगकर्ता के PATH
एनवायरमेंट वैरिएबल की वैल्यू से पास होता है.
PATH
की वैल्यू में कोई भी बदलाव करने पर, Bazel अगले बिल्ड में
निर्देश फिर से लागू कर देगा.
जेनरूल निर्देश को नेटवर्क को ऐक्सेस नहीं करना चाहिए. हालांकि, उन प्रोसेस को कनेक्ट किया जाना चाहिए जो निर्देश से जुड़े हों. हालांकि, फ़िलहाल इसे लागू नहीं किया जाना चाहिए.
बिल्ड सिस्टम, मौजूदा आउटपुट फ़ाइल को अपने-आप मिटा देता है. हालांकि, जनरेट होने से पहले ही यह सभी ज़रूरी पैरंट डायरेक्ट्री बना लेता है. गड़बड़ी होने पर, यह आउटपुट फ़ाइल भी हटा देता है.
सामान्य सलाह
- यह पक्का करें कि जेनरूल का इस्तेमाल करके चलाए जाने वाले टूल, डिटर्मिनिस्टिक और हेरमेटिक हों. उन्हें अपने आउटपुट में टाइमस्टैंप नहीं लिखने चाहिए. साथ ही, उन्हें सेट और मैप के लिए स्टेबल ऑर्डर का इस्तेमाल करना चाहिए. साथ ही, उन्हें आउटपुट के लिए सिर्फ़ रिलेटिव फ़ाइल पाथ लिखना चाहिए, न कि कोई ऐब्सलूट पाथ. इस नियम का पालन न करने से, बिल्ड के ऐसे नतीजे होंगे जो उम्मीद के मुताबिक नहीं होंगे. (Bazel, आपके हिसाब से जनरेट किए गए नियम को फिर से नहीं बना पाएंगे) और कैश मेमोरी की परफ़ॉर्मेंस में कमी आएगी.
- आउटपुट, टूल, और सोर्स के लिए,
$(location)
का ज़्यादा से ज़्यादा इस्तेमाल करें. अलग-अलग कॉन्फ़िगरेशन के लिए आउटपुट फ़ाइलों को अलग-अलग किए जाने की वजह से, genrules हार्ड कोड और/या ऐब्सलूट पाथ पर भरोसा नहीं कर सकता. - अगर एक जैसे या काफ़ी मिलते-जुलते जनरेट कई जगहों पर इस्तेमाल किए जाते हैं, तो एक सामान्य स्टारलार्क मैक्रो लिखें. अगर जेनरूल जटिल है, तो इसे स्क्रिप्ट में या स्टारलार्क नियम के तौर पर लागू करें. इससे पढ़ने और टेस्ट करने की क्षमता बेहतर होती है.
- पक्का करें कि एग्ज़िट कोड, जेनरूल की सफलता या असफलता को सही तरीके से दिखाता हो.
- stdout या stderr पर जानकारी देने वाले मैसेज न लिखें. हालांकि, यह डीबग करने में काम का होता है, लेकिन यह आसानी से नॉइज़ बन सकता है. हालांकि, जनरेट किए गए डेटा को प्रोसेस करने में कोई समस्या नहीं होनी चाहिए. वहीं दूसरी ओर, ऐसा कोई भी जेनरूल काम नहीं आने पर गड़बड़ी के अच्छे मैसेज मिलें.
$$
evaluates to a$
, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such asls $(dirname $x)
, one must escape it thus:ls $$(dirname $$x)
.- सिमलिंक और डायरेक्ट्री बनाने से बचें. Bazel, genrules की मदद से बनाई गई डायरेक्ट्री/सिमलिंक स्ट्रक्चर को कॉपी नहीं करता है. साथ ही, डायरेक्ट्री की डिपेंडेंसी जांच की आवाज़ ठीक नहीं है.
- दूसरे नियमों में जेनरूल का इस्तेमाल करते समय, जेनरूल का लेबल इस्तेमाल किया जा सकता है या अलग-अलग आउटपुट फ़ाइलों के लेबल इस्तेमाल किए जा सकते हैं. कभी-कभी एक तरीका ज़्यादा आसानी से पढ़ा जा सकता है, कभी-कभी दूसरा: आउटपुट को इस्तेमाल करने वाले नियम के
srcs
में नाम से रेफ़र करने से, अनजाने में जनरेट किए गए नियम के दूसरे आउटपुट लेने से बचा जा सकता है. हालांकि, अगर जेनरूल कई आउटपुट देता है, तो यह मुश्किल हो सकता है.
उदाहरण
यह उदाहरण foo.h
जनरेट करता है. कोई सोर्स नहीं है, क्योंकि कमांड कोई इनपुट नहीं लेता. निर्देश से चलाई जाने वाली "बाइनरी", पर्ल स्क्रिप्ट होती है. यह उसी पैकेज में होती है जिसमें जेनरूल होता है.
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
|
लेबल की सूची;
यह एट्रिब्यूट, उन टूल की सूची के लिए सही नहीं है जिन्हें
बिल्ड सिस्टम यह पक्का करता है कि ये ज़रूरी शर्तें, gen फ़्रेम की मदद से चलाने से पहले बनाई गई हों; इन्हें उसी कॉन्फ़िगरेशन का इस्तेमाल करके बनाया गया है जिसका इस्तेमाल मूल बिल्ड अनुरोध में किया गया है. इन ज़रूरी शर्तों की फ़ाइलों के नाम, निर्देश के लिए |
outs
|
फ़ाइलों के नाम की सूची; कॉन्फ़िगर नहीं की जा सकती; ज़रूरी है इस नियम से जनरेट की गई फ़ाइलों की सूची.आउटपुट फ़ाइलें, पैकेज की सीमाओं को पार नहीं करनी चाहिए. आउटपुट फ़ाइलों के नाम, पैकेज के मुताबिक बताए जाते हैं.
अगर
जेनरूल निर्देश से, पहले से तय की गई जगह पर हर आउटपुट फ़ाइल बनाने की उम्मीद की जाती है.
जगह की जानकारी, |
cmd
|
स्ट्रिंग; $(location)
और "Make" वैरिएबल के बदलाव पर निर्भर करता है.
cmd_bash , cmd_ps , और cmd_bat का फ़ॉलबैक है.
अगर कमांड लाइन की लंबाई, प्लैटफ़ॉर्म के लिए तय की गई सीमा (Linux/macOS पर 64K और Windows पर 8K) से ज़्यादा हो जाती है,
तो gen फ़्रेम एक स्क्रिप्ट पर निर्देश लिखेगा और उस स्क्रिप्ट को पूरा करेगा, ताकि काम करने के लिए यह स्क्रिप्ट लागू की जा सके. यह
सभी cmd एट्रिब्यूट ( |
cmd_bash
|
स्ट्रिंग; इस एट्रिब्यूट की प्राथमिकता |
cmd_bat
|
स्ट्रिंग; इस एट्रिब्यूट की प्राथमिकता
|
cmd_ps
|
स्ट्रिंग; इस एट्रिब्यूट की प्राथमिकता
Powershel को आसानी से इस्तेमाल किया जा सके और गड़बड़ी की आशंका कम हो, इसके लिए हम नीचे दिए गए कमांड इस्तेमाल करते हैं, ताकि जेनरूल में Powershel कमांड लागू करने से पहले, एनवायरमेंट सेट अप किया जा सके.
|
executable
|
बूलियन; कॉन्फ़िगर नहीं किया जा सकता;
इस फ़्लैग को 'सही है' पर सेट करने का मतलब है कि आउटपुट एक एक्ज़ीक्यूटेबल फ़ाइल है और इसे
जनरेट किए गए एक्ज़ीक्यूटेबल के लिए, डेटा डिपेंडेंसी का एलान करना काम नहीं करता. |
local
|
बूलियन; डिफ़ॉल्ट मान
अगर इस विकल्प को 'सही है' पर सेट किया जाता है, तो यह विकल्प इस
यह टैग ( |
message
|
स्ट्रिंग;
बिल्ड चरण पूरा होने के बाद, प्रोग्रेस दिखाने वाला मैसेज प्रिंट किया जाएगा. डिफ़ॉल्ट रूप से,
मैसेज "आउटपुट जनरेट हो रहा है" (या इसके बराबर कोई टेक्स्ट जनरेट हो रहा है) होता है. हालांकि, आपके पास ज़्यादा सटीक जानकारी देने का विकल्प होता है. अपने |
output_licenses
|
लाइसेंस का टाइप; डिफ़ॉल्ट तौर पर common attributes
देखें
|
output_to_bindir
|
बूलियन; कॉन्फ़िगर नहीं किया जा सकता;
अगर इस नीति को 'सही है' पर सेट किया जाता है, तो इस विकल्प की वजह से आउटपुट फ़ाइलें, |
tools
|
लेबल की सूची;
बिल्ड सिस्टम यह पक्का करता है कि ये ज़रूरी शर्तें, gen फ़्रेम की मदद से चलाने से पहले बनाई गई हों;
इन्हें exec
कॉन्फ़िगरेशन का इस्तेमाल करके बनाया जाता है, क्योंकि इन टूल को बिल्ड के हिस्से के तौर पर एक्ज़ीक्यूट किया जाता है. किसी
|
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
बाइनरी प्रोटो है, जैसा कि
Bzel सोर्स ट्री में
stardoc_output.proto
में बताया गया है.
इंप्लिसिट आउटपुट टारगेट
name.binaryproto
(डिफ़ॉल्ट आउटपुट): एकModuleInfo
बाइनरी प्रोटो.name.textproto
(सिर्फ़ तब बनाया जाता है, जब साफ़ तौर पर इसका अनुरोध किया गया हो):name.binaryproto
का टेक्स्ट प्रोटो वर्शन.
चेतावनी: इस नियम के आउटपुट फ़ॉर्मैट के स्थिर होने की गारंटी नहीं है. यह मुख्य रूप से Stardoc के अंदरूनी इस्तेमाल के लिए है.
तर्क
एट्रिब्यूट | |
---|---|
name |
नाम; ज़रूरी है इस टारगेट के लिए एक खास नाम. |
deps
|
लेबल की सूची; src की मदद से load()
बनाया गया है. ये टारगेट, सामान्य इस्तेमाल के तहत
bzl_library
टारगेट होने चाहिए
हालांकि, starlark_doc_extract नियम उसे लागू नहीं करता है और
ऐसे सभी टारगेट को स्वीकार करता है जो अपने DefaultInfo में Starlark फ़ाइलें उपलब्ध कराते हैं.
ध्यान दें कि रैप की गई Starlark फ़ाइलें, सोर्स ट्री की फ़ाइलें होनी चाहिए. Bazel, जनरेट की गई
फ़ाइलें |
src
|
लेबल; ज़रूरी है Starlark फ़ाइल जिससे दस्तावेज़ एक्सट्रैक्ट करना है.ध्यान दें कि यह सोर्स ट्री में मौजूद फ़ाइल होनी चाहिए. Bazel, जनरेट की गई
फ़ाइलें |
render_main_repo_name
|
बूलियन; डिफ़ॉल्ट मान //foo:bar.bzl को
@main_repo_name//foo:bar.bzl के तौर पर उत्सर्जित किया जाएगा).
मुख्य रिपॉज़िटरी के लिए इस्तेमाल किया जाने वाला नाम, मुख्य रिपॉज़िटरी की Starlark फ़ाइलों के लिए दस्तावेज़ जनरेट करते समय,
इस एट्रिब्यूट को |
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" का सुइट टैग टेस्ट के "छोटा" साइज़ से मेल खाता है. बाकी सभी टैग को पॉज़िटिव टैग माना जाता है. इसके अलावा, पॉज़िटिव टैग को और बेहतर बनाने के लिए, टैग की शुरुआत "+" वर्ण से भी की जा सकती है. इसका आकलन टैग के टेक्स्ट के हिस्से के तौर पर नहीं किया जाएगा. इससे, सकारात्मक और नकारात्मक के बीच के फ़र्क़ को समझना आसान हो जाता है. टेस्ट सुइट में सिर्फ़ उन टेस्ट नियमों को शामिल किया जाएगा जो सभी पॉज़िटिव टैग से मैच करते हैं और किसी भी नेगेटिव टैग से नहीं. ध्यान दें, इसका मतलब यह नहीं है कि फ़िल्टर किए गए टेस्ट पर डिपेंडेंसी के लिए गड़बड़ी की जांच को छोड़ दिया गया है.स्किप किए गए टेस्ट पर निर्भरता अब भी कानूनी तौर पर होनी चाहिए. उदाहरण के लिए, विज़िबिलिटी की कमी की वजह से ब्लॉक न किया गया हो.
ध्यान दें कि टेस्ट के
अगर आपको |
tests
|
लेबल की सूची; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट है
किसी भी भाषा के लिए, यहां कोई भी
अगर |