외부 종속 항목 개요

문제 신고하기 소스 보기

Bazel은 작업공간에서 가져오지 않은 빌드에 사용되는 외부 종속 항목, 소스 파일 (텍스트 및 바이너리 모두)을 지원합니다. 예를 들어 GitHub 저장소에서 호스팅되는 규칙 세트, Maven 아티팩트 또는 현재 작업공간 외부에 있는 로컬 머신의 디렉터리일 수 있습니다.

Bazel 6.0부터 Bazel을 사용하여 외부 종속 항목을 관리하는 방법에는 두 가지가 있습니다. 하나는 저장소 중심적인 기존 WORKSPACE 시스템이고 다른 하나는 최신 모듈 중심 MODULE.bazel 시스템 (코드명이 Bzlmod이며 --enable_bzlmod 플래그가 사용 설정됨)입니다. 두 시스템을 함께 사용할 수 있지만 Bzlmod는 향후 Bazel 출시 버전에서 WORKSPACE 시스템을 대체하고 있습니다. Bzl0 이전 방법 가이드를 확인하세요.

이 문서에서는 Bazel의 외부 종속 항목 관리를 둘러싼 개념을 설명한 후 두 시스템을 순서대로 자세히 살펴봅니다.

개념

저장소

루트에 경계 마커 파일이 있는 디렉터리 트리. Bazel 빌드에서 사용할 수 있는 소스 파일이 포함되어 있습니다. 보통 repo로 축약합니다.

저장소 경계 마커 파일은 MODULE.bazel (이 저장소가 Bazel 모듈을 나타낸다는 신호), REPO.bazel (아래 참고), 기존 컨텍스트의 경우 WORKSPACE 또는 WORKSPACE.bazel일 수 있습니다. 모든 저장소 경계 마커 파일은 저장소의 경계를 나타냅니다. 이러한 여러 파일이 하나의 디렉터리에 공존할 수 있습니다.

기본 저장소

현재 Bazel 명령어가 실행되고 있는 저장소입니다.

기본 저장소의 루트는 작업공간 루트라고도 합니다.

작업공간

모든 Bazel 명령어가 공유하는 환경은 동일한 기본 저장소에서 실행됩니다. 여기에는 기본 저장소와 정의된 모든 외부 저장소 집합이 포함됩니다.

지금까지 '저장소'와 '작업공간'의 개념은 서로 혼동되었습니다. '작업공간'이라는 용어는 종종 기본 저장소를 나타내는 데 사용되었으며 때로는 '저장소'의 동의어로 사용되기도 합니다.

표준 저장소 이름

저장소의 주소를 지정할 수 있는 표준 이름입니다. 작업공간의 컨텍스트 내에서 각 저장소에는 단일 표준 이름이 있습니다. 표준 이름이 canonical_name인 저장소 내부의 대상은 @@canonical_name//pac/kage:target 라벨로 지정할 수 있습니다 (이중 @ 참고).

기본 저장소에는 항상 표준 이름으로 빈 문자열이 있습니다.

명확한 저장소 이름

다른 특정 저장소의 컨텍스트에서 주소를 지정할 수 있는 저장소 이름입니다. 이를 저장소의 '닉네임'으로 간주할 수 있습니다. 표준 이름이 michael인 저장소의 경우 저장소 alice의 컨텍스트에서는 명확한 이름 mike이 있을 수 있지만 저장소 bob의 컨텍스트에서는 명확한 이름 mickey이 있을 수 있습니다. 이 경우 michael 내의 타겟은 alice의 컨텍스트에서 @mike//pac/kage:target 라벨로 주소를 지정할 수 있습니다 (단일 @ 참고).

반대로 이는 저장소 매핑으로 이해할 수 있습니다. 각 저장소는 '명확한 저장소 이름'에서 '표준 저장소 이름'으로의 매핑을 유지합니다.

저장소 규칙

