Bzlmod 이전 가이드

문제 신고 소스 보기 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

WORKSPACE의 단점으로 인해 Bzlmod가 기존 WORKSPACE 시스템을 대체할 예정입니다. WORKSPACE 파일은 Bazel 8 (2024년 말)에서 기본적으로 사용 중지되며 Bazel 9 (2025년 말)에서 삭제됩니다. 이 가이드는 프로젝트를 Bzlmod로 이전하고 외부 종속 항목을 가져오기 위해 WORKSPACE를 삭제하는 데 도움이 됩니다.

WORKSPACE와 Bzlmod 비교

Bazel의 WORKSPACE와 Bzlmod는 서로 다른 문법으로 유사한 기능을 제공합니다. 이 섹션에서는 특정 WORKSPACE 기능을 Bzlmod로 이전하는 방법을 설명합니다.

Bazel 워크스페이스의 루트 정의

WORKSPACE 파일은 Bazel 프로젝트의 소스 루트를 표시합니다. 이 책임은 Bazel 버전 6.3 이상에서 MODULE.bazel로 대체됩니다. Bazel 버전 6.3 미만에서는 작업 영역 루트에 여전히 WORKSPACE 또는 WORKSPACE.bazel 파일이 있어야 하며 다음과 같은 주석이 있을 수 있습니다.

• 워크스페이스

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

bazelrc에서 Bzlmod 사용 설정

.bazelrc를 사용하면 Bazel을 실행할 때마다 적용되는 플래그를 설정할 수 있습니다. Bzlmod를 사용 설정하려면 --enable_bzlmod 플래그를 사용하고 모든 명령어에 적용되도록 common 명령어에 적용합니다.

• .bazelrc

  # Enable Bzlmod for every Bazel command
  common --enable_bzlmod
  

워크스페이스의 저장소 이름 지정

• 워크스페이스

  workspace 함수는 작업공간의 저장소 이름을 지정하는 데 사용됩니다. 이렇게 하면 워크스페이스의 대상 //foo:bar를 @<workspace name>//foo:bar로 참조할 수 있습니다. 지정하지 않으면 워크스페이스의 기본 저장소 이름은 __main__입니다.

  ## WORKSPACE
  workspace(name = "com_foo_bar")
  

• Bzlmod

  @<repo name>가 없는 //foo:bar 문법으로 동일한 워크스페이스의 타겟을 참조하는 것이 좋습니다. 하지만 이전 문법이 필요한 경우 module 함수에서 지정한 모듈 이름을 저장소 이름으로 사용할 수 있습니다. 모듈 이름이 필요한 저장소 이름과 다른 경우 module 함수의 repo_name 속성을 사용하여 저장소 이름을 재정의할 수 있습니다.

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

외부 종속 항목을 Bazel 모듈로 가져오기

종속 항목이 Bazel 프로젝트인 경우 Bzlmod도 채택하는 경우 Bazel 모듈로 종속 항목을 사용할 수 있습니다.

• 워크스페이스

  WORKSPACE를 사용하는 경우 일반적으로 http_archive 또는 git_repository 저장소 규칙을 사용하여 Bazel 프로젝트의 소스를 다운로드합니다.

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

  보시다시피 사용자는 종속 항목의 매크로에서 전이 종속 항목을 로드해야 하는 일반적인 패턴입니다. bazel_skylib와 rules_java가 모두 platform에 종속된다고 가정하면 platform 종속 항목의 정확한 버전은 매크로 순서에 따라 결정됩니다.

• Bzlmod

  Bzlmod를 사용하면 종속 항목을 Bazel Central Registry 또는 맞춤 Bazel 레지스트리에서 사용할 수 있는 한 bazel_dep 디렉티브를 사용하여 종속 항목에 종속할 수 있습니다.

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

  Bzlmod는 MVS 알고리즘을 사용하여 Bazel 모듈 종속 항목을 전이적으로 확인합니다. 따라서 platform의 최대 필수 버전이 자동으로 선택됩니다.

