BazelCon 2024 등록이 시작되었습니다

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Bzlmod로 외부 종속 항목 관리

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

Bzlmod는 Bazel 5.0에 도입된 새로운 외부 종속 항목 시스템의 코드명입니다. 기존 시스템의 여러 문제점 중 점진적으로 해결할 수 없는 문제를 해결하기 위해 도입되었습니다. 자세한 내용은 원본 설계 문서의 문제 제기 섹션을 참고하세요.

Bazel 5.0에서는 Bzlmod가 기본적으로 사용 설정되지 않습니다. 다음이 적용되려면 --experimental_enable_bzlmod 플래그를 지정해야 합니다. 플래그 이름에서 알 수 있듯이 이 기능은 현재 실험용입니다. 기능이 공식적으로 출시될 때까지 API와 동작이 변경될 수 있습니다.

프로젝트를 Bzlmod로 마이그레이션하려면 Bzlmod 이전 가이드를 따르세요. examples 저장소에서도 Bzlmod 사용 예시를 확인할 수 있습니다.

Bazel 모듈

이전 WORKSPACE 기반 외부 종속 항목 시스템은 저장소 규칙 (또는 저장소 규칙)을 통해 생성된 저장소 (또는 저장소)를 중심으로 합니다. 저장소는 여전히 새 시스템에서 중요한 개념이지만 모듈이 종속 항목의 핵심 단위입니다.

모듈은 기본적으로 여러 버전이 있을 수 있는 Bazel 프로젝트이며, 각 버전은 종속되는 다른 모듈에 관한 메타데이터를 게시합니다. 이는 다른 종속 항목 관리 시스템의 익숙한 개념(예: Maven 아티팩트, npm 패키지, Cargo 크레이트, Go 모듈 등)과 유사합니다.

모듈은 WORKSPACE의 특정 URL 대신 name 및 version 쌍을 사용하여 종속 항목을 지정합니다. 그런 다음 Bazel 레지스트리(기본적으로 Bazel Central Registry)에서 종속 항목을 조회합니다. 그러면 작업공간에서 각 모듈이 저장소로 변환됩니다.

MODULE.bazel

모든 모듈의 모든 버전에는 종속 항목 및 기타 메타데이터를 선언하는 MODULE.bazel 파일이 있습니다. 다음은 기본 예입니다.

module(
    name = "my-module",
    version = "1.0",
)

bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")

MODULE.bazel 파일은 작업공간 디렉터리의 루트(WORKSPACE 파일 옆)에 있어야 합니다. WORKSPACE 파일과 달리 전이 종속 항목을 지정할 필요가 없습니다. 대신 직접 종속 항목만 지정하면 종속 항목의 MODULE.bazel 파일이 처리되어 전이 종속 항목을 자동으로 찾습니다.

MODULE.bazel 파일은 어떤 형태의 제어 흐름도 지원하지 않으므로 BUILD 파일과 유사합니다. 또한 load 문을 금지합니다. MODULE.bazel 파일에서 지원하는 지시는 다음과 같습니다.

module: 이름, 버전 등을 포함하여 현재 모듈에 관한 메타데이터를 지정합니다.
bazel_dep: 다른 Bazel 모듈의 직접 종속 항목을 지정합니다.
재정의: 루트 모듈 (즉, 종속 항목으로 사용되는 모듈이 아님)에서만 사용하여 특정 직접 또는 전이 종속 항목의 동작을 맞춤설정할 수 있습니다.
모듈 확장과 관련된 디렉티브는 다음과 같습니다.
- use_extension
- use_repo

버전 형식

Bazel에는 다양한 생태계가 있으며 프로젝트는 다양한 버전 관리 스키마를 사용합니다. 가장 인기 있는 것은 SemVer이지만 Abseil과 같이 다른 스키마를 사용하는 유명한 프로젝트도 있습니다. 이 프로젝트의 버전은 날짜 기반(예: 20210324.2)입니다.

이 때문에 Bzlmod는 더 완화된 버전의 SemVer 사양을 채택합니다. 차이점은 다음과 같습니다.

SemVer에 따르면 버전의 '출시' 부분은 MAJOR.MINOR.PATCH 세그먼트 3개로 구성되어야 합니다. Bazel에서는 이 요구사항이 완화되어 세그먼트 수가 얼마든지 허용됩니다.
SemVer에서 '출시' 부분의 각 세그먼트는 숫자만으로 구성되어야 합니다. Bazel에서는 문자도 허용하도록 완화되었으며 비교 시맨틱은 '사전 출시' 부분의 '식별자'와 일치합니다.
또한 주, 부, 패치 버전 증가의 시맨틱은 적용되지 않습니다. 단, 이전 버전과의 호환성을 나타내는 방법에 관한 자세한 내용은 호환성 수준을 참고하세요.

