फ़ंक्शन

सामग्री

• package
• package_group
• exports_files
• glob
• चुनें
• सब-पैकेज

पैकेज

package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)

यह फ़ंक्शन, पैकेज के हर नियम पर लागू होने वाले मेटाडेटा की जानकारी देता है. इसका इस्तेमाल, पैकेज (BUILD फ़ाइल) में ज़्यादा से ज़्यादा एक बार किया जाता है.

package() फ़ंक्शन को फ़ाइल में सबसे ऊपर मौजूद सभी load() स्टेटमेंट के ठीक बाद, किसी भी नियम से पहले कॉल किया जाना चाहिए.

तर्क

उदाहरण

package(default_visibility = ["//foo:target"])

package_group

package_group(name, packages, includes)

यह फ़ंक्शन, पैकेज का एक सेट तय करता है और सेट के साथ एक लेबल जोड़ता है. लेबल का रेफ़रंस, visibility एट्रिब्यूट में दिया जा सकता है.

पैकेज ग्रुप का इस्तेमाल मुख्य रूप से विज़िबिलिटी कंट्रोल करने के लिए किया जाता है. सार्वजनिक तौर पर दिखने वाले टारगेट का रेफ़रंस, सोर्स ट्री के हर पैकेज से लिया जा सकता है. निजी तौर पर दिखने वाले टारगेट का रेफ़रंस, सिर्फ़ अपने पैकेज में दिया जा सकता है, न कि सब-पैकेज में. इन दोनों स्थितियों के बीच, टारगेट अपने पैकेज के साथ-साथ, एक या उससे ज़्यादा पैकेज ग्रुप के बताए गए किसी भी पैकेज का ऐक्सेस दे सकता है. 'किसको दिखे' सेटिंग के बारे में ज़्यादा जानकारी के लिए, visibility एट्रिब्यूट देखें.

किसी पैकेज को ग्रुप में तब शामिल माना जाता है, जब वह packages एट्रिब्यूट से मैच करता हो या includes एट्रिब्यूट में बताए गए किसी अन्य पैकेज ग्रुप में पहले से शामिल हो.

पैकेज ग्रुप तकनीकी तौर पर टारगेट होते हैं, लेकिन इन्हें नियमों के हिसाब से नहीं बनाया जाता. साथ ही, इनके लिए दिखने से जुड़ी कोई सुरक्षा नहीं होती.

तर्क

उदाहरण

यहां दिए गए package_group एलान में, "ट्रॉपिकल" नाम के पैकेज ग्रुप के बारे में बताया गया है. इसमें ट्रॉपिकल फ़्रूट शामिल हैं.

package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)

यहां दिए गए एलान, किसी काल्पनिक ऐप्लिकेशन के पैकेज ग्रुप के बारे में बताते हैं:

package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

package_group(
    name = "model",
    packages = ["//fooapp/database"],
)

package_group(
    name = "view",
    packages = [
        "//fooapp/swingui",
        "//fooapp/webui",
    ],
)

package_group(
    name = "controller",
    packages = ["//fooapp/algorithm"],
)

exports_files

exports_files([label, ...], visibility, licenses)

exports_files(), इस पैकेज से जुड़ी उन फ़ाइलों की सूची दिखाता है जिन्हें दूसरे पैकेज में एक्सपोर्ट किया गया है.

किसी पैकेज की BUILD फ़ाइल में, किसी दूसरे पैकेज की सोर्स फ़ाइलों का सीधे तौर पर सिर्फ़ तब रेफ़रंस दिया जा सकता है, जब उन्हें exports_files() स्टेटमेंट के साथ साफ़ तौर पर एक्सपोर्ट किया गया हो. फ़ाइलों के दिखने की सेटिंग के बारे में ज़्यादा जानें.

लेगसी व्यवहार के तौर पर, किसी नियम के इनपुट के तौर पर बताई गई फ़ाइलों को भी डिफ़ॉल्ट तौर पर दिखने के साथ एक्सपोर्ट किया जाता है. ऐसा तब तक होता है, जब तक फ़्लैग --incompatible_no_implicit_file_export को फ़्लिप नहीं किया जाता. हालांकि, इस व्यवहार पर भरोसा नहीं किया जाना चाहिए और इसे सक्रिय रूप से माइग्रेट कर दिया जाना चाहिए.

तर्क

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

उदाहरण

यहां दिए गए उदाहरण में, test_data पैकेज से golden.txt टेक्स्ट फ़ाइल को एक्सपोर्ट किया गया है, ताकि अन्य पैकेज इसका इस्तेमाल कर सकें. उदाहरण के लिए, टेस्ट के data एट्रिब्यूट में.

