Bzlmod Taşıma Kılavuzu

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

WORKSPACE vs 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ümlerinde, çalışma alanınızın kökünde WORKSPACE veya WORKSPACE.bazel dosyası hâlâ mevcuttur. Bu dosyada aşağıdaki gibi yorumlar bulunabilir:

• 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 komut için geçerli olması amacıyla common komutuna uygulayın:

• .bazelrc

  # Enable Bzlmod for every Bazel command
  common --enable_bzlmod
  

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

• WORKSPACE

  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 hedef //foo:bar, @<workspace name>//foo:bar olarak referans verilebilir. Belirtilmemişse ç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 dizimi kullanmanız gerekiyorsa depo adı olarak module işlevi tarafından belirtilen modül adını kullanabilirsiniz. Modül adı, gerekli depolama alanı adından farklıysa depolama alanı 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 benimsediğinde Bazel modülü olarak bu projeye 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, kullanıcıların geçişli bağımlılıkları bağımlılık makrosundan yüklemesi yaygın bir kalıptır. Hem bazel_skylib hem de rules_java'un platform'e 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 Merkezi Kaydı'nda veya özel Bazel kaydınızda mevcut 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, 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ı şekillerde geçersiz kılabilirsiniz.

Daha fazla bilgi için lütfen üstlenmeler 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.

• 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, MODULE.bazel dosyanızdaki use_repo_rule yönergesini kullanarak depoları doğrudan örneklendirebilirsiniz:

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

  Depoyu kök projeye görünür hale getirmek için MODULE.bazel dosyasında modül uzantısının ve deposunun kullanımlarını belirtmeniz 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 dış bağımlılıkların çakışması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 bir çakışmaya neden oluyorsa 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
    )

• WORKSPACE

  WORKSPACE ile makroyu @foo'ten yükleyebilir ve ihtiyacınız olan veri bağımlılığının 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ının ihtiyaç duyduğu sürümü almak için WORKSPACE'teki makroların sırasını dikkatlice ayarlaması gerekir. Bağımlılıkları çözmek için mantıklı bir yöntem sunmadığından bu, Workspace'in 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 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ü, bağımlılık modülü bar ise 3.0 sürümünü gerektirir. 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ümde de belirtildiği gibi, modül uzantısı, bağımlılık grafiğinden bilgi toplama, bağımlılıklarını çözmek için özel mantık yürütme ve harici depoları tanıtmak için depo kurallarını çağırma olanağı sağladığından, kural yazarlarının belirli diller için paket yöneticilerini entegre eden kural kümelerini geliştirmesi için mükemmel bir yöntemdir.

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ık almak için Bzlmod'u halihazırda benimsemiş kural kümelerinin listesi aşağıda verilmiştir:

• rules_jvm_external
• rules_go
• rules_python

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 kullanılabildiğini algılaması gerektiğinde, ana makineyi incelemek ve araç zinciri bilgilerini harici depolama alanları olarak oluşturmak için depolama alanı 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ümde, araç zinciri bilgilerini barındıran bir depo (ör. local_config_sh) tanıttıktan sonra araç zincirini kaydetmek isteyebilirsiniz.

• WORKSPACE

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

  1. Aracı zincirini .bzl dosyasına 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 kaydedilen 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ı tanıtma

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

• WORKSPACE

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

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

• Bzlmod

  Bzlmod ile, yerel bir yola sahip bir modülü 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ısı içeren yerel bir depo da ekleyebilirsiniz. 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). Ardından, modül uzantısında ilgili starlark local_repository öğesini çağırabilirsiniz. Sizin için engelleyici bir sorunsa local_repository depolama alanı kuralının özel bir sürümünü uygulamak da kolaydır.

Hedefleri bağlama

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. Bu API'ye bağlı tüm kullanıcılar bu API'den geçiş yapmalı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. Aşağıdaki adımları uygulayarak bu durumdan çıkabilirsiniz:

• //external:openssl ifadesinin tüm 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 işleminizle ilgili yararlı bilgiler ve rehberlik 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ğinde, WORKSPACE dosyasına tam olarak hangi bağımlılıkların eklendiğini anlamak zor olabilir.

Workspace'te çözülmüş dosyayla harici bağımlılığı inceleme

Neyse ki işaret --experimental_repository_resolved_file bu konuda 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ıklarla ilgili bilgileri almak için kullanılır.

   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ımları
   • 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 resolved.bzl dosyasında harici bağımlılıklarınızla ilgili bilgilere sahip olursunuz.

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

bazel query'ün, aşağıdaki komutla depo kurallarını incelemek için kullanılabileceğini de biliyor olabilirsiniz:

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

Daha kullanışlı ve çok daha hızlı olsa da bazel sorgusu, harici bağımlılık sürümü hakkında yalan söyleyebilir. Bu nedenle, bu sorguyu kullanırken dikkatli olun. Bzlmod ile harici bağımlılıkları sorgulamak ve incelemek için yeni bir alt komut kullanılacak.

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 birlikte çalışabilir. Bu sayede, WORKSPACE dosyasından Bzlmod'a olan bağımlılıkların kademeli bir şekilde taşınması sağlanır.

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çerli olur ve WORKSPACE içeriği yok sayılır.
• WORKSPACE.bzlmod dosyasına önek veya sonek eklenmemelidir.

WORKSPACE.bzlmod dosyasını kullanmak, taşıma işlemini kolaylaştırabilir. Bunun nedeni:

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

Aşağıda, WORKSPACE da dikkate alınarak farklı türdeki depolardan depo görünürlüğüne dair bir özet verilmiştir.

Taşıma süreci

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

1. WORKSPACE'te hangi bağımlılıklara sahip olduğunuzu 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. Hedeflerinizi Bzlmod etkinken oluşturun ve hangi deponun eksik olduğunu kontrol edin.
5. Çözüme ulaştırılan 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 için WORKSPACE.bzlmod dosyasında 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:

• Çözüme ulaştırılan WORKSPACE dosyasını 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.
• Bir bağımlılığın BCR'de 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ü 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 diğer projeler için bağımlıysa projenizi Bazel Merkezi Kaydı'nda yayınlayabilirsiniz.

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

• Arşivin belirli bir sürümü gösterdiğ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ş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, istek üzerine oluşturulan kaynak arşivlerinin 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 bilgi için GitHub Arşivi Karma'ne göz atın.

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

  Deponuzdan gereksiz kaynakları kaldırarak daha küçük boyutlu bir dağıtım arşivi oluşturmak istiyorsanız lütfen kaldırdığınız 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ın dışı bir sürümle geçersiz kılmalarını kolaylaştırır.

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

  Test modülü, kaynak arşivinin bir alt dizininde bulunan ve yayınlanacak asıl modüle bağlı olan 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şiv URL'niz hazır olduğunda, GitHub çekme isteğiyle modülünüzü 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 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ı getirmemek için hedefleri farklı paketlere bölün.

Testler için geliştirici bağımlılıklarının, bunlara ihtiyaç duymayan hedefleri derlemek için gereksiz yere getirilmesi sorununun ele alındığı #12835 ile ilgili makaleyi inceleyin. Bu aslında Bzlmod'a özgü değildir ancak bu uygulamaları takip etmek, 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ö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şleminizin önündeki engelleri kaldırmaya yardımcı olabilecek yeni sorunlar veya özellik istekleri gönderebilirsiniz.