आर्ग्स

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

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

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

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

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

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

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

add*() के हर तरीके का एक वैकल्पिक फ़ॉर्म होता है. यह एक अतिरिक्त पोज़ीशनल पैरामीटर स्वीकार करता है. साथ ही, यह "arg name" स्ट्रिंग को बाकी के आर्ग्युमेंट से पहले डालने की अनुमति देता है. अगर क्रम खाली है, तो 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 default = unbound
वह ऑब्जेक्ट जिसे जोड़ना है. इसे ऊपर बताए गए स्टैंडर्ड कन्वर्ज़न का इस्तेमाल करके, स्ट्रिंग में बदल दिया जाएगा. इस फ़ंक्शन के लिए कोई map_each पैरामीटर नहीं है. इसलिए, value को स्ट्रिंग या File होना चाहिए. इस तरीके के बजाय, सूची, टपल, डिप्सेट या डायरेक्ट्री File को add_all() या add_joined() में पास किया जाना चाहिए.
format string; or None; default = 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; default = unbound
वह सूची, टपल या depset जिसमें आइटम जोड़े जाएंगे.
map_each callable; or None; default = None
यह एक ऐसा फ़ंक्शन है जो हर आइटम को शून्य या उससे ज़्यादा स्ट्रिंग में बदलता है. इन्हें जोड़ने से पहले, प्रोसेस किया जा सकता है. अगर यह पैरामीटर उपलब्ध नहीं कराया जाता है, तो स्टैंडर्ड कन्वर्ज़न का इस्तेमाल किया जाता है.

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

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

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

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

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

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

format_each string; or None; default = None
यह फ़ॉर्मैट स्ट्रिंग पैटर्न का एक वैकल्पिक पैरामीटर है. इसे map_each फ़ंक्शन से मिलने वाली हर स्ट्रिंग पर लागू किया जाता है. फ़ॉर्मैट स्ट्रिंग में सिर्फ़ एक '%s' प्लेसहोल्डर होना चाहिए.
before_each string; or None; default = None
यह एक ऐसी स्ट्रिंग है जिसे values से मिले हर आर्ग्युमेंट से पहले जोड़ा जा सकता है.
omit_if_empty default = True
अगर यह वैल्यू सही है, तो values से मिले किसी भी आर्ग्युमेंट को जोड़ने के लिए, आगे की सभी प्रोसेस को बंद कर दिया जाएगा. साथ ही, कमांड लाइन में कोई बदलाव नहीं किया जाएगा. अगर यह वैल्यू 'गलत है' पर सेट है, तो आर्ग्युमेंट का नाम और terminate_with (अगर दिया गया है) अब भी जोड़ा जाएगा. भले ही, अन्य आर्ग्युमेंट मौजूद हों या न हों.
uniquify default = False
If true, duplicate arguments that are derived from values will be omitted. हर आर्ग्युमेंट का सिर्फ़ पहला उदाहरण दिखेगा. आम तौर पर, इस सुविधा की ज़रूरत नहीं होती, क्योंकि depsets पहले से ही डुप्लीकेट आइटम हटा देते हैं. हालांकि, अगर map_each कई आइटम के लिए एक ही स्ट्रिंग दिखाता है, तो यह सुविधा काम की हो सकती है.
expand_directories default = True
अगर यह 'सही है' पर सेट है, तो values में मौजूद सभी डायरेक्ट्री को फ़ाइलों की फ़्लैट सूची में बड़ा किया जाएगा. ऐसा map_each लागू होने से पहले होता है.
terminate_with string; or None; default = None
यह एक ऐसी स्ट्रिंग है जिसे सभी अन्य आर्ग्युमेंट के बाद जोड़ा जा सकता है. अगर omit_if_empty की वैल्यू 'सही है' (डिफ़ॉल्ट रूप से) पर सेट है और कोई अन्य आइटम नहीं जोड़ा गया है, तो यह स्ट्रिंग नहीं जोड़ी जाएगी. ऐसा तब होता है, जब values खाली हो या उसके सभी आइटम फ़िल्टर किए गए हों.
allow_closure default = False
If true, allows the use of closures in function parameters like 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; default = unbound
वह सूची, टपल या depset जिसके आइटम जोड़े जाएंगे.
join_with ज़रूरी है
यह एक सीमांकक स्ट्रिंग है. इसका इस्तेमाल map_each और format_each को लागू करने से मिली स्ट्रिंग को एक साथ जोड़ने के लिए किया जाता है. यह string.join() की तरह ही काम करता है.
map_each callable; or None; default = None
यह add_all के लिए इस्तेमाल किए गए तरीके जैसा ही है.
format_each string; or None; default = None
यह add_all के लिए इस्तेमाल किए गए तरीके जैसा ही है.
format_joined string; or None; default = None
यह एक वैकल्पिक फ़ॉर्मैट स्ट्रिंग पैटर्न है, जिसे जोड़ी गई स्ट्रिंग पर लागू किया जाता है. फ़ॉर्मैट स्ट्रिंग में सिर्फ़ एक '%s' प्लेसहोल्डर होना चाहिए.
omit_if_empty default = True
अगर यह वैल्यू सही है, तो एक साथ जोड़ने के लिए कोई स्ट्रिंग न होने पर (ऐसा values के खाली होने या उसके सभी आइटम फ़िल्टर किए जाने की वजह से हो सकता है), आगे की सभी प्रोसेसिंग बंद कर दी जाती है. साथ ही, कमांड लाइन में कोई बदलाव नहीं होता. अगर यह विकल्प गलत है, तो दो आर्ग्युमेंट जोड़े जाएंगे. भले ही, जोड़ने के लिए कोई स्ट्रिंग न हो. पहला आर्ग्युमेंट, आर्ग्युमेंट का नाम होगा. इसके बाद, एक खाली स्ट्रिंग जोड़ी जाएगी. यह खाली स्ट्रिंग, शून्य स्ट्रिंग का लॉजिकल जॉइन है.
uniquify default = False
यह add_all के लिए इस्तेमाल किए गए विकल्प की तरह ही है.
expand_directories default = True
यह add_all के लिए भी यही काम करता है.
allow_closure default = False
यह add_all के लिए इस्तेमाल किए गए विकल्प की तरह ही है.

set_param_file_format

Args Args.set_param_file_format(format)

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

पैरामीटर

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

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

use_param_file

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

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

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

पैरामीटर

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

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

use_always default = False
Whether to always spill the args to a params file. अगर यह वैल्यू 'गलत है' पर सेट है, तो Bazel यह तय करेगा कि आपके सिस्टम और आर्ग्युमेंट की लंबाई के आधार पर, आर्ग्युमेंट को स्पिल करने की ज़रूरत है या नहीं.