종속 항목을 Bazel 모듈로 재정의

루트 모듈로서 다양한 방법으로 Bazel 모듈 종속 항목을 재정의할 수 있습니다.

자세한 내용은 재정의 섹션을 참고하세요.

예시 저장소에서 몇 가지 사용 예시를 확인할 수 있습니다.

모듈 확장 프로그램으로 외부 종속 항목 가져오기

종속 항목이 Bazel 프로젝트가 아니거나 아직 Bazel 레지스트리에서 사용할 수 없는 경우 use_repo_rule 또는 모듈 확장 프로그램을 사용하여 도입할 수 있습니다.

• 워크스페이스

  http_file 저장소 규칙을 사용하여 파일을 다운로드합니다.

  ## 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를 사용하면 MODULE.bazel 파일에서 use_repo_rule 지시어를 사용하여 저장소를 직접 인스턴스화할 수 있습니다.

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

  이는 모듈 확장 프로그램을 사용하여 구현됩니다. 단순히 저장소 규칙을 호출하는 것보다 더 복잡한 로직을 실행해야 하는 경우 모듈 확장 프로그램을 직접 구현할 수도 있습니다. 정의는 .bzl 파일로 이동해야 하며, 이렇게 하면 이전 기간 동안 WORKSPACE와 Bzlmod 간에 정의를 공유할 수도 있습니다.

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

  종속 항목 매크로를 로드하는 모듈 확장 프로그램을 구현합니다. 매크로와 동일한 .bzl 파일에서 정의할 수 있지만 이전 Bazel 버전과의 호환성을 유지하려면 별도의 .bzl 파일에서 정의하는 것이 좋습니다.

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

  저장소를 루트 프로젝트에 표시하려면 MODULE.bazel 파일에서 모듈 확장 프로그램 및 저장소의 사용을 선언해야 합니다.

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

모듈 확장 프로그램으로 외부 종속 항목 충돌 해결

프로젝트는 호출자의 입력을 기반으로 외부 저장소를 도입하는 매크로를 제공할 수 있습니다. 하지만 종속 항목 그래프에 호출자가 여러 개 있고 충돌이 발생하면 어떻게 해야 할까요?

프로젝트 foo가 version를 인수로 사용하는 다음 매크로를 제공한다고 가정해 보겠습니다.

## 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를 사용하면 @foo에서 매크로를 로드하고 필요한 데이터 종속 항목의 버전을 지정할 수 있습니다. @foo에 종속되지만 다른 버전의 데이터 종속 항목이 필요한 다른 종속 항목 @bar이 있다고 가정해 보겠습니다.

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

  이 경우 최종 사용자는 필요한 버전을 가져오기 위해 워크스페이스에서 매크로의 순서를 신중하게 조정해야 합니다. 이는 WORKSPACE의 가장 큰 문제 중 하나입니다. 종속 항목을 해결하는 적절한 방법을 제공하지 않기 때문입니다.

• Bzlmod

  Bzlmod를 사용하면 프로젝트 foo의 작성자가 모듈 확장 프로그램을 사용하여 충돌을 해결할 수 있습니다. 예를 들어 모든 Bazel 모듈 중에서 항상 데이터 종속 항목의 최대 필수 버전을 선택하는 것이 적절하다고 가정해 보겠습니다.

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

  이 경우 루트 모듈에는 데이터 버전 2.0가 필요하지만 종속 항목 bar에는 3.0가 필요합니다. foo의 모듈 확장 프로그램은 이 충돌을 올바르게 해결하고 데이터 종속 항목의 버전 3.0를 자동으로 선택할 수 있습니다.

서드 파티 패키지 관리자 통합

모듈 확장은 종속 항목 그래프에서 정보를 수집하고, 맞춤 로직을 실행하여 종속 항목을 확인하고, 저장소 규칙을 호출하여 외부 저장소를 도입하는 방법을 제공하므로, 규칙 작성자가 특정 언어의 패키지 관리자를 통합하는 규칙 집합을 개선하는 데 유용합니다.

