नियम
उपनाम
नियम का सोर्स देखेंalias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
alias
नियम एक और नाम बनाता है, जिसे नियम कहा जा सकता है.
एलियासिंग सिर्फ़ "सामान्य" टारगेट के लिए काम करता है. खास तौर पर, package_group
और test_suite
को दूसरे ईमेल पते के तौर पर इस्तेमाल नहीं किया जा सकता.
एलियासिंग से, डेटा स्टोर करने की उन बड़ी जगहों में मदद मिल सकती है जहां टारगेट का नाम बदलने के लिए, कई फ़ाइलों में बदलाव करने की ज़रूरत होती है. अगर आपको एक से ज़्यादा टारगेट के लिए, select फ़ंक्शन का लॉजिक फिर से इस्तेमाल करना है, तो उसे स्टोर करने के लिए भी उपनाम नियम का इस्तेमाल किया जा सकता है.
अन्य नियम के तहत, 'किसको दिखे' सेटिंग का अपना एलान होता है. दूसरे सभी मामलों में, यह नियम की तरह काम करता है (उदाहरण के लिए, उपनाम पर सिर्फ़ टेस्ट-ओनली को अनदेखा किया जाता है; इसके बजाय, रेफ़र किए गए नियम की जांच करने के तरीके का इस्तेमाल किया जाता है) जैसे कि:
-
अगर कमांड लाइन में उपनाम का इस्तेमाल किया जाता है, तो जांच नहीं की जाती हैं. बताया गया टेस्ट चलाने वाला उपनाम
तय करने के लिए,
test_suite
नियम का इस्तेमाल करें, जिसकेtests
एट्रिब्यूट में एक ही टारगेट हो. -
एनवायरमेंट ग्रुप तय करते समय,
environment
नियमों के लिए उपनाम का इस्तेमाल नहीं किया जा सकता. ये--target_environment
कमांड लाइन विकल्प में भी काम नहीं करती हैं.
उदाहरण
filegroup( name = "data", srcs = ["data.txt"], ) alias( name = "other", actual = ":data", )
तर्क
विशेषताएं | |
---|---|
name |
नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम. |
actual
|
लेबल; ज़रूरी है वह टारगेट जिससे यह उपनाम दिखाता है. इसके लिए कोई नियम होना ज़रूरी नहीं है. यह एक इनपुट फ़ाइल भी हो सकती है. |
config_setting
नियम का सोर्स देखेंconfig_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)
कॉन्फ़िगर किए जा सकने वाले एट्रिब्यूट को ट्रिगर करने के लिए, कॉन्फ़िगरेशन की अनुमानित स्थिति (इसे बिल्ड फ़्लैग या प्लैटफ़ॉर्म कंस्ट्रेंट के तौर पर बताया जाता है) से मेल खाता है. इस नियम का इस्तेमाल करने का तरीका जानने के लिए, चुनें और सामान्य सुविधा की खास जानकारी के लिए, कॉन्फ़िगर किए जा सकने वाले एट्रिब्यूट देखें.
उदाहरण
नीचे दी गई चीज़ें ऐसे किसी भी बिल्ड से मेल खाती हैं जो --compilation_mode=opt
या
-c opt
को सेट करती है (साफ़ तौर पर कमांड लाइन पर या सीधे तौर पर .baZZrc फ़ाइलों से):
config_setting( name = "simple", values = {"compilation_mode": "opt"} )
नीचे दी गई जानकारी ऐसे किसी भी बिल्ड से मेल खाती है जो ARM को टारगेट करता है और कस्टम डेफ़िनिशन
FOO=bar
(उदाहरण के लिए, bazel build --cpu=arm --define FOO=bar ...
) लागू करता है:
config_setting( name = "two_conditions", values = { "cpu": "arm", "define": "FOO=bar" } )
नीचे दी गई चीज़ें ऐसे किसी भी बिल्ड से मेल खाती हैं जो
उपयोगकर्ता के तय किए गए फ़्लैग
--//custom_flags:foo=1
को सेट करता है (या तो साफ़ तौर पर कमांड लाइन पर या सीधे तौर पर
.bazzrc फ़ाइलों से):
config_setting( name = "my_custom_flag_is_set", flag_values = { "//custom_flags:foo": "1" }, )
यहां दिए गए बिल्ड ऐसे किसी भी बिल्ड से मेल खाते हैं जो x86_64 आर्किटेक्चर और glibc वर्शन 2.25 वाले प्लैटफ़ॉर्म को टारगेट करता है. ऐसा तब होता है, जब लेबल //example:glibc_2_25
वाला constraint_value
मौजूद हो. ध्यान दें कि अगर कोई प्लैटफ़ॉर्म इन दोनों के अलावा,
अन्य कंस्ट्रेंट वैल्यू को भी तय करता है, तो यह अब भी मैच होता है.
config_setting( name = "64bit_glibc_2_25", constraint_values = [ "@platforms//cpu:x86_64", "//example:glibc_2_25", ] )इन सभी मामलों में, बिल्ड में कॉन्फ़िगरेशन में बदलाव हो सकता है. उदाहरण के लिए, जब किसी टारगेट को उसके डिपार्टमेंट के अलावा किसी दूसरे प्लैटफ़ॉर्म के लिए बनाने की ज़रूरत हो. इसका मतलब है कि
config_setting
, टॉप-लेवल के कमांड-लाइन फ़्लैग से मेल न खाने पर भी,
कुछ बिल्ड टारगेट से मेल खा सकता है.
ज़रूरी जानकारी
- जब एक से ज़्यादा
config_setting
, कॉन्फ़िगरेशन की मौजूदा स्थिति से मैच करते हैं, तो क्या होता है, यह जानने के लिए चुनें देखें. --compilation_mode
बनाम-c
जैसे शॉर्टहैंड फ़ॉर्म के साथ काम करने वाले फ़्लैग के लिए,values
परिभाषाओं में पूरे फ़ॉर्म का इस्तेमाल किया जाना चाहिए. ये किसी भी फ़ॉर्म का इस्तेमाल करके, बोले जाने वाले वाक्यों का अपने-आप मिलान करते हैं.-
अगर किसी फ़्लैग में एक से ज़्यादा वैल्यू होती हैं (जैसे कि
--copt=-Da --copt=-Db
या सूची के तौर पर स्टारलार्क फ़्लैग), तोvalues = { "flag": "a" }
मैच करता है. ऐसा तब होता है, जब असल सूची में"a"
कहीं भी मौजूद हो.values = { "myflag": "a,b" }
की तरह ही काम करता है: यह--myflag=a --myflag=b
,--myflag=a --myflag=b --myflag=c
,--myflag=a,b
, और--myflag=c,b,a
से मेल खाता है. फ़्लैग के बीच सटीक सिमेंटिक्स अलग-अलग होता है. उदाहरण के लिए,--copt
एक ही मामले में एक से ज़्यादा वैल्यू के साथ काम नहीं करता:--copt=a,b
,["a,b"]
जनरेट करता है, जबकि--copt=a --copt=b
,["a", "b"]
जनरेट करता है. इसलिए,values = { "copt": "a,b" }
पहले वाली वैल्यू से मेल खाता है, लेकिन बाद वाली वैल्यू से नहीं. हालांकि,--ios_multi_cpus
(Apple के नियमों के हिसाब से) ऐसा होता है:-ios_multi_cpus=a,b
औरios_multi_cpus=a --ios_multi_cpus=b
, दोनों["a", "b"]
बनाते हैं. फ़्लैग की परिभाषाएं देखें और उम्मीदों के मुताबिक नतीजे पाने के लिए, अपनी शर्तों को ध्यान से जांच लें. - अगर आपको ऐसी स्थितियां तय करनी हैं जिन्हें पहले से मौजूद बिल्ड फ़्लैग से मॉडल नहीं किया गया है, तो
Starlark के तय किए गए फ़्लैग इस्तेमाल करें. आप
--define
का भी इस्तेमाल कर सकते हैं. हालांकि, यह सुविधा बेहतर तरीके से काम करती है. इसलिए, हमारा सुझाव है कि आप ऐसा न करें. ज़्यादा बातचीत के लिए यहां देखें. - अलग-अलग पैकेज में, एक जैसी
config_setting
परिभाषाएं दोहराने से बचें. इसके बजाय, कैननिकल पैकेज में बताए गए सामान्यconfig_setting
का रेफ़रंस दें. values
,define_values
, औरconstraint_values
को एक हीconfig_setting
में किसी भी कॉम्बिनेशन में इस्तेमाल किया जा सकता है, लेकिन किसी भीconfig_setting
के लिए कम से कम एक सेट होना चाहिए.
तर्क
विशेषताएं | |
---|---|
name |
नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम. |
constraint_values
|
लेबल की सूची कॉन्फ़िगर नहीं की जा सकती; डिफ़ॉल्ट रूप से यह constraint_values का कम से कम सेट, जिसे टारगेट प्लैटफ़ॉर्म को
इस config_setting से मेल खाने के लिए तय करना होगा. (यहां प्रोग्राम चलाने के लिए इस्तेमाल किए जाने वाले प्लैटफ़ॉर्म के बारे में नहीं बताया गया है.) प्लैटफ़ॉर्म ने जिन अतिरिक्त कंस्ट्रेंट वैल्यू को शामिल नहीं किया है उन्हें अनदेखा कर दिया जाता है. ज़्यादा जानकारी के लिए,
कॉन्फ़िगर किए जा सकने वाले बिल्ड एट्रिब्यूट देखें.
ऐसे मामले में जहां दो |
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
|
डिक्शनरी: label -> स्ट्रिंग; कॉन्फ़िगर नहीं की जा सकती; डिफ़ॉल्ट रूप से 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
नियम का सोर्स देखेंgenquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)
genquery()
,
ब्लेज़ क्वेरी लैंग्वेज में बताई गई क्वेरी को चलाता है और नतीजे को
एक फ़ाइल में डंप करता है.
बिल्ड को एक जैसा बनाए रखने के लिए, क्वेरी को सिर्फ़
scope
एट्रिब्यूट में दिए गए टारगेट के ट्रांज़िटिव क्लोज़र पर जाने की
अनुमति है. अगर strict
के बारे में जानकारी नहीं दी गई है या सही है, तो इस नियम का उल्लंघन करने वाली क्वेरी लागू नहीं होंगी (अगर strict
गलत है, तो दायरे से बाहर वाले टारगेट को चेतावनी के साथ छोड़ दिया जाएगा). ऐसा न हो, इसे पक्का करने का सबसे आसान तरीका यह है कि आप स्कोप में उन लेबल के बारे में बताएं जो क्वेरी एक्सप्रेशन में हैं.
यहां और कमांड लाइन में इस्तेमाल की जा सकने वाली क्वेरी के बीच सिर्फ़ यह अंतर है कि वाइल्डकार्ड टारगेट की खास जानकारी (जैसे कि //pkg:*
या //pkg:all
) वाली क्वेरी की यहां अनुमति नहीं है.
इसकी दो वजहें हैं: पहली, क्योंकि genquery
में
क्वेरी के ट्रांज़िटिव क्लोज़ से बाहर के टारगेट को उसके आउटपुट पर असर डालने के लिए, स्कोप तय करना है.
दूसरी वजह यह है कि BUILD
फ़ाइलें,
वाइल्डकार्ड डिपेंडेंसी के साथ काम नहीं करतीं (उदाहरण के लिए, deps=["//a/..."]
की अनुमति नहीं है).
डिटरमिनिस्टिक आउटपुट लागू करने के लिए, जेनक्वेरी के आउटपुट को लेक्सिकोग्राफ़िक तरीके से क्रम में लगाया जाता है.
हालांकि, --output=graph|minrank|maxrank
या जब somepath
का इस्तेमाल टॉप-लेवल फ़ंक्शन के तौर पर किया जाता है, तो इसे अपवाद माना जाता है.
आउटपुट फ़ाइल का नाम ही नियम का नाम होता है.
उदाहरण
यह उदाहरण किसी फ़ाइल के लिए तय टारगेट के ट्रांज़िटिव क्लोज़र में लेबल की सूची लिखता है.
genquery( name = "kiwi-deps", expression = "deps(//kiwi:kiwi_lib)", scope = ["//kiwi:kiwi_lib"], )
तर्क
विशेषताएं | |
---|---|
name |
नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम. |
compressed_output
|
बूलियन; डिफ़ॉल्ट True है, तो क्वेरी आउटपुट को GZIP फ़ाइल फ़ॉर्मैट में लिखा जाता है. इस सेटिंग का इस्तेमाल तब किया जा सकता है,
जब क्वेरी आउटपुट के ज़्यादा होने की संभावना हो. इस सेटिंग की वैल्यू चाहे जो भी हो, Baज़ल, क्वेरी आउटपुट को 220 बाइट से ज़्यादा पहले से कंप्रेस करता है. इसलिए, इसे 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
|
बूलियन; डिफ़ॉल्ट |
सामान्य
नियम का सोर्स देखें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 का इस्तेमाल करें.
टेस्ट करने के लिए जेनरूल का इस्तेमाल न करें. जांच और जांच के नतीजों के लिए खास तरीके उपलब्ध हैं.
इनमें कैश मेमोरी की नीतियां और एनवायरमेंट वैरिएबल भी शामिल हैं. आम तौर पर, बिल्ड पूरा होने के बाद और टारगेट आर्किटेक्चर पर टेस्ट किए जाने चाहिए. वहीं, जेन रूल को बिल्ड के दौरान और एक्ज़ेक्यूटिव आर्किटेक्चर पर लागू किया जाता है (ये दोनों अलग-अलग हो सकते हैं). अगर आपको किसी सामान्य मकसद के लिए जांच करने के नियम की ज़रूरत है, तो sh_test
का इस्तेमाल करें.
क्रॉस-कंपाइलेशन के बारे में ध्यान देने वाली बातें
क्रॉस-कंपाइलेशन के बारे में ज़्यादा जानकारी के लिए, इस्तेमाल के लिए गाइड देखें.
जेन रूल, बिल्ड के दौरान चलते हैं, लेकिन उनके आउटपुट का इस्तेमाल बिल्ड के बाद, डिप्लॉयमेंट या जांच के लिए किया जाता है. माइक्रोकंट्रोलर के लिए C कोड कंपाइल करने के उदाहरण पर विचार करें: कंपाइलर C सोर्स फ़ाइलों को स्वीकार करता है और माइक्रोकंट्रोलर पर चलने वाला कोड जनरेट करता है. साफ़ तौर पर, जनरेट किया गया कोड उस सीपीयू पर नहीं चल सकता जिसका इस्तेमाल उसे बनाने के लिए किया गया था, लेकिन सी कंपाइलर (अगर सोर्स से कंपाइल किया जाता है) को खुद ऐसा करना चाहिए.
बिल्ड सिस्टम एक्ज़िक कॉन्फ़िगरेशन का इस्तेमाल करके उन मशीन की जानकारी देता है जिन पर बिल्ड चलता है. वहीं, टारगेट कॉन्फ़िगरेशन का इस्तेमाल उन मशीन की जानकारी देने के लिए किया जाता है जिन पर बिल्ड का आउटपुट चलना चाहिए. यह इनमें से हर एक को कॉन्फ़िगर करने के विकल्प देता है और यह टकरावों से बचने के लिए इससे जुड़ी फ़ाइलों को अलग-अलग डायरेक्ट्री में बांटता है.
जेनरूल के लिए, बिल्ड सिस्टम यह पक्का करता है कि डिपेंडेंसी सही तरीके से बनाई गई हैं:
srcs
को टारगेट कॉन्फ़िगरेशन के लिए (ज़रूरी होने पर) बनाया गया है,
tools
को एक्ज़िक कॉन्फ़िगरेशन के लिए बनाया गया है और आउटपुट को
टारगेट कॉन्फ़िगरेशन के लिए बनाया गया है. यह
"Make" वैरिएबल भी उपलब्ध कराता है, जिसे जेन नियम कमांड से जुड़े टूल तक भेजा जा सकता है.
यह जान-बूझकर बनाया गया है कि जेन नियम किसी deps
एट्रिब्यूट की जानकारी नहीं देता है: अन्य बिल्ट-इन नियम,
नियमों के बीच पास की गई भाषा पर आधारित मेटा जानकारी का इस्तेमाल करते हैं, ताकि यह अपने-आप तय हो सके कि
डिपेंडेंट नियमों को कैसे मैनेज किया जाए. हालांकि, जेन रूल के लिए इस तरह का ऑटोमेशन मुमकिन नहीं है. जेन नियम पूरी तरह से
फ़ाइल और रनफ़ाइल लेवल पर काम करते हैं.
खास मामले
एक्ज़िक-एक्ज़ेक्यूलेशन कंपाइलेशन: कुछ मामलों में, बिल्ड सिस्टम को जेन रूल चलाने की ज़रूरत इसलिए पड़ती है, ताकि बिल्ड के दौरान भी आउटपुट को एक्ज़ीक्यूट किया जा सके. उदाहरण के लिए, अगर कोई जेनरुल कुछ कस्टम कंपाइलर बनाता है,
जिसे बाद में किसी दूसरे जेनरूल के लिए इस्तेमाल किया जाता है, तो पहले वाले को exec कॉन्फ़िगरेशन के लिए अपना आउटपुट देना होता है. ऐसा इसलिए, क्योंकि दूसरे जेनरूल में कंपाइलर इसी जगह पर काम करता है. इस मामले में,
बिल्ड सिस्टम सही काम अपने-आप करता है: यह टारगेट कॉन्फ़िगरेशन के बजाय, exec कॉन्फ़िगरेशन के लिए, पहले जेन नियम का srcs
और
outs
बनाता है. ज़्यादा जानकारी के लिए, इस्तेमाल के लिए गाइड देखें.
JDK और C++ टूल: JDK या C++ कंपाइलर सुइट से किसी टूल का इस्तेमाल करने के लिए, बिल्ड सिस्टम इस्तेमाल करने के लिए वैरिएबल का एक सेट देता है. ज़्यादा जानकारी के लिए, "बनाएं" वैरिएबल देखें.
जेनरुल एनवायरमेंट
जेनरूल कमांड को ऐसे बैश शेल से चलाया जाता है जिसे set -e -o pipefail
का इस्तेमाल करके, किसी निर्देश
या पाइपलाइन के काम न करने पर, फ़ेल होने के लिए कॉन्फ़िगर किया जाता है.
बिल्ड टूल, Bash कमांड को सैनिटाइज़ प्रोसेस एनवायरमेंट में एक्ज़ीक्यूट करता है. यह
सिर्फ़ PATH
, PWD
,
TMPDIR
, और कुछ अन्य कोर वैरिएबल के बारे में जानकारी देता है.
यह पक्का करने के लिए कि बिल्ड फिर से बनाए जा सकें, उपयोगकर्ता के शेल एनवायरमेंट में तय किए गए ज़्यादातर वैरिएबल, जेन रूल के निर्देश पर पास न किए जाएं. हालांकि, Baze, (लेकिन
Blaze नहीं) उपयोगकर्ता के PATH
एनवायरमेंट वैरिएबल की वैल्यू से गुजरता है.
PATH
की वैल्यू में कोई भी बदलाव करने से, Baze अगले बिल्ड पर
निर्देश फिर से लागू कर देगा.
जेनरूल कमांड को सिर्फ़ उन प्रोसेस को कनेक्ट करने के अलावा नेटवर्क को ऐक्सेस नहीं करना चाहिए जो खुद कमांड की चाइल्ड हैं. हालांकि, इसे अभी लागू नहीं किया गया है.
बिल्ड सिस्टम, किसी भी मौजूदा आउटपुट फ़ाइल को अपने-आप मिटा देता है. हालांकि, यह जेनरूल चलाने से पहले सभी ज़रूरी पैरंट डायरेक्ट्री बना देता है. गड़बड़ी होने पर, आउटपुट वाली सभी फ़ाइलें भी हटा दी जाएंगी.
सामान्य सलाह
- यह पक्का करें कि जेनरूल की मदद से चलने वाले टूल डिटरमिनिस्टिक और हर्मेटिक हों. उन्हें अपने आउटपुट के लिए टाइमस्टैंप नहीं लिखने चाहिए. साथ ही, उन्हें सेट और मैप के लिए स्टेबल ऑर्डर का इस्तेमाल करना चाहिए. साथ ही, उन्हें आउटपुट के मिलते-जुलते फ़ाइल पाथ लिखने चाहिए, ऐब्सलूट पाथ का इस्तेमाल नहीं करना चाहिए. इस नियम का पालन न करने से बिल्ड के तरीके में कोई गड़बड़ी होगी (बेज़ल, उस सामान्य नियम को फिर से नहीं बना पाएगा जो आपको लगता था) और कैश मेमोरी की परफ़ॉर्मेंस में कमी आएगी.
- आउटपुट, टूल, और सोर्स के लिए,
$(location)
का ज़्यादा इस्तेमाल करें. अलग-अलग कॉन्फ़िगरेशन के लिए आउटपुट फ़ाइलों को अलग-अलग करने की वजह से, जनरेशन नियम हार्ड कोड किए गए और/या ऐब्सलूट पाथ पर निर्भर नहीं हो सकते. - अगर एक जैसे या काफ़ी मिलते-जुलते जेन नियम कई जगहों पर इस्तेमाल किए गए हैं, तो एक सामान्य Starlark मैक्रो ज़रूर लिखें. अगर जेनरुल जटिल है, तो इसे स्क्रिप्ट या स्टारलार्क नियम के तौर पर लागू करें. इससे ऐप्लिकेशन को पढ़ना आसान होने के साथ-साथ, टेस्ट करने में आसानी होती है.
- पक्का करें कि एग्ज़िट कोड सही तरीके से यह दिखाता हो कि सामान्य नियम लागू हुआ या नहीं.
- 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)
.- सिमलिंक और डायरेक्ट्री बनाने से बचें. Basel, genनियमों के ज़रिए बनाई गई डायरेक्ट्री/सिमलिंक स्ट्रक्चर को कॉपी नहीं करता है. साथ ही, डायरेक्ट्री के लिए इसकी डिपेंडेंसी की जांच से जुड़ी कोई जानकारी नहीं मिलती है.
- अन्य नियमों में जेन रूल का रेफ़रंस देते समय, जेनरूल के लेबल या अलग-अलग आउटपुट फ़ाइलों के
लेबल का इस्तेमाल किया जा सकता है. कभी-कभी एक तरीका ज़्यादा पढ़ने लायक होता है, कभी-कभी दूसरा: इस्तेमाल करने वाले नियम के
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 |
नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम. आप इस नियम को srcs या BUILD के अन्य नियमों के deps सेक्शन में नाम दे सकते हैं. अगर यह नियम सोर्स फ़ाइलें जनरेट करता है, तो आपको
srcs एट्रिब्यूट का इस्तेमाल करना चाहिए.
|
srcs
|
लेबल की सूची; डिफ़ॉल्ट
यह एट्रिब्यूट, उन टूल की सूची बनाने के लिए सही नहीं है जिन्हें
बिल्ड सिस्टम यह पक्का करता है कि ये ज़रूरी शर्तें, gen बचाने
वाले निर्देश को चलाने से पहले बनाई गई हैं. इन्हें बनाने के लिए, उसी कॉन्फ़िगरेशन का इस्तेमाल किया जाता है जिसका इस्तेमाल मूल बिल्ड अनुरोध में किया गया था. इन ज़रूरी शर्तों की फ़ाइलों के नाम, कमांड में, |
outs
|
फ़ाइल नामों की सूची कॉन्फ़िगर नहीं की जा सकती; ज़रूरी है इस नियम के तहत जनरेट की गई फ़ाइलों की सूची.आउटपुट फ़ाइलों को पैकेज की सीमाएं पार नहीं करनी चाहिए. आउटपुट फ़ाइल नामों को पैकेज के हिसाब से समझा जाता है.
अगर
जेनरूल कमांड से हर आउटपुट फ़ाइल को पहले से तय जगह पर बनाया जाता है.
जगह की जानकारी |
cmd
|
स्ट्रिंग; डिफ़ॉल्ट तौर पर $(location)
और "बनाएं" वैरिएबल के विकल्प पर निर्भर करता है.
cmd_bash , cmd_ps , और cmd_bat का फ़ॉलबैक है.
अगर कमांड लाइन की लंबाई, प्लैटफ़ॉर्म की सीमा (Linux/macOS पर 64K, Windows पर 8K) से ज़्यादा हो जाती है, तो gen दवा, स्क्रिप्ट में कमांड लिख देगा और उस स्क्रिप्ट को लागू करने के लिए उसे लागू कर देगा. यह
सभी cmd एट्रिब्यूट ( |
cmd_bash
|
स्ट्रिंग; डिफ़ॉल्ट तौर पर इस एट्रिब्यूट की प्राथमिकता |
cmd_bat
|
स्ट्रिंग; डिफ़ॉल्ट तौर पर इस एट्रिब्यूट की प्राथमिकता
|
cmd_ps
|
स्ट्रिंग; डिफ़ॉल्ट तौर पर इस एट्रिब्यूट की प्राथमिकता
PowerShell को इस्तेमाल करना आसान बनाने के साथ-साथ गड़बड़ियों को भी कम करने के लिए, हम इन निर्देशों का पालन करके एनवायरमेंट को सेट अप करते हैं. इसके बाद, हम जेनरल में PowerShell निर्देश का इस्तेमाल करते हैं.
|
executable
|
बूलियन; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट है
इस फ़्लैग को 'सही है' पर सेट करने का मतलब है कि आउटपुट एक एक्ज़ीक्यूटेबल फ़ाइल है और उसे
जनरेट की गई एक्ज़ीक्यूटेबल के लिए डेटा डिपेंडेंसी का एलान नहीं किया जा सकता. |
local
|
बूलियन; डिफ़ॉल्ट
अगर नीति को 'सही है' पर सेट किया जाता है, तो यह विकल्प इस
यह 'स्थानीय' को टैग ( |
message
|
स्ट्रिंग; डिफ़ॉल्ट तौर पर
बिल्ड का यह चरण पूरा होते ही, प्रोग्रेस का मैसेज प्रिंट किया जाएगा. डिफ़ॉल्ट रूप से, आपको "आउटपुट जनरेट हो रहा है" (या इतना ही साफ़-साफ़ मैसेज नहीं दिखेगा) लेकिन आप ज़्यादा सटीक मैसेज
दे सकते हैं. अपने |
output_licenses
|
लाइसेंस का टाइप, common attributes
देखें
|
output_to_bindir
|
बूलियन; कॉन्फ़िगर नहीं किया जा सकता; डिफ़ॉल्ट है
अगर इस विकल्प को 'सही है' पर सेट किया जाता है, तो इस विकल्प की वजह से आउटपुट फ़ाइलें |
tools
|
लेबल की सूची; डिफ़ॉल्ट
बिल्ड सिस्टम यह पक्का करता है कि जनरेटिव कमांड का इस्तेमाल करने से पहले, इन ज़रूरी शर्तों को पूरा किया जाए.
इन्हें 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
बाइनरी प्रोटो है, जैसा कि Basel के सोर्स ट्री में
stardoc_output.proto
में बताया गया है.
इंप्लिसिट आउटपुट टारगेट
name.binaryproto
(डिफ़ॉल्ट आउटपुट):ModuleInfo
बाइनरी प्रोटो.name.textproto
(सिर्फ़ तब बनाया जाता है, जब साफ़ तौर पर अनुरोध किया गया हो):name.binaryproto
का टेक्स्ट प्रोटो वर्शन.
चेतावनी: इस नियम के आउटपुट फ़ॉर्मैट के स्थिर होने की कोई गारंटी नहीं है. इसे मुख्य रूप से Stardoc में इस्तेमाल करने के लिए बनाया गया है.
तर्क
विशेषताएं | |
---|---|
name |
नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम. |
deps
|
लेबल की सूची; डिफ़ॉल्ट src ने load() के तौर पर मार्क किया है. सामान्य इस्तेमाल के तहत, ये टारगेट bzl_library टारगेट होने चाहिए. हालांकि, starlark_doc_extract नियम इसे लागू नहीं करता. साथ ही, यह ऐसे किसी भी टारगेट को स्वीकार करता है जो Starlark की DefaultInfo में फ़ाइलें उपलब्ध कराता है.
ध्यान दें कि रैप की गई Starlark फ़ाइलें, सोर्स ट्री में मौजूद होनी चाहिए. Basel, जनरेट की गई फ़ाइलों को
|
src
|
लेबल; ज़रूरी है एक Starlark फ़ाइल जिससे दस्तावेज़ एक्सट्रैक्ट करना है.ध्यान दें कि यह सोर्स ट्री में मौजूद फ़ाइल होनी चाहिए; Basel, जनरेट की गई फ़ाइलों को |
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
|
लेबल की सूची कॉन्फ़िगर नहीं की जा सकती; डिफ़ॉल्ट रूप से यह
भाषा के अलावा, यहां किसी भी
अगर |