유효한 SemVer 버전은 유효한 Bazel 모듈 버전입니다. 또한 두 SemVer 버전 a 및 b는 Bazel 모듈 버전으로 비교할 때 동일한 경우에만 a < b와 비교됩니다.

버전 확인

다이아몬드 종속 항목 문제는 버전이 지정된 종속 항목 관리 공간의 기본입니다. 다음과 같은 종속 항목 그래프가 있다고 가정해 보겠습니다.

       A 1.0
      /     \
   B 1.0    C 1.1
     |        |
   D 1.0    D 1.1

어떤 버전의 D를 사용해야 하나요? 이 문제를 해결하기 위해 Bzlmod는 Go 모듈 시스템에 도입된 최소 버전 선택(MVS) 알고리즘을 사용합니다. MVS는 모듈의 모든 새 버전이 이전 버전과 호환된다고 가정하고 종속 항목에서 지정한 가장 높은 버전 (이 예에서는 D 1.1)을 선택합니다. 여기서 D 1.1은 요구사항을 충족할 수 있는 최소 버전이므로 '최소'라고 합니다. D 1.2 이상 버전이 있더라도 선택하지 않습니다. 이렇게 하면 버전 선택이 고화질이고 재현 가능이라는 추가 이점이 있습니다.

버전 확인은 레지스트리가 아닌 로컬 머신에서 실행됩니다.

호환성 수준

MVS는 이전 버전과 호환되지 않는 모듈 버전을 별도의 모듈로 간단히 처리하므로 이전 버전과의 호환성에 관한 MVS의 가정은 실행 가능합니다. SemVer 측면에서 이는 A 1.x와 A 2.x가 서로 다른 모듈로 간주되며, 확인된 종속 항목 그래프에 공존할 수 있음을 의미합니다. 이는 주 버전이 Go의 패키지 경로에 인코딩되어 컴파일 시간 또는 연결 시간 충돌이 없기 때문에 가능합니다.

Bazel에서는 이러한 보장이 없습니다. 따라서 이전 버전과 호환되지 않는 버전을 감지하려면 '주 버전' 번호를 나타내는 방법이 필요합니다. 이 숫자를 호환성 수준이라고 하며 module() 디렉티브의 각 모듈 버전에서 지정합니다. 이 정보를 바탕으로, 해결된 종속 항목 그래프에 호환성 수준이 다른 동일한 모듈의 버전이 있는 것을 감지하면 오류를 발생시킬 수 있습니다.

저장소 이름

Bazel에서는 모든 외부 종속 항목에 저장소 이름이 있습니다. 동일한 종속 항목이 다른 저장소 이름을 통해 사용될 수도 있고 (예: @io_bazel_skylib와 @bazel_skylib 모두 Bazel skylib를 의미함) 동일한 저장소 이름이 여러 프로젝트의 여러 종속 항목에 사용될 수도 있습니다.

Bzlmod에서는 Bazel 모듈과 모듈 확장 프로그램으로 저장소를 생성할 수 있습니다. 저장소 이름 충돌을 해결하기 위해 새 시스템에서 저장소 매핑 메커니즘을 채택하고 있습니다. 다음은 두 가지 중요한 개념입니다.

표준 저장소 이름: 각 저장소의 전 세계적으로 고유한 저장소 이름입니다. 저장소가 있는 디렉터리 이름입니다.
다음과 같이 구성됩니다 (경고: 표준 이름 형식은 종속해야 하는 API가 아니며 언제든지 변경될 수 있음).
- Bazel 모듈 저장소의 경우: module_name~version
  (예: @bazel_skylib~1.0.3)
- 모듈 확장 저장소의 경우 module_name~version~extension_name~repo_name
  (예: @rules_cc~0.0.1~cc_configure~local_config_cc)
표시 저장소 이름: 저장소 내 BUILD 및 .bzl 파일에 사용될 저장소 이름입니다. 동일한 종속 항목이 저장소마다 다른 표시 이름을 가질 수 있습니다.
다음과 같이 결정됩니다.
- Bazel 모듈 저장소의 경우 기본적으로 module_name이거나 bazel_dep의 repo_name 속성으로 지정된 이름입니다.
- 모듈 확장 프로그램 저장소의 경우 use_repo를 통해 도입된 저장소 이름입니다.