Bazel에 저장소를 구체화하는 방법을 알려주는 저장소 정의에 대한 스키마입니다. 예를 들어 '특정 URL에서 zip 보관 파일을 다운로드하여 추출'하거나 '특정 Maven 아티팩트를 가져와 java_import 타겟으로 제공'하거나 단순히 '로컬 디렉터리를 심볼릭 링크로 연결'할 수 있습니다. 모든 저장소는 적절한 수의 인수로 저장소 규칙을 호출하여 정의합니다.

자체 저장소 규칙을 작성하는 방법에 대한 자세한 내용은 저장소 규칙을 참조하세요.

현재 가장 일반적인 저장소 규칙은 URL에서 보관 파일을 다운로드하여 추출하는 http_archive와 이미 Bazel 저장소인 로컬 디렉터리를 심볼릭 링크하는 local_repository입니다.

저장소 가져오기

연결된 저장소 규칙을 실행하여 로컬 디스크에서 저장소를 사용할 수 있도록 하는 작업입니다. 작업공간에 정의된 저장소는 가져오기 전에는 로컬 디스크에서 사용할 수 없습니다.

일반적으로 Bazel은 저장소에서 무언가가 필요하고 아직 저장소를 가져오지 않은 경우에만 저장소를 가져옵니다. 이전에 저장소를 가져온 경우 Bazel은 정의가 변경된 경우에만 저장소를 다시 가져옵니다.

fetch 명령어를 사용하여 저장소, 대상 또는 빌드를 수행하는 데 필요한 모든 저장소의 프리패치를 시작할 수 있습니다. 이 기능은 --nofetch 옵션을 사용하여 오프라인 빌드를 사용 설정합니다.

--fetch 옵션은 네트워크 액세스를 관리하는 역할을 합니다. 기본값은 true입니다. 하지만 false (--nofetch)로 설정하면 명령어는 캐시된 종속 항목 버전을 활용하며 존재하지 않는 경우 명령어가 실패합니다.

가져오기 제어에 관한 자세한 내용은 가져오기 옵션을 참고하세요.

디렉터리 레이아웃

가져온 후에는 저장소는 표준 이름 아래의 출력 베이스에 있는 external 하위 디렉터리에서 찾을 수 있습니다.

다음 명령어를 실행하여 표준 이름이 canonical_name인 저장소의 콘텐츠를 확인할 수 있습니다.

ls $(bazel info output_base)/external/ canonical_name 

REPO.bazel 파일

REPO.bazel 파일은 저장소를 구성하는 디렉터리 트리의 최상위 경계를 표시하는 데 사용됩니다. 저장소 경계 파일로 사용할 아무것도 포함할 필요는 없습니다. 하지만 저장소 내의 모든 빌드 대상에 대한 몇 가지 공통 속성을 지정하는 데도 사용할 수 있습니다.

REPO.bazel 파일의 구문은 BUILD 파일과 유사하지만, load 문이 지원되지 않고 단일 함수 repo()만 사용할 수 있다는 점이 다릅니다. repo()BUILD 파일의 package() 함수와 동일한 인수를 사용합니다. package()는 패키지 내의 모든 빌드 타겟에 공통 속성을 지정하고, repo()는 저장소 내의 모든 빌드 대상에 공통 속성을 지정합니다.

예를 들어 다음 REPO.bazel 파일을 사용하여 저장소의 모든 대상에 공통 라이선스를 지정할 수 있습니다.

repo(
    default_package_metadata = ["//:my_license"],
)

Bzlmod를 사용한 외부 종속 항목 관리

새로운 외부 종속 항목 하위 시스템인 Bzlmod는 저장소 정의에서 직접 작동하지 않습니다. 대신 모듈에서 종속 항목 그래프를 빌드하고, 그래프 위에서 확장 프로그램을 실행한 후 그에 따라 저장소를 정의합니다.

Bazel 모듈은 여러 버전이 있을 수 있는 Bazel 프로젝트이며 각 버전은 종속된 다른 모듈에 대한 메타데이터를 게시합니다. 모듈의 저장소 루트에 WORKSPACE 파일 옆에 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")

