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

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

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

WORKSPACE बनाम Bzlmod

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

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

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

  • वर्कस्पेस

    # 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 मॉड्यूल के तौर पर फ़ेच करना

अगर आपकी डिपेंडेंसी Basel प्रोजेक्ट है, तो इस प्रोजेक्ट पर Bzlmod का इस्तेमाल करते समय, इस पर बैजेल मॉड्यूल के तौर पर भरोसा किया जा सकता है.

  • वर्कस्पेस

    Workspace का इस्तेमाल करते समय, बैज प्रोजेक्ट के सोर्स डाउनलोड करने के लिए, 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 एल्गोरिदम का इस्तेमाल करके, बेज़ल मॉड्यूल डिपेंडेंसी को एक जगह पर रिज़ॉल्व करता है. इसलिए, 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 में मैक्रो के क्रम में सावधानी से बदलाव करना होगा. यह वर्कस्पेस के साथ होने वाली सबसे बड़ी समस्याओं में से एक है. इसकी वजह यह है कि यह डिपेंडेंसी से जुड़ी समस्या को हल करने का सही तरीका नहीं है.

  • 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 का पहले से इस्तेमाल कर रहे हैं:

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

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

जब 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 फ़ाइल में रजिस्टर करने और मैक्रो को वर्कस्पेस फ़ाइल में लोड करने का विकल्प है.

      ## 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",
    )
    

    मॉड्यूल एक्सटेंशन के साथ लोकल रिपॉज़िटरी भी जोड़ी जा सकती है. हालांकि, मॉड्यूल एक्सटेंशन में 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. वर्कस्पेस फ़ाइल में तय की गई सभी बाहरी डिपेंडेंसी की जानकारी फ़ेच करने के लिए.

    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 से जनरेट की गई फ़ाइल की जांच की जाती है, तो आपको ऐसी कई डिपेंडेंसी मिलेंगी जो आपके वर्कस्पेस में तय नहीं की गई हैं. ऐसा इसलिए है, क्योंकि Basel ने असल में कुछ डिफ़ॉल्ट डिपेंडेंसी को इंजेक्ट करने के लिए, उपयोगकर्ता की Workspace फ़ाइल के कॉन्टेंट में प्रीफ़िक्स और सफ़िक्स जोड़े हैं, जो आम तौर पर नेटिव नियमों (जैसे, @bazel_tools, @platforms, और @remote_java_tools) के लिए ज़रूरी होती हैं. Bzlmod की मदद से, ये डिपेंडेंसी बिल्ट-इन मॉड्यूल bazel_tools के साथ शुरू होती हैं, जो हर दूसरे बैजल मॉड्यूल के लिए डिफ़ॉल्ट डिपेंडेंसी होती है.

माइग्रेशन के लिए हाइब्रिड मोड

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 की मदद से, किन डिपेंडेंसी को माइग्रेट करना बाकी है.

डेटा स्टोर करने की जगह की जानकारी देखने की सुविधा

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

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

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

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

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

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

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

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

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

  • WORKSPACE की रिज़ॉल्व की गई फ़ाइल जनरेट और पार्स करें.
  • ठीक की गई फ़ाइल से, रिपॉज़िटरी की जानकारी को ऐसे प्रिंट करें जिसे कोई भी व्यक्ति आसानी से पढ़ सके.
  • bazel build कमांड चलाएं, गड़बड़ी के पहचाने गए मैसेज का पता लगाएं, और माइग्रेट करने का तरीका सुझाएं.
  • देखें कि बीसीआर में पहले से कोई डिपेंडेंसी उपलब्ध है या नहीं.
  • 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>

Baज़र के मॉड्यूल पब्लिश करें

अगर आपका Basel प्रोजेक्ट अन्य प्रोजेक्ट पर निर्भर है, तो आपके पास अपने प्रोजेक्ट को Baaz 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 समस्याओं के लिए, कृपया Bazu GitHub की समस्या की सूची देखें. नई समस्याएं दर्ज करें या ऐसी सुविधाओं का अनुरोध करें जिनसे माइग्रेशन की प्रक्रिया में आ रही रुकावटों को दूर करने में मदद मिल सके!