आर्ग्स

एक ऑब्जेक्ट, जो मेमोरी की कम खपत करने वाले तरीके से, किसी कमांड लाइन का एक हिस्सा या पूरा डेटा बनाने के लिए ज़रूरी डेटा इकट्ठा करता है.

अक्सर ऐसा होता है कि किसी कार्रवाई के लिए एक बड़ी कमांड लाइन की ज़रूरत होती है, जिसमें ट्रांज़िटिव डिपेंडेंसी से इकट्ठा की गई वैल्यू होती हैं. उदाहरण के लिए, लिंकर कमांड लाइन, लिंक की जा रही सभी लाइब्रेरी के लिए ज़रूरी हर ऑब्जेक्ट फ़ाइल की सूची बना सकती है. ऐसे ट्रांज़िटिव डेटा को depset में सेव करना सबसे सही तरीका है, ताकि उन्हें कई टारगेट शेयर कर सकें. हालांकि, अगर नियम के लेखक को कार्रवाई कमांड लाइन बनाने के लिए, इन जानकारी को स्ट्रिंग की सूचियों में बदलना पड़े, तो यह मेमोरी शेयर करने का ऑप्टिमाइज़ेशन बंद कर देगा.

इस वजह से, ऐक्शन बनाने वाले फ़ंक्शन, स्ट्रिंग के साथ-साथ Args ऑब्जेक्ट भी स्वीकार करते हैं. हर Args ऑब्जेक्ट, स्ट्रिंग और डिपेसेट का कॉम्बिनेशन दिखाता है. साथ ही, डेटा में बदलाव करने के लिए वैकल्पिक ट्रांसफ़ॉर्मेशन ऐक्शन के साथ उपलब्ध होता है. Args ऑब्जेक्ट, कमांड लाइन को कैलकुलेट करने का समय आने पर, एक्ज़ीक्यूशन फ़ेज़ तक उन डेटा सेट को प्रोसेस नहीं करते हैं जिन्हें वे एनकैप्सुलेट करते हैं. इसकी मदद से, विश्लेषण के चरण पूरा होने तक किसी भी महंगी कॉपी को टाल दिया जाता है. ज़्यादा जानकारी के लिए, परफ़ॉर्मेंस को ऑप्टिमाइज़ करना पेज देखें.

Args, ctx.actions.args() को कॉल करके बनाए गए हैं. इन्हें ctx.actions.run() या ctx.actions.run_shell() के arguments पैरामीटर के तौर पर पास किया जा सकता है. Args ऑब्जेक्ट में होने वाले हर बदलाव से, आखिर में कमांड लाइन में वैल्यू जुड़ जाती है.

map_each सुविधा की मदद से, आइटम को स्ट्रिंग में बदलने का तरीका अपनी पसंद के मुताबिक बनाया जा सकता है. अगर आपने map_each फ़ंक्शन नहीं दिया है, तो स्टैंडर्ड कन्वर्ज़न इस तरह होगा:

  • जो वैल्यू पहले से ही स्ट्रिंग हैं उन्हें ज्यों का त्यों छोड़ दिया जाता है.
  • File ऑब्जेक्ट को उनकी File.path वैल्यू में बदला गया है.
  • बाकी सभी टाइप को बिना जानकारी के स्ट्रिंग में बदला जाता है. इस वजह से, आपको add() के लिए ऐसी वैल्यू पास नहीं करनी चाहिए जो स्ट्रिंग या File टाइप की न हों. अगर उन्हें add_all() या add_joined() पर पास किया जाता है, तो आपको map_each फ़ंक्शन देना चाहिए.

स्ट्रिंग फ़ॉर्मैटिंग का इस्तेमाल करते समय (add*() तरीकों के format, format_each, और format_joined पैरामीटर), फ़ॉर्मैट टेंप्लेट की व्याख्या उसी तरह की जाती है जैसे स्ट्रिंग पर %-विकल्प की मदद से किया जाता है. हालांकि, टेंप्लेट में सिर्फ़ एक सब्सिटिट्यूशन प्लेसहोल्डर होना चाहिए और यह %s होना चाहिए. लिटरल प्रतिशत को %% के तौर पर एस्केप किया जा सकता है. वैल्यू को स्ट्रिंग में ऊपर बताए गए तरीके के मुताबिक बदलने के बाद, फ़ॉर्मैटिंग लागू की जाती है.

