BazelCon 2022는 11월 16~17일에 뉴욕과 온라인에서 개최됩니다.
지금 등록하기

규칙 배포

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 페이지는 다른 사용자에게 자신의 규칙을 제공할 계획인 규칙 작성자를 대상으로 합니다.

호스팅 및 이름 지정 규칙

새 규칙은 조직의 자체 GitHub 저장소에 들어가야 합니다. 규칙이 bazelbuild 조직에 속한다고 생각되면 bazel-dev 메일링 리스트에 문의하세요.

Bazel 규칙의 저장소 이름은 $ORGANIZATION/rules_$NAME 형식으로 표준화됩니다. GitHub에서 예시를 참조하세요. 일관성을 위해 Bazel 규칙을 게시할 때 동일한 형식을 사용해야 합니다.

설명이 포함된 GitHub 저장소 설명 및 README.md 제목을 사용해야 합니다. 예를 들면 다음과 같습니다.

  • 저장소 이름: bazelbuild/rules_go
  • 저장소 설명: Bazel의 Go 규칙
  • 저장소 태그: golang, bazel
  • README.md 헤더: Bazel의 Go 규칙(익숙하지 않은 사용자를 안내하는 https://bazel.build 링크를 참조하세요. 올바른 위치에 Bazel 추가)

규칙은 언어 (예: Scala) 또는 플랫폼(예: Android)으로 그룹화할 수 있습니다.

저장소 콘텐츠

모든 규칙 저장소에는 사용자가 새 규칙을 빠르게 이해할 수 있도록 특정 레이아웃이 있어야 합니다.

예를 들어 (make-believe) mockascript 언어의 새 규칙을 작성할 때 규칙 저장소의 구조는 다음과 같습니다.

/
  LICENSE
  README
  WORKSPACE
  mockascript/
    constraints/
      BUILD
    runfiles/
      BUILD
      runfiles.mocs
    BUILD
    defs.bzl
  tests/
    BUILD
    some_test.sh
    another_test.py
  examples/
    BUILD
    bin.mocs
    lib.mocs
    test.mocs

작업공간

프로젝트의 WORKSPACE에서 사용자가 규칙을 참조하는 데 사용할 이름을 정의해야 합니다. 규칙이 bazelbuild 조직에 속한 경우 rules_<lang>를 사용해야 합니다 (예: rules_mockascript). 그렇지 않으면 저장소 이름을 <org>_rules_<lang> (예: build_stack_rules_proto)로 지정해야 합니다. 규칙이 bazelbuild 조직의 규칙 규칙을 따라야 한다고 생각되면 bazel-dev 메일링 리스트에 문의하세요.

다음 섹션에서는 저장소가 bazelbuild 조직에 속한다고 가정합니다.

workspace(name = "rules_mockascript")

리드미

최상위 수준에는 규칙을 사용하여 사용자가 WORKSPACE 파일에 복사하여 붙여넣어야 하는 항목이 포함된 README가 있어야 합니다. 일반적으로 이는 GitHub 출시를 가리키는 http_archive과 규칙에 필요한 도구를 다운로드/구성하는 매크로 호출을 의미합니다. 예를 들어 Go 규칙의 경우 이는 다음과 같습니다.

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_go",
    urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
    sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()

규칙이 다른 저장소의 규칙에 종속되는 경우 규칙 문서에 해당 규칙을 지정하고 (예: Sass 규칙에 종속되는 Skydoc 규칙 참조) 모든 종속 항목을 다운로드하는 WORKSPACE 매크로 (위의 rules_go 참고)

규칙

저장소에서 제공하는 규칙이 여러 개 있을 때가 많습니다. 언어로 명명된 디렉터리를 만들고 모든 규칙을 내보내는 defs.bzl 파일 진입점을 제공합니다. 디렉터리가 패키지이므로 BUILD 파일도 포함합니다. 즉, rules_mockascript에는 mockascript라는 디렉터리와 BUILD 파일, defs.bzl 파일이 있습니다.

/
  mockascript/
    BUILD
    defs.bzl

제약 조건

규칙에서 도구 모음 규칙을 정의하면 커스텀 constraint_setting 또는 constraint_value를 정의해야 할 수도 있습니다. 이를 //<LANG>/constraints 패키지에 넣습니다. 디렉터리 구조는 다음과 같습니다.

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

github.com/bazelbuild/platforms에서 권장사항을 확인하고 어떤 제약조건이 이미 존재하는지 확인하고 언어 제약이 있는 경우 제약조건에 기여하는 것이 좋습니다. 맞춤 제약조건을 도입할 때 규칙의 모든 사용자는 맞춤 제약 조건을 사용하여 BUILD 파일에서 플랫폼별 로직을 수행합니다 (예: selects 사용). 커스텀 제약조건을 사용하여 전체 Bazel 생태계가 사용할 언어를 정의합니다.

Runfiles 라이브러리

규칙이 실행 파일에 액세스하기 위한 표준 라이브러리를 제공하는 경우 //<LANG>/runfiles (//<LANG>/runfiles:runfiles의 약어)에 있는 라이브러리 타겟 형식이어야 합니다. 데이터 종속 항목에 액세스해야 하는 사용자 대상은 일반적으로 deps 속성에 이 대상을 추가합니다.

저장소 규칙

종속 항목

규칙에 외부 종속 항목이 있을 수 있습니다. 규칙에 따라 더 간단한 작업을 하려면 외부 종속 항목의 종속 항목을 선언하는 WORKSPACE 매크로를 제공합니다. 테스트 종속 항목을 선언하지 말고, 규칙이 작동해야 하는 종속 항목만 선언합니다. 개발 종속 항목을 WORKSPACE 파일에 넣습니다.

이름이 <LANG>/repositories.bzl인 파일을 만들고 rules_<LANG>_dependencies라는 단일 진입점 매크로를 제공합니다. 디렉터리는 다음과 같습니다.

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl
    repositories.bzl

도구 모음 등록

규칙에서 도구 모음을 등록할 수도 있습니다. 이러한 도구 모음을 등록하는 별도의 WORKSPACE 매크로를 제공하세요. 이렇게 하면 도구 모음을 등록할 수 있는 동시에 사용자가 이전 매크로를 생략하고 종속 항목을 수동으로 제어할 수 있습니다.

따라서 rules_<LANG>_toolchains이라는 WORKSPACE 매크로를 <LANG>/repositories.bzl 파일에 추가합니다.

분석 단계에서 도구 모음을 해결하려면 Bazel이 등록된 모든 toolchain 대상을 분석해야 합니다. Bazel은 toolchain.toolchain 속성에서 참조하는 모든 대상을 분석할 필요가 없습니다. 도구 모음을 등록하려면 저장소에서 복잡한 계산을 수행해야 하는 경우 <LANG>_toolchain 대상을 사용하여 저장소를 toolchain 대상으로 분할하는 것이 좋습니다. 이전 코드는 항상 가져오고 후자는 사용자가 실제로 <LANG> 코드를 빌드해야 하는 경우에만 가져옵니다.

출시 스니펫

출시 공지에서 사용자가 WORKSPACE 파일에 복사하여 붙여넣을 수 있는 스니펫을 제공합니다. 이 스니펫은 일반적으로 다음과 같습니다.

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_<LANG>",
    urls = ["<url_to_the_release.zip"],
    sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()

테스트

규칙이 예상대로 작동하는지 확인하는 테스트가 있어야 합니다. 이러한 위치는 규칙이 적용되는 언어의 표준 위치 또는 최상위 수준의 tests/ 디렉터리일 수 있습니다.

예 (선택사항)

사용자에게 규칙을 사용할 수 있는 기본적인 몇 가지 방법을 보여주는 examples/ 디렉터리가 있는 것이 유용합니다.

테스트

시작 문서에 설명된 대로 Travis를 설정합니다. 그런 다음 .travis.yml 파일을 저장소에 다음과 같은 콘텐츠로 추가합니다.

dist: xenial  # Ubuntu 16.04

# On trusty (or later) images, the Bazel apt repository can be used.
addons:
  apt:
    sources:
    - sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
      key_url: 'https://bazel.build/bazel-release.pub.gpg'
    packages:
    - bazel

script:
  - bazel build //...
  - bazel test //...

저장소가 bazelbuild 조직에 속한 경우 ci.bazel.build에 저장소를 추가하도록 요청할 수 있습니다.

문서

문서가 자동으로 생성될 수 있도록 규칙을 주석 처리하는 방법은 Stardoc 문서를 참조하세요.

FAQ

기본 Bazel GitHub 저장소에 규칙을 추가할 수 없는 이유는 무엇인가요?

Bazel 출시 버전에서 규칙을 최대한 분리하려고 합니다. 개별 규칙을 소유하는 것이 더 명확하므로 Bazel 개발자의 부하가 줄어듭니다. 사용자가 분리하면 규칙을 더 쉽게 수정, 업그레이드, 다운그레이드 및 대체할 수 있습니다. 해당 GitHub 저장소에 대한 전체 제출 액세스 권한을 포함하여 규칙에 따라 Bazel에 기여하는 것보다 규칙에 더 크게 기여할 수 있습니다. Bazel 자체에 대한 제출 액세스 권한을 얻는 것은 훨씬 더 복잡한 과정입니다.

단점은 사용자에게 보다 복잡한 일회성 설치 프로세스입니다. 위의 README.md 섹션과 같이 규칙을 복사하여 WORKSPACE 파일에 붙여넣어야 하기 때문입니다.

이전에는 Bazel 저장소의 모든 규칙 (//tools/build_rules 또는 //tools/build_defs 아래)이 있었습니다. 아직 두어 가지 규칙이 있지만 나머지 규칙을 이전하는 중입니다.