Bzlmod माइग्रेशन गाइड

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

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

WORKSPACE बनाम Bzlmod

Bazel के WORKSPACE और Bzlmod, अलग-अलग सिंटैक्स के साथ मिलती-जुलती सुविधाएं देते हैं. इस सेक्शन में, WORKSPACE की कुछ सुविधाओं से Bzlmod पर माइग्रेट करने का तरीका बताया गया है.

Bazel वर्कस्पेस का रूट तय करना

WORKSPACE फ़ाइल, Bazel प्रोजेक्ट के सोर्स रूट को मार्क करती है. Bazel के 6.3 और उसके बाद के वर्शन में, इस काम को MODULE.bazel से बदल दिया गया है. Bazel के 6.3 से पहले के वर्शन में, आपके वर्कस्पेस के रूट में अब भी WORKSPACE या WORKSPACE.bazel फ़ाइल होनी चाहिए. इसमें ऐसी टिप्पणियां हो सकती हैं:

• WORKSPACE

  # This file marks the root of the Bazel workspace.
  # See MODULE.bazel for external dependencies setup.
  

अपनी bazelrc में Bzlmod चालू करना

.bazelrc की मदद से, ऐसे फ़्लैग सेट किए जा सकते हैं जो हर बार Bazel को चलाने पर लागू होते हैं. Bzlmod को चालू करने के लिए, --enable_bzlmod फ़्लैग का इस्तेमाल करें और इसे common कमांड पर लागू करें, ताकि यह हर कमांड पर लागू हो:

• .bazelrc

  # Enable Bzlmod for every Bazel command
  common --enable_bzlmod
  

अपने फ़ाइल फ़ोल्डर के लिए रिपॉज़िटरी का नाम डालें

• WORKSPACE

  workspace फ़ंक्शन का इस्तेमाल, अपने फ़ाइल फ़ोल्डर के लिए रिपॉज़िटरी का नाम बताने के लिए किया जाता है. इससे वर्कस्पेस में मौजूद टारगेट //foo:bar को @<workspace name>//foo:bar के तौर पर रेफ़र किया जा सकता है. अगर कोई नाम नहीं दिया जाता है, तो आपके वर्कस्पेस के लिए डिफ़ॉल्ट रिपॉज़िटरी का नाम __main__ होता है.

  ## WORKSPACE
  workspace(name = "com_foo_bar")
  

• Bzlmod

  हमारा सुझाव है कि एक ही फ़ाइल फ़ोल्डर में मौजूद टारगेट का रेफ़रंस, @<repo name> के बिना //foo:bar सिंटैक्स का इस्तेमाल करके दें. हालांकि, अगर आपको पुराने सिंटैक्स की ज़रूरत है, तो module फ़ंक्शन से तय किए गए मॉड्यूल के नाम का इस्तेमाल, रिपॉज़िटरी के नाम के तौर पर किया जा सकता है. अगर मॉड्यूल का नाम, ज़रूरी रिपॉज़िटरी के नाम से अलग है, तो रिपॉज़िटरी के नाम को बदलने के लिए, module फ़ंक्शन के repo_name एट्रिब्यूट का इस्तेमाल किया जा सकता है.

  ## MODULE.bazel
  module(
      name = "bar",
      repo_name = "com_foo_bar",
  )
  

बाहरी डिपेंडेंसी को Bazel मॉड्यूल के तौर पर फ़ेच करना

अगर आपकी डिपेंडेंसी कोई Bazel प्रोजेक्ट है, तो Bzlmod का इस्तेमाल करने पर, आपको उस पर Bazel मॉड्यूल के तौर पर निर्भर रहना चाहिए.

• WORKSPACE

  WORKSPACE में, Bazel प्रोजेक्ट के सोर्स डाउनलोड करने के लिए, आम तौर पर http_archive या git_repository रिपॉज़िटरी नियमों का इस्तेमाल किया जाता है.

  ## WORKSPACE
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
  
  http_archive(
      name = "bazel_skylib",
      urls = ["https://github.com/bazelbuild/bazel-skylib/releases/download/1.4.2/bazel-skylib-1.4.2.tar.gz"],
      sha256 = "66ffd9315665bfaafc96b52278f57c7e2dd09f5ede279ea6d39b2be471e7e3aa",
  )
  load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
  bazel_skylib_workspace()
  
  http_archive(
      name = "rules_java",
      urls = ["https://github.com/bazelbuild/rules_java/releases/download/6.1.1/rules_java-6.1.1.tar.gz"],
      sha256 = "76402a50ae6859d50bd7aed8c1b8ef09dae5c1035bb3ca7d276f7f3ce659818a",
  )
  load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains")
  rules_java_dependencies()
  rules_java_toolchains()
  

  जैसा कि आप देख सकते हैं, यह एक सामान्य पैटर्न है कि उपयोगकर्ताओं को डिपेंडेंसी के मैक्रो से ट्रांज़िशन डिपेंडेंसी लोड करनी होती है. मान लें कि bazel_skylib और rules_java, दोनों platform पर निर्भर करते हैं. platform पर निर्भरता का सटीक वर्शन, मैक्रो के क्रम से तय होता है.