add*() के हर तरीके में एक वैकल्पिक फ़ॉर्म होता है, जो एक और पोज़िशनल पैरामीटर को स्वीकार करता है. बाकी तर्कों के पहले एक "आर्ग का नाम" स्ट्रिंग होती है, जिसे डाला जाता है. add_all और add_joined के लिए, अगर क्रम खाली होता है, तो अतिरिक्त स्ट्रिंग को नहीं जोड़ा जाएगा. उदाहरण के लिए, उसी इस्तेमाल से कमांड लाइन में --foo val1 val2 val3 --bar या सिर्फ़ --bar जोड़ा जा सकता है. हालांकि, यह इस बात पर निर्भर करता है कि दिए गए क्रम में val1..val3 है या नहीं.

अगर कमांड लाइन का साइज़, सिस्टम की ओर से मंज़ूर किए गए ज़्यादा से ज़्यादा साइज़ से ज़्यादा हो सकता है, तो तर्क, पैरामीटर फ़ाइलों में भी छोड़े जा सकते हैं. use_param_file() और set_param_file_format() देखें.

उदाहरण: मान लें कि हम कमांड लाइन जनरेट करना चाहते थे: 

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
हम इस Args ऑब्जेक्ट का इस्तेमाल कर सकते हैं: 
# foo_deps and bar_deps are depsets containing
# File objects for the foo and bar .txt files.
args = ctx.actions.args()
args.add_all("--foo", foo_deps)
args.add_joined("--bar", bar_deps, join_with=",")
args.add("--baz")
ctx.actions.run(
  ...
  arguments = [args],
  ...
)

पैसे चुकाकर बने सदस्य

जोड़ें

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

इस कमांड लाइन में तर्क जोड़ता है.

पैरामीटर

पैरामीटर ब्यौरा
arg_name_or_value ज़रूरी है
अगर दो पोज़िशनल पैरामीटर पास होते हैं, तो इसे आर्ग्युमेंट का नाम माना जाता है. आर्ग्युमेंट का नाम, बिना किसी प्रोसेसिंग के वैल्यू से पहले जोड़ दिया जाता है. अगर सिर्फ़ एक पोज़िशन का पैरामीटर पास किया जाता है, तो इसे value के तौर पर माना जाता है (नीचे देखें).
value डिफ़ॉल्ट = अनबाउंड
जोड़ने के लिए ऑब्जेक्ट. ऊपर बताए गए स्टैंडर्ड कन्वर्ज़न का इस्तेमाल करके, इसे स्ट्रिंग में बदल दिया जाएगा. इस फ़ंक्शन के लिए कोई map_each पैरामीटर नहीं है, इसलिए value कोई स्ट्रिंग या File होना चाहिए. इस तरीके के बजाय, File को add_all() या add_joined() पर पास किया जाना चाहिए.
format string; or None; डिफ़ॉल्ट = कोई नहीं
value के स्ट्रिंग वाले वर्शन पर लागू किया जाने वाला फ़ॉर्मैट स्ट्रिंग पैटर्न.

add_all

Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)

इस कमांड लाइन में एक से ज़्यादा तर्क जोड़ता है. एक्ज़ीक्यूशन के दौरान, आइटम को लेज़ी तरीके से प्रोसेस किया जाता है.

ज़्यादातर प्रोसेसिंग, जोड़ने के लिए तर्कों की सूची में होती है. इसे नीचे दिया गया तरीका बताया गया है:

  1. हर डायरेक्ट्री के File आइटम को, उस डायरेक्ट्री में बार-बार शामिल किए जाने वाले सभी File से बदल दिया जाता है.
  2. अगर map_each दिया गया है, तो उसे हर आइटम पर लागू किया जाता है. साथ ही, स्ट्रिंग की ऐसी सूचियों को जोड़ा जाता है जो शुरुआती तर्क की सूची बनाती हैं. अगर ऐसा नहीं है, तो हर आइटम में स्टैंडर्ड कन्वर्ज़न लागू करने से, शुरुआती तर्क सूची मिलती है.
  3. अगर सूची में हर तर्क मौजूद है, तो उसे format_each के साथ फ़ॉर्मैट किया जाता है.
  4. अगर uniquify सही है, तो डुप्लीकेट आर्ग्युमेंट हटा दिए जाते हैं. पहली समस्या वही रहती है जो बाद में होती है.
  5. अगर before_each स्ट्रिंग दी गई है, तो इसे सूची में मौजूद हर आर्ग्युमेंट के पहले, नए आर्ग्युमेंट के तौर पर शामिल किया जाता है. यह इस पॉइंट से जोड़े जाने वाले तर्कों की संख्या को असरदार तरीके से दोगुना कर देता है.
  6. अगर सूची खाली है और omit_if_empty 'सही' है (डिफ़ॉल्ट तौर पर), तो आर्ग्युमेंट का नाम पहले और आखिरी आर्ग्युमेंट के तौर पर, terminate_with डाले जाते हैं.
