किसको दिखाई दे

इस पेज पर, Bazel के विज़िबिलिटी सिस्टम के बारे में बताया गया है: टारगेट विज़िबिलिटी और लोड विज़िबिलिटी.

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

टारगेट किसको दिखे

टारगेट की दिखने की सेटिंग से यह कंट्रोल होता है कि आपके टारगेट पर कौन निर्भर हो सकता है. इसका मतलब है कि deps जैसे किसी एट्रिब्यूट में, आपके टारगेट के लेबल का इस्तेमाल कौन कर सकता है.

टारगेट A, टारगेट B को तब दिखता है, जब वे एक ही पैकेज में हों या A, B के पैकेज को दिखने की अनुमति देता हो. इसलिए, पैकेज यह तय करने के लिए बारीकी से यह तय करते हैं कि ऐक्सेस देना है या नहीं. अगर B, A पर निर्भर करता है, लेकिन B को A नहीं दिखता, तो विश्लेषण के दौरान B बनाने की कोई भी कोशिश फ़ेल हो जाती है.

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

प्रोटोटाइप बनाने के लिए, टारगेट के दिखने की नीति को लागू करने की सुविधा को बंद किया जा सकता है. इसके लिए, --check_visibility=false फ़्लैग सेट करें. सबमिट किए गए कोड में प्रोडक्शन के इस्तेमाल के लिए ऐसा नहीं किया जाना चाहिए.

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

प्रॉडक्ट के दिखने की जानकारी

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

• "//visibility:public": सभी पैकेज का ऐक्सेस देता है. (इसे किसी अन्य स्पेसिफ़िकेशन के साथ नहीं जोड़ा जा सकता.)

• "//visibility:private": कोई अतिरिक्त ऐक्सेस नहीं देता; सिर्फ़ इस पैकेज में मौजूद टारगेट, इस टारगेट का इस्तेमाल कर सकते हैं. (इसे किसी अन्य विशेषता के साथ जोड़ा नहीं जा सकता.)

• "//foo/bar:__pkg__": //foo/bar का ऐक्सेस देता है, लेकिन इसके सब-पैकेज का नहीं.

• "//foo/bar:__subpackages__": //foo/bar और इसके सभी डायरेक्ट और इनडायरेक्ट सबपैकेज का ऐक्सेस देता है.

• "//some_pkg:my_package_group": दिए गए package_group के हिस्से वाले सभी पैकेज का ऐक्सेस देता है.

  • पैकेज ग्रुप, पैकेज की जानकारी देने के लिए एक अलग सिंटैक्स का इस्तेमाल करते हैं. पैकेज ग्रुप में, "//foo/bar:__pkg__" और "//foo/bar:__subpackages__" फ़ॉर्म को "//foo/bar" और "//foo/bar/..." से बदल दिया जाता है. इसी तरह, "//visibility:public" और "//visibility:private" सिर्फ़ "public" और "private" हैं.

उदाहरण के लिए, अगर //some/package:mytarget का visibility, [":__subpackages__", "//tests:__pkg__"] पर सेट है, तो इसका इस्तेमाल //some/package/... सोर्स ट्री के साथ-साथ //tests/BUILD में तय किए गए किसी भी टारगेट के लिए किया जा सकता है. हालांकि, इसका इस्तेमाल //tests/integration/BUILD में तय किए गए टारगेट के लिए नहीं किया जा सकता.

सबसे सही तरीका: पैकेज के एक ही सेट को कई टारगेट दिखाने के लिए, हर टारगेट के visibility एट्रिब्यूट में मौजूद सूची को दोहराने के बजाय, package_group का इस्तेमाल करें. इससे सूचियों को पढ़ना आसान हो जाता है और वे सिंक होने से नहीं रुकती हैं.

नियम टारगेट किसको दिखे

नियम के टारगेट की स्थिति:

1. अगर सेट हो, तो इसके visibility एट्रिब्यूट का मान या कुछ और

2. अगर टारगेट की BUILD फ़ाइल में package स्टेटमेंट का एलान मौजूद है, तो default_visibility एरग्युमेंट की वैल्यू

3. //visibility:private.