모든 저장소에는 직접 종속 항목의 저장소 매핑 사전이 있습니다. 이 사전은 표시된 저장소 이름에서 표준 저장소 이름으로의 매핑입니다. 라벨을 구성할 때 저장소 매핑을 사용하여 저장소 이름을 확인합니다. 표준 저장소 이름은 충돌하지 않으며 표시된 저장소 이름의 사용은 MODULE.bazel 파일을 파싱하여 확인할 수 있으므로 다른 종속 항목에 영향을 주지 않고 충돌을 쉽게 포착하고 해결할 수 있습니다.

엄격한 종속 항목

새로운 종속 항목 사양 형식을 사용하면 더 엄격한 검사를 실행할 수 있습니다. 특히 이제 모듈은 직접 종속 항목에서 생성된 저장소만 사용할 수 있습니다. 이렇게 하면 전이 종속 항목 그래프의 항목이 변경될 때 실수로 인해 디버그하기 어려운 중단이 방지됩니다.

엄격한 종속 항목은 저장소 매핑을 기반으로 구현됩니다. 기본적으로 각 저장소의 저장소 매핑에는 모든 직접 종속 항목이 포함되며 다른 저장소는 표시되지 않습니다. 각 저장소의 표시되는 종속 항목은 다음과 같이 결정됩니다.

Bazel 모듈 저장소는 bazel_dep 및 use_repo를 통해 MODULE.bazel 파일에 도입된 모든 저장소를 볼 수 있습니다.
모듈 확장 저장소는 확장 프로그램을 제공하는 모듈의 모든 표시된 종속 항목과 동일한 모듈 확장 프로그램에서 생성된 다른 모든 저장소를 볼 수 있습니다.

레지스트리

Bzlmod는 Bazel 레지스터에서 정보를 요청하여 종속 항목을 찾습니다. Bazel 레지스트리는 단순히 Bazel 모듈의 데이터베이스입니다. 지원되는 유일한 레지스트리 형식은 특정 형식을 따르는 로컬 디렉터리 또는 정적 HTTP 서버인 색인 레지스트리입니다. 향후 프로젝트의 소스 및 기록이 포함된 git 저장소인 단일 모듈 레지스트리에 대한 지원을 추가할 계획입니다.

색인 레지스트리

색인 레지스트리는 홈페이지, 유지관리자, 각 버전의 MODULE.bazel 파일, 각 버전의 소스를 가져오는 방법을 비롯한 모듈 목록에 관한 정보가 포함된 로컬 디렉터리 또는 정적 HTTP 서버입니다. 특히 소스 보관 파일 자체를 제공할 필요는 없습니다.

색인 레지스트리는 다음 형식을 따라야 합니다.

/bazel_registry.json: 다음과 같은 레지스터의 메타데이터가 포함된 JSON 파일입니다.
- mirrors: 소스 보관 파일에 사용할 미러 목록을 지정합니다.
- module_base_path: source.json 파일에서 local_repository 유형의 모듈의 기본 경로를 지정합니다.
/modules: 이 레지스트리의 각 모듈에 대한 하위 디렉터리가 포함된 디렉터리입니다.
/modules/$MODULE: 이 모듈의 각 버전에 관한 하위 디렉터리와 다음 파일이 포함된 디렉터리입니다.
- metadata.json: 모듈에 관한 정보가 포함된 JSON 파일로 다음 필드가 있습니다.
  - homepage: 프로젝트 홈페이지의 URL입니다.
  - maintainers: 각각 레지스트리의 모듈 유지보여자 정보에 해당하는 JSON 객체 목록입니다. 이는 프로젝트의 작성자와 반드시 동일하지는 않습니다.
  - versions: 이 레지스트리에서 찾을 수 있는 이 모듈의 모든 버전 목록입니다.
  - yanked_versions: 이 모듈의 삭제된 버전 목록입니다. 현재는 아무 일도 일어나지 않지만 향후에는 삭제된 버전이 건너뛰어지거나 오류가 발생합니다.
