Bzlmod Taşıma Kılavuzu

Sorun bildir Kaynağı göster

WORKSPACE'in eksiklikleri nedeniyle Bzlmod, gelecekteki Bazel sürümlerinde eski WORKSPACE sistemini değiştirecek. 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 karşılaştırması

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şaretler. Bu sorumluluk Bazel 6.3 ve sonraki sürümlerinde MODULE.bazel ile değiştirilir. Bazel'ın 6.3'ten önceki sürümlerinde, çalışma alanı kök dizininizde şuna benzer yorumlarla hâlâ bir WORKSPACE veya WORKSPACE.bazel dosyası olmalıdır:

  • ÇALIŞMA ALANI

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

Marketplace'te Bzlmod'u etkinleştirin

.bazelrc, Bazel'i her çalıştırdığınızda uygulanacak bayraklar ayarlamanızı sağlar. 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ı belirtin

  • ÇALIŞMA ALANI

    workspace işlevi, çalışma alanınız için depo adını belirtmek amacıyla kullanılır. Bu, çalışma alanındaki bir hedef //foo:bar için @<workspace name>//foo:bar olarak referans verilmesini sağlar. Belirtilmezse çalışma alanınız için varsayılan kod deposu adı __main__ olur.

    ## WORKSPACE
workspace(name = "com_foo_bar")

  • Bzlmod

    Aynı çalışma alanındaki hedeflere, @<repo name> olmadan //foo:bar söz dizimiyle referans verilmesi önerilir. Ancak eski söz dizimine ihtiyacınız olursa depo adı olarak module işlevi tarafından 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 al

Bağımlılığınız bir Bazel projesiyse Bzlmod'u da benimsediğinde Bazel modülü olarak bu projeye bağımlı olabilirsiniz.

  • ÇALIŞMA ALANI

    WORKSPACE ile Bazel projesinin kaynaklarını indirmek için genellikle 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ı bir bağımlılık makrosundan yüklemesi gereken yaygın bir kalıptır. Hem bazel_skylib hem de rules_java öğesinin platform ürününe bağlı olduğunu varsayın. platform bağımlılığının tam sürümü, makroların sırasına göre belirlenir.

  • Bzlmod

    Bzlmod'da, bağımlılığınız Bazel CentralRegistry'de veya özel Bazel kayıt defterinizde mevcut olduğu sürece bir bazel_dep yönergesiyle ona 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 çözer. Bu nedenle, platform için gereken maksimum sürüm otomatik olarak seçilir.

Bazel modülü olarak bir bağımlılığı 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 overrides bölümünü okuyun.

Bazı örnek kullanımları examples 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 tanıtabilirsiniz.

  • ÇALIŞMA ALANI

    http_file deposu kuralını kullanarak bir 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 depoları doğrudan örneklendirmek 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",
)

    Temelde, bu işlem bir modül uzantısı kullanılarak uygulanır. Bir depo kuralını çağırmaktan daha karmaşık bir mantık gerçekleştirmeniz gerekiyorsa modül uzantısını kendiniz de uygulayabilirsiniz. Tanımı bir .bzl dosyasına taşımanız gerekir. Bu sayede, taşıma işlemi sırasında tanımı WORKSPACE ile Bzlmod arasında 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 bunu 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,
)

    Depoyu kök projede görünür hale getirmek 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 çelişen dış bağımlılıkları çözme

Bir proje, çağrı yapanlardan gelen girdilere dayanarak harici depolar sunan 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 bağımsız değişkenini 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
    )

  • Ç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. @foo öğesine bağımlı olan ancak veri bağımlılığının farklı bir sürümünü gerektiren başka bir @bar bağımlılığı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ının, ihtiyaç duyduğu sürümü alabilmek için WORKSPACE'te makroların sırasını dikkatli bir şekilde ayarlaması gerekir. Bu, bağımlılıkları çözmek için makul bir yol sunmadığından WORKSPACE’in en büyük sorunlarından biri.

  • Bzlmod

    Bzlmod ile, foo projesinin yazarı, çakışmaları gidermek için modül uzantısını kullanabilir. Örneğin, tüm Bazel modülleri arasında her zaman veri bağımlılığı için gereken maksimum sürümü 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 2.0 veri sürümünü gerektirirken bar bağımlılığı için 3.0 gerekir. foo üzerindeki modül uzantısı bu çakışmayı doğru şekilde çözebilir ve veri bağımlılığı için otomatik olarak 3.0 sürümünü seçebilir.

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

Son bölümden sonra, modül uzantısı bağımlılık grafiğinden bilgi toplamak, bağımlılıkları çözmek için özel mantık uygulamak ve harici depolar eklemek amacıyla kod deposu kurallarını çağırmak için bir yol sağladığından, bu yöntem kural yazarlarının belirli diller için paket yöneticilerini 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 kümelerinin listesini aşağıda bulabilirsiniz:

Sözde paket yöneticisini entegre eden minimal bir örneği examples deposunda bulabilirsiniz.