सबसे सही तरीका: default_visibility को 'सार्वजनिक' पर सेट करने से बचें. यह प्रोटोटाइप बनाने या छोटे कोडबेस के लिए सुविधाजनक हो सकता है. हालांकि, कोडबेस के बड़े होने पर, अनजाने में सार्वजनिक टारगेट बनाने का जोखिम बढ़ जाता है. हालांकि, यह बताना बेहतर होता है कि कौनसे टारगेट पैकेज के सार्वजनिक इंटरफ़ेस का हिस्सा हैं.

उदाहरण

फ़ाइल //frobber/bin/BUILD:

# This target is visible to everyone
cc_binary(
    name = "executable",
    visibility = ["//visibility:public"],
    deps = [":library"],
)

# This target is visible only to targets declared in the same package
cc_library(
    name = "library",
    # No visibility -- defaults to private since no
    # package(default_visibility = ...) was used.
)

# This target is visible to targets in package //object and //noun
cc_library(
    name = "subject",
    visibility = [
        "//noun:__pkg__",
        "//object:__pkg__",
    ],
)

# See package group "//frobber:friends" (below) for who can
# access this target.
cc_library(
    name = "thingy",
    visibility = ["//frobber:friends"],
)

फ़ाइल //frobber/BUILD:

# This is the package group declaration to which target
# //frobber/bin:thingy refers.
#
# Our friends are packages //frobber, //fribber and any
# subpackage of //fribber.
package_group(
    name = "friends",
    packages = [
        "//fribber/...",
        "//frobber",
    ],
)

जनरेट की गई फ़ाइल का टारगेट किसको दिखे

जनरेट की गई फ़ाइल के टारगेट को उसी तरह देखा जा सकता है जिस तरह से उसे जनरेट करने वाले नियम के टारगेट को देखा जा सकता है.

सोर्स फ़ाइल के टारगेट की उपलब्धता

exports_files को कॉल करके, सोर्स फ़ाइल टारगेट की दिखने की सेटिंग को साफ़ तौर पर सेट किया जा सकता है. जब exports_files को कोई visibility तर्क पास नहीं किया जाता है, तो यह 'किसको दिखे' सेटिंग को सार्वजनिक कर देता है. जनरेट की गई फ़ाइल को दिखाने की सेटिंग को बदलने के लिए, exports_files का इस्तेमाल नहीं किया जा सकता.

exports_files को कॉल करने पर न दिखने वाले सोर्स फ़ाइल टारगेट के लिए, दिखने की स्थिति, फ़्लैग --incompatible_no_implicit_file_export की वैल्यू पर निर्भर करती है:

• अगर फ़्लैग सेट है, तो इसका मतलब है कि वीडियो निजी है.

• ऐसा न होने पर, लेगसी कार्रवाई लागू होती है: BUILD फ़ाइल की default_visibility के दिखने की ही तरह होती है या डिफ़ॉल्ट रूप से 'किसको दिखे' सेटिंग निजी न होने पर, यह 'निजी' पर सेट होती है.

लेगसी वर्शन के काम करने के तरीके पर भरोसा न करें. जब भी किसी सोर्स फ़ाइल टारगेट को निजी के बजाय सार्वजनिक तौर पर दिखाना हो, तो हमेशा exports_files एलान लिखें.

सबसे सही तरीका: जब भी मुमकिन हो, सोर्स फ़ाइल के बजाय नियम के टारगेट को दिखाएं. उदाहरण के लिए, .java फ़ाइल पर exports_files को कॉल करने के बजाय, फ़ाइल को किसी ऐसे टारगेट में रैप करें जो निजी न हो, जैसे कि java_library. आम तौर पर, नियम के टारगेट में सिर्फ़ उन सोर्स फ़ाइलों का रेफ़रंस होना चाहिए जो एक ही पैकेज में मौजूद हों.

उदाहरण

फ़ाइल //frobber/data/BUILD:

exports_files(["readme.txt"])

फ़ाइल //frobber/bin/BUILD:

cc_binary(
  name = "my-program",
  data = ["//frobber/data:readme.txt"],
)

कॉन्फ़िगरेशन सेटिंग की विज़िबिलिटी

अब तक, Bazel ने select() की कुंजियों में रेफ़रंस दिए गए config_setting टारगेट के लिए, दिखने की सेटिंग लागू नहीं की है. इस लेगसी व्यवहार को हटाने के लिए, दो फ़्लैग हैं:

• --incompatible_enforce_config_setting_visibility इन टारगेट के लिए, दिखने की जांच की सुविधा चालू करता है. माइग्रेशन में मदद करने के लिए, ऐसा करने पर, किसी भी config_setting को सार्वजनिक माना जाता है. भले ही, पैकेज-लेवल default_visibility कुछ भी हो. ऐसा तब भी होता है, जब config_setting में visibility की जानकारी न दी गई हो.

• --incompatible_config_setting_private_default_visibility config_setting को पैकेज के default_visibility का पालन करने के लिए मजबूर करता है. साथ ही, किसी भी दूसरे नियम के टारगेट की तरह ही, visibility के न होने पर निजी तौर पर दिखने की सेटिंग पर फ़ॉलबैक करता है. अगर --incompatible_enforce_config_setting_visibility सेट नहीं है, तो यह काम नहीं करेगा.

लेगसी वर्शन के काम करने के तरीके पर भरोसा न करें. अगर पैकेज में पहले से कोई सही default_visibility नहीं दिया गया है, तो मौजूदा पैकेज के बाहर इस्तेमाल किए जाने वाले किसी भी config_setting के लिए, साफ़ तौर पर visibility दिया जाना चाहिए.

पैकेज ग्रुप टारगेट किसको दिखे

package_group टारगेट में visibility एट्रिब्यूट नहीं है. ये हमेशा सार्वजनिक तौर पर दिखते हैं.

इंप्लिसिट डिपेंडेंसी की विज़िबिलिटी

कुछ नियमों में अहम डिपेंडेंसी होती हैं — ऐसी डिपेंडेंसी जिन्हें BUILD फ़ाइल में नहीं बताया गया है, लेकिन वे उस नियम के हर उदाहरण में मौजूद होती हैं. उदाहरण के लिए, cc_library नियम अपने हर नियम के टारगेट से, C++ कंपाइलर को दिखाने वाले एक ऐसे टारगेट पर, डिफ़ॉल्ट रूप से डिपेंडेंसी बना सकता है जिसे चलाया जा सकता है.

इस तरह की लागू होने वाली डिपेंडेंसी की दिखने की स्थिति की जांच, उस पैकेज के हिसाब से की जाती है जिसमें .bzl फ़ाइल होती है. इस फ़ाइल में नियम (या आसपेक्ट) तय किया जाता है. हमारे उदाहरण में, C++ कंपाइलर तब तक निजी हो सकता है, जब तक वह cc_library नियम की परिभाषा वाले पैकेज में मौजूद हो. फ़ॉलबैक के तौर पर, अगर डेफ़िनिशन में इंप्लिसिट डिपेंडेंसी नहीं दिख रही है, तो cc_library टारगेट के हिसाब से इसकी जांच की जाती है.

--incompatible_visibility_private_attributes_at_definition को बंद करके, ऐसा किया जा सकता है. बंद होने पर, इनपुट डिपेंडेंसी को किसी भी अन्य डिपेंडेंसी की तरह ही माना जाता है. इसका मतलब है कि जिस टारगेट पर निर्भर किया जा रहा है (जैसे, हमारा C++ कंपाइलर) वह नियम के हर इंस्टेंस के लिए दिखना चाहिए. आम तौर पर, इसका मतलब है कि टारगेट को सार्वजनिक तौर पर दिखाया जाना चाहिए.

अगर आपको किसी नियम के इस्तेमाल को कुछ पैकेज तक सीमित करना है, तो इसके बजाय लोड की जाने वाली प्रॉपर्टी का इस्तेमाल करें.

लोड की गई इमेज किसको दिखे

लोड विज़िबिलिटी से यह कंट्रोल होता है कि किसी .bzl फ़ाइल को दूसरी BUILD या .bzl फ़ाइलों से लोड किया जा सकता है या नहीं.

जिस तरह टारगेट के दिखने की सेटिंग, टारगेट में शामिल किए गए सोर्स कोड को सुरक्षित रखती है उसी तरह लोड के दिखने की सेटिंग, .bzl फ़ाइलों में शामिल किए गए बिल्ड लॉजिक को सुरक्षित रखती है. उदाहरण के लिए, हो सकता है कि BUILD फ़ाइल का लेखक, .bzl फ़ाइल में मैक्रो में कुछ बार-बार इस्तेमाल होने वाली टारगेट परिभाषाओं को शामिल करना चाहे. हो सकता है कि लोड दृश्यता की सुरक्षा के बिना, उन्हें अपना मैक्रो उसी फ़ाइल फ़ोल्डर में अन्य सहयोगियों द्वारा फिर से उपयोग किया गया मिल जाए, जिससे मैक्रो में बदलाव करने से अन्य टीमों का बिल्ड टूट जाता है.