모듈은 Bzlmod가 Bazel 레지스트리(기본적으로 Bazel Central Registry)에서 조회하는 직접 종속 항목만 나열해야 합니다. 레지스트리는 종속 항목의 MODULE.bazel 파일을 제공하므로 Bazel이 버전 확인을 실행하기 전에 전체 전이 종속 항목 그래프를 검색할 수 있습니다.

버전 확인 후(각 모듈에 하나의 버전이 선택됨) Bazel은 레지스트리를 다시 참조하여 각 모듈의 저장소를 정의하는 방법을 알아봅니다(대부분의 경우 http_archive 사용).

모듈은 또한 태그라는 맞춤설정된 데이터 조각을 지정할 수 있습니다. 태그는 모듈 확인 후 모듈 확장에서 사용하여 추가 저장소를 정의합니다. 이러한 확장 프로그램은 저장소 규칙과 유사한 기능을 가지므로 파일 I/O 및 네트워크 요청 전송과 같은 작업을 수행할 수 있습니다. 무엇보다도 Bazel이 Bazel을 기반으로 빌드된 종속 항목 그래프를 준수하는 동시에 다른 패키지 관리 시스템과 상호작용할 수 있게 해줍니다.

WORKSPACE로 저장소 정의

이전에는 WORKSPACE (또는 WORKSPACE.bazel) 파일에 저장소를 정의하여 외부 종속 항목을 관리할 수 있었습니다. 이 파일은 BUILD 파일과 유사한 구문을 가지고 있으며, 빌드 규칙 대신 저장소 규칙을 사용합니다.

다음 스니펫은 WORKSPACE 파일에서 http_archive 저장소 규칙을 사용하는 예시입니다.

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "foo",
    urls = ["https://example.com/foo.zip"],
    sha256 = "c9526390a7cd420fdcec2988b4f3626fe9c5b51e2959f685e8f4d170d1a9bd96",
)

스니펫은 표준 이름이 foo인 저장소를 정의합니다. WORKSPACE 시스템에서 기본적으로 저장소의 표준 이름은 다른 모든 저장소에서도 명확한 이름으로 사용됩니다.

WORKSPACE 파일에서 사용할 수 있는 함수의 전체 목록을 참조하세요.

WORKSPACE 시스템의 단점

WORKSPACE 시스템이 도입된 이후 몇 년 동안 사용자는 다음을 비롯한 많은 문제를 보고했습니다.

  • Bazel은 종속 항목의 WORKSPACE 파일을 평가하지 않으므로 모든 전이 종속 항목은 직접 종속 항목 외에도 주 저장소의 WORKSPACE 파일에서 정의해야 합니다.
  • 이 문제를 해결하기 위해 프로젝트에서는 여러 저장소를 정의하는 매크로를 정의하고 사용자에게 WORKSPACE 파일에서 이 매크로를 호출하도록 요청하는 'deps.bzl' 패턴을 채택했습니다.
    • 여기에는 자체적인 문제가 있습니다. 매크로는 다른 .bzl 파일을 load할 수 없으므로 이러한 프로젝트는 이 'deps' 매크로에 전이 종속 항목을 정의하거나 사용자가 여러 계층의 'deps' 매크로를 호출하도록 하여 이 문제를 해결해야 합니다.
    • Bazel은 WORKSPACE 파일을 순차적으로 평가합니다. 또한 종속 항목은 버전 정보 없이 URL과 함께 http_archive를 사용하여 지정됩니다. 즉, 다이아몬드 종속 항목의 경우 버전 확인을 실행하는 안정적인 방법이 없습니다 (ABC에 종속되며 BC는 모두 다른 D 버전에 종속됨).

WORKSPACE의 단점으로 인해 Bzlmod는 향후 Bazel 출시에서 기존 WORKSPACE 시스템을 대체할 예정입니다. Bzlmod로 마이그레이션하는 방법은 Bzlmod 마이그레이션 가이드를 참고하세요.