Ana makinedeki araç zincirlerini algılama

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

  • ÇALIŞMA ALANI

    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'te 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 tanıtmaya benzer şekilde, bir modül uzantısı kullanarak aynı depoyu tanıtabilirsiniz.

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

    Daha sonra, 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ı kaydedin

Son bölümün ardından, araç zinciri bilgilerini (ör. local_config_sh) barındıran bir depoyu tanıttıktan sonra muhtemelen araç zincirini kaydetmek istersiniz.

  • ÇALIŞMA ALANI

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

    1. Araç zincirini .bzl dosyasına kaydedip 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. Modül uzantısında native.register_toolchains ç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 ve 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 şu öncelik sırasını izler (en yüksekten en düşüğe):

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

Yerel depoları kullanıma 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, iki yerel depo kuralıyla (local_repository ve new_local_repository) gerçekleştirilir.

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

  • Bzlmod

    Bzlmod ile bir modülü yerel bir yolla geçersiz kılmak için local_path_override 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ılı yerel bir depoyu kullanıma sunmak da mümkündür. Ancak modül uzantısında native.local_repository çağrısı yapılamaz. Tüm yerel depo kurallarına yıldızlar eklemek için devam eden bir çalışma var (ilerleme durumu için #18285'e bakın). Daha sonra, bir modül uzantısında karşılık gelen starlark local_repository öğesini çağırabilirsiniz. Bu sizin için sorun teşkil ediyorsa local_repository kod deposu kuralının özel bir sürümünü uygulamak da çok önemlidir.

Hedefleri bağla

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

Örneğin

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

Bu, diğer hedeflerin //external:openssl kaynağına bağımlı olmasına olanak tanır. Bu durumdan başka bir hesaba geçiş yapmak için şunları yapabilirsiniz:

  • //external:openssl öğesinin tüm 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 ile değiştir.

Getirme ve Senkronizasyon

Getirme ve senkronize etme komutları, harici depoları yerel olarak indirmek ve güncel tutmak için kullanılır. Bazen bir derleme için gereken tüm depoları getirdikten sonra --nofetch işaretini kullanarak çevrimdışı derlemeye de izin verebilirsiniz.

  • ÇALIŞMA ALANI

    Senkronizasyon, tüm kod depoları veya yapılandırılmış belirli bir depo grubu için zorla getirme işlemi gerçekleştirir. Getirme ise yalnızca belirli bir hedefi getirmek için kullanılır.

  • Bzlmod

    Senkronizasyon komutu artık geçerli değildir ancak getirme işlevi çeşitli seçenekler sunar. Bağımlılık çözümlemeniz ve modül uzantılarınızda yer alan bir hedefi, kod deposunu, yapılandırılmış bir depo kümesini veya tüm depoları getirebilirsiniz. Getirme sonucu önbelleğe alınır. Getirmeyi zorunlu kılmak için getirme işlemi sırasında --force seçeneğini eklemeniz gerekir.

Taşıma

Bu bölümde, Bzlmod geçiş sürecinizle ilgili yararlı bilgiler ve yol gösterici bilgiler sağlanmaktadır.

WORKSPACE'teki bağımlılıklarınızı bilin

Taşıma işleminin ilk adımı, hangi bağımlılıklarınız olduğunu 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 tam olarak hangisine yerleştirildiğini anlamak zor olabilir.

Çalışma alanı çözümlenmiş dosyasıyla 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. Bu blog yayınında daha ayrıntılı bilgi edinebilirsiniz.

İ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 aşağıdakiler dahil tüm bağımlılıkları getirebilirsiniz:

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

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

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

bazel query ürününün,

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

Daha kullanışlı ve çok daha hızlı olsa da bazel sorgusu, dış bağımlılık sürümü hakkında bilgi içerebilir. Bu yüzden bu sürümü kullanırken dikkatli olun. Dış bağımlılıkları Bzlmod ile sorgulama ve inceleme işlemleri yeni bir alt komut ile gerçekleştirilecektir.

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

--experimental_repository_resolved_file tarafından oluşturulan dosyayı kontrol ederseniz WORKSPACE sayfanızda tanımlanmamış birçok bağımlılık bulursunuz. Bunun nedeni Bazel'in, genellikle yerel kurallar (ör. @bazel_tools, @platforms ve @remote_java_tools) tarafından zorunlu kılınan bazı varsayılan bağımlılıkları eklemek için kullanıcının WORKSPACE dosyası içeriğine önekler ve sonekler 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 yerleşik bir modül bazel_tools ile kullanıma sunulur.

Kademeli geçiş için karma mod

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

WORKSPACE.bzlmod

Taşıma sırasında Bazel kullanıcılarının, Bzlmod etkin olan ve olmayan derlemeler arasında geçiş yapması gerekebilir. Süreci daha sorunsuz hale getirmek için WORKSPACE.bzlmod desteği uygulanmıştır.

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

  • WORKSPACE.bzlmod yürürlüğe girer ve WORKSPACE içeriği yok sayılır.
  • WORKSPACE.bzlmod dosyasına herhangi bir önek veya sonek eklenmez.

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

  • Bzlmod devre dışı bırakıldığında bağımlılıkları orijinal WORKSPACE dosyasından getirirsiniz.
  • Bzlmod etkinleştirildiğinde WORKSPACE.bzlmod ile taşınacak 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. Daha fazla ayrıntı için depo adlarını ve katı derinlikleri kontrol edin.

WORKSPACE'i de hesaba katarak farklı depo türlerindeki depo görünürlüklerinin özetini aşağıda bulabilirsiniz.

Ana depodan Bazel modül depolarından Modül uzantı kod 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 havuzları Doğrudan işlemler Doğrudan uçuşlar Modül uzantısını barındıran modülün doğrudan bölümleri Kök modülün doğrudan sürümleri
Modül uzantı depoları Doğrudan uçuşlar Doğrudan uçuşlar Modül uzantısını barındıran modülün doğrudan konumları + aynı modül uzantısı tarafından oluşturulan tüm depolar Kök modülün doğrudan sürümleri
WORKSPACE Kod Depoları Tümü görünür Görünmez Görünmez Tümü görünür
@bar

Taşıma süreci

Tipik bir Bzlmod taşıma süreci şu şekilde görünebilir:

  1. WORKSPACE'te hangi bağımlılıklarınız olduğunu anlayın.
  2. Proje kök klasörünüze boş bir MODULE.bazel dosyası ekleyin.
  3. WORKSPACE dosya içeriğini geçersiz kılmak için boş bir WORKSPACE.bzlmod dosyası ekleyin.
  4. Bzlmod etkin durumdayken hedeflerinizi oluşturun ve hangi deponun eksik olduğunu kontrol edin.
  5. Çözülmüş bağımlılık dosyasındaki eksik deponun tanımını kontrol edin.
  6. Eksik bağımlılığı Bazel modülü veya modül uzantısı aracılığıyla sunun ya da daha sonra taşıma işlemi için WORKSPACE.bzlmod içinde bırakın.
  7. 4’e geri dönün ve tüm bağımlılıklar kullanılabilir hale gelene 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ı şunları yapar:

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

Kullanabilmek 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 <your workspace root>
<BCR repo root>/tools/migrate_to_bzlmod.py -t <your build targets>

Bazel modüllerini yayınla

Bazel projeniz başka projelere bağımlıysa projenizi Bazel Central Registry'de yayınlayabilirsiniz.

BCR'de projenizi kontrol edebilmek için projenin kaynak arşiv URL'sine ihtiyacınız vardır. Kaynak arşivi oluştururken birkaç noktaya dikkat edin:

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

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

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

    Bazel, arşivin içeriğini bir 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ı olarak kabul edilirken https://github.com/<org>/<repo>/archive/... değildir. Daha fazla bağlam için GitHub Arşiv Sağlama Toplamı Kesintisi'ne göz atın.

  • Kaynak ağacının, orijinal kod deposunun düzenine uyduğundan emin olun.

    Deponuz çok büyükse ve gereksiz kaynakları çıkararak daha küçük boyutlu bir dağıtım arşivi oluşturmak istiyorsanız lütfen sadeleştirilmiş 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 aracılığıyla modülü yayın dışı bir sürüme geçirmelerini kolaylaştırır.

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

    Test modülü, yayınlanacak asıl modüle bağlı olarak kaynak arşivinin bir alt dizininde bulunan kendi WORKSPACE ve MODULE.bazel dosyasına sahip bir Bazel projesidir. Test, en yaygın API'lerinizi kapsayan örnekler veya bazı entegrasyon testleri içermelidir. Nasıl oluşturulacağını öğrenmek için test modülünü inceleyin.

Kaynak arşiv URL'niz hazır olduğunda, modülünüzü bir GitHub Pull İsteği ile BCR'ye göndermek için BCR katkı kurallarını uygulayın.

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

En iyi uygulamalar

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

Gereksiz bağımlılıkları getirmekten kaçınmak için hedefleri farklı paketlere bölün.

Testlere yönelik geliştirici bağımlılıklarının, bunlara ihtiyacı olmayan derleme hedefleri için gereksiz yere getirilmesine zorlandığı #12835 bölümünü kontrol edin. Bu aslında Bzlmod'a özgü değildir ancak bu uygulamaların izlenmesi geliştirici bağımlılıklarını doğru şekilde belirtmeyi kolaylaştırır.

Geliştirici bağımlılıklarını belirtin

bazel_dep ve use_extension yönergeleri için dev_dependency özelliğini "true" olarak ayarlayabilirsiniz. Böylece bu yönerge, bağımlı projelere yayılmaz. Kök modül olarak, hedeflerinizin hâlâ geliştirici bağımlıları olmadan derlenip derlenmediğini doğrulamak için --ignore_dev_dependency işaretini kullanabilirsiniz.

Topluluk taşıma işlemi ilerleme durumu

Bağımlılıklarınızın hâlihazırda mevcut olup olmadığını öğrenmek için Bazel Central Registry'ye göz atabilirsiniz. Aksi takdirde, taşıma işleminizi engelleyen bağımlılıkları onaylamak 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. Geçişin önündeki engelleri kaldırmanızı sağlayabilecek yeni sorunlar veya özellik istekleri göndermekten çekinmeyin.