आर्ग्स

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

अक्सर ऐसा होता है कि किसी कार्रवाई के लिए, बड़ी कमांड लाइन की ज़रूरत होती है. इसमें ट्रांज़िशन वाली डिपेंडेंसी से इकट्ठा की गई वैल्यू होती हैं. उदाहरण के लिए, लिंकर कमांड लाइन में उन सभी ऑब्जेक्ट फ़ाइलों की सूची हो सकती है जो लिंक की जा रही सभी लाइब्रेरी के लिए ज़रूरी हैं. सबसे सही तरीका यह है कि इस तरह के ट्रांज़िशन डेटा को 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*() के हर तरीके का एक वैकल्पिक फ़ॉर्म होता है, जो एक अतिरिक्त पोज़िशनल पैरामीटर स्वीकार करता है. यह "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 डिफ़ॉल्ट = अनबाउंड
जोड़ने के लिए ऑब्जेक्ट. इसे ऊपर बताए गए स्टैंडर्ड कन्वर्ज़न का इस्तेमाल करके, स्ट्रिंग में बदल दिया जाएगा. इस फ़ंक्शन के लिए कोई map_each पैरामीटर नहीं है, इसलिए value, स्ट्रिंग या File में से कोई एक होना चाहिए. इस तरीके के बजाय, add_all() या add_joined() को सूची, ट्यूपल, डिप्सेट या डायरेक्ट्री File पास करना होगा.
format string; or None; डिफ़ॉल्ट = 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
वह सूची, ट्यूपल या डेपसेट जिसका आइटम जोड़ा जाएगा.
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; डिफ़ॉल्ट = None
यह स्ट्रिंग फ़ॉर्मैट का पैटर्न है. इसे map_each फ़ंक्शन से मिली हर स्ट्रिंग पर लागू किया जा सकता है. हालांकि, ऐसा करना ज़रूरी नहीं है. फ़ॉर्मैट स्ट्रिंग में सिर्फ़ एक '%s' प्लेसहोल्डर होना चाहिए.
before_each string; or None; default = None
values से मिले हर आर्ग्युमेंट को जोड़ने से पहले, जोड़ने के लिए वैकल्पिक स्ट्रिंग.
omit_if_empty डिफ़ॉल्ट = True
अगर values से कोई आर्ग्युमेंट नहीं मिला है, तो आगे की प्रोसेसिंग रोक दी जाती है और कमांड लाइन में कोई बदलाव नहीं होता. अगर यह फ़ील्ड 'गलत' पर सेट है, तो आर्ग्युमेंट का नाम और terminate_with, अगर दिया गया है, तो उसे जोड़ दिया जाएगा. भले ही, कोई अन्य आर्ग्युमेंट दिया गया हो या नहीं.
uniquify डिफ़ॉल्ट = False
अगर यह True है, तो values से मिले डुप्लीकेट आर्ग्युमेंट हटा दिए जाएंगे. हर आर्ग्युमेंट की सिर्फ़ पहली बार होने वाली वैल्यू ही दिखेगी. आम तौर पर, इस सुविधा की ज़रूरत नहीं होती, क्योंकि डेपसेट पहले से ही डुप्लीकेट को हटा देते हैं. हालांकि, अगर map_each एक से ज़्यादा आइटम के लिए एक ही स्ट्रिंग दिखाता है, तो यह सुविधा काम की हो सकती है.
expand_directories डिफ़ॉल्ट = True
अगर यह 'सही है' पर सेट है, तो values में मौजूद किसी भी डायरेक्ट्री को फ़ाइलों की फ़्लैट सूची में बड़ा किया जाएगा. ऐसा map_each लागू होने से पहले होता है.
terminate_with string; or None; डिफ़ॉल्ट = 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; डिफ़ॉल्ट = None
जॉइन की गई स्ट्रिंग पर लागू किया जाने वाला, फ़ॉर्मैट स्ट्रिंग पैटर्न. यह पैटर्न इस्तेमाल करना ज़रूरी नहीं है. फ़ॉर्मैट स्ट्रिंग में सिर्फ़ एक '%s' प्लेसहोल्डर होना चाहिए.
omit_if_empty डिफ़ॉल्ट = True
अगर सही है, तो अगर एक साथ जोड़ने के लिए कोई स्ट्रिंग नहीं है (values खाली है या उसके सभी आइटम फ़िल्टर किए गए हैं), तो आगे की सभी प्रोसेसिंग रोक दी जाएगी और कमांड लाइन में कोई बदलाव नहीं होगा. अगर यह फ़ील्ड false है, तो एक साथ जोड़ने के लिए कोई स्ट्रिंग न होने पर भी, दो आर्ग्युमेंट जोड़ दिए जाएंगे: आर्ग्युमेंट का नाम और उसके बाद खाली स्ट्रिंग (जो शून्य स्ट्रिंग का लॉजिकल जॉइन है).
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": हर आइटम (आर्ग्युमेंट का नाम या वैल्यू) को पैरामीटर फ़ाइल में हूबहू लिखा जाता है. इसके बाद, एक नया लाइन वर्ण जोड़ा जाता है.
  • "shell": यह "multiline" जैसा ही है, लेकिन आइटम को शेल कोटेशन में रखा जाता है
  • "flag_per_line": यह "multiline" के जैसा ही है. हालांकि, (1) पैरामीटर फ़ाइल में सिर्फ़ फ़्लैग ('--' से शुरू होने वाले) लिखे जाते हैं और (2) अगर कोई फ़्लैग है, तो उसकी वैल्यू एक ही लाइन में '=' सेपरेटर के साथ लिखी जाती है. Abseil flags library के लिए यह फ़ॉर्मैट ज़रूरी है.

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

use_param_file

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

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

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

पैरामीटर

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

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

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