ध्यान दें कि .bzl फ़ाइल में, सोर्स फ़ाइल का टारगेट हो सकता है या नहीं. अगर ऐसा होता है, तो इस बात की कोई गारंटी नहीं है कि लोड विज़िबिलिटी और टारगेट विज़िबिलिटी एक ही हो. इसका मतलब है कि एक ही BUILD फ़ाइल, .bzl फ़ाइल को लोड कर सकती है, लेकिन उसे filegroup के srcs में शामिल नहीं कर सकती. इसके अलावा, ऐसा भी हो सकता है कि BUILD फ़ाइल, .bzl फ़ाइल को लोड न कर पाए, लेकिन उसे filegroup के srcs में शामिल कर सके. इससे कभी-कभी उन नियमों में समस्याएं आ सकती हैं जो .bzl फ़ाइलों को सोर्स कोड के तौर पर इस्तेमाल करना चाहते हैं. जैसे, दस्तावेज़ जनरेट करने या टेस्टिंग के लिए.

प्रोटोटाइप बनाने के लिए, --check_bzl_visibility=false सेट करके, लोड दिखने की ज़रूरी शर्त को बंद किया जा सकता है. --check_visibility=false की तरह ही, सबमिट किए गए कोड के लिए ऐसा नहीं किया जाना चाहिए.

लोड की जानकारी देखने की सुविधा, Bazel 6.0 से उपलब्ध है.

लोड की स्थिति की जानकारी देना

.bzl फ़ाइल के लोड होने पर दिखने की सेटिंग सेट करने के लिए, फ़ाइल में जाकर visibility() फ़ंक्शन को कॉल करें. visibility() फ़ंक्शन, पैकेज के स्पेसिफ़िकेशन की सूची है, ठीक package_group के packages एट्रिब्यूट की तरह. हालांकि, visibility() नेगेटिव पैकेज की खास बातें स्वीकार नहीं करता.

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

टारगेट की दृश्यता के उलट, डिफ़ॉल्ट लोड की दृश्यता हमेशा सार्वजनिक होती है. जो फ़ाइलें visibility() को कॉल नहीं करती हैं वे फ़ाइल फ़ोल्डर में कहीं से भी लोड की जा सकती हैं. किसी भी नई .bzl फ़ाइल के सबसे ऊपर visibility("private") जोड़ना अच्छा होता है. ऐसा खास तौर पर तब करें, जब फ़ाइल का इस्तेमाल पैकेज के बाहर न किया जाना हो.

उदाहरण

# //mylib/internal_defs.bzl

# Available to subpackages and to mylib's tests.
visibility(["//mylib/...", "//tests/mylib/..."])

def helper(...):
    ...

# //mylib/rules.bzl

load(":internal_defs.bzl", "helper")
# Set visibility explicitly, even though public is the default.
# Note the [] can be omitted when there's only one entry.
visibility("public")

myrule = rule(
    ...
)

# //someclient/BUILD

load("//mylib:rules.bzl", "myrule")          # ok
load("//mylib:internal_defs.bzl", "helper")  # error

...

लोड दिखने के तरीके

इस सेक्शन में, लोड दिखने की जानकारी को मैनेज करने के बारे में सलाह दी गई है.

फ़ैक्टर की जानकारी

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

# //mylib/internal_defs.bzl

visibility("private")

clients = [
    "//foo",
    "//bar/baz/...",
    ...
]

# //mylib/feature_A.bzl

load(":internal_defs.bzl", "clients")
visibility(clients)

...

# //mylib/feature_B.bzl

load(":internal_defs.bzl", "clients")
visibility(clients)

...

इससे, अलग-अलग .bzl फ़ाइलों के दिखने के तरीके में अनजाने में होने वाले बदलावों को रोकने में मदद मिलती है. clients सूची बड़ी होने पर भी, इसे पढ़ना आसान होता है.

'किसे दिखे' एट्रिब्यूट की वैल्यू कॉम्पोज़ करना