• Bzlmod

  Bzlmod की मदद से, जब तक आपकी डिपेंडेंसी Bazel Central रजिस्ट्री या आपकी कस्टम Bazel रजिस्ट्री में उपलब्ध है, तब तक bazel_dep डायरेक्टिव की मदद से, उस पर आसानी से निर्भर किया जा सकता है.

  ## MODULE.bazel
  bazel_dep(name = "bazel_skylib", version = "1.4.2")
  bazel_dep(name = "rules_java", version = "6.1.1")
  

  Bzlmod, MVS एल्गोरिदम का इस्तेमाल करके, Bazel मॉड्यूल की डिपेंडेंसी को ट्रांज़िशन के तौर पर हल करता है. इसलिए, platform का ज़रूरी वर्शन अपने-आप चुन लिया जाता है.

किसी डिपेंडेंसी को Bazel मॉड्यूल के तौर पर बदलना

रूट मॉड्यूल के तौर पर, Bazel मॉड्यूल की डिपेंडेंसी को अलग-अलग तरीकों से बदला जा सकता है.

ज़्यादा जानकारी के लिए, कृपया ओवरराइड सेक्शन पढ़ें.

इस्तेमाल के कुछ उदाहरण देखने के लिए, उदाहरण रिपॉज़िटरी पर जाएं.

मॉड्यूल एक्सटेंशन की मदद से, बाहरी डिपेंडेंसी फ़ेच करना

अगर आपकी डिपेंडेंसी कोई Bazel प्रोजेक्ट नहीं है या वह अब तक किसी भी Bazel रजिस्ट्री में उपलब्ध नहीं है, तो उसे use_repo_rule या मॉड्यूल एक्सटेंशन का इस्तेमाल करके जोड़ा जा सकता है.

• WORKSPACE

  http_file रिपॉज़िटरी नियम का इस्तेमाल करके, कोई फ़ाइल डाउनलोड करना.

  ## WORKSPACE
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  
  http_file(
      name = "data_file",
      url = "http://example.com/file",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )
  

• Bzlmod

  Bzlmod की मदद से, अपनी MODULE.bazel फ़ाइल में use_repo_rule डायरेक्टिव का इस्तेमाल करके, सीधे तौर पर रिपॉज़िटरी इंस्टैंशिएट किए जा सकते हैं:

  ## MODULE.bazel
  http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  http_file(
      name = "data_file",
      url = "http://example.com/file",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )
  

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

  ## repositories.bzl
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  def my_data_dependency():
      http_file(
          name = "data_file",
          url = "http://example.com/file",
          sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      )
  

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

  ## extensions.bzl
  load("//:repositories.bzl", "my_data_dependency")
  def _non_module_dependencies_impl(_ctx):
      my_data_dependency()
  
  non_module_dependencies = module_extension(
      implementation = _non_module_dependencies_impl,
  )
  

  रिपॉज़िटरी को रूट प्रोजेक्ट में दिखने के लिए, आपको MODULE.bazel फ़ाइल में मॉड्यूल एक्सटेंशन और रिपॉज़िटरी के इस्तेमाल के बारे में बताना होगा.

  ## MODULE.bazel
  non_module_dependencies = use_extension("//:extensions.bzl", "non_module_dependencies")
  use_repo(non_module_dependencies, "data_file")
  

मॉड्यूल एक्सटेंशन की मदद से, बाहरी डिपेंडेंसी से जुड़ी समस्या हल करना

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

मान लें कि प्रोजेक्ट foo में यह मैक्रो दिया गया है, जो version को आर्ग्युमेंट के तौर पर लेता है.

## repositories.bzl in foo {:#repositories.bzl-foo}
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
def data_deps(version = "1.0"):
    http_file(
        name = "data_file",
        url = "http://example.com/file-%s" % version,
        # Omitting the "sha256" attribute for simplicity
    )

• WORKSPACE

  Workspace की मदद से, @foo से मैक्रो लोड किया जा सकता है. साथ ही, अपनी ज़रूरत के हिसाब से डेटा डिपेंडेंसी का वर्शन भी तय किया जा सकता है. मान लें कि आपके पास एक और डिपेंडेंसी @bar है, जो @foo पर भी निर्भर करती है. हालांकि, इसके लिए डेटा डिपेंडेंसी के किसी दूसरे वर्शन की ज़रूरत है.

  ## WORKSPACE
  
  # Introduce @foo and @bar.
  ...
  
  load("@foo//:repositories.bzl", "data_deps")
  data_deps(version = "2.0")
  
  load("@bar//:repositories.bzl", "bar_deps")
  bar_deps() # -> which calls data_deps(version = "3.0")
  

  इस मामले में, असली उपयोगकर्ता को अपनी ज़रूरत के वर्शन को पाने के लिए, Workspace में मैक्रो के क्रम में सावधानी से बदलाव करना होगा. यह Workspace की सबसे बड़ी समस्याओं में से एक है, क्योंकि यह डिपेंडेंसी को ठीक करने का कोई सही तरीका नहीं बताता.

