Bzlmod Taşıma Kılavuzu

Sorun bildirme Kaynağı görüntüleme Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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 dizimi ile 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ümlerde MODULE.bazel ile değiştirilir. 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:

  • 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 common komutuna uygulayarak tüm komutlara uygulayın:

  • .bazelrc

    # Enable Bzlmod for every Bazel command
common --enable_bzlmod

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

  • ÇALIŞMA ALANI

    workspace işlevi, çalışma alanınız için bir 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ındaki hedeflere @<repo name> olmadan //foo:bar söz dizimini kullanarak 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 benimsediğinde ona Bazel modülü olarak bağımlı olabilirsiniz.

  • WORKSPACE

    WORKSPACE'te, Bazel projesinin kaynaklarını indirmek için http_archive veya git_repository depo kurallarının kullanılması 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 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'un platform'ye 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 çözer. Bu nedenle, platform için gereken en yüksek sürüm otomatik olarak seçilir.

Bir bağımlılık için 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 geçersiz kılmalar 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 mevcut değilse use_repo_rule veya modül uzantılarını kullanarak tanıtabilirsiniz.

  • WORKSPACE

    http_file depolama alanı 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ızdaki 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 işlem, modül uzantısı kullanılarak uygulanır. Yalnızca bir depo kuralını çağırmaktan daha karmaşık mantık yürütmeniz gerekiyorsa modül uzantısını kendiniz de uygulayabilirsiniz. Tanımlamayı bir .bzl dosyasına taşımanız gerekir. Bu, taşıma döneminde tanımı WORKSPACE ile 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. Bu işlevi makronun bulunduğu .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

Bir proje, arayanlardan gelen girişlere göre 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
    )

  • WORKSPACE

    WORKSPACE ile makroyu @foo kaynağından yükleyebilir ve ihtiyacınız olan veri bağımlılığı sürümünü belirtebilirsiniz. @foo'a da bağlı olan ancak veri bağımlılığının farklı bir sürümünü 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ı 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ığının her zaman en yüksek gerekli 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 2.0 veri sürümünü gerektirirken bar bağımlılığı için 3.0 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ü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 burada bulabilirsiniz:

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

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.

  • WORKSPACE

    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, modül uzantısı kullanarak aynı deposu tanıtabilirsiniz. Bu, son bölümde @data_file deposunu tanıtmaya 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ında 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.

  • WORKSPACE

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

  1. kök modülün MODULE.bazel dosyasına kayıtlı araç zincirleri ve yürütme platformları.
  2. WORKSPACE veya WORKSPACE.bzlmod dosyasına kayıtlı 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 ekinde kayıtlı araç zincirleri.

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.

  • WORKSPACE

    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 aracını 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 çağrısı yapamazsınız. Tüm yerel depo kurallarının Starlark'a dönüştürülmesi için çalışmalar devam etmektedir (ilerleme durumu için #18285 konusuna 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 sayede diğer hedefler //external:openssl'e bağlı olabilir. 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.

  • Dilerseniz alias derleme kuralını da kullanabilirsiniz.

    • Bir 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-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ı öğrenme

Taşıma işleminin ilk adımı, hangi bağımlılıklara sahip olduğunuzu 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ı anlamak 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, temel olarak son Bazel komutunuzda getirilen tüm harici bağımlılıkların "kilit dosyasını" oluşturur. Daha fazla bilgiyi bu blog yayınında bulabilirsiniz.

Bu özellik iki şekilde kullanılabilir:

  1. Belirli hedefleri oluşturmak için gereken harici bağımlılıklarla ilgili bilgileri almak için.

    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 arasında şunlar yer alır:

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

    Ancak projeniz platformlar arasıysa bazı depo kuralları yalnızca desteklenen platformlarda düzgün şekilde çalışabileceğinden bazel senkronizasyonu belirli platformlarda 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