# from //test_data/BUILD

exports_files(["golden.txt"])

glob

glob(include, exclude=[], exclude_directories=1, allow_empty=True)

Glob एक हेल्पर फ़ंक्शन है, जो कुछ खास पाथ पैटर्न से मैच होने वाली सभी फ़ाइलें ढूंढता है. साथ ही, उनके पाथ की एक नई सूची दिखाता है, जिसे बदला जा सकता है और जिसे क्रम से लगाया जा सकता है. Glob सिर्फ़ अपने पैकेज में मौजूद फ़ाइलों को खोजता है. साथ ही, यह सिर्फ़ सोर्स फ़ाइलों को खोजता है, न कि जनरेट की गई फ़ाइलों या अन्य टारगेट को.

अगर फ़ाइल का पैकेज-रिलेटिव पाथ, include पैटर्न में से किसी एक से मैच करता है और exclude पैटर्न में से किसी से भी नहीं मैच करता है, तो सोर्स फ़ाइल का लेबल नतीजे में शामिल किया जाता है.

include और exclude सूचियों में, मौजूदा पैकेज से जुड़े पाथ पैटर्न शामिल होते हैं. हर पैटर्न में एक या एक से ज़्यादा पाथ सेगमेंट हो सकते हैं. यूनिक्स पाथ की तरह ही, इन सेगमेंट को / से अलग किया जाता है. सेगमेंट में * वाइल्डकार्ड शामिल हो सकता है: यह डायरेक्ट्री सेपरेटर / को छोड़कर, पाथ सेगमेंट में मौजूद किसी भी सबस्ट्रिंग से मैच करता है. इस वाइल्डकार्ड का इस्तेमाल, एक पाथ सेगमेंट में कई बार किया जा सकता है. इसके अलावा, ** वाइल्डकार्ड, शून्य या एक से ज़्यादा पूरे पाथ सेगमेंट से मैच कर सकता है. हालांकि, इसे स्टैंडअलोन पाथ सेगमेंट के तौर पर दिखाया जाना चाहिए.

• foo/bar.txt, इस पैकेज में मौजूद foo/bar.txt फ़ाइल से पूरी तरह मैच करता है
• foo/*.txt, foo/ डायरेक्ट्री में मौजूद हर फ़ाइल से मैच करता है, अगर फ़ाइल का आखिरी हिस्सा .txt है (जब तक कि foo/ कोई सब-पैकेज न हो)
• foo/a*.htm*, foo/ डायरेक्ट्री में मौजूद हर उस फ़ाइल से मैच करता है जो a से शुरू होती है. इसके बाद, उसमें कोई भी स्ट्रिंग होती है (यह खाली हो सकती है), फिर .htm होती है, और आखिर में कोई भी स्ट्रिंग होती है. जैसे, foo/axx.htm और foo/a.html या foo/axxx.html
• **/a.txt, इस पैकेज की हर सबडायरेक्ट्री में मौजूद हर a.txt फ़ाइल से मैच करता है
• **/bar/**/*.txt, इस पैकेज की हर डायरेक्ट्री में मौजूद हर .txt फ़ाइल से मैच करता है. ऐसा तब होता है, जब नतीजे वाले पाथ में कम से कम एक डायरेक्ट्री का नाम bar हो, जैसे कि xxx/bar/yyy/zzz/a.txt या bar/a.txt (याद रखें कि **, शून्य सेगमेंट से भी मैच करता है) या bar/zzz/a.txt
• **, इस पैकेज की हर सबडायरेक्ट्री में मौजूद हर फ़ाइल से मैच करता है
• foo**/a.txt एक अमान्य पैटर्न है, क्योंकि ** को सेगमेंट के तौर पर अपने-आप दिखना चाहिए

अगर exclude_directories आर्ग्युमेंट चालू है (1 पर सेट है), तो टाइप डायरेक्ट्री की फ़ाइलों को नतीजों से हटा दिया जाएगा (डिफ़ॉल्ट तौर पर 1).

अगर allow_empty आर्ग्युमेंट को False पर सेट किया जाता है, तो glob फ़ंक्शन गड़बड़ी दिखाएगा. ऐसा तब होगा, जब नतीजा खाली सूची होगा.

इस सुविधा में कुछ ज़रूरी सीमाएं और सावधानियां हैं:

1. glob(), फ़ाइल के आकलन के दौरान चलता है. इसलिए, glob() सिर्फ़ आपके सोर्स ट्री में मौजूद फ़ाइलों से मैच करता है, जनरेट की गई फ़ाइलों से कभी नहीं. अगर आपको ऐसा टारगेट बनाना है जिसके लिए, सोर्स और जनरेट की गई फ़ाइलों, दोनों की ज़रूरत है, तो आपको जनरेट की गई फ़ाइलों की एक अलग सूची को ग्लोब में जोड़ना होगा. :mylib और :gen_java_srcs के साथ, यहां दिया गया उदाहरण देखें.

2. अगर किसी नियम का नाम, मैच होने वाली सोर्स फ़ाइल के नाम से मेल खाता है, तो नियम उस फ़ाइल को "शैडो" कर देगा.

   इसे समझने के लिए, याद रखें कि glob(), पाथ की सूची दिखाता है. इसलिए, दूसरे नियमों के एट्रिब्यूट (उदाहरण के लिए, srcs = glob(["*.cc"])) में glob() का इस्तेमाल करने का असर, मैच होने वाले पाथ को साफ़ तौर पर सूची में शामिल करने जैसा ही होता है. उदाहरण के लिए, अगर glob() से ["Foo.java", "bar/Baz.java"] मिलता है, लेकिन पैकेज में "Foo.java" नाम का एक नियम भी है (इसकी अनुमति है, हालांकि Bazel इसके बारे में चेतावनी देता है), तो glob() का इस्तेमाल करने वाला व्यक्ति "Foo.java" फ़ाइल के बजाय, "Foo.java" नियम (इसके आउटपुट) का इस्तेमाल करेगा. ज़्यादा जानकारी के लिए, GitHub पर मौजूद समस्या #10395 देखें.

3. ग्लोब, सबडायरेक्ट्री में मौजूद फ़ाइलों से मेल खा सकते हैं. साथ ही, सबडायरेक्ट्री के नामों में वाइल्डकार्ड का इस्तेमाल किया जा सकता है. हालांकि...

