Bzlmod Taşıma Kılavuzu

Sorun bildir Kaynağı görüntüle Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Bzlmod, WORKSPACE'in eksiklikleri nedeniyle eski WORKSPACE sisteminin yerini alıyor. WORKSPACE dosyası Bazel 8'de (2024'ün sonlarında) devre dışı bırakıldı ve Bazel 9'da (2025'in sonlarında) kaldırılacak. Bu kılavuz, projenizi Bzlmod'a taşımanıza ve harici bağımlılıkları yönetmek için WORKSPACE'i bırakmanıza yardımcı olur.

Neden Bzlmod'a geçmelisiniz?

  • Eski WORKSPACE sistemine kıyasla birçok avantajı vardır. Bu avantajlar, Bazel ekosisteminin sağlıklı büyümesini sağlar.

  • Projeniz diğer projelerin bağımlılığıysa Bzlmod'a geçiş, bu projelerin geçişini engellemeyi kaldırır ve projenize bağımlı olmalarını kolaylaştırır.

  • Gelecekteki Bazel sürümlerini kullanmak için Bzlmod'a geçiş yapılması gerekir (Bazel 9'da zorunludur).

WORKSPACE ve Bzlmod karşılaştırması

Bazel'in WORKSPACE ve Bzlmod'u, farklı söz dizimleriyle benzer özellikler sunar. Bu bölümde, belirli WORKSPACE işlevlerinden Bzlmod'a nasıl geçiş yapılacağı açıklanmaktadır.

Bazel çalışma alanının kökünü tanımlama

WORKSPACE dosyası, Bazel projesinin kaynak kökünü işaretler. Bu sorumluluk, Bazel 6.3 ve sonraki sürümlerde MODULE.bazel ile değiştirilir. 6.3'ten önceki Bazel sürümlerinde, çalışma alanınızın kök dizininde WORKSPACE veya WORKSPACE.bazel dosyası bulunmalıdır. Bu dosyada aşağıdaki gibi yorumlar olabilir:

  • WORKSPACE

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

bazelrc dosyanızda Bzlmod'u etkinleştirin.

.bazelrc, Bazel'i her çalıştırdığınızda geçerli olacak işaretler ayarlamanıza olanak tanır. Bzlmod'u etkinleştirmek için --enable_bzlmod işaretini kullanın ve her komuta uygulanması için common komutuna uygulayın:

  • .bazelrc

    # Enable Bzlmod for every Bazel command
    common --enable_bzlmod
    

Çalışma alanınız için depo adını belirtin

  • WORKSPACE

    workspace işlevi, çalışma alanınız için bir depo adı belirtmek üzere kullanılır. Bu, çalışma alanındaki bir hedef //foo:bar öğesinin @<workspace name>//foo:bar olarak referans verilmesine olanak tanır. Belirtilmezse çalışma alanınızın varsayılan depo adı __main__ olur.

    ## WORKSPACE
    workspace(name = "com_foo_bar")
    
  • Bzlmod

    @<repo name> olmadan //foo:bar söz dizimiyle aynı çalışma alanındaki hedeflere referans verilmesi önerilir. Ancak eski söz dizimine ihtiyacınız varsa module işlevi tarafından belirtilen modül adını depo adı olarak kullanabilirsiniz. Modül adı, gerekli depo adından farklıysa depo adını geçersiz kılmak için module işlevinin repo_name özelliğini kullanabilirsiniz.

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

Harici bağımlılıkları Bazel modülleri olarak getirme

Bağımlılığınız bir Bazel projesiyse Bzlmod'u da kullandığında Bazel modülü olarak bağımlı olabilirsiniz.

  • WORKSPACE

    WORKSPACE ile Bazel projesinin kaynaklarını indirmek için http_archive veya git_repository depo kurallarını kullanmak yaygındır.

    ## 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()
    

    Gördüğünüz gibi, kullanıcıların bağımlılığın makrosundan geçişli bağımlılıkları yüklemesi yaygın bir durumdur. Hem bazel_skylib hem de rules_java öğesinin platform öğesine bağlı olduğunu varsayarsak platform bağımlılığının tam sürümü makroların sırasına göre belirlenir.

  • Bzlmod

    Bzlmod ile bağımlılığınız Bazel Central Registry'de veya özel Bazel kayıt defterinizde olduğu sürece bazel_dep yönergesiyle bağımlılığınızı kullanabilirsiniz.

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

    Bzlmod, Bazel modülü bağımlılıklarını MVS algoritmasını kullanarak geçişli olarak çözer. Bu nedenle, platform için gereken maksimum sürüm otomatik olarak seçilir.

Bağımlılığı Bazel modülü olarak geçersiz kılma

Kök modül olarak, Bazel modülü bağımlılıklarını farklı şekillerde geçersiz kılabilirsiniz.

Daha fazla bilgi için lütfen geçersiz kılmalar bölümünü okuyun.

Bazı örnek kullanımları örnekler deposunda bulabilirsiniz.

Modül uzantılarıyla harici bağımlılıkları getirme

Bağımlılığınız bir Bazel projesi değilse veya henüz herhangi bir Bazel kayıt defterinde mevcut değilse use_repo_rule veya modül uzantılarını kullanarak bağımlılığınızı tanıtabilirsiniz.

  • WORKSPACE

    http_file depo kuralını kullanarak dosya indirme

    ## 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 ile, depoları doğrudan oluşturmak için MODULE.bazel dosyanızda use_repo_rule yönergesini kullanabilirsiniz:

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

    Bu özellik, arka planda bir modül uzantısı kullanılarak uygulanır. Yalnızca bir depo kuralını çağırmaktan daha karmaşık bir mantık uygulamanız gerekiyorsa modül uzantısını kendiniz de uygulayabilirsiniz. Tanımı .bzl dosyasına taşımanız gerekir. Bu dosya, taşıma döneminde tanımı WORKSPACE ve Bzlmod arasında paylaşmanıza da olanak tanır.

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

    Bağımlılıklar makrosunu yüklemek için bir modül uzantısı uygulayın. Makronun .bzl dosyası içinde tanımlayabilirsiniz ancak eski Bazel sürümleriyle uyumluluğu korumak için ayrı bir .bzl dosyasında tanımlamanız daha iyi olur.

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

    Deponun kök projede görünür olması için MODULE.bazel dosyasında modül uzantısının ve deponun kullanımlarını bildirmeniz gerekir.

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

Modül uzantısıyla harici bağımlılık çakışmalarını çözme

Bir proje, arayanlardan gelen girişlere göre harici depoları tanıtan bir makro sağlayabilir. Ancak bağımlılık grafiğinde birden fazla arayan varsa ve bunlar çakışmaya neden oluyorsa ne olur?

foo projesinin, version değerini bağımsız değişken olarak alan aşağıdaki makroyu sağladığını varsayalım.

## 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 ile makroyu @foo konumundan yükleyebilir ve ihtiyacınız olan veri bağımlılığı sürümünü belirtebilirsiniz. @foo öğesine bağlı olan ancak farklı bir veri bağımlılığı sürümü gerektiren başka bir bağımlılığınız @bar olduğunu varsayalım.

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

    Bu durumda, son kullanıcının ihtiyacı olan sürümü elde etmek için WORKSPACE'teki makroların sırasını dikkatli bir şekilde ayarlaması gerekir. WORKSPACE'in bağımlılıkları çözmek için mantıklı bir yol sunmaması, en büyük sorunlarından biridir.

  • Bzlmod

    Bzlmod ile foo projesinin yazarı, çakışmaları çözmek için modül uzantısını kullanabilir. Örneğin, tüm Bazel modülleri arasında her zaman veri bağımlılığının gereken maksimum sürümünü seçmenin mantıklı olduğunu varsayalım.

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

    Bu durumda, kök modülün 2.0 veri sürümü gerekirken bağımlılığı bar için 3.0 sürümü gerekir. foo içindeki modül uzantısı bu çakışmayı doğru şekilde çözebilir ve veri bağımlılığı için 3.0 sürümünü otomatik olarak seçebilir.

Üçüncü taraf paket yöneticisini entegre etme

Son bölümün ardından, modül uzantısı bağımlılık grafiğinden bilgi toplama yolu sağladığından, bağımlılıkları çözmek için özel mantık yürütün ve harici depoları tanıtmak için depo kurallarını çağırın. Bu, kural yazarlarının belirli diller için paket yöneticilerini entegre eden kural kümelerini geliştirmeleri için harika bir yol sağlar.

Modül uzantılarını kullanma hakkında daha fazla bilgi edinmek için lütfen modül uzantıları sayfasını okuyun.

Bağımlılıkları farklı paket yöneticilerinden getirmek için Bzlmod'u zaten kullanan kural kümelerinin listesini aşağıda bulabilirsiniz:

Sözde paket yöneticisi entegre eden en basit örneği examples deposunda bulabilirsiniz.

Ana makinede araç zincirlerini algılama

Bazel derleme kurallarının, ana makinenizde hangi araç zincirlerinin bulunduğunu tespit etmesi gerektiğinde ana makineyi incelemek ve araç zinciri bilgilerini harici depolar olarak oluşturmak için depo kurallarını kullanır.

  • WORKSPACE

    Bir kabuk araç zincirini algılamak için aşağıdaki depo kuralı verilmiştir.

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

    Depo kuralını WORKSPACE'e yükleyebilirsiniz.

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

    Bzlmod ile, son bölümde @data_file deposunu kullanmaya benzer şekilde, modül uzantısı kullanarak aynı depoyu kullanabilirsiniz.

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

    Ardından, uzantıyı MODULE.bazel dosyasında kullanın.

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

Araç zincirlerini ve yürütme platformlarını kaydetme

Son bölümün ardından, bir depo barındırma araç zinciri bilgisi (ör. local_config_sh) sunduktan sonra araç zincirini kaydetmek isteyebilirsiniz.

  • WORKSPACE

    WORKSPACE ile araç zincirini aşağıdaki şekillerde kaydedebilirsiniz.

    1. Araç zincirini .bzl dosyasıyla kaydedebilir ve makroyu WORKSPACE dosyasına yükleyebilirsiniz.

      ## 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. Alternatif olarak, araç zincirini doğrudan WORKSPACE dosyasında kaydedebilirsiniz.

      ## 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 ile register_toolchains ve register_execution_platforms API'leri yalnızca MODULE.bazel dosyasında kullanılabilir. Bir modül uzantısında native.register_toolchains işlevini çağıramazsınız.

    ## 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 içinde kaydedilen araç zincirleri ve yürütme platformları ile her Bazel modülünün MODULE.bazel dosyası, araç zinciri seçimi sırasında aşağıdaki öncelik sırasını (en yüksekten en düşüğe) izler:

  1. Kök modülün MODULE.bazel dosyasında kayıtlı araç zincirleri ve yürütme platformları.
  2. WORKSPACE veya WORKSPACE.bzlmod dosyasına kaydedilen araç zincirleri ve yürütme platformları.
  3. Kök modülün (geçişli) bağımlılıkları olan modüller tarafından kaydedilen araç zincirleri ve yürütme platformları.
  4. WORKSPACE.bzlmod kullanılmadığında: WORKSPACE.bzlmod sonekiyle kaydedilen araç zincirleri.WORKSPACE

Yerel depoları tanıtma

Hata ayıklama için bağımlılığın yerel bir sürümüne ihtiyacınız olduğunda veya çalışma alanınızdaki bir dizini harici depo olarak dahil etmek istediğinizde bağımlılığı yerel depo olarak tanıtmanız gerekebilir.

  • WORKSPACE

    WORKSPACE'te bu, iki yerel depo kuralı olan local_repository ve new_local_repository ile sağlanır.

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

    Bzlmod ile local_path_override kullanarak bir modülü yerel yolla geçersiz kılabilirsiniz.

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

    Modül uzantılı yerel bir depo da kullanabilirsiniz. Ancak modül uzantısında native.local_repository işlevini çağıramazsınız. Tüm yerel depo kurallarını Starlark'a dönüştürme çalışmaları devam etmektedir (ilerleme durumu için #18285 numaralı sorunu inceleyin). Ardından, bir modül uzantısında ilgili starlark local_repository işlevini çağırabilirsiniz. Bu durum sizin için engelleyici bir sorunsa local_repository deposu kuralının özel bir sürümünü uygulamak da kolaydır.

Bağlama hedefleri

WORKSPACE'teki bind kuralı kullanımdan kaldırıldı ve Bzlmod'da desteklenmiyor. Bu özellik, özel //external paketinde bir hedefe takma ad vermek için kullanıma sunulmuştur. Buna bağlı olan tüm kullanıcılar geçiş yapmalıdır.

Örneğin, abone sayınız

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

Bu, diğer hedeflerin //external:openssl'ya bağlı olmasına olanak tanır. Aşağıdaki yöntemleri kullanarak bu durumdan kurtulabilirsiniz:

  • //external:openssl ifadesinin tüm kullanımlarını @my-ssl//src:openssl-lib ile değiştirin.

    • İpucu: Hedefle ilgili alakalı bilgileri bulmak için bazel query --output=build --noenable_bzlmod --enable_workspace [target] komutunu kullanın.
  • Veya alias kural oluşturma özelliğini kullanın.

    • Pakette aşağıdaki hedefi tanımlayın (ör.//third_party).

      ## third_party/BUILD
      alias(
          name = "openssl",
          actual = "@my-ssl//src:openssl-lib",
      )
      
    • //external:openssl ifadesinin tüm kullanımlarını //third_party:openssl ile değiştirin.

Getirme ve senkronizasyon arasındaki fark

Harici depoları yerel olarak indirip güncel tutmak için getirme ve senkronize etme komutları kullanılır. Bazen de derleme için gereken tüm depolar getirildikten sonra --nofetch işaretini kullanarak çevrimdışı derlemeye izin vermek için kullanılır.

  • WORKSPACE

    Senkronizasyon, tüm depolar veya belirli bir yapılandırılmış depo grubu için zorunlu getirme işlemi gerçekleştirirken getirme işlemi yalnızca belirli bir hedef için getirme işlemi yapmak üzere kullanılır.

  • Bzlmod

    Senkronizasyon komutu artık geçerli değil ancak getirme işlemi çeşitli seçenekler sunar. Bir hedefi, depoyu, yapılandırılmış bir dizi depoyu veya bağımlılık çözümlemenize ve modül uzantılarınıza dahil olan tüm depoları getirebilirsiniz. Getirme sonucu önbelleğe alınır ve getirme işlemini zorlamak için getirme işlemi sırasında --force seçeneğini eklemeniz gerekir.

Taşıma

Bu bölümde, Bzlmod'a geçiş sürecinizle ilgili faydalı bilgiler ve rehberlik sağlanmaktadır.

WORKSPACE'teki bağımlılıklarınızı öğrenme

Taşıma işleminin ilk adımı, sahip olduğunuz bağımlılıkları anlamaktır. Geçişli bağımlılıklar genellikle *_deps makrolarıyla yüklendiğinden WORKSPACE dosyasında hangi bağımlılıkların kullanıldığını belirlemek zor olabilir.

Çalışma alanında çözümlenen dosyayla harici bağımlılığı inceleme

Neyse ki --experimental_repository_resolved_file işareti bu konuda yardımcı olabilir. Bu işaret, son Bazel komutunuzda getirilen tüm harici bağımlılıkların bir "kilit dosyasını" oluşturur. Daha fazla bilgiyi bu blog yayınında bulabilirsiniz.

İki şekilde kullanılabilir:

  1. Belirli hedeflerin oluşturulması için gereken harici bağımlılıkların bilgilerini getirmek için kullanılır.

    bazel clean --expunge
    bazel build --nobuild --experimental_repository_resolved_file=resolved.bzl //foo:bar
    
  2. WORKSPACE dosyasında tanımlanan tüm harici bağımlılıkların bilgilerini getirmek için.

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

    bazel sync komutuyla, WORKSPACE dosyasında tanımlanan tüm bağımlılıkları (aşağıdakiler dahil) getirebilirsiniz:

    • bind kullanımları
    • register_toolchains ve register_execution_platforms kullanım

    Ancak projeniz platformlar arasıysa bazı depo kuralları yalnızca desteklenen platformlarda doğru şekilde çalışabileceğinden Bazel senkronizasyonu belirli platformlarda bozulabilir.

Komutu çalıştırdıktan sonra, resolved.bzl dosyasında harici bağımlılıklarınızla ilgili bilgiler yer alır.

bazel query ile harici bağımlılığı inceleyin

bazel query ile depo kurallarını incelemek için de kullanılabileceğini biliyor olabilirsiniz.

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

Daha rahat ve çok daha hızlı olsa da bazel query, harici bağımlılık sürümü hakkında yalan söyleyebilir. Bu nedenle, kullanırken dikkatli olun. Bzlmod ile harici bağımlılıkları sorgulama ve inceleme işlemi yeni bir alt komut aracılığıyla gerçekleştirilecek.

Yerleşik varsayılan bağımlılıklar

--experimental_repository_resolved_file tarafından oluşturulan dosyayı kontrol ederseniz WORKSPACE'inizde tanımlanmamış birçok bağımlılık bulursunuz. Bunun nedeni, Bazel'in bazı varsayılan bağımlılıkları eklemek için kullanıcının WORKSPACE dosya içeriğine aslında önekler ve sonekler eklemesidir.Bu bağımlılıklar genellikle yerel kurallar (ör. @bazel_tools, @platforms ve @remote_java_tools) tarafından gereklidir. Bzlmod ile bu bağımlılıklar, diğer tüm Bazel modülleri için varsayılan bağımlılık olan yerleşik bir modül bazel_tools ile tanıtılır.

Kademeli geçiş için karma mod

Bzlmod ve WORKSPACE yan yana çalışabilir. Bu sayede, bağımlılıkların WORKSPACE dosyasından Bzlmod'a taşınması kademeli bir süreç olabilir.

WORKSPACE.bzlmod

Taşıma işlemi sırasında Bazel kullanıcılarının Bzlmod'un etkin olduğu ve olmadığı derlemeler arasında geçiş yapması gerekebilir. WORKSPACE.bzlmod desteği, süreci kolaylaştırmak için uygulanır.

WORKSPACE.bzlmod, WORKSPACE ile aynı söz dizimine sahiptir. Bzlmod etkinleştirildiğinde, çalışma alanı kökünde WORKSPACE.bzlmod dosyası da varsa:

  • WORKSPACE.bzlmod geçerli olur ve WORKSPACE içeriği yok sayılır.
  • WORKSPACE.bzlmod dosyasına önek veya sonek eklenmez.

WORKSPACE.bzlmod dosyasını kullanmak, aşağıdaki nedenlerden dolayı taşımayı kolaylaştırabilir:

  • Bzlmod devre dışı bırakıldığında, bağımlılıkları orijinal WORKSPACE dosyasından getirmeye geri dönersiniz.
  • Bzlmod etkinleştirildiğinde, WORKSPACE.bzlmod ile hangi bağımlılıkların taşınması gerektiğini daha iyi takip edebilirsiniz.

Depo görünürlüğü

Bzlmod, belirli bir depodan hangi diğer depoların görülebileceğini kontrol edebilir. Daha fazla bilgi için depo adları ve strict_deps bölümüne bakın.

Aşağıda, WORKSPACE de dikkate alındığında farklı türlerdeki depolardaki depo görünürlüklerinin özeti verilmiştir.

Ana depodan Bazel modülü depolarından Modül uzantısı depolarından WORKSPACE depolarından
Ana depo Gösteriliyor Kök modül doğrudan bağımlıysa Kök modül, modül uzantısını barındıran modülün doğrudan bağımlısıysa Gösteriliyor
Bazel modülü depoları Doğrudan mevduatlar Doğrudan mevduatlar Modül uzantısını barındıran modülün doğrudan bağımlılıkları Kök modülün doğrudan bağımlılıkları
Modül uzantısı depoları Doğrudan mevduatlar Doğrudan mevduatlar Modül uzantısını barındıran modülün doğrudan bağımlılıkları + aynı modül uzantısı tarafından oluşturulan tüm depolar Kök modülün doğrudan bağımlılıkları
WORKSPACE Repos Tümü görünür Görünmez Görünmez Tümü görünür

Taşıma süreci

Standart bir Bzlmod taşıma süreci şu şekilde olabilir:

  1. WORKSPACE'te hangi bağımlılıklarınız olduğunu anlayın.
  2. Projenizin kök dizinine boş bir MODULE.bazel dosyası ekleyin.
  3. WORKSPACE dosyasının içeriğini geçersiz kılmak için boş bir WORKSPACE.bzlmod dosyası ekleyin.
  4. Bzlmod etkinleştirilmiş şekilde hedeflerinizi oluşturun ve hangi deponun eksik olduğunu kontrol edin.
  5. Çözümlenen bağımlılık dosyasında eksik deponun tanımını kontrol edin.
  6. Eksik bağımlılığı bir modül uzantısı aracılığıyla Bazel modülü olarak ekleyin veya daha sonra taşımak üzere WORKSPACE.bzlmod dosyasında bırakın.
  7. 4. adıma geri dönün ve tüm bağımlılıklar kullanılabilir olana kadar tekrarlayın.

Taşıma aracı

Başlamanıza yardımcı olabilecek etkileşimli bir Bzlmod taşıma yardımcı komut dosyası vardır.

Komut dosyası aşağıdaki işlemleri yapar:

  • WORKSPACE çözümlenmiş dosyasını oluşturun ve ayrıştırın.
  • Çözümlenen dosyadan depo bilgilerini okunabilir şekilde yazdırın.
  • Bazel build komutunu çalıştırın, tanınan hata mesajlarını tespit edin ve taşıma için bir yöntem önerin.
  • Bir bağımlılığın BCR'de zaten mevcut olup olmadığını kontrol edin.
  • MODULE.bazel dosyasına bağımlılık ekleyin.
  • Modül uzantısı aracılığıyla bağımlılık ekleyin.
  • WORKSPACE.bzlmod dosyasına bağımlılık ekleyin.

Bu özelliği kullanmak için en son Bazel sürümünün yüklü olduğundan emin olun ve aşağıdaki komutu çalıştırın:

git clone https://github.com/bazelbuild/bazel-central-registry.git
cd bazel-central-registry
bazel build //tools:migrate_to_bzlmod
alias migrate2bzlmod=$(realpath ./bazel-bin/tools/migrate_to_bzlmod)

cd <your workspace root>
migrate2bzlmod -t <your build targets>

Bazel modüllerini yayınlama

Bazel projeniz diğer projeler için bağımlılık oluşturuyorsa projenizi Bazel Central Registry'de yayınlayabilirsiniz.

Projenizi BCR'ye ekleyebilmek için projenin kaynak arşiv URL'sine ihtiyacınız vardır. Kaynak arşivi oluştururken dikkat etmeniz gereken birkaç nokta:

  • Arşivin belirli bir sürümü işaret ettiğinden emin olun.

    Bzlmod, bağımlılık çözümleme sırasında sürüm karşılaştırması yapması gerektiğinden BCR yalnızca sürüm oluşturulmuş kaynak arşivlerini kabul edebilir.

  • Arşiv URL'sinin sabit olduğundan emin olun.

    Bazel, arşivin içeriğini karma değeriyle doğrular. Bu nedenle, indirilen dosyanın sağlama toplamının hiçbir zaman değişmediğinden emin olmanız gerekir. URL GitHub'dan geliyorsa lütfen sürüm sayfasında bir sürüm arşivi oluşturup yükleyin. GitHub, isteğe bağlı olarak oluşturulan kaynak arşivlerin sağlama toplamını garanti etmez. Kısacası, https://github.com/<org>/<repo>/releases/download/... biçimindeki URL'ler kararlı, https://github.com/<org>/<repo>/archive/... biçimindeki URL'ler ise kararsız olarak kabul edilir. Daha fazla bilgi için GitHub Archive Checksum Outage'a göz atın.

  • Kaynak ağacın, orijinal deponun düzenine uygun olduğundan emin olun.

    Deponuz çok büyükse ve gereksiz kaynakları kaldırarak boyutu küçültülmüş bir dağıtım arşivi oluşturmak istiyorsanız lütfen kaldırılan kaynak ağacının orijinal kaynak ağacının bir alt kümesi olduğundan emin olun. Bu, son kullanıcıların archive_override ve git_override ile modülü yayınlanmamış bir sürümle geçersiz kılmasını kolaylaştırır.

  • En yaygın API'lerinizi test eden bir alt dizinde test modülü bulundurun.

    Test modülü, yayınlanacak gerçek modüle bağlı olan kaynak arşivinin bir alt dizininde bulunan kendi WORKSPACE ve MODULE.bazel dosyasına sahip bir Bazel projesidir. En yaygın API'lerinizi kapsayan örnekler veya bazı entegrasyon testleri içermelidir. Nasıl ayarlayacağınızı öğrenmek için test modülüne göz atın.

Kaynak arşivinizin URL'si hazır olduğunda, modülünüzü GitHub çekme isteğiyle BCR'ye göndermek için BCR katkı yönergelerini uygulayın.

Modülünüzü BCR'ye gönderme sürecini otomatikleştirmek için deponuzda Publish to BCR GitHub uygulamasını ayarlamanız şiddetle tavsiye edilir.

En iyi uygulamalar

Bu bölümde, harici bağımlılıklarınızı daha iyi yönetmek için uygulamanız gereken birkaç en iyi uygulama açıklanmaktadır.

Gereksiz bağımlılıkların getirilmesini önlemek için hedefleri farklı paketlere ayırın.

Testler için geliştirme bağımlılıklarının, bunlara ihtiyaç duymayan hedef oluşturma işlemleri için gereksiz yere getirilmeye zorlandığı #12835'i kontrol edin. Bu aslında Bzlmod'a özgü değildir ancak bu uygulamaları izlemek geliştirme bağımlılıklarını doğru şekilde belirtmeyi kolaylaştırır.

Geliştirme bağımlılıklarını belirtme

bazel_dep ve use_extension yönergeleri için dev_dependency özelliğini true olarak ayarlayabilirsiniz. Böylece bu yönergeler bağımlı projelere yayılmaz. Kök modül olarak, hedeflerinizin geliştirme bağımlılıkları ve geçersiz kılmalar olmadan hâlâ oluşturulup oluşturulmadığını doğrulamak için --ignore_dev_dependency işaretini kullanabilirsiniz.

Topluluk taşıma işleminin ilerleme durumu

Bağımlılıklarınızın kullanıma sunulup sunulmadığını öğrenmek için Bazel Central Registry'yi kontrol edebilirsiniz. Aksi takdirde, geçişinizi engelleyen bağımlılıkları oylamak veya yayınlamak için bu GitHub tartışmasına katılabilirsiniz.

Sorun bildirme

Bilinen Bzlmod sorunları için lütfen Bazel GitHub sorun listesini kontrol edin. Taşıma işleminizin engellenmesini önlemeye yardımcı olabilecek yeni sorunlar veya özellik istekleri gönderebilirsiniz.