Bzlmod Taşıma Kılavuzu

Sorun bildirin Kaynağı göster

WORKSPACE'in yetersiz olması nedeniyle Bzlmod, gelecekteki Bazel sürümlerinde eski WORKSPACE sisteminin yerini alacaktır. Bu kılavuz, projenizi Bzlmod'a taşımanıza ve harici bağımlılıkları getirmek için WORKSPACE'i bırakmanıza yardımcı olur.

WORKSPACE - Bzlmod

Bazel'in WORKSPACE ve Bzlmod farklı söz dizimiyle 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ı bir Bazel projesinin kaynak kökünü işaret eder. Bu sorumluluğun yerini Bazel 6.3 ve sonraki sürümlerinde MODULE.bazel alır. 6.3'ten önceki Bazel sürümünde, çalışma alanı kökünüzde hâlâ bir WORKSPACE veya WORKSPACE.bazel dosyası bulunur. Bu dosya, aşağıdaki gibi yorumlarla olabilir:

  • ÇALIŞMA ALANI

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

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

  • ÇALIŞMA ALANI

    workspace işlevi, çalışma alanınız için depo adı belirtmek amacıyla kullanılır. Bu sayede çalışma alanındaki bir //foo:bar hedefine @<workspace name>//foo:bar olarak referansta bulunulabilir. Belirtilmezse çalışma alanınızın varsayılan depo adı __main__ olur.

    ## WORKSPACE
workspace(name = "com_foo_bar")

  • Bzlmod

    Aynı çalışma alanında, @<repo name> içermeyen //foo:bar söz dizimini kullanan hedeflere referans vermeniz önerilir. Ancak eski söz dizimine ihtiyacınız varsa depo adı olarak module işleviyle belirtilen modül adını 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",
)

Dış bağımlılıkları Bazel modülleri olarak getirin

Bağımlılığınız bir Bazel projesiyse, Bzlmod’u da kullandığında Bazel modülü olarak buna güvenebilirsiniz.

  • ÇALIŞMA ALANI

    WORKSPACE ile genellikle Bazel projesinin kaynaklarını indirmek için http_archive veya git_repository deposu kuralları kullanılı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 bu, kullanıcıların geçişli bağımlılıkları bağımlılığın bir makrosundan yüklemesi gereken yaygın bir kalıptır. Hem bazel_skylib hem de rules_java öğesinin platoform öğesine bağlı olduğunu varsayalım. 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 otoritenizde bulunduğu sürece, bir bazel_dep yönergesiyle bağımlılığınıza güvenebilirsiniz.

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

    Bzlmod, MVS algoritmasını kullanarak Bazel modülü bağımlılıklarını geçişli olarak çözümler. Bu nedenle, platform için gereken en yüksek 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ı yöntemlerle geçersiz kılabilirsiniz.

Daha fazla bilgi için lütfen overrides bölümünü okuyun.

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

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

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

  • ÇALIŞMA ALANI

    http_file kod deposu kuralını kullanarak dosya indirin.

    ## 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 tanımı bir .bzl dosyasına taşımanız gerekir. Bu sayede, taşıma sürecinde WORKSPACE ve Bzlmod arasındaki tanımı paylaşabilirsiniz.

    ## 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. Bunu, makronun aynı .bzl dosyasında tanımlayabilirsiniz. Ancak, eski Bazel sürümleriyle uyumluluğu korumak için ayrı bir .bzl dosyasında tanımlamak daha iyidir.

    ## 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 proje tarafından görülebilmesi için modül uzantısının ve deponun kullanımlarını MODULE.bazel dosyasında beyan etmeniz 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 çakışma harici bağımlılıkları çözün

Projeler, çağrı yapanlardan gelen girişlere dayanarak harici depoları tanıtan bir makro sağlayabilir. Peki bağımlılık grafiğinde birden fazla arayan varsa ve bunlar bir çakışmaya neden olursa ne olur?