/modules/$MODULE/$VERSION: 다음 파일이 포함된 디렉터리입니다.
- MODULE.bazel: 이 모듈 버전의 MODULE.bazel 파일입니다.
- source.json: 이 모듈 버전의 소스를 가져오는 방법에 관한 정보가 포함된 JSON 파일입니다.
  - 기본 유형은 다음 필드가 있는 'archive'입니다.
    - url: 소스 보관 파일의 URL입니다.
    - integrity: 보관 파일의 하위 요소 무결성 체크섬입니다.
    - strip_prefix: 소스 보관 파일을 추출할 때 제거할 디렉터리 접두사입니다.
    - patches: 추출된 보관 파일에 적용할 패치 파일의 이름을 각각 지정하는 문자열 목록입니다. 패치 파일은 /modules/$MODULE/$VERSION/patches 디렉터리에 있습니다.
    - patch_strip: Unix 패치의 --strip 인수와 같습니다.
  - 다음 필드와 함께 로컬 경로를 사용하도록 유형을 변경할 수 있습니다.
    - type: local_path
    - path: 다음과 같이 계산된 저장소의 로컬 경로입니다.
      - 경로가 절대 경로인 경우 그대로 사용됩니다.
      - path가 상대 경로이고 module_base_path가 절대 경로인 경우 path가 <module_base_path>/<path>로 확인됩니다.
      - path와 module_base_path가 모두 상대 경로인 경우 path가 <registry_path>/<module_base_path>/<path>로 확인됩니다. 레지스트리는 로컬에서 호스팅되고 --registry=file://<registry_path>에서 사용해야 합니다. 그렇지 않으면 Bazel에서 오류가 발생합니다.
- patches/: 패치 파일이 포함된 선택적 디렉터리입니다. source.json에 '보관처리' 유형이 있는 경우에만 사용됩니다.

Bazel 중앙 레지스트리

Bazel Central Registry (BCR)는 bcr.bazel.build에 있는 색인 레지스트리입니다. 콘텐츠는 GitHub 저장소 bazelbuild/bazel-central-registry에서 백업됩니다.

BCR은 Bazel 커뮤니티에서 유지관리합니다. 참여자는 풀 리퀘스트를 제출할 수 있습니다. Bazel Central Registry 정책 및 절차를 참고하세요.

BCR은 일반 색인 레지스터의 형식을 따르는 것 외에도 각 모듈 버전(/modules/$MODULE/$VERSION/presubmit.yml)의 presubmit.yml 파일이 필요합니다. 이 파일은 이 모듈 버전의 유효성을 검사하는 데 사용할 수 있는 몇 가지 필수 빌드 및 테스트 타겟을 지정하며 BCR의 CI 파이프라인에서 BCR의 모듈 간의 상호 운용성을 보장하는 데 사용됩니다.

레지스트리 선택

반복 가능한 Bazel 플래그 --registry를 사용하여 모듈을 요청할 레지스트리 목록을 지정할 수 있으므로 서드 파티 또는 내부 레지스트리에서 종속 항목을 가져오도록 프로젝트를 설정할 수 있습니다. 이전 레지스트리가 우선 적용됩니다. 편의를 위해 프로젝트의 .bazelrc 파일에 --registry 플래그 목록을 배치할 수 있습니다.

모듈 확장 프로그램

모듈 확장 프로그램을 사용하면 종속 항목 그래프 전체에서 모듈의 입력 데이터를 읽고, 종속 항목을 확인하는 데 필요한 로직을 실행하고, 마지막으로 저장소 규칙을 호출하여 저장소를 만들어 모듈 시스템을 확장할 수 있습니다. 이러한 매크로는 오늘날의 WORKSPACE 매크로와 기능적으로 유사하지만 모듈과 전이 종속 항목의 세계에 더 적합합니다.

모듈 확장 프로그램은 저장소 규칙이나 WORKSPACE 매크로와 마찬가지로 .bzl 파일에 정의됩니다. 직접 호출되지는 않습니다. 대신 각 모듈은 확장 프로그램에서 읽을 태그라는 데이터를 지정할 수 있습니다. 그런 다음 모듈 버전 확인이 완료되면 모듈 확장이 실행됩니다. 각 확장 프로그램은 모듈 해상 후 (아직 빌드가 실제로 실행되기 전) 한 번 실행되며 전체 종속 항목 그래프에서 확장 프로그램에 속한 모든 태그를 읽을 수 있습니다.

          [ A 1.1                ]
          [   * maven.dep(X 2.1) ]
          [   * maven.pom(...)   ]
              /              \
   bazel_dep /                \ bazel_dep
            /                  \
[ B 1.2                ]     [ C 1.0                ]
[   * maven.dep(X 1.2) ]     [   * maven.dep(X 2.1) ]
[   * maven.dep(Y 1.3) ]     [   * cargo.dep(P 1.1) ]
            \                  /
   bazel_dep \                / bazel_dep
              \              /
          [ D 1.4                ]
          [   * maven.dep(Z 1.4) ]
          [   * cargo.dep(Q 1.1) ]