모듈 확장 프로그램을 사용하는 방법에 관한 자세한 내용은 모듈 확장 프로그램 페이지를 참고하세요.

다음은 이미 Bzlmod를 채택하여 여러 패키지 관리자에서 종속 항목을 가져오는 규칙 집합 목록입니다.

• rules_jvm_external
• rules_go
• rules_python

가상 패키지 관리자를 통합하는 최소한의 예시는 예시 저장소에서 확인할 수 있습니다.

호스트 머신에서 도구 모음 감지

Bazel 빌드 규칙이 호스트 머신에서 사용할 수 있는 도구 모음을 감지해야 하는 경우 저장소 규칙을 사용하여 호스트 머신을 검사하고 도구 모음 정보를 외부 저장소로 생성합니다.

• 워크스페이스

  셸 도구 모음을 감지하는 다음 저장소 규칙이 있습니다.

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

  WORKSPACE에서 저장소 규칙을 로드할 수 있습니다.

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

• Bzlmod

  Bzlmod를 사용하면 모듈 확장 프로그램을 사용하여 동일한 저장소를 도입할 수 있습니다. 이는 지난 섹션에서 @data_file 저장소를 도입하는 것과 유사합니다.

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

  그런 다음 MODULE.bazel 파일에서 확장자를 사용합니다.

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

도구 모음 및 실행 플랫폼 등록

마지막 섹션에 따라 도구 모음 정보를 호스팅하는 저장소 (예: local_config_sh)를 도입한 후에는 도구 모음을 등록하는 것이 좋습니다.

• 워크스페이스

  WORKSPACE를 사용하면 다음과 같은 방법으로 도구 모음을 등록할 수 있습니다.

  1. .bzl 파일에 도구 모음을 등록하고 WORKSPACE 파일에 매크로를 로드할 수 있습니다.

     ## 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. 또는 WORKSPACE 파일에 도구 모음을 직접 등록합니다.

     ## 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를 사용하면 register_toolchains 및 register_execution_platforms API를 MODULE.bazel 파일에서만 사용할 수 있습니다. 모듈 확장 프로그램에서는 native.register_toolchains를 호출할 수 없습니다.

  ## 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, 각 Bazel 모듈의 MODULE.bazel 파일에 등록된 도구 모음 및 실행 플랫폼은 도구 모음 선택 중에 다음 우선순위를 따릅니다 (가장 높은 순서부터 낮은 순서까지).

1. 루트 모듈의 MODULE.bazel 파일에 등록된 도구 모음 및 실행 플랫폼
2. WORKSPACE 또는 WORKSPACE.bzlmod 파일에 등록된 도구 모음 및 실행 플랫폼
3. 루트 모듈의 (전이적) 종속 항목인 모듈에 의해 등록된 도구 모음 및 실행 플랫폼
4. WORKSPACE.bzlmod를 사용하지 않는 경우: WORKSPACE 접미사에 등록된 도구 모음

로컬 저장소 소개

디버깅을 위해 종속 항목의 로컬 버전이 필요하거나 작업공간에 디렉터리를 외부 저장소로 통합하려는 경우 종속 항목을 로컬 저장소로 도입해야 할 수 있습니다.

• 워크스페이스

  WORKSPACE에서는 두 가지 네이티브 저장소 규칙인 local_repository 및 new_local_repository를 사용하여 이 작업을 실행합니다.

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