• Bzlmod

  Bzlmod की मदद से, प्रोजेक्ट foo का लेखक, संघर्षों को हल करने के लिए मॉड्यूल एक्सटेंशन का इस्तेमाल कर सकता है. उदाहरण के लिए, मान लें कि सभी Bazel मॉड्यूल में से, डेटा डिपेंडेंसी का ज़्यादा से ज़्यादा ज़रूरी वर्शन हमेशा चुनना सही है.

  ## extensions.bzl in foo
  load("//:repositories.bzl", "data_deps")
  
  data = tag_class(attrs={"version": attr.string()})
  
  def _data_deps_extension_impl(module_ctx):
      # Select the maximal required version in the dependency graph.
      version = "1.0"
      for mod in module_ctx.modules:
          for data in mod.tags.data:
              version = max(version, data.version)
      data_deps(version)
  
  data_deps_extension = module_extension(
      implementation = _data_deps_extension_impl,
      tag_classes = {"data": data},
  )
  

  ## MODULE.bazel in bar
  bazel_dep(name = "foo", version = "1.0")
  
  foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension")
  foo_data_deps.data(version = "3.0")
  use_repo(foo_data_deps, "data_file")
  

  ## MODULE.bazel in root module
  bazel_dep(name = "foo", version = "1.0")
  bazel_dep(name = "bar", version = "1.0")
  
  foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension")
  foo_data_deps.data(version = "2.0")
  use_repo(foo_data_deps, "data_file")
  

  इस मामले में, रूट मॉड्यूल के लिए डेटा वर्शन 2.0 की ज़रूरत है, जबकि उसकी डिपेंडेंसी bar के लिए 3.0 की ज़रूरत है. foo में मौजूद मॉड्यूल एक्सटेंशन, इस विरोध को सही तरीके से हल कर सकता है और डेटा डिपेंडेंसी के लिए, 3.0 वर्शन को अपने-आप चुन सकता है.

तीसरे पक्ष के पैकेज मैनेजर को इंटिग्रेट करना

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

मॉड्यूल एक्सटेंशन इस्तेमाल करने के तरीके के बारे में ज़्यादा जानने के लिए, कृपया मॉड्यूल एक्सटेंशन पेज पढ़ें.

यहां उन नियमों की सूची दी गई है जिन्होंने अलग-अलग पैकेज मैनेजर से डिपेंडेंसी फ़ेच करने के लिए, पहले से ही Bzlmod का इस्तेमाल किया है:

• rules_jvm_external
• rules_go
• rules_python

उदाहरण रिपॉज़िटरी में, एक छोटा सा उदाहरण उपलब्ध है. इसमें, एक स्यूडो पैकेज मैनेजर को इंटिग्रेट किया गया है.

होस्ट मशीन पर टूलचेन का पता लगाना

जब Bazel के बिल्ड नियमों को यह पता लगाना होता है कि आपकी होस्ट मशीन पर कौनसे टूलचेन उपलब्ध हैं, तो वे होस्ट मशीन की जांच करने के लिए, रिपॉज़िटरी नियमों का इस्तेमाल करते हैं. साथ ही, टूलचेन की जानकारी को बाहरी रिपॉज़िटरी के तौर पर जनरेट करते हैं.

• WORKSPACE

  शेल टूलचेन का पता लगाने के लिए, यहां दिया गया रिपॉज़िटरी नियम.

  ## local_config_sh.bzl
  def _sh_config_rule_impl(repository_ctx):
      sh_path = get_sh_path_from_env("SH_BIN_PATH")
  
      if not sh_path:
          sh_path = detect_sh_from_path()
  
      if not sh_path:
          sh_path = "/shell/binary/not/found"
  
      repository_ctx.file("BUILD", """
  load("@bazel_tools//tools/sh:sh_toolchain.bzl", "sh_toolchain")
  sh_toolchain(
      name = "local_sh",
      path = "{sh_path}",
      visibility = ["//visibility:public"],
  )
  toolchain(
      name = "local_sh_toolchain",
      toolchain = ":local_sh",
      toolchain_type = "@bazel_tools//tools/sh:toolchain_type",
  )
  """.format(sh_path = sh_path))
  
  sh_config_rule = repository_rule(
      environ = ["SH_BIN_PATH"],
      local = True,
      implementation = _sh_config_rule_impl,
  )
  

  WORKSPACE में, रिपॉज़िटरी का नियम लोड किया जा सकता है.

  ## WORKSPACE
  load("//:local_config_sh.bzl", "sh_config_rule")
  sh_config_rule(name = "local_config_sh")
  

• Bzlmod

  Bzlmod की मदद से, मॉड्यूल एक्सटेंशन का इस्तेमाल करके उसी रिपॉज़िटरी को जोड़ा जा सकता है. यह पिछले सेक्शन में @data_file रिपॉज़िटरी को जोड़ने जैसा ही है.

  ## local_config_sh_extension.bzl
  load("//:local_config_sh.bzl", "sh_config_rule")
  
  sh_config_extension = module_extension(
      implementation = lambda ctx: sh_config_rule(name = "local_config_sh"),
  )
  

  इसके बाद, MODULE.bazel फ़ाइल में एक्सटेंशन का इस्तेमाल करें.

  ## MODULE.bazel
  sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension")
  use_repo(sh_config_ext, "local_config_sh")
  