foo projesinin, version öğesini bağımsız değişken olarak kabul eden 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
    )

  • ÇALIŞMA ALANI

    WORKSPACE ile makroyu @foo kaynağından yükleyebilir ve ihtiyacınız olan veri bağımlılığı sürümünü belirtebilirsiniz. Aynı zamanda @foo öğesine bağlı olan ancak veri bağımlılığının farklı bir sürümünü gerektiren başka bir @bar bağımlınızın 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ı ihtiyaç duyduğu sürümü elde etmek için WORKSPACE'teki makroların sırasını dikkatlice ayarlamalıdır. Bu, bağımlılıkları çözmek için makul bir yol sunmadığı için WORKSPACE ile ilgili en büyük sorunlardan biri.

  • Bzlmod

    foo projesinin yazarı, Bzlmod ile çakışmaları çözmek için modül uzantısını kullanabilir. Örneğin, tüm Bazel modülleri arasında veri bağımlılığı için gereken maksimum sürümü seçmenin her zaman 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 2.0 veri sürümünü gerektirirken bar bağımlılığı için 3.0 gerekir. foo ürünündeki 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üme geçelim. Modül uzantısı bağımlılık grafiğinden bilgi toplama, bağımlılıkları çözmek için özel mantık yürütme ve harici depoları kullanıma sunmak için kod deposu kurallarını çağırma işlemlerini yapma imkanı sunduğundan, bu, kural yazarlarının paket yöneticilerini belirli diller için entegre eden kural kümelerini geliştirmeleri için mükemmel bir yol sağlar.

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

Farklı paket yöneticilerinden bağımlılıkları getirmek için Bzlmod'u kullanmakta olan kural setlerinin listesini aşağıda bulabilirsiniz:

examples deposunda, yapay bir paket yöneticisini entegre eden minimal bir örnek bulunmaktadır.

Ana makinedeki araç zincirlerini algılama

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

  • ÇALIŞMA ALANI

    Kabuk araç zincirini algılamak için aşağıdaki depo kuralından yararlanılır.

    ## 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'te yükleyebilirsiniz.

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

  • Bzlmod

    Bzlmod ile aynı depoyu modül uzantısı kullanarak tanıtabilirsiniz. Bu işlem, son bölümde @data_file deposunu kullanıma sunmaya benzer.

    ## 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, MODULE.bazel dosyasındaki uzantıyı 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ümden sonra, depo barındırma araç zinciri bilgilerini (ör. local_config_sh) sunduktan sonra muhtemelen araç zincirini kaydetmek istersiniz.

  • ÇALIŞMA ALANI

    WORKSPACE ile araç zincirini aşağıdaki yöntemlerle kaydedebilirsiniz.

    1. .bzl dosyasına araç zincirini 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ına kaydedin.

      ## 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 yöntemini ç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")