ध्यान दें कि खाली स्ट्रिंग, मान्य तर्क हैं. इन सभी चरणों को प्रोसेस करने की ज़रूरत होती है.

पैरामीटर

पैरामीटर ब्यौरा
arg_name_or_values ज़रूरी है
अगर दो पोज़िशनल पैरामीटर पास होते हैं, तो इसे आर्ग्युमेंट का नाम माना जाता है. आर्ग्युमेंट का नाम बिना किसी प्रोसेसिंग के values के पहले जोड़ दिया जाता है. अगर omit_if_empty 'सही' है (डिफ़ॉल्ट) और कोई अन्य आइटम नहीं जोड़ा गया है, तो इस आर्ग्युमेंट का नाम नहीं जोड़ा जाएगा. ऐसा तब होता है, जब values खाली हो या इसके सभी आइटम फ़िल्टर किए गए हों. अगर सिर्फ़ एक पोज़िशन का पैरामीटर पास किया जाता है, तो इसे values के तौर पर माना जाता है (नीचे देखें).
values sequence; or depset; डिफ़ॉल्ट = अनबाउंड
वह सूची, टपल या डिपसेट जिसके आइटम जोड़े जाएंगे.
map_each callable; or None; डिफ़ॉल्ट = कोई नहीं
यह एक ऐसा फ़ंक्शन है जो हर आइटम को शून्य या उससे ज़्यादा स्ट्रिंग में बदलता है. इसे जोड़ने से पहले प्रोसेस किया जा सकता है. अगर यह पैरामीटर नहीं दिया गया है, तो स्टैंडर्ड कन्वर्ज़न का इस्तेमाल किया जाता है.

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

रिटर्न वैल्यू किस तरह की होगी, यह इस बात पर निर्भर करता है कि आइटम के लिए कितने आर्ग्युमेंट बनाए जाने हैं:

  • सामान्य मामले में, जब हर आइटम एक स्ट्रिंग में बदलता है, तो फ़ंक्शन को वह स्ट्रिंग देनी चाहिए.
  • अगर आइटम को पूरी तरह से फ़िल्टर करना है, तो फ़ंक्शन None देगा.
  • अगर आइटम एक से ज़्यादा स्ट्रिंग में बदल जाता है, तो फ़ंक्शन उन स्ट्रिंग की एक सूची दिखाता है.
एक स्ट्रिंग या None दिखाने से, वैसा ही असर होता है जैसा लंबाई 1 या लंबाई 0 वाली सूची को लौटाने पर होता है. हालांकि, जहां इसकी ज़रूरत न हो वहां सूची बनाने से बचना बेहतर और आसान है.

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

विश्लेषण के बड़े चरण वाले डेटा स्ट्रक्चर को एक्ज़ीक्यूट करने के दौरान, अनचाहे रखरखाव से बचने के लिए map_each फ़ंक्शन का एलान, टॉप लेवल के def स्टेटमेंट के ज़रिए करना ज़रूरी है. हो सकता है कि यह डिफ़ॉल्ट रूप से, नेस्ट किया गया फ़ंक्शन क्लोज़र न हो.

चेतावनी: map_each को कॉल करने के दौरान लागू किए जाने वाले print() स्टेटमेंट, दिखने वाला कोई आउटपुट नहीं देंगे.