टूलचेन और एक्सीक्यूशन प्लैटफ़ॉर्म रजिस्टर करना

आखिरी सेक्शन के बाद, होस्ट की जा रही रिपॉज़िटरी के टूलचैन (उदाहरण के लिए, local_config_sh) के बारे में जानकारी देने के बाद, शायद आपको टूलचैन रजिस्टर करना हो.

• WORKSPACE

  WORKSPACE की मदद से, टूलचेन को इन तरीकों से रजिस्टर किया जा सकता है.

  1. .bzl फ़ाइल में टूलचेन को रजिस्टर किया जा सकता है और मैक्रो को WORKSPACE फ़ाइल में लोड किया जा सकता है.

     ## local_config_sh.bzl
     def sh_configure():
         sh_config_rule(name = "local_config_sh")
         native.register_toolchains("@local_config_sh//:local_sh_toolchain")
     

     ## WORKSPACE
     load("//:local_config_sh.bzl", "sh_configure")
     sh_configure()
     

  2. इसके अलावा, टूलचेन को सीधे WORKSPACE फ़ाइल में रजिस्टर करें.

     ## WORKSPACE
     load("//:local_config_sh.bzl", "sh_config_rule")
     sh_config_rule(name = "local_config_sh")
     register_toolchains("@local_config_sh//:local_sh_toolchain")
     

• Bzlmod

  Bzlmod के साथ, register_toolchains और register_execution_platforms एपीआई सिर्फ़ MODULE.bazel फ़ाइल में उपलब्ध होते हैं. मॉड्यूल एक्सटेंशन में native.register_toolchains को कॉल नहीं किया जा सकता.

  ## MODULE.bazel
  sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension")
  use_repo(sh_config_ext, "local_config_sh")
  register_toolchains("@local_config_sh//:local_sh_toolchain")
  

WORKSPACE और WORKSPACE.bzlmod में रजिस्टर किए गए टूलचेन और एक्सीक्यूशन प्लैटफ़ॉर्म के साथ-साथ, हर Bazel मॉड्यूल की MODULE.bazel फ़ाइल, टूलचेन चुनने के दौरान इस प्राथमिकता के क्रम का पालन करती है (सबसे ज़्यादा से सबसे कम):

1. रूट मॉड्यूल की MODULE.bazel फ़ाइल में रजिस्टर किए गए टूलचेन और एक्सीक्यूशन प्लैटफ़ॉर्म.
2. WORKSPACE या WORKSPACE.bzlmod फ़ाइल में रजिस्टर किए गए टूलचेन और एक्सीक्यूशन प्लैटफ़ॉर्म.
3. ऐसे मॉड्यूल से रजिस्टर किए गए टूलचेन और एक्सीक्यूशन प्लैटफ़ॉर्म जो रूट मॉड्यूल की डिपेंडेंसी (ट्रांज़िटिव) हैं.
4. WORKSPACE.bzlmod का इस्तेमाल न करने पर: WORKSPACE सर्फ़िक्स में रजिस्टर किए गए टूलचेन.

डेटा स्टोर करने की स्थानीय जगहों के बारे में जानकारी

अगर आपको डिबग करने के लिए, डिपेंडेंसी का लोकल वर्शन चाहिए या आपको अपने वर्कस्पेस में किसी डायरेक्ट्री को बाहरी रिपॉज़िटरी के तौर पर शामिल करना है, तो आपको डिपेंडेंसी को लोकल रिपॉज़िटरी के तौर पर जोड़ना पड़ सकता है.

• WORKSPACE

  WORKSPACE में, यह दो नेटिव रिपॉज़िटरी नियमों की मदद से किया जाता है: local_repository और new_local_repository.

  ## WORKSPACE
  local_repository(
      name = "rules_java",
      path = "/Users/bazel_user/workspace/rules_java",
  )
  

• Bzlmod

  Bzlmod की मदद से, किसी मॉड्यूल को किसी लोकल पाथ से बदलने के लिए, local_path_override का इस्तेमाल किया जा सकता है.

  ## MODULE.bazel
  bazel_dep(name = "rules_java")
  local_path_override(
      module_name = "rules_java",
      path = "/Users/bazel_user/workspace/rules_java",
  )
  

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

  मॉड्यूल एक्सटेंशन के साथ लोकल रिपॉज़िटरी भी जोड़ी जा सकती है. हालांकि, मॉड्यूल एक्सटेंशन में native.local_repository को कॉल नहीं किया जा सकता. सभी नेटिव रिपॉज़िटरी नियमों को Starlark में बदलने की कोशिश की जा रही है. इस प्रोसेस की स्थिति जानने के लिए, #18285 देखें. इसके बाद, किसी मॉड्यूल एक्सटेंशन में उससे जुड़े starlark local_repository को कॉल किया जा सकता है. अगर यह समस्या आपके लिए कोई समस्या है, तो local_repository रिपॉज़िटरी नियम का कस्टम वर्शन लागू करना भी आसान है.