• Bzlmod

  Bzlmod를 사용하면 local_path_override를 사용하여 로컬 경로로 모듈을 재정의할 수 있습니다.

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

  참고: local_path_override를 사용하면 로컬 디렉터리를 Bazel 모듈로만 도입할 수 있습니다. 즉, MODULE.bazel 파일이 있어야 하며 종속 항목 확인 중에 그 전이 종속 항목이 고려됩니다. 또한 모든 모듈 재정의 디렉티브는 루트 모듈에서만 사용할 수 있습니다.

  모듈 확장자가 있는 로컬 저장소를 도입할 수도 있습니다. 그러나 모듈 확장 프로그램에서는 native.local_repository를 호출할 수 없습니다. 모든 네이티브 저장소 규칙을 Starlark로 변환하기 위한 작업이 진행 중입니다 (진행 상황은 #18285를 확인하세요). 그런 다음 모듈 확장 프로그램에서 해당하는 Starlark local_repository를 호출할 수 있습니다. 이 문제가 차단 문제인 경우 맞춤 버전의 local_repository 저장소 규칙을 구현하는 것도 간단합니다.

타겟 바인딩

WORKSPACE의 bind 규칙은 지원 중단되었으며 Bzlmod에서 지원되지 않습니다. 이는 특수 //external 패키지에서 타겟에 별칭을 지정하기 위해 도입되었습니다. 이를 사용하는 모든 사용자는 이전해야 합니다.

예를 들어, 영역 1에

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

이렇게 하면 다른 타겟이 //external:openssl에 종속될 수 있습니다. 다음과 같이 이전할 수 있습니다.

• //external:openssl의 모든 사용을 @my-ssl//src:openssl-lib로 바꿉니다.

• 또는 alias 빌드 규칙을 사용합니다.

  • 패키지에서 다음 타겟을 정의합니다 (예: //third_party).

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

  • //external:openssl의 모든 사용을 //third_party:openssl로 바꿉니다.

가져오기와 동기화 비교

가져오기 및 동기화 명령어는 외부 저장소를 로컬로 다운로드하고 업데이트된 상태로 유지하는 데 사용됩니다. 빌드에 필요한 모든 저장소를 가져온 후 --nofetch 플래그를 사용하여 오프라인 빌드를 허용하는 경우도 있습니다.

• 워크스페이스

  동기화는 모든 저장소 또는 구성된 특정 저장소 세트에 대해 강제 가져오기를 실행하는 반면 가져오기는 특정 타겟을 가져오는 데 만 사용됩니다.

• Bzlmod

  동기화 명령어는 더 이상 적용되지 않지만 가져오기에는 다양한 옵션이 있습니다. 대상, 저장소, 구성된 저장소 집합 또는 종속 항목 확인 및 모듈 확장에 관련된 모든 저장소를 가져올 수 있습니다. 가져오기 결과는 캐시되며 가져오기를 강제하려면 가져오기 프로세스 중에 --force 옵션을 포함해야 합니다.

마이그레이션

이 섹션에서는 Bzlmod 이전 프로세스에 관한 유용한 정보와 안내를 제공합니다.

WORKSPACE의 종속 항목 알아보기

이전의 첫 번째 단계는 어떤 종속 항목이 있는지 파악하는 것입니다. 전이 종속 항목은 *_deps 매크로로 로드되는 경우가 많으므로 WORKSPACE 파일에 도입된 정확한 종속 항목을 파악하기 어려울 수 있습니다.

워크스페이스에서 확인된 파일로 외부 종속 항목 검사

다행히 --experimental_repository_resolved_file 플래그를 사용하면 이 문제를 해결할 수 있습니다. 이 플래그는 기본적으로 마지막 Bazel 명령어에서 가져온 모든 외부 종속 항목의 '잠금 파일'을 생성합니다. 자세한 내용은 이 블로그 게시물을 참고하세요.

다음 두 가지 방법으로 사용할 수 있습니다.

1. 특정 타겟을 빌드하는 데 필요한 외부 종속 항목의 정보를 가져옵니다.

   bazel clean --expunge
   bazel build --nobuild --experimental_repository_resolved_file=resolved.bzl //foo:bar
   

2. WORKSPACE 파일에 정의된 모든 외부 종속 항목의 정보를 가져옵니다.

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

   bazel sync 명령어를 사용하면 WORKSPACE 파일에 정의된 모든 종속 항목을 가져올 수 있습니다. 여기에는 다음이 포함됩니다.

   • bind 사용
   • register_toolchains 및 register_execution_platforms 사용

   그러나 프로젝트가 크로스 플랫폼인 경우 일부 저장소 규칙이 지원되는 플랫폼에서만 올바르게 실행될 수 있으므로 특정 플랫폼에서 bazel 동기화가 중단될 수 있습니다.

명령어를 실행하면 resolved.bzl 파일에 외부 종속 항목에 관한 정보가 있어야 합니다.

bazel query로 외부 종속 항목 검사

bazel query를 사용하여 다음과 같이 저장소 규칙을 검사할 수도 있습니다.

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

더 편리하고 훨씬 빠르지만 bazel 쿼리는 외부 종속 항목 버전에 관해 거짓말을 할 수 있습니다. 따라서 주의해서 사용하세요. Bzlmod를 사용하여 외부 종속 항목을 쿼리하고 검사하는 작업은 새로운 하위 명령어로 실행됩니다.

기본 제공되는 기본 종속 항목

--experimental_repository_resolved_file로 생성된 파일을 확인하면 WORKSPACE에 정의되지 않은 많은 종속 항목이 표시됩니다. 이는 Bazel이 실제로 사용자의 WORKSPACE 파일 콘텐츠에 접두사와 접미사를 추가하여 일반적으로 네이티브 규칙 (예: @bazel_tools, @platforms, @remote_java_tools)에 필요한 일부 기본 종속 항목을 삽입하기 때문입니다. Bzlmod를 사용하면 이러한 종속 항목이 다른 모든 Bazel 모듈의 기본 종속 항목인 내장 모듈 bazel_tools로 도입됩니다.

점진적 이전을 위한 하이브리드 모드

Bzlmod와 WORKSPACE는 나란히 작동할 수 있으므로 WORKSPACE 파일에서 Bzlmod로 종속 항목을 점진적으로 이전할 수 있습니다.

참고: 실제로 WORKSPACE에서 '*_deps' 매크로를 로드하면 Bzlmod 종속 항목과 혼동이 발생하는 경우가 많으므로 WORKSPACE.bzlmod 파일로 시작하고 매크로로 전이 종속 항목을 로드하지 않는 것이 좋습니다.

WORKSPACE.bzlmod

이전하는 동안 Bazel 사용자는 Bzlmod가 사용 설정된 빌드와 사용 중지된 빌드 간에 전환해야 할 수 있습니다. WORKSPACE.bzlmod 지원이 구현되어 프로세스가 더 원활해집니다.

WORKSPACE.bzlmod의 구문은 WORKSPACE와 정확히 동일합니다. Bzlmod가 사용 설정되어 있고 WORKSPACE.bzlmod 파일이 작업공간 루트에 있는 경우:

• WORKSPACE.bzlmod가 적용되고 WORKSPACE의 콘텐츠는 무시됩니다.
• WORKSPACE.bzlmod 파일에 접두사 또는 접미사가 추가되지 않았습니다.

WORKSPACE.bzlmod 파일을 사용하면 다음과 같은 이유로 이전이 더 쉬워집니다.

• Bzlmod가 사용 중지되면 원래 WORKSPACE 파일에서 종속 항목을 가져오는 대체 방법이 사용됩니다.
• Bzlmod가 사용 설정되면 WORKSPACE.bzlmod를 사용하여 이전할 종속 항목을 더 잘 추적할 수 있습니다.

저장소 공개 상태

Bzlmod는 지정된 저장소에서 표시되는 다른 저장소를 제어할 수 있습니다. 자세한 내용은 저장소 이름 및 엄격한 종속 항목을 참고하세요.

다음은 WORKSPACE도 고려할 때 다양한 유형의 저장소의 저장소 공개 상태를 요약한 것입니다.

	기본 저장소에서	Bazel 모듈 저장소	모듈 확장 저장소에서	WORKSPACE 저장소에서
기본 저장소	표시	루트 모듈이 직접 종속 항목인 경우	루트 모듈이 모듈 확장 프로그램을 호스팅하는 모듈의 직접 종속 항목인 경우	표시
Bazel 모듈 저장소	직접 종속 항목	직접 종속 항목	모듈 확장 프로그램을 호스팅하는 모듈의 직접 종속 항목	루트 모듈의 직접 종속 항목
모듈 확장 프로그램 저장소	직접 종속 항목	직접 종속 항목	모듈 확장 프로그램을 호스팅하는 모듈의 직접 종속 항목 + 동일한 모듈 확장 프로그램에서 생성된 모든 저장소	루트 모듈의 직접 종속 항목
Workspace 저장소	모두 표시	표시 안 됨	표시 안 됨	모두 표시

참고: 루트 모듈의 경우 저장소 @foo가 WORKSPACE에 정의되어 있고 @foo가 MODULE.bazel에서 표시 저장소 이름으로 사용되는 경우 @foo는 MODULE.bazel에 도입된 저장소를 참조합니다.

참고: 모듈 확장 생성 저장소 @bar의 경우 @foo가 동일한 모듈 확장으로 생성된 다른 저장소의 표시 저장소 이름으로 사용되고 모듈 확장 프로그램을 호스팅하는 모듈의 직접 종속 항목으로 사용되는 경우 저장소 @bar의 경우 @foo는 후자를 참조합니다.

마이그레이션 프로세스

일반적인 Bzlmod 이전 프로세스는 다음과 같습니다.

1. WORKSPACE에 있는 종속 항목을 이해합니다.
2. 프로젝트 루트에 빈 MODULE.bazel 파일을 추가합니다.
3. 빈 WORKSPACE.bzlmod 파일을 추가하여 WORKSPACE 파일 콘텐츠를 재정의합니다.
4. Bzlmod를 사용 설정하여 타겟을 빌드하고 누락된 저장소를 확인합니다.
5. 해결된 종속 항목 파일에서 누락된 저장소의 정의를 확인합니다.
6. 모듈 확장 프로그램을 통해 누락된 종속 항목을 Bazel 모듈로 도입하거나 나중에 이전할 수 있도록 WORKSPACE.bzlmod에 두세요.
7. 4단계로 돌아가서 모든 종속 항목을 사용할 수 있을 때까지 반복합니다.

마이그레이션 도구

시작하는 데 도움이 되는 대화형 Bzlmod 이전 도우미 스크립트가 있습니다.

스크립트는 다음을 실행합니다.

• WORKSPACE 확인된 파일을 생성하고 파싱합니다.
• 사람이 읽을 수 있는 방식으로 확인된 파일의 저장소 정보를 출력합니다.
• bazel build 명령어를 실행하고 인식된 오류 메시지를 감지하며 이전 방법을 추천합니다.
• BCR에서 종속 항목을 이미 사용할 수 있는지 확인합니다.
• MODULE.bazel 파일에 종속 항목을 추가합니다.
• 모듈 확장 프로그램을 통해 종속 항목을 추가합니다.
• WORKSPACE.bzlmod 파일에 종속 항목을 추가합니다.

이를 사용하려면 최신 Bazel 출시 버전이 설치되어 있는지 확인하고 다음 명령어를 실행합니다.

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>

참고: 마이그레이션 스크립트는 완벽하지 않으며 Bzlmod가 발전함에 따라 최신 버전이 아닐 수 있습니다. 항상 권장 솔루션이 올바른지 다시 확인하세요.

Bazel 모듈 게시

Bazel 프로젝트가 다른 프로젝트의 종속 항목인 경우 Bazel Central Registry에 프로젝트를 게시할 수 있습니다.

BCR에서 프로젝트를 체크인하려면 프로젝트의 소스 보관 파일 URL이 필요합니다. 소스 보관 파일을 만들 때 다음 사항에 유의하세요.

• 보관 파일이 특정 버전을 가리키고 있는지 확인합니다.

  Bzlmod는 종속 항목 확인 중에 버전 비교를 실행해야 하므로 BCR은 버전이 지정된 소스 보관 파일만 수용할 수 있습니다.

• 보관처리 URL이 안정적인지 확인합니다.

  Bazel은 해시 값으로 보관 파일의 콘텐츠를 확인하므로 다운로드한 파일의 체크섬이 변경되지 않도록 해야 합니다. GitHub의 URL인 경우 출시 페이지에서 출시 보관 파일을 만들고 업로드하세요. GitHub는 주문 시 생성된 소스 보관 파일의 체크섬을 보장하지 않습니다. 요약하자면 https://github.com/<org>/<repo>/releases/download/... 형식의 URL은 안정적인 것으로 간주되지만 https://github.com/<org>/<repo>/archive/...는 그렇지 않습니다. 자세한 내용은 GitHub 보관 파일 체크섬 서비스 중단을 참고하세요.

• 소스 트리가 원래 저장소의 레이아웃을 따르는지 확인합니다.

  저장소가 매우 크고 불필요한 소스를 제거하여 크기가 줄어든 배포 보관 파일을 만들려는 경우 제거된 소스 트리가 원래 소스 트리의 하위 집합인지 확인하세요. 이렇게 하면 최종 사용자가 archive_override 및 git_override를 사용하여 모듈을 출시되지 않은 버전으로 재정의하기가 더 쉬워집니다.

• 가장 일반적인 API를 테스트하는 하위 디렉터리에 테스트 모듈을 포함합니다.

  테스트 모듈은 자체 WORKSPACE 및 MODULE.bazel 파일이 소스 보관 파일의 하위 디렉터리에 있는 Bazel 프로젝트로, 게시할 실제 모듈에 종속됩니다. 여기에는 가장 일반적인 API를 다루는 예시나 몇 가지 통합 테스트가 포함되어야 합니다. 테스트 모듈에서 설정 방법을 확인하세요.

소스 보관 파일 URL이 준비되면 BCR 참여 가이드라인에 따라 GitHub 풀 리퀘스트를 사용하여 BCR에 모듈을 제출합니다.

저장소에 BCR에 게시 GitHub 앱을 설정하여 BCR에 모듈을 제출하는 프로세스를 자동화하는 것이 매우 좋습니다.

권장사항

이 섹션에서는 외부 종속 항목을 더 효과적으로 관리하기 위해 따라야 하는 몇 가지 권장사항을 설명합니다.

불필요한 종속 항목을 가져오지 않도록 타겟을 여러 패키지로 분할합니다.

테스트에 필요한 개발자 종속 항목이 필요하지 않은 타겟을 빌드하기 위해 불필요하게 가져와야 하는 #12835를 확인하세요. 이는 실제로 Bzlmod에만 해당하는 것은 아니지만 이 관행을 따르면 개발 종속 항목을 더 쉽게 올바르게 지정할 수 있습니다.

개발 종속 항목 지정

bazel_dep 및 use_extension 디렉티브가 종속 프로젝트로 전파되지 않도록 dev_dependency 속성을 true로 설정할 수 있습니다. 루트 모듈로 --ignore_dev_dependency 플래그를 사용하여 개발 종속 항목 및 재정의 없이도 타겟이 여전히 빌드되는지 확인할 수 있습니다.

커뮤니티 이전 진행 상황

Bazel Central Registry에서 종속 항목을 이미 사용할 수 있는지 확인할 수 있습니다. 그렇지 않은 경우 언제든지 이 GitHub 토론에 참여하여 이전을 차단하는 종속 항목에 찬성 투표하거나 게시할 수 있습니다.

문제 신고

알려진 Bzlmod 문제는 Bazel GitHub 문제 목록을 확인하세요. 이전을 차단하는 데 도움이 되는 새로운 문제나 기능 요청을 언제든지 제출하세요.