format_each string; or None; डिफ़ॉल्ट = कोई नहीं
एक वैकल्पिक फ़ॉर्मैट स्ट्रिंग पैटर्न, जो map_each फ़ंक्शन से मिलने वाली हर स्ट्रिंग पर लागू किया जाता है. फ़ॉर्मैट स्ट्रिंग में सिर्फ़ एक '%s' प्लेसहोल्डर होना चाहिए.
before_each string; or None; डिफ़ॉल्ट = कोई नहीं
values से मिले हर तर्क को जोड़ने से पहले, जोड़ने के लिए एक वैकल्पिक स्ट्रिंग जोड़ी जाती है.
omit_if_empty डिफ़ॉल्ट = True
अगर सही है, तो अगर values से मिले आर्ग्युमेंट को जोड़ने के लिए कोई आर्ग्युमेंट नहीं बनाया गया है, तो आगे की प्रोसेस को दबा दिया जाएगा और कमांड लाइन में कोई बदलाव नहीं किया जाएगा. गलत होने पर, तर्क का नाम और terminate_with दिए जाने पर भी उन्हें जोड़ा जाएगा. भले ही, दूसरे तर्क मौजूद हों या नहीं.
uniquify डिफ़ॉल्ट = गलत
सही होने पर, values से मिले डुप्लीकेट तर्क हटा दिए जाएंगे. हर आर्ग्युमेंट की सिर्फ़ पहली एंट्री ही बची रहेगी. आम तौर पर, इस सुविधा की ज़रूरत नहीं होती, क्योंकि जानकारी में पहले ही डुप्लीकेट को हटा दिया जाता है. हालांकि, अगर map_each एक से ज़्यादा आइटम के लिए एक ही स्ट्रिंग का इस्तेमाल करता है, तो यह फ़ायदेमंद हो सकता है.
expand_directories default = True
अगर सही होती है, तो values में मौजूद किसी भी डायरेक्ट्री को फ़ाइलों की फ़्लैट लिस्ट में शामिल कर दिया जाएगा. यह कार्रवाई, map_each के लागू होने से पहले होती है.
terminate_with string; or None; डिफ़ॉल्ट = कोई नहीं
दूसरे सभी तर्कों के बाद जोड़ने के लिए, एक वैकल्पिक स्ट्रिंग. अगर omit_if_empty 'सही' है (डिफ़ॉल्ट तौर पर) और कोई दूसरा आइटम नहीं जोड़ा गया है, तो यह स्ट्रिंग नहीं जोड़ी जाएगी. ऐसा तब होता है, जब values खाली हो या इसके सभी आइटम फ़िल्टर किए गए हों.
allow_closure डिफ़ॉल्ट = False
सही होने पर, map_each जैसे फ़ंक्शन पैरामीटर में बंद करने की सुविधा का इस्तेमाल करने की अनुमति देता है. आम तौर पर, यह ज़रूरी नहीं होता और इससे विश्लेषण के चरण वाले बड़े डेटा स्ट्रक्चर को एक्ज़ीक्यूशन के चरण में बनाए रखने में जोखिम पैदा होता है.

add_joined

Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)

सेपरेटर का इस्तेमाल करके, कई वैल्यू को एक साथ जोड़कर इस कमांड लाइन में तर्क जोड़ता है. एक्ज़ीक्यूशन के दौरान, आइटम को लेज़ी तरीके से प्रोसेस किया जाता है.

प्रोसेसिंग, add_all() की तरह है, लेकिन values से मिले तर्कों की सूची को join_with.join(...) की तरह ही एक ही तर्क में जोड़ा जाता है. इसके बाद, दिए गए format_joined स्ट्रिंग टेंप्लेट का इस्तेमाल करके, इसे फ़ॉर्मैट किया जाता है. add_all() से अलग, कोई before_each या terminate_with पैरामीटर नहीं होता, क्योंकि आम तौर पर ये तब काम के नहीं होते हैं, जब आइटम को एक तर्क में जोड़ा जाता है.

अगर फ़िल्टर करने के बाद किसी आर्ग्युमेंट में शामिल होने के लिए कोई स्ट्रिंग नहीं है और omit_if_empty 'सही' है (डिफ़ॉल्ट तौर पर), तो कोई प्रोसेसिंग नहीं होगी. अगर ऐसा नहीं है, तो अगर जोड़ने के लिए कोई स्ट्रिंग नहीं है, लेकिन omit_if_empty गलत है, तो जोड़ी गई स्ट्रिंग खाली स्ट्रिंग होगी.

पैरामीटर

