आर्ग्स

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

अक्सर ऐसा होता है कि किसी कार्रवाई के लिए एक बड़ी कमांड लाइन की ज़रूरत होती है, जिसमें ट्रांज़िटिव डिपेंडेंसी से इकट्ठा की गई वैल्यू होती हैं. उदाहरण के लिए, लिंकर कमांड लाइन, लिंक की जा रही सभी लाइब्रेरी के लिए ज़रूरी हर ऑब्जेक्ट फ़ाइल की सूची बना सकती है. इस तरह के ट्रांज़िटिव डेटा को 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 default = 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 ज़रूरी है
map_each और format_each को लागू करने पर मिली स्ट्रिंग को string.join() की तरह एक साथ जोड़ने के लिए इस्तेमाल की जाने वाली डीलिमिटर स्ट्रिंग.
map_each callable; or None; डिफ़ॉल्ट = कोई नहीं
जो add_all के लिए समान है.
format_each string; or None; डिफ़ॉल्ट = कोई नहीं
जो add_all के लिए समान है.
format_joined string; or None; डिफ़ॉल्ट = कोई नहीं
जोड़ी गई स्ट्रिंग पर लागू किया गया वैकल्पिक फ़ॉर्मैट स्ट्रिंग पैटर्न. फ़ॉर्मैट स्ट्रिंग में सिर्फ़ एक '%s' प्लेसहोल्डर होना चाहिए.
omit_if_empty default = True
अगर सही है, तो अगर एक साथ जोड़ने के लिए कोई स्ट्रिंग नहीं है (क्योंकि या तो values खाली है या उसके सभी आइटम फ़िल्टर किए गए हैं), तो आगे की प्रोसेस बंद हो जाएगी और कमांड लाइन में कोई बदलाव नहीं होगा. अगर गलत है, तो भले ही एक साथ जोड़ने के लिए कोई स्ट्रिंग न हो, फिर भी दो आर्ग्युमेंट जोड़ दिए जाएंगे: आर्ग्युमेंट का नाम और उसके बाद एक खाली स्ट्रिंग (जो शून्य स्ट्रिंग का लॉजिकल जॉइन है).
uniquify डिफ़ॉल्ट = गलत है
यह add_all के जैसा ही है.
expand_directories डिफ़ॉल्ट = True
इसके जैसा ही add_all के लिए होता है.
allow_closure डिफ़ॉल्ट = गलत है
यह add_all के जैसा ही है.

set_param_file_format

Args Args.set_param_file_format(format)

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

पैरामीटर

पैरामीटर ब्यौरा
format ज़रूरी है
इनमें से कोई एक होना चाहिए:
  • "multiline": हर आइटम (तर्क का नाम या वैल्यू) को पैरामीटर फ़ाइल में हूबहू लिखा जाता है. इसके बाद एक नई लाइन होती है.
  • "shell": "मल्टीलाइन" के जैसा ही है, लेकिन आइटम शेल कोट किए हुए हैं
  • "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 डिफ़ॉल्ट = गलत
क्या आर्ग्युमेंट को हमेशा पैरामीटर फ़ाइल में दिखाना है. अगर गलत है, तो bazel यह तय करेगा कि आपके सिस्टम और तर्क की लंबाई के हिसाब से आर्ग्युमेंट को अलग-अलग करने की ज़रूरत है या नहीं.