मॉड्यूल एक्सटेंशन

किसी समस्या की शिकायत करें सोर्स देखें Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

मॉड्यूल एक्सटेंशन की मदद से उपयोगकर्ता, डिपेंडेंसी ग्राफ़ में मॉड्यूल से इनपुट डेटा को पढ़कर, डिपेंडेंसी हल करने के लिए ज़रूरी लॉजिक परफ़ॉर्म करके, और रेपो नियमों को कॉल करके रेपो बनाते हुए, मॉड्यूल सिस्टम को बढ़ा सकते हैं. इन एक्सटेंशन में रेपो नियमों से मिलती-जुलती सुविधाएं होती हैं. इनसे उन्हें फ़ाइल I/O चलाने, नेटवर्क के अनुरोध भेजने वगैरह में मदद मिलती है. दूसरी बातों के साथ-साथ, वे Basel मॉड्यूल से बनाए गए डिपेंडेंसी ग्राफ़ का भी ध्यान रखते हुए दूसरे पैकेज मैनेजमेंट सिस्टम के साथ इंटरैक्ट करने में मदद करते हैं.

रेपो नियमों की तरह ही, .bzl फ़ाइलों में मॉड्यूल एक्सटेंशन तय किए जा सकते हैं. इन्हें सीधे तौर पर शुरू नहीं किया जाता. इसके बजाय, हर मॉड्यूल में एक्सटेंशन के लिए पढ़ने के लिए, टैग नाम के डेटा के हिस्से होते हैं. किसी भी एक्सटेंशन का आकलन करने से पहले, Basel मॉड्यूल रिज़ॉल्यूशन को रन करता है. एक्सटेंशन, इससे जुड़े सभी टैग को पूरे डिपेंडेंसी ग्राफ़ में पढ़ता है.

एक्सटेंशन का इस्तेमाल

एक्सटेंशन, Basel मॉड्यूल में खुद होस्ट किए जाते हैं. किसी मॉड्यूल में एक्सटेंशन का इस्तेमाल करने के लिए, सबसे पहले उस मॉड्यूल में bazel_dep जोड़ें जिसमें एक्सटेंशन होस्ट किया जा रहा है. इसके बाद, उसे स्कोप में लाने के लिए, पहले से मौजूद use_extension फ़ंक्शन को कॉल करें. इस उदाहरण पर विचार करें — rules_jvm_external मॉड्यूल में तय किए गए "मेवेन" एक्सटेंशन का इस्तेमाल करने के लिए, MODULE.bazel फ़ाइल से एक स्निपेट:

bazel_dep(name = "rules_jvm_external", version = "4.5")
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")

यह use_extension की रिटर्न वैल्यू को किसी वैरिएबल से बाइंड करता है. इससे उपयोगकर्ता, एक्सटेंशन के लिए टैग तय करने के लिए डॉट-सिंटैक्स का इस्तेमाल कर सकता है. टैग, एक्सटेंशन डेफ़िनिशन में मौजूद टैग क्लास के तय किए गए स्कीमा का पालन करते हैं. कुछ maven.install और maven.artifact टैग के उदाहरण के लिए:

maven.install(artifacts = ["org.junit:junit:4.13.2"])
maven.artifact(group = "com.google.guava",
               artifact = "guava",
               version = "27.0-jre",
               exclusions = ["com.google.j2objc:j2objc-annotations"])

एक्सटेंशन से जनरेट किए गए रिपॉज़िटरी को मौजूदा मॉड्यूल के दायरे में लाने के लिए, use_repo डायरेक्टिव का इस्तेमाल करें.

use_repo(maven, "maven")

किसी एक्सटेंशन के ज़रिए जनरेट किए गए डेटा स्टोर करने की जगह, इसके एपीआई का हिस्सा होती है. इस उदाहरण में, "मेवन" मॉड्यूल एक्सटेंशन, maven नाम का एक रेपो जनरेट करने का वादा करता है. ऊपर दिए गए एलान के साथ, एक्सटेंशन @maven//:org_junit_junit जैसे लेबल को ठीक से हल करता है, ताकि "maven" एक्सटेंशन से जनरेट किए गए repo पर ले जाया जा सके.

एक्सटेंशन की परिभाषा

module_extension फ़ंक्शन का इस्तेमाल करके, रेपो नियमों की तरह ही मॉड्यूल एक्सटेंशन तय किए जा सकते हैं. हालांकि, रेपो नियमों में कई एट्रिब्यूट होते हैं, लेकिन मॉड्यूल एक्सटेंशन में tag_class होते हैं. हर एक एट्रिब्यूट में कई एट्रिब्यूट होते हैं. टैग क्लास, इस एक्सटेंशन में इस्तेमाल किए जाने वाले टैग के लिए स्कीमा तय करती हैं. उदाहरण के लिए, ऊपर दिया गया "मैवेन" एक्सटेंशन इस तरह से परिभाषित किया जा सकता है:

# @rules_jvm_external//:extensions.bzl

_install = tag_class(attrs = {"artifacts": attr.string_list(), ...})
_artifact = tag_class(attrs = {"group": attr.string(), "artifact": attr.string(), ...})
maven = module_extension(
  implementation = _maven_impl,
  tag_classes = {"install": _install, "artifact": _artifact},
)