पैरामीटर ब्यौरा
arg_name_or_values ज़रूरी है
अगर दो पोज़िशनल पैरामीटर पास होते हैं, तो इसे आर्ग्युमेंट का नाम माना जाता है. आर्ग्युमेंट का नाम values से पहले जोड़ा जाता है. इसके लिए, किसी प्रोसेसिंग की ज़रूरत नहीं होती. अगर omit_if_empty 'सही' है (डिफ़ॉल्ट) और एक साथ जोड़ने के लिए values से कोई स्ट्रिंग नहीं ली गई है, तो यह तर्क नहीं जोड़ा जाएगा (ऐसा तब हो सकता है, जब values खाली हो या इसके सभी आइटम फ़िल्टर किए गए हों). अगर सिर्फ़ एक पोज़िशन का पैरामीटर पास किया जाता है, तो इसे values के तौर पर माना जाता है (नीचे देखें).
values sequence; or depset; डिफ़ॉल्ट = अनबाउंड
वह सूची, टपल या डिपसेट जिसके आइटम को जोड़ा जाएगा.
join_with ज़रूरी है
string.join() की तरह, map_each और format_each को लागू करने पर मिली स्ट्रिंग को एक साथ जोड़ने के लिए इस्तेमाल की जाने वाली डीलिमिटर स्ट्रिंग.
map_each callable; or None; डिफ़ॉल्ट = कोई नहीं
add_all के जैसा ही है.
format_each string; or None; डिफ़ॉल्ट = कोई नहीं
add_all के जैसा ही है.
format_joined string; or None; डिफ़ॉल्ट = कोई नहीं
जोड़ी गई स्ट्रिंग पर एक वैकल्पिक फ़ॉर्मैट स्ट्रिंग पैटर्न लागू किया गया है. हालांकि, यह ज़रूरी नहीं है. फ़ॉर्मैट स्ट्रिंग में सिर्फ़ एक '%s' प्लेसहोल्डर होना चाहिए.
omit_if_empty डिफ़ॉल्ट = True
अगर सही है, तो अगर एक साथ जोड़ने के लिए कोई स्ट्रिंग नहीं है (क्योंकि या तो values खाली है या इसके सभी आइटम फ़िल्टर किए गए हैं), तो आगे की प्रोसेस बंद कर दी जाएगी और कमांड लाइन में कोई बदलाव नहीं किया जाएगा. अगर गलत है, तो एक साथ जोड़ने के लिए कोई स्ट्रिंग न होने पर भी, दो तर्क जोड़े जाएंगे: तर्क नाम के बाद एक खाली स्ट्रिंग (जो शून्य स्ट्रिंग का लॉजिकल जॉइन है).
uniquify डिफ़ॉल्ट = False
यह add_all के जैसा है.
expand_directories डिफ़ॉल्ट = True
add_all के जैसा ही है.
allow_closure डिफ़ॉल्ट = False
यह add_all के जैसा है.

set_param_file_format

Args Args.set_param_file_format(format)

अगर किसी पैरामीटर का इस्तेमाल किया जाता है, तो पैरामीटर फ़ाइल का फ़ॉर्मैट सेट करता है

पैरामीटर

पैरामीटर ब्यौरा
format ज़रूरी है
इनमें से कोई एक होना चाहिए:
  • "multiline": हर आइटम (तर्क का नाम या वैल्यू) को पैरामीटर फ़ाइल में हूबहू लिखा जाता है. इसके बाद नई लाइन दिखती है.
  • "शेल": "मल्टीलाइन" के जैसा है, लेकिन इसमें मौजूद आइटम शेल कोट किए गए हैं
  • "flag_per_line": "multiline" के समान होता है, लेकिन (1) पैरामीटर फ़ाइल में सिर्फ़ फ़्लैग ('--' से शुरू होने वाले) लिखे जाते हैं और (2) फ़्लैग के मान, अगर कोई हों, तो '=' सेपरेटर के साथ उसी लाइन पर लिखे जाते हैं. यह फ़ॉर्मैट, Abseil फ़्लैग लाइब्रेरी के मुताबिक है.

अगर फ़ॉर्मैट को कॉल नहीं किया जाता है, तो डिफ़ॉल्ट रूप से "शेल" सेट हो जाता है.

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

तर्क को किसी पैरामीटर फ़ाइल में स्पिल करता है और उन्हें पैरामीटर फ़ाइल के पॉइंटर से बदलता है. इसका इस्तेमाल तब करें, जब सिस्टम की कमांड की लंबाई की सीमाओं के लिए आपके तर्क बहुत बड़े हों.

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

पैरामीटर

पैरामीटर ब्यौरा
param_file_arg ज़रूरी है
सिर्फ़ "%s" वाली फ़ॉर्मैट स्ट्रिंग. अगर तर्क, किसी पैरामीटर फ़ाइल पर चले गए हैं, तो उन्हें पैरामीटर फ़ाइल के पाथ से फ़ॉर्मैट किए गए इस स्ट्रिंग वाले तर्क से बदल दिया जाता है.

उदाहरण के लिए, अगर तर्क, पैरामीटर फ़ाइल "params.txt" तक फैले हुए हैं, तो "--file=%s" तय करने से कार्रवाई कमांड लाइन में "--file=params.txt" शामिल हो जाएगा.

use_always डिफ़ॉल्ट = False
क्या आर्ग्युमेंट को हमेशा पैरामीटर फ़ाइल पर डालना है. अगर गलत है, तो bazel यह तय करेगा कि आपके सिस्टम और तर्क की लंबाई के हिसाब से आर्ग्युमेंट को फैलाने की ज़रूरत है या नहीं.