위의 종속 항목 그래프 예에서 A 1.1 및 B 1.2 등은 Bazel 모듈입니다. 각 모듈을 MODULE.bazel 파일로 생각할 수 있습니다. 각 모듈은 모듈 확장 프로그램에 태그를 지정할 수 있습니다. 여기서는 일부가 확장 프로그램 'maven'에 지정되고 일부는 'cargo'에 지정됩니다. 이 종속 항목 그래프가 완료되면 (예: B 1.2에 실제로 D 1.3에 bazel_dep가 있지만 C로 인해 D 1.4로 업그레이드된 경우) 확장 프로그램 'maven'이 실행되고 모든 maven.* 태그를 읽은 후 그 정보를 사용하여 만들려는 저장소를 결정합니다. 'cargo' 확장 프로그램도 마찬가지입니다.

확장 프로그램 사용

확장 프로그램은 Bazel 모듈 자체에서 호스팅되므로 모듈에서 확장 프로그램을 사용하려면 먼저 해당 모듈에 bazel_dep를 추가한 다음 use_extension 내장 함수를 호출하여 범위로 가져와야 합니다. 다음 예를 살펴보세요. rules_jvm_external 모듈에 정의된 가상의 'maven' 확장자를 사용하는 MODULE.bazel 파일의 스니펫입니다.

bazel_dep(name = "rules_jvm_external", version = "1.0")
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")

확장 프로그램을 범위로 가져온 후 점 구문을 사용하여 확장 프로그램의 태그를 지정할 수 있습니다. 태그는 상응하는 태그 클래스에서 정의된 스키마를 따라야 합니다 (아래 확장 프로그램 정의 참고). 다음은 일부 maven.dep 및 maven.pom 태그를 지정하는 예입니다.

maven.dep(coord="org.junit:junit:3.0")
maven.dep(coord="com.google.guava:guava:1.2")
maven.pom(pom_xml="//:pom.xml")

확장 프로그램에서 모듈에 사용하려는 저장소를 생성하는 경우 use_repo 지시어를 사용하여 선언합니다. 이는 엄격한 종속 항목 조건을 충족하고 로컬 저장소 이름 충돌을 방지하기 위함입니다.

use_repo(
    maven,
    "org_junit_junit",
    guava="com_google_guava_guava",
)

확장 프로그램에서 생성된 저장소는 API의 일부이므로 지정한 태그를 보면 'maven' 확장 프로그램이 'org_junit_junit' 저장소와 'com_google_guava_guava' 저장소를 생성한다는 것을 알 수 있습니다. use_repo를 사용하면 원하는 경우 모듈 범위 내에서 이름을 바꿀 수 있습니다(여기서는 'guava'로).

확장 프로그램 정의

모듈 확장 프로그램은 module_extension 함수를 사용하여 저장소 규칙과 유사하게 정의됩니다. 둘 다 구현 함수가 있습니다. 하지만 저장소 규칙에는 여러 속성이 있는 반면 모듈 확장 프로그램에는 여러 tag_class가 있으며 각각 여러 속성이 있습니다. 태그 클래스는 이 확장 프로그램에서 사용하는 태그의 스키마를 정의합니다. 위의 가상 'maven' 확장 프로그램 예시를 계속 진행합니다.

# @rules_jvm_external//:extensions.bzl
maven_dep = tag_class(attrs = {"coord": attr.string()})
maven_pom = tag_class(attrs = {"pom_xml": attr.label()})
maven = module_extension(
    implementation=_maven_impl,
    tag_classes={"dep": maven_dep, "pom": maven_pom},
)

이러한 선언은 위에 정의된 속성 스키마를 사용하여 maven.dep 및 maven.pom 태그를 지정할 수 있음을 명확하게 보여줍니다.

구현 함수는 종속 항목 그래프 및 모든 관련 태그에 대한 액세스 권한을 부여하는 module_ctx 객체를 가져온다는 점을 제외하고 WORKSPACE 매크로와 유사합니다. 그런 다음 구현 함수는 저장소 규칙을 호출하여 저장소를 생성해야 합니다.

# @rules_jvm_external//:extensions.bzl
load("//:repo_rules.bzl", "maven_single_jar")
def _maven_impl(ctx):
  coords = []
  for mod in ctx.modules:
    coords += [dep.coord for dep in mod.tags.dep]
  output = ctx.execute(["coursier", "resolve", coords])  # hypothetical call
  repo_attrs = process_coursier(output)
  [maven_single_jar(**attrs) for attrs in repo_attrs]

위 예에서는 종속 항목 그래프(ctx.modules)의 모든 모듈을 살펴봅니다. 각 모듈은 tags 필드가 모듈의 모든 maven.* 태그를 노출하는 bazel_module 객체입니다. 그런 다음 CLI 유틸리티인 Coursier를 호출하여 Maven에 연결하고 해결을 실행합니다. 마지막으로 가상의 maven_single_jar 저장소 규칙을 사용하여 해결 결과를 사용하여 여러 저장소를 만듭니다.