इन एलान से पता चलता है कि एट्रिब्यूट के लिए तय किए गए स्कीमा का इस्तेमाल करके, maven.install और maven.artifact टैग की जानकारी दी जा सकती है.

मॉड्यूल एक्सटेंशन को लागू करने का फ़ंक्शन, रेपो नियमों की तरह ही होता है. हालांकि, इसमें सिर्फ़ module_ctx ऑब्जेक्ट मिलता है, जो एक्सटेंशन और सभी ज़रूरी टैग का इस्तेमाल करने वाले सभी मॉड्यूल को ऐक्सेस करने की अनुमति देता है. इसके बाद, लागू करने वाला फ़ंक्शन, रिपॉज़िटरी जनरेट करने के लिए रिपॉज़िटरी के नियमों को कॉल करता है.

# @rules_jvm_external//:extensions.bzl

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")  # a repo rule
def _maven_impl(ctx):
  # This is a fake implementation for demonstration purposes only

  # collect artifacts from across the dependency graph
  artifacts = []
  for mod in ctx.modules:
    for install in mod.tags.install:
      artifacts += install.artifacts
    artifacts += [_to_artifact(artifact) for artifact in mod.tags.artifact]

  # call out to the coursier CLI tool to resolve dependencies
  output = ctx.execute(["coursier", "resolve", artifacts])
  repo_attrs = _process_coursier_output(output)

  # call repo rules to generate repos
  for attrs in repo_attrs:
    http_file(**attrs)
  _generate_hub_repo(name = "maven", repo_attrs)

एक्सटेंशन आइडेंटिटी

मॉड्यूल एक्सटेंशन की पहचान, use_extension को किए गए कॉल में मौजूद नाम और .bzl फ़ाइल से की जाती है. यहां दिए गए उदाहरण में, एक्सटेंशन maven की पहचान .bzl फ़ाइल @rules_jvm_external//:extension.bzl और नाम maven से की गई है:

maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")

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

एक्सटेंशन के लेखक के तौर पर, आपको यह पक्का करना चाहिए कि उपयोगकर्ता सिर्फ़ एक .bzl फ़ाइल से आपके मॉड्यूल एक्सटेंशन का इस्तेमाल करें.

रिपॉज़िटरी के नाम और उन्हें दिखने की सेटिंग

एक्सटेंशन के ज़रिए जनरेट किए गए डेटा संग्रह में module_repo_canonical_name~extension_name~repo_name के तौर पर कैननिकल नाम होते हैं. रूट मॉड्यूल में होस्ट किए गए एक्सटेंशन के लिए, module_repo_canonical_name वाले हिस्से को स्ट्रिंग _main से बदल दिया जाता है. ध्यान दें कि कैननिकल नाम का फ़ॉर्मैट वह एपीआई नहीं है जिस पर आपको निर्भर रहना चाहिए. इसमें किसी भी समय बदलाव हो सकता है.

नाम रखने की इस नीति का मतलब है कि हर एक्सटेंशन का अपना "रिपो नेमस्पेस" होता है. दो अलग-अलग एक्सटेंशन, एक ही नाम वाले रिपो को तय कर सकते हैं. इसका यह भी मतलब है कि repository_ctx.name, रिपॉज़िटरी का कैननिकल नाम दिखाता है. यह नाम, रिपॉज़िटरी के नियम के कॉल में बताए गए नाम से अलग होता है.

मॉड्यूल एक्सटेंशन से जनरेट किए गए रिपो को ध्यान में रखते हुए, रेपो को देखने के कई नियम हैं:

  • बेज़ल मॉड्यूल रेपो, bazel_dep और use_repo के ज़रिए, अपनी MODULE.bazel फ़ाइल में उपलब्ध सभी रेपो देख सकता है.
  • मॉड्यूल एक्सटेंशन से जनरेट किए गए किसी रिपॉज़िटरी में, एक्सटेंशन को होस्ट करने वाले मॉड्यूल के सभी रिपॉज़िटरी दिख सकते हैं. साथ ही, उसी मॉड्यूल एक्सटेंशन से जनरेट किए गए सभी अन्य रिपॉज़िटरी भी दिख सकते हैं. इसके लिए, रिपॉज़िटरी के नियमों के कॉल में बताए गए नामों का इस्तेमाल उनके सही नामों के तौर पर किया जाता है.
    • इसकी वजह से विवाद हो सकता है. अगर मॉड्यूल का रिपॉज़िटरी, foo नाम वाले रिपॉज़िटरी को देख सकता है और एक्सटेंशन, foo नाम वाले रिपॉज़िटरी को जनरेट करता है, तो उस एक्सटेंशन से जनरेट किए गए सभी रिपॉज़िटरी के लिए, foo का मतलब पहले वाले रिपॉज़िटरी से होगा.

सबसे सही तरीके

इस सेक्शन में एक्सटेंशन लिखने के सबसे सही तरीकों के बारे में बताया गया है, ताकि उन्हें इस्तेमाल करना, मैनेज करना आसान हो, और वे समय के साथ होने वाले बदलावों के हिसाब से खुद को ढाल सकें.

हर एक्सटेंशन को एक अलग फ़ाइल में डालें

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