bazel query işlevinin 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ımlanmayan birçok bağımlılık görürsünüz. 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 dosya içeriğine ön ekler ve son ekler 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 tanıtılır.

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 kolaylaştırmak 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 WORKSPACE.bzlmod dosyası da varsa:

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

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

  • 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 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ünür olacağını kontrol edebilir. Daha fazla bilgi için depo adları ve katı bağımlılar bölümüne bakın.

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ısı 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 ödemeler Modül uzantısını barındıran modülün doğrudan bağımlılıkları Kök modülün doğrudan açıklamaları
Modül uzantısı depoları Doğrudan satış Doğrudan deps Modül uzantısını barındıran modülün doğrudan bağımlılıkları ve aynı modül uzantısı tarafından oluşturulan tüm depolar Kök modülün doğrudan açıklamaları
WORKSPACE Depoları Tümü görünür durumda Görünmez Görünmez Tümü görünür durumda

Taşıma süreci

Tipik bir Bzlmod taşıma işlemi aşağıdaki gibi görünebilir:

  1. WORKSPACE'te hangi bağımlılıklarınızın olduğunu anlayın.
  2. Proje kökü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 olacak şekilde hedeflerinizi oluşturun ve hangi depoda eksiklik 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ığı bir modül uzantısı aracılığıyla Bazel modülü olarak sunun veya daha sonra taşımak için WORKSPACE.bzlmod içinde bırakın.
  7. 4. adıma geri dönün ve tüm bağımlılıklar kullanılabilir hale gelene kadar işlemi 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ümlenen dosyayı oluşturun ve ayrıştırın.
  • Çözüme ulaştırılan dosyadaki depo bilgilerini kullanıcılar tarafından okunabilir şekilde yazdırın.
  • bazel build komutunu çalıştırın, tanınan hata mesajlarını algılayın ve taşıma yöntemi önerin.
  • BCR'de halihazırda bir bağımlılık 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ü yüklediğinizden 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ınlama

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

Projenizi BCR'de kontrol edebilmek için projenin kaynak arşiv URL'sine ihtiyacınız vardır. Kaynak arşivi oluştururken dikkate almanız gereken birkaç nokta vardır:

  • 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ı yapması gerektiğinden BCR yalnızca sürümlendirilmiş kaynak arşivleri kabul edebilir.

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

    Bazel, arşiv içeriğini bir karma değeriyle doğrular. Bu nedenle, indirilen dosyanın sağlaması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ı kabul edilirken https://github.com/<org>/<repo>/archive/... biçimindeki URL'ler kararlı kabul edilmez. Daha fazla içerik için GitHub Arşiv Denetimi Toplamı Kesinti'yi kontrol edin.

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

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

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

    Test modülü, yayınlanacak gerçek modüle bağlı olan kaynak arşivin bir alt dizininde yer alan ve kendi WORKSPACE ve MODULE.bazel dosyalarının bulunduğu 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ünü kontrol edin.

Kaynak arşiv URL'niz hazır olduğunda, modülünüzü GitHub Çekme İsteği ile BCR'ye göndermek için BCR ekleme yönergelerini uygulayın.

Modülünüzü BCR'ye gönderme sürecini otomatikleştirmek için deponuz için BCR'ye yayınla GitHub uygulamasını ayarlamanızı öneriz.

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ı getirmekten kaçınmak için hedefleri farklı paketlere bölün.

Testler için geliştirici bağımlılıklarının, bunlara ihtiyaç duymayan hedefleri oluşturmak için gereksiz yere getirilmeye zorlandığı #12835 sorununu kontrol edin. Bu, aslında Bzlmod'a özgü değildir ancak bu uygulamaları izleyerek geliştirici bağımlılıklarını doğru bir şekilde belirtmeniz kolaylaşır.

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

bazel_dep ve use_extension yönergelerinin bağımlı projelere yayılmaması için dev_dependency özelliğini true olarak ayarlayabilirsiniz. Kök modül olarak, hedeflerinizin geliştirici bağımlılıkları ve geçersiz kılma işlemleri olmadan derlenip derlenmediğini doğrulamak için --ignore_dev_dependency işaretini kullanabilirsiniz.

Topluluk taşıma işleminin ilerleme durumu

Bağımlılıklarınızın mevcut olup olmadığını öğrenmek için Bazel Merkezi Sicil Dairesi'ni kontrol edebilirsiniz. Aksi takdirde, taşıma işlemini engelleyen bağımlılıkları beğenmek 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 inceleyin. Taşıma işleminin önündeki engelleri kaldırmanızı sağlayacak yeni sorunları bildirebilir veya yeni özellik isteğinde bulunabilirsiniz.