टारगेट बांधना

WORKSPACE में bind नियम अब काम नहीं करता और Bzlmod में काम नहीं करता. इसे खास //external पैकेज में, टारगेट को कोई दूसरा नाम देने के लिए लॉन्च किया गया था. इस पर निर्भर सभी उपयोगकर्ताओं को माइग्रेट कर देना चाहिए.

उदाहरण के लिए, अगर आपके चैनल पर इतने सदस्य हैं

## WORKSPACE
bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

इससे दूसरे टारगेट, //external:openssl पर निर्भर हो सकते हैं. इसे हटाने के लिए, यह तरीका अपनाएं:

• //external:openssl के सभी इस्तेमाल को @my-ssl//src:openssl-lib से बदलें.

• इसके अलावा, alias बिल्ड नियम का इस्तेमाल करें

  • पैकेज में यह टारगेट तय करें (उदाहरण के लिए, //third_party)

    ## third_party/BUILD
    alias(
        name = "openssl,
        actual = "@my-ssl//src:openssl-lib",
    )
    

  • //external:openssl के सभी इस्तेमाल को //third_party:openssl-lib से बदलें.

माइग्रेशन

इस सेक्शन में, Bzlmod माइग्रेशन प्रोसेस के बारे में ज़रूरी जानकारी और दिशा-निर्देश दिए गए हैं.

Workspace में डिपेंडेंसी के बारे में जानकारी

माइग्रेशन का पहला चरण यह समझना है कि आपके पास कौनसी डिपेंडेंसी हैं. यह पता लगाना मुश्किल हो सकता है कि WORKSPACE फ़ाइल में कौनसी डिपेंडेंसी शामिल की गई हैं, क्योंकि ट्रांज़िटिव डिपेंडेंसी अक्सर *_deps मैक्रो के साथ लोड की जाती हैं.

Workspace में मौजूद, हल की गई फ़ाइल की मदद से बाहरी डिपेंडेंसी की जांच करना

फ़्लैग --experimental_repository_resolved_file से मदद मिल सकती है. यह फ़्लैग, आपके पिछले Bazel निर्देश में फ़ेच की गई सभी बाहरी डिपेंडेंसी की "लॉक फ़ाइल" जनरेट करता है. ज़्यादा जानकारी के लिए, यह ब्लॉग पोस्ट पढ़ें.

इसका इस्तेमाल दो तरीकों से किया जा सकता है:

1. कुछ टारगेट बनाने के लिए ज़रूरी बाहरी डिपेंडेंसी की जानकारी फ़ेच करने के लिए.

   bazel clean --expunge
   bazel build --nobuild --experimental_repository_resolved_file=resolved.bzl //foo:bar
   

2. WORKSPACE फ़ाइल में तय की गई सभी बाहरी डिपेंडेंसी की जानकारी फ़ेच करने के लिए.

   bazel clean --expunge
   bazel sync --experimental_repository_resolved_file=resolved.bzl
   

   bazel sync कमांड की मदद से, WORKSPACE फ़ाइल में बताई गई सभी डिपेंडेंसी फ़ेच की जा सकती हैं. इनमें ये शामिल हैं:

   • bind इस्तेमाल
   • register_toolchains और register_execution_platforms के इस्तेमाल

   हालांकि, अगर आपका प्रोजेक्ट अलग-अलग प्लैटफ़ॉर्म पर काम करता है, तो हो सकता है कि कुछ प्लैटफ़ॉर्म पर bazel सिंक न हो. ऐसा इसलिए, क्योंकि कुछ रिपॉज़िटरी नियम सिर्फ़ उन प्लैटफ़ॉर्म पर सही तरीके से काम कर सकते हैं जिन पर ये काम करते हैं.

कमांड चलाने के बाद, आपको resolved.bzl फ़ाइल में अपनी बाहरी डिपेंडेंसी की जानकारी मिल जाएगी.

bazel query की मदद से, बाहरी डिपेंडेंसी की जांच करना

आपको यह भी पता हो सकता है कि bazel query का इस्तेमाल,

bazel query --output=build //external:<repo name>

यह ज़्यादा सुविधाजनक और तेज़ है, लेकिन bazel क्वेरी, बाहरी डिपेंडेंसी के वर्शन के बारे में गलत जानकारी दे सकती है. इसलिए, इसका इस्तेमाल सावधानी से करें! Bzlmod की मदद से, बाहरी डिपेंडेंसी के बारे में क्वेरी करने और उनकी जांच करने के लिए, नया सब-कमांड जोड़ा गया है.

पहले से मौजूद डिफ़ॉल्ट डिपेंडेंसी

--experimental_repository_resolved_file से जनरेट की गई फ़ाइल की जांच करने पर, आपको कई ऐसी डिपेंडेंसी मिलेंगी जो आपके WORKSPACE में तय नहीं की गई हैं. ऐसा इसलिए होता है, क्योंकि Bazel, उपयोगकर्ता की WORKSPACE फ़ाइल के कॉन्टेंट में प्रीफ़िक्स और सफ़िक्स जोड़ता है. ऐसा कुछ डिफ़ॉल्ट डिपेंडेंसी इंजेक्ट करने के लिए किया जाता है. आम तौर पर, इन डिफ़ॉल्ट डिपेंडेंसी की ज़रूरत, नेटिव नियमों (जैसे, @bazel_tools, @platforms, और @remote_java_tools) के मुताबिक होती है. Bzlmod की मदद से, उन डिपेंडेंसी को पहले से मौजूद मॉड्यूल bazel_tools के साथ जोड़ा जाता है. यह हर दूसरे Bazel मॉड्यूल के लिए डिफ़ॉल्ट डिपेंडेंसी होती है.

धीरे-धीरे माइग्रेट करने के लिए हाइब्रिड मोड

Bzlmod और WORKSPACE एक साथ काम कर सकते हैं. इससे, WORKSPACE फ़ाइल से Bzlmod में डिपेंडेंसी को माइग्रेट करने की प्रोसेस धीरे-धीरे की जा सकती है.

WORKSPACE.bzlmod

माइग्रेशन के दौरान, Bazel के उपयोगकर्ताओं को Bzlmod के चालू और बंद होने के आधार पर, बिल्ड के बीच स्विच करना पड़ सकता है. प्रोसेस को आसान बनाने के लिए, WORKSPACE.bzlmod का इस्तेमाल किया गया है.

WORKSPACE.bzlmod का सिंटैक्स, WORKSPACE जैसा ही होता है. Bzlmod चालू होने पर, अगर फ़ाइल फ़ोल्डर के रूट में WORKSPACE.bzlmod फ़ाइल भी मौजूद है, तो:

• WORKSPACE.bzlmod लागू हो जाता है और WORKSPACE के कॉन्टेंट को अनदेखा कर दिया जाता है.
• WORKSPACE.bzlmod फ़ाइल में कोई प्रीफ़िक्स या सफ़िक्स नहीं जोड़ा जाता.

WORKSPACE.bzlmod फ़ाइल का इस्तेमाल करके, माइग्रेशन को आसान बनाया जा सकता है, क्योंकि:

• Bzlmod बंद होने पर, आपको मूल WORKSPACE फ़ाइल से डिपेंडेंसी फ़ेच करनी पड़ती है.
• Bzlmod चालू होने पर, यह बेहतर तरीके से ट्रैक किया जा सकता है कि WORKSPACE.bzlmod की मदद से, किन डिपेंडेंसी को माइग्रेट करना बाकी है.

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

रिपॉज़िटरी किसको दिखे

Bzlmod यह कंट्रोल कर सकता है कि किसी रिपॉज़िटरी से कौनसी अन्य रिपॉज़िटरी दिखें. ज़्यादा जानकारी के लिए, रिपॉज़िटरी के नाम और सख्त डिपेंडेंसी देखें.

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

	मुख्य रिपॉज़िटरी से	Bazel मॉड्यूल के रिपॉज़िटरी से	मॉड्यूल एक्सटेंशन के रिपॉज़िटरी से	WORKSPACE के डेटा स्टोर करने की जगहों से
मुख्य रिपॉज़िटरी	दिख रहा है	अगर रूट मॉड्यूल, डायरेक्ट डिपेंडेंसी है	अगर रूट मॉड्यूल, मॉड्यूल एक्सटेंशन को होस्ट करने वाले मॉड्यूल पर सीधे तौर पर निर्भर है	दिख रहा है
Bazel मॉड्यूल के रिपॉज़िटरी	डायरेक्ट डिपेंडेंसी	डायरेक्ट डिपेंडेंसी	मॉड्यूल एक्सटेंशन को होस्ट करने वाले मॉड्यूल के डायरेक्ट डिपेंडेंसी	रूट मॉड्यूल के डायरेक्ट डिपेंडेंसी
मॉड्यूल एक्सटेंशन का डेटा स्टोर	डायरेक्ट डिपेंडेंसी	डायरेक्ट डिपेंडेंसी	मॉड्यूल एक्सटेंशन को होस्ट करने वाले मॉड्यूल के डायरेक्ट डिपेंडेंसी + उसी मॉड्यूल एक्सटेंशन से जनरेट किए गए सभी रिपॉज़िटरी	रूट मॉड्यूल के डायरेक्ट डिपेंडेंसी
Workspace के डेटा स्टोर	सभी दिख रहे हैं	नहीं दिख रहा है	नहीं दिख रहा है	सभी दिख रहे हैं

ध्यान दें: रूट मॉड्यूल के लिए, अगर WORKSPACE में कोई रिसॉर्स @foo तय किया गया है और @foo का इस्तेमाल MODULE.bazel में रिसॉर्स के सही नाम के तौर पर भी किया गया है, तो @foo का मतलब MODULE.bazel में बताए गए रिसॉर्स से है.

ध्यान दें: मॉड्यूल एक्सटेंशन से जनरेट किए गए रिसॉर्स @bar के लिए, अगर @foo का इस्तेमाल उसी मॉड्यूल एक्सटेंशन और मॉड्यूल एक्सटेंशन को होस्ट करने वाले मॉड्यूल की डायरेक्ट डिपेंडेंसी से जनरेट किए गए किसी दूसरे रिसॉर्स के सही नाम के तौर पर किया जाता है, तो रिसॉर्स @bar के लिए, @foo का मतलब बाद वाले रिसॉर्स से है.

माइग्रेट करने का तरीका

Bzlmod माइग्रेशन की सामान्य प्रोसेस कुछ ऐसी हो सकती है:

1. जानें कि आपके पास Workspace में कौनसी डिपेंडेंसी हैं.
2. अपने प्रोजेक्ट के रूट में, खाली MODULE.bazel फ़ाइल जोड़ें.
3. WORKSPACE फ़ाइल के कॉन्टेंट को बदलने के लिए, खाली WORKSPACE.bzlmod फ़ाइल जोड़ें.
4. Bzlmod चालू करके अपने टारगेट बनाएं और देखें कि कौनसा रिपॉज़िटरी मौजूद नहीं है.
5. रिपॉज़िटरी की समस्या हल करने वाली फ़ाइल में, मौजूद न होने वाली रिपॉज़िटरी की परिभाषा देखें.
6. मॉड्यूल एक्सटेंशन की मदद से, मौजूद नहीं होने वाली डिपेंडेंसी को Bazel मॉड्यूल के तौर पर जोड़ें या बाद में माइग्रेट करने के लिए, इसे WORKSPACE.bzlmod में छोड़ दें.
7. चौथे चरण पर वापस जाएं और सभी डिपेंडेंसी उपलब्ध होने तक यह तरीका दोहराएं.

डेटा दूसरी जगह भेजने वाला टूल (माइग्रेशन टूल)

Bzlmod माइग्रेशन की एक इंटरैक्टिव हेल्पर स्क्रिप्ट है, जिससे आपको माइग्रेशन की प्रोसेस शुरू करने में मदद मिल सकती है.

स्क्रिप्ट ये काम करती है:

• WORKSPACE की रिज़ॉल्व की गई फ़ाइल जनरेट और पार्स करें.
• ठीक की गई फ़ाइल से, रिपॉज़िटरी की जानकारी को ऐसे प्रिंट करें जिसे कोई भी व्यक्ति आसानी से पढ़ सके.
• bazel build कमांड चलाएं, गड़बड़ी के पहचाने गए मैसेज का पता लगाएं, और माइग्रेट करने का तरीका सुझाएं.
• देखें कि BCR में कोई डिपेंडेंसी पहले से मौजूद है या नहीं.
• MODULE.bazel फ़ाइल में कोई डिपेंडेंसी जोड़ें.
• मॉड्यूल एक्सटेंशन की मदद से, डिपेंडेंसी जोड़ें.
• WORKSPACE.bzlmod फ़ाइल में कोई डिपेंडेंसी जोड़ें.

इसका इस्तेमाल करने के लिए, पक्का करें कि आपने Bazel का नया वर्शन इंस्टॉल किया हो. इसके बाद, यह कमांड चलाएं:

git clone https://github.com/bazelbuild/bazel-central-registry.git
cd <your workspace root>
<BCR repo root>/tools/migrate_to_bzlmod.py -t <your build targets>

ध्यान दें: माइग्रेशन स्क्रिप्ट पूरी तरह से सही नहीं है और हो सकता है कि वह अप-टू-डेट न हो, क्योंकि Bzlmod का लगातार विकास हो रहा है. इसलिए, हमेशा दोबारा जांच लें कि सुझाया गया समाधान सही है या नहीं.

Bazel मॉड्यूल पब्लिश करना

अगर आपका Bazel प्रोजेक्ट, दूसरे प्रोजेक्ट के लिए डिपेंडेंसी है, तो अपने प्रोजेक्ट को Bazel Central Registry में पब्लिश किया जा सकता है.

बीसीआर में अपने प्रोजेक्ट को चेक इन करने के लिए, आपके पास प्रोजेक्ट के सोर्स संग्रह का यूआरएल होना चाहिए. सोर्स संग्रह बनाते समय इन बातों का ध्यान रखें:

• पक्का करें कि संग्रह किसी खास वर्शन पर ले जाता हो.

  BCR सिर्फ़ वर्शन वाले सोर्स संग्रह स्वीकार कर सकता है, क्योंकि Bzlmod को डिपेंडेंसी रिज़ॉल्यूशन के दौरान वर्शन की तुलना करनी होती है.

• पक्का करें कि संग्रह का यूआरएल स्टेबल हो.

  Bazel, हैश वैल्यू की मदद से संग्रह के कॉन्टेंट की पुष्टि करता है. इसलिए, आपको यह पक्का करना चाहिए कि डाउनलोड की गई फ़ाइल का चेकसम कभी न बदले. अगर यूआरएल, GitHub से है, तो कृपया रिलीज़ पेज पर रिलीज़ का संग्रह बनाएं और अपलोड करें. GitHub, मांग पर जनरेट किए गए सोर्स संग्रह के चेकसम की गारंटी नहीं देगा. कम शब्दों में कहें, तो https://github.com/<org>/<repo>/releases/download/... वाले यूआरएल को स्थिर माना जाता है, जबकि https://github.com/<org>/<repo>/archive/... वाले यूआरएल को नहीं. ज़्यादा जानकारी के लिए, GitHub के संग्रह के लिए चेकसम की सुविधा के काम न करने के बारे में पढ़ें.

• पक्का करें कि सोर्स ट्री, ओरिजनल रिपॉज़िटरी के लेआउट के मुताबिक हो.

  अगर आपका रिपॉज़िटरी बहुत बड़ा है और आपको ज़रूरत के मुताबिक सोर्स हटाकर, कम साइज़ वाला डिस्ट्रिब्यूशन संग्रह बनाना है, तो कृपया पक्का करें कि हटाया गया सोर्स ट्री, ओरिजनल सोर्स ट्री का सबसेट हो. इससे असली उपयोगकर्ताओं के लिए, archive_override और git_override की मदद से मॉड्यूल को रिलीज़ नहीं किए गए वर्शन पर बदलना आसान हो जाता है.

• सब-डायरेक्ट्री में एक टेस्ट मॉड्यूल शामिल करें, जो आपके सबसे सामान्य एपीआई की जांच करता हो.

  टेस्ट मॉड्यूल, एक ऐसा Bazel प्रोजेक्ट होता है जिसमें अपना WORKSPACE और MODULE.bazel फ़ाइल होती है. यह फ़ाइल, सोर्स संग्रह की सबडायरेक्ट्री में होती है. यह फ़ाइल, पब्लिश किए जाने वाले असल मॉड्यूल पर निर्भर करती है. इसमें ऐसे उदाहरण या इंटिग्रेशन टेस्ट शामिल होने चाहिए जिनमें आपके सबसे सामान्य एपीआई शामिल हों. इसे सेट अप करने का तरीका जानने के लिए, टेस्ट मॉड्यूल देखें.

सोर्स का संग्रह करने के बाद, उसका यूआरएल तैयार हो जाएगा. इसके बाद, GitHub के पुल रिक्वेस्ट की मदद से, BCR में अपना मॉड्यूल सबमिट करने के लिए, बीसीआर में योगदान देने के दिशा-निर्देशों का पालन करें.

हमारा सुझाव है कि आप अपने डेटा स्टोर करने की जगह के लिए, बीसीआर पर पब्लिश करें GitHub ऐप्लिकेशन सेट अप करें. इससे, बीसीआर में मॉड्यूल सबमिट करने की प्रोसेस अपने-आप हो जाएगी.

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

इस सेक्शन में, बाहरी डिपेंडेंसी को बेहतर तरीके से मैनेज करने के लिए, कुछ सबसे सही तरीके बताए गए हैं.

ग़ैर-ज़रूरी डिपेंडेंसी फ़ेच करने से बचने के लिए, टारगेट को अलग-अलग पैकेज में बांटें.

#12835 देखें. इसमें, टेस्ट के लिए डेवलपर डिपेंडेंसी को ज़रूरत न होने पर भी फ़ेच किया जाता है. ऐसा उन टारगेट को बनाने के लिए किया जाता है जिनमें इन डिपेंडेंसी की ज़रूरत नहीं होती. यह असल में Bzlmod के लिए नहीं है, लेकिन इन तरीकों का पालन करने से, डेवलपर डिपेंडेंसी को सही तरीके से बताना आसान हो जाता है.

डेवलपर डिपेंडेंसी की जानकारी देना

bazel_dep और use_extension डायरेक्टिव के लिए, dev_dependency एट्रिब्यूट को 'सही है' पर सेट किया जा सकता है, ताकि वे डिपेंडेंट प्रोजेक्ट में लागू न हों. रूट मॉड्यूल के तौर पर, --ignore_dev_dependency फ़्लैग का इस्तेमाल करके पुष्टि की जा सकती है कि आपके टारगेट अब भी डेवलपर डिपेंडेंसी के बिना बन रहे हैं या नहीं.

कम्यूनिटी का डेटा माइग्रेट करने की प्रोग्रेस

Bazel Central Registry पर जाकर, यह पता लगाया जा सकता है कि आपकी डिपेंडेंसी पहले से उपलब्ध हैं या नहीं. इसके अलावा, अगर आपको उन डिपेंडेंसी के बारे में बताना है जो माइग्रेशन को रोक रही हैं, तो GitHub पर इस चर्चा में हिस्सा लें. साथ ही, उन डिपेंडेंसी को अपवोट करें.

समस्याओं की शिकायत करना

Bzlmod से जुड़ी समस्याओं के बारे में जानने के लिए, कृपया Bazel की GitHub समस्याओं की सूची देखें. नई समस्याएं दर्ज करें या ऐसी सुविधाओं का अनुरोध करें जिनसे माइग्रेशन की प्रक्रिया में आ रही रुकावटों को दूर करने में मदद मिल सके!