कभी-कभी, किसी .bzl फ़ाइल को ऐसी अनुमति सूची में दिखना पड़ सकता है जो कई छोटी अनुमति सूचियों से बनी हो. यह ठीक उसी तरह है जैसे कोई package_group अपनी includes एट्रिब्यूट की मदद से दूसरे package_group को शामिल कर सकता है.

मान लें कि आप बड़े पैमाने पर इस्तेमाल किए जाने वाले मैक्रो का इस्तेमाल बंद कर रहे हैं. आपको इसे सिर्फ़ मौजूदा उपयोगकर्ताओं और अपनी टीम के मालिकाना हक वाले पैकेज को दिखाना है. आपके पास यह लिखने का विकल्प है:

# //mylib/macros.bzl

load(":internal_defs.bzl", "our_packages")
load("//some_big_client:defs.bzl", "their_remaining_uses)

# List concatenation. Duplicates are fine.
visibility(our_packages + their_remaining_uses)

पैकेज ग्रुप की डुप्लीकेट कॉपी हटाई जा रही हैं

टारगेट के हिसाब से दिखने की सेटिंग के उलट, लोड किसको दिखे, इसे package_group के तौर पर तय नहीं किया जा सकता. अगर आपको टारगेट के दिखने और लोड के दिखने, दोनों के लिए एक ही अनुमति वाली सूची का फिर से इस्तेमाल करना है, तो पैकेज की खास बातों की सूची को .bzl फ़ाइल में ले जाना सबसे अच्छा है. यहां दोनों तरह के एलान, इस सूची का रेफ़रंस दे सकते हैं. ऊपर दिए गए दिखने वाले आंकड़ों के फ़ैक्टर में दिए गए उदाहरण को ध्यान में रखते हुए, यह लिखा जा सकता है:

# //mylib/BUILD

load(":internal_defs", "clients")

package_group(
    name = "my_pkg_grp",
    packages = clients,
)

यह सिर्फ़ तब काम करता है, जब सूची में पैकेज की कोई नेगेटिव जानकारी शामिल न हो.

अलग-अलग सिंबल को सुरक्षित रखना

किसी भी Starlark सिंबल को किसी दूसरी फ़ाइल से लोड नहीं किया जा सकता, जिसका नाम अंडरस्कोर से शुरू होता है. इससे निजी सिंबल बनाना आसान हो जाता है. हालांकि, इन सिंबल को भरोसेमंद फ़ाइलों के सीमित सेट के साथ शेयर नहीं किया जा सकता. दूसरी ओर, लोड होने पर दिखने की सेटिंग की मदद से यह कंट्रोल किया जा सकता है कि दूसरे पैकेज आपके .bzl file को देख सकते हैं या नहीं. हालांकि, इस सेटिंग की मदद से, अंडरस्कोर के बिना किसी भी सिंबल को लोड होने से नहीं रोका जा सकता.

अच्छी बात यह है कि बेहतर कंट्रोल पाने के लिए, इन दोनों सुविधाओं को एक साथ इस्तेमाल किया जा सकता है.

# //mylib/internal_defs.bzl

# Can't be public, because internal_helper shouldn't be exposed to the world.
visibility("private")

# Can't be underscore-prefixed, because this is
# needed by other .bzl files in mylib.
def internal_helper(...):
    ...

def public_util(...):
    ...

# //mylib/defs.bzl

load(":internal_defs", "internal_helper", _public_util="public_util")
visibility("public")

# internal_helper, as a loaded symbol, is available for use in this file but
# can't be imported by clients who load this file.
...

# Re-export public_util from this file by assigning it to a global variable.
# We needed to import it under a different name ("_public_util") in order for
# this assignment to be legal.
public_util = _public_util

bzl-visibility Buildifier lint

Buildifier lint एक ऐसी सुविधा है जो चेतावनी देती है. यह चेतावनी तब दी जाती है, जब उपयोगकर्ता internal या private नाम की डायरेक्ट्री से कोई फ़ाइल लोड करते हैं और उनकी फ़ाइल उस डायरेक्ट्री के पैरंट डायरेक्ट्री में मौजूद नहीं होती. यह लिंट, फ़ाइल लोड होने पर उसकी स्थिति दिखाने की सुविधा से पहले का है. यह उन वर्कस्पेस में ज़रूरी नहीं है जहां .bzl फ़ाइलों में, फ़ाइल की स्थिति की जानकारी दी गई है.