Yerel depolar sunun

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ıza harici depo olarak bir dizin eklemek istediğinizde, bağımlılığı yerel depo olarak eklemeniz gerekebilir.

  • ÇALIŞMA ALANI

    WORKSPACE ile bu işlem local_repository ve new_local_repository adlı iki yerel depo kuralı ile gerçekleştirilir.

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

  • Bzlmod

    Bzlmod ile bir modülü yerel yolla geçersiz kılmak için local_path_override özelliğini kullanabilirsiniz.

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

    Modül uzantısına sahip yerel bir depo sunmak da mümkündür. Ancak, modül uzantısında native.local_repository yöntemini çağıramazsınız. Tüm yerel depo kurallarına yıldız eklemek için devam eden çalışmalar devam etmektedir (ilerleme durumu için #18285'e bakın). Daha sonra, bir modül uzantısında ilgili starlark'ı local_repository çağırabilirsiniz. Bu sizin için engelleyen bir sorunsa local_repository deposu kuralının özel sürümünü uygulamak da önemsizdir.

Hedefleri bağla

WORKSPACE'teki bind kuralı kullanımdan kaldırıldı ve Bzlmod'da desteklenmiyor. Özel //external paketinde bir hedefe takma ad vermek için kullanıma sunulmuştur. Buna bağlı olarak tüm kullanıcılar taşınmalıdır.

Örneğin, abone sayınız

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

Bu, diğer hedeflerin //external:openssl bağımlılığına bağlı olmasına izin verir. Bundan başka bir yere taşıma işlemini şu şekilde yapabilirsiniz:

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

  • İsterseniz alias derleme kuralını da kullanabilirsiniz

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

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

    • Tüm //external:openssl kullanımlarını //third_party:openssl-lib ile değiştirin.

Taşıma

Bu bölümde, Bzlmod taşıma sürecinizle ilgili faydalı bilgiler ve yol gösterici bilgiler sunulmaktadır.

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

Taşımanın 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 tam bağımlılıkların ortaya çıktığını belirlemek zor olabilir.

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

Neyse ki, --experimental_repository_resolved_file işareti size yardımcı olabilir. Bu işaret, temelde 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 hedefleri oluşturmak için gereken dış bağımlılıklarla ilgili bilgileri getirmek.

    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ı getirebilirsiniz. Bu bağımlılıklar şunları içerir:

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

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

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

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

Ayrıca bazel query hizmetinin depo kurallarını incelemek için kullanılabileceğini

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

Daha pratik ve çok daha hızlı olsa da bazel sorgusu dış bağımlılık sürümü hakkında yalan beyanda bulunabilir. Bu nedenle bu sürümü kullanırken dikkatli olun. Bzlmod ile dış bağımlılıkların sorgulanması ve denetlenmesi yeni bir alt komutla 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 görürsünüz. Bunun nedeni, Bazel'in genellikle yerel kuralların (ör. @bazel_tools, @platforms ve @remote_java_tools) gerektirdiği bazı varsayılan bağımlılıkları yerleştirmek için kullanıcının WORKSPACE dosya içeriğine ön ek ve sonek eklemesidir. Bzlmod ile bu bağımlılıklar, diğer tüm Bazel modülleri için varsayılan bir bağımlılık olan bazel_tools yerleşik bir modülle oluşturulur.

Kademeli taşıma için karma mod

Bzlmod ve WORKSPACE yan yana çalışarak WORKSPACE dosyasından Bzlmod'a bağımlılıkların taşınmasını aşamalı bir süreç haline getirir.

WORKSPACE.bzlmod

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

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

  • WORKSPACE.bzlmod geçerlilik kazanır ve WORKSPACE içeriği yoksayılır.
  • WORKSPACE.bzlmod dosyasına herhangi bir önek veya sonek eklenmez.

WORKSPACE.bzlmod dosyasını kullanmak taşıma işlemini kolaylaştırabilir, çünkü:

  • Bzlmod devre dışı bırakıldığında orijinal WORKSPACE dosyasından bağımlılıkları getirmeye geri dönersiniz.
  • Bzlmod etkinleştirildiğinde, WORKSPACE.bzlmod ile taşınmak için kalan bağımlılıkları daha iyi takip edebilirsiniz.

Depo görünürlüğü

Bzlmod, belirli bir depodan hangi diğer depoların görülebileceğini kontrol edebilir. Ayrıntılı bilgi için depo adlarını ve katı depoları inceleyin.

WORKSPACE'i de dikkate alırken farklı depo türlerindeki depo görünürlüklerinin özetini burada bulabilirsiniz.

Ana depodan Bazel modül depolarından Modül uzantı depolarından WORKSPACE depolarından
Ana depo Gösteriliyor Kök modül doğrudan bağımlılıksa Kök modül, modül uzantısını barındıran modülün doğrudan bağımlılığıysa Gösteriliyor
Bazel modülü depoları Doğrudan satış Doğrudan satış Modül uzantısını barındıran modülün doğrudan açıklamaları Kök modülün doğrudan açıklamaları
Modül uzantısı depoları Doğrudan satış Doğrudan satış Modül uzantısını barındıran modülün doğrudan açıklamaları + aynı modül uzantısı tarafından oluşturulan tüm depolar Kök modülün doğrudan açıklamaları
WORKSPACE Kod Depoları Tümü görünür durumda Görünmez Görünmez Tümü görünür durumda
, MODULE.bazel'de tanıtılan depoyu ifade eder.{/