4. लेबल, पैकेज की सीमा से बाहर नहीं जा सकते और ग्लोब, सब-पैकेज में मौजूद फ़ाइलों से मैच नहीं करता.

   उदाहरण के लिए, अगर x/y पैकेज के तौर पर मौजूद है, तो पैकेज x में ग्लोब एक्सप्रेशन **/*.cc में x/y/z.cc शामिल नहीं होता. पैकेज x/y, x/y/BUILD के तौर पर या package-path पर कहीं और मौजूद हो सकता है. इसका मतलब है कि ग्लोब एक्सप्रेशन का नतीजा, असल में BUILD फ़ाइलों के मौजूद होने पर निर्भर करता है. इसका मतलब है कि अगर x/y नाम का कोई पैकेज नहीं है या उसे --deleted_packages फ़्लैग का इस्तेमाल करके मिटाए जाने के तौर पर मार्क किया गया है, तो उसी ग्लोब एक्सप्रेशन में x/y/z.cc शामिल होगा.

5. ऊपर दी गई पाबंदी, सभी ग्लोब एक्सप्रेशन पर लागू होती है. इससे कोई फ़र्क़ नहीं पड़ता कि वे किस तरह के वाइल्डकार्ड का इस्तेमाल करते हैं.
6. . से शुरू होने वाले नाम वाली छिपी हुई फ़ाइल, ** और *, दोनों वाइल्डकार्ड से पूरी तरह से मैच होती है. अगर आपको किसी छिपी हुई फ़ाइल को किसी कंपाउंड पैटर्न से मैच करना है, तो आपका पैटर्न . से शुरू होना चाहिए. उदाहरण के लिए, * और .*.txt, .foo.txt से मैच करेंगे, लेकिन *.txt नहीं. छिपी हुई डायरेक्ट्री भी इसी तरह से मैच की जाती हैं. छिपी हुई डायरेक्ट्री में ऐसी फ़ाइलें शामिल हो सकती हैं जो इनपुट के तौर पर ज़रूरी नहीं हैं. साथ ही, इनसे ग्लोब की गई फ़ाइलों की संख्या और मेमोरी खपत भी बढ़ सकती है. छिपी हुई डायरेक्ट्री को बाहर रखने के लिए, उन्हें "बाहर रखें" सूची के आर्ग्युमेंट में जोड़ें.
7. "**" वाइल्डकार्ड का एक खास मामला है: पैटर्न "**", पैकेज की डायरेक्ट्री पाथ से मेल नहीं खाता. इसका मतलब है कि glob(["**"], exclude_directories = 0), मौजूदा पैकेज की डायरेक्ट्री में मौजूद सभी फ़ाइलों और डायरेक्ट्री से मैच करता है. हालांकि, यह सब-पैकेज की डायरेक्ट्री में नहीं जाता - इस बारे में पिछला नोट देखें.

आम तौर पर, आपको ग्लोब पैटर्न के लिए सिर्फ़ '*' का इस्तेमाल करने के बजाय, कोई सही एक्सटेंशन (उदाहरण के लिए, *.html) देना चाहिए. ज़्यादा जानकारी देने वाला नाम, अपने-आप दस्तावेज़ बन जाता है. साथ ही, यह पक्का करता है कि आपने गलती से बैकअप फ़ाइलों या emacs/vi/... की अपने-आप सेव होने वाली फ़ाइलों को न चुना हो.

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

ग्लोब के उदाहरण

इस डायरेक्ट्री में मौजूद सभी Java फ़ाइलों और :gen_java_srcs नियम से जनरेट हुई सभी फ़ाइलों से बनी Java लाइब्रेरी बनाएं.

java_library(
    name = "mylib",
    srcs = glob(["*.java"]) + [":gen_java_srcs"],
    deps = "...",
)

genrule(
    name = "gen_java_srcs",
    outs = [
        "Foo.java",
        "Bar.java",
    ],
    ...
)

experimental.txt को छोड़कर, डायरेक्ट्री testdata में सभी txt फ़ाइलें शामिल करें. ध्यान दें कि testdata की सब-डायरेक्ट्री में मौजूद फ़ाइलें शामिल नहीं की जाएंगी. अगर आपको उन फ़ाइलों को शामिल करना है, तो बार-बार इस्तेमाल होने वाले ग्लोब (**) का इस्तेमाल करें.

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

बार-बार होने वाले ग्लोब के उदाहरण

टेस्ट को testdata डायरेक्ट्री और उसकी किसी भी सबडायरेक्ट्री (और उनकी सबडायरेक्ट्री वगैरह) में मौजूद सभी TXT फ़ाइलों पर निर्भर करें. जिन सब-डायरेक्ट्री में BUILD फ़ाइल होती है उन्हें अनदेखा कर दिया जाता है. (ऊपर दी गई सीमाएं और पाबंदियां देखें.)

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)

इस डायरेक्ट्री और सभी सब-डायरेक्ट्री में मौजूद सभी Java फ़ाइलों से बनाई गई लाइब्रेरी बनाएं. हालांकि, उन फ़ाइलों को शामिल न करें जिनके पाथ में testing नाम की डायरेक्ट्री शामिल है. अगर हो सके, तो इस पैटर्न का इस्तेमाल नहीं करना चाहिए. ऐसा करने से, बिडिंग में बढ़ोतरी की दर कम हो सकती है और बिडिंग में लगने वाला समय बढ़ सकता है.

java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)

बड़े किए गए ग्लोब के उदाहरण

मौजूदा डायरेक्ट्री में *_test.cc के लिए एक अलग genrule बनाएं, जो फ़ाइल में लाइनों की संख्या की गिनती करता है.

# Conveniently, the build language supports list comprehensions.
[genrule(
    name = "count_lines_" + f[:-3],  # strip ".cc"
    srcs = [f],
    outs = ["%s-linecount.txt" % f[:-3]],
    cmd = "wc -l $< >$@",
 ) for f in glob(["*_test.cc"])]

अगर ऊपर दी गई BUILD फ़ाइल, पैकेज //foo में है और पैकेज में तीन मैच होने वाली फ़ाइलें, a_test.cc, b_test.cc, और c_test.cc हैं, तो bazel query '//foo:all' चलाने पर, जनरेट किए गए सभी नियमों की सूची दिखेगी:

$ bazel query '//foo:all' | sort
//foo:count_lines_a_test
//foo:count_lines_b_test
//foo:count_lines_c_test

चुनें

select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)

select() एक हेल्पर फ़ंक्शन है, जो नियम एट्रिब्यूट को कॉन्फ़िगर करने लायक बनाता है. यह किसी भी एट्रिब्यूट असाइनमेंट के दाईं ओर मौजूद वैल्यू को लगभग बदल सकता है. इसलिए, इसकी वैल्यू, कमांड-लाइन Bazel फ़्लैग पर निर्भर करती है. उदाहरण के लिए, इसका इस्तेमाल प्लैटफ़ॉर्म के हिसाब से डिपेंडेंसी तय करने या अलग-अलग रिसॉर्स को एम्बेड करने के लिए किया जा सकता है. यह इस बात पर निर्भर करता है कि नियम "डेवलपर" मोड बना है या "रिलीज़" मोड.

इसका बुनियादी इस्तेमाल इस तरह किया जाता है:

sh_binary(
    name = "mytarget",
    srcs = select({
        ":conditionA": ["mytarget_a.sh"],
        ":conditionB": ["mytarget_b.sh"],
        "//conditions:default": ["mytarget_default.sh"]
    })
)

इससे sh_binary के srcs एट्रिब्यूट को कॉन्फ़िगर किया जा सकता है. इसके लिए, इसके सामान्य लेबल सूची असाइनमेंट को select कॉल से बदला जाता है. यह कॉल, कॉन्फ़िगरेशन की शर्तों को मैच करने वाली वैल्यू पर मैप करता है. हर शर्त, config_setting या constraint_value का लेबल रेफ़रंस होती है. अगर टारगेट का कॉन्फ़िगरेशन, वैल्यू के उम्मीद के मुताबिक सेट से मैच करता है, तो यह "मैच" होती है. इसके बाद, mytarget#srcs की वैल्यू वह लेबल सूची बन जाती है जो मौजूदा कॉल से मैच करती है.

ध्यान दें:

• किसी भी कॉल के लिए, सिर्फ़ एक शर्त चुनी जाती है.
• अगर कई शर्तें मैच करती हैं और उनमें से एक शर्त, अन्य शर्तों की विशेषज्ञता है, तो स्पेशलिस्ट को प्राथमिकता दी जाती है. शर्त B को शर्त A की विशेषता माना जाता है, अगर B में A के सभी फ़्लैग और पाबंदी की वैल्यू के साथ-साथ कुछ अतिरिक्त फ़्लैग या पाबंदी की वैल्यू भी हों. इसका मतलब यह भी है कि विशेषज्ञता के हिसाब से क्रम तय करने की सुविधा को, नीचे दिए गए दूसरे उदाहरण में दिखाए गए तरीके से क्रम तय करने के लिए डिज़ाइन नहीं किया गया है.
• अगर कई शर्तें मैच करती हैं और कोई एक शर्त, बाकी सभी शर्तों की विशेषता नहीं है, तो Bazel गड़बड़ी का मैसेज दिखाता है. ऐसा तब तक होता रहेगा, जब तक सभी शर्तें एक ही वैल्यू पर न पहुंच जाएं.
• अगर कोई दूसरी शर्त मैच नहीं होती है, तो खास स्यूडो-लेबल //conditions:default को मैच माना जाता है. अगर यह शर्त छोड़ दी जाती है, तो गड़बड़ी से बचने के लिए, किसी अन्य नियम से मैच करना ज़रूरी है.
• select को बड़े एट्रिब्यूट असाइनमेंट के अंदर एम्बेड किया जा सकता है. इसलिए, srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...}) और srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]}) मान्य एक्सप्रेशन हैं.
• select ज़्यादातर एट्रिब्यूट के साथ काम करता है, लेकिन सभी के साथ नहीं. काम न करने वाले एट्रिब्यूट के दस्तावेज़ में, उन्हें nonconfigurable के तौर पर मार्क किया जाता है.

  सब-पैकेज

  subpackages(include, exclude=[], allow_empty=True)

  subpackages(), glob() जैसा ही एक हेल्पर फ़ंक्शन है. यह फ़ंक्शन, फ़ाइलों और डायरेक्ट्री के बजाय सब-पैकेज की सूची दिखाता है. यह glob() के जैसे ही पाथ पैटर्न का इस्तेमाल करता है. साथ ही, यह किसी भी ऐसे सब-पैकेज से मैच कर सकता है जो फ़िलहाल लोड हो रही BUILD फ़ाइल का सीधा वंशज है. शामिल करने और बाहर रखने के पैटर्न के बारे में ज़्यादा जानकारी और उदाहरणों के लिए, glob देखें.

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

  उदाहरण

  नीचे दिए गए उदाहरण में, पैकेज foo/BUILD के सभी डायरेक्ट सबपैकेज की सूची दी गई है

  # The following BUILD files exist:
  # foo/BUILD
  # foo/bar/baz/BUILD
  # foo/sub/BUILD
  # foo/sub/deeper/BUILD
  #
  # In foo/BUILD a call to
  subs = subpackages(include = ["**"])
  
  # results in subs == ["sub", "bar/baz"]
  #
  # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
  # 'foo'
  

  आम तौर पर, इस फ़ंक्शन को सीधे कॉल करने के बजाय, उपयोगकर्ताओं को skylib के 'सब-पैकेज' मॉड्यूल का इस्तेमाल करना चाहिए.