이 페이지는 다른 사용자에게 규칙을 제공하려는 규칙 작성자를 위한 페이지입니다.
https://github.com/bazel-contrib/rules-template 템플릿 저장소에서 새 규칙 세트를 시작하는 것이 좋습니다. 이 템플릿은 아래 권장사항을 따르며 API 문서 생성을 포함하고 규칙 세트를 쉽게 배포할 수 있도록 CI/CD 파이프라인을 설정합니다.
호스팅 및 이름 지정 규칙
새 규칙은 조직의 자체 GitHub 저장소에 있어야 합니다. 규칙이 bazelbuild 조직에 속한다고 생각되면 GitHub에서 스레드를 시작하세요.
Bazel 규칙의 저장소 이름은 $ORGANIZATION/rules_$NAME
형식으로 표준화됩니다.
GitHub의 예를 참고하세요.
일관성을 위해 Bazel 규칙을 게시할 때도 동일한 형식을 따라야 합니다.
설명이 포함된 GitHub 저장소 설명과 README.md
제목을 사용해야 합니다. 예를 들면 다음과 같습니다.
- 저장소 이름:
bazelbuild/rules_go
- 저장소 설명: Bazel용 Go 규칙
- 저장소 태그:
golang
,bazel
README.md
헤더: Bazel용 Go 규칙(Bazel에 익숙하지 않은 사용자를 올바른 위치로 안내하는 https://bazel.build 링크 참고)
규칙은 언어 (예: Scala), 런타임 플랫폼(예: Android) 또는 프레임워크 (예: Spring)별로 그룹화할 수 있습니다.
저장소 콘텐츠
사용자가 새 규칙을 빠르게 이해할 수 있도록 모든 규칙 저장소에는 특정 레이아웃이 있어야 합니다.
예를 들어 (가상의) mockascript
언어에 대한 새 규칙을 작성할 때 규칙 저장소의 구조는 다음과 같습니다.
/
LICENSE
README
MODULE.bazel
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
MODULE.bazel
프로젝트의 MODULE.bazel
에서 사용자가 규칙을 참조하는 데 사용할 이름을 정의해야 합니다. 규칙이 bazelbuild 조직에 속하는 경우 rules_<lang>
(예: rules_mockascript
)을 사용해야 합니다. 그렇지 않으면 저장소 이름을 <org>_rules_<lang>
(예: build_stack_rules_proto
)로 지정해야 합니다. 규칙이 bazelbuild 조직의 규칙 관례를 따라야 한다고 생각되면 GitHub에서 스레드를 시작하세요.
다음 섹션에서는 저장소가 bazelbuild 조직에 속한다고 가정합니다.
module(name = "rules_mockascript")
리드미
최상위 수준에는 규칙 세트와 API 사용자가 예상해야 하는 사항에 관한 간략한 설명이 포함된 README
가 있어야 합니다.
규칙
저장소에서 제공하는 규칙이 여러 개인 경우가 많습니다. 언어로 이름이 지정된 디렉터리를 만들고 모든 규칙을 내보내는 진입점인 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
속성에 추가합니다.
저장소 규칙
종속 항목
규칙에 외부 종속 항목이 있을 수 있으며, 이는 MODULE.bazel 파일에 지정해야 합니다.
도구 모음 등록
규칙은 툴체인을 등록할 수도 있으며, 툴체인은 MODULE.bazel 파일에서도 지정할 수 있습니다.
분석 단계에서 도구 모음을 해결하려면 Bazel이 등록된 모든 toolchain
타겟을 분석해야 합니다. Bazel은 toolchain.toolchain
속성에서 참조하는 모든 타겟을 분석할 필요가 없습니다. 툴체인을 등록하기 위해 저장소에서 복잡한 계산을 실행해야 하는 경우 <LANG>_toolchain
타겟이 있는 저장소에서 toolchain
타겟이 있는 저장소를 분할하는 것이 좋습니다. 전자는 항상 가져오고 후자는 사용자가 실제로 <LANG>
코드를 빌드해야 하는 경우에만 가져옵니다.
스니펫 출시
출시 공지사항에서 사용자가 MODULE.bazel
파일에 복사하여 붙여넣을 수 있는 스니펫을 제공합니다. 일반적으로 이 스니펫은 다음과 같습니다.
bazel_dep(name = "rules_<LANG>", version = "<VERSION>")
테스트
규칙이 예상대로 작동하는지 확인하는 테스트가 있어야 합니다. 이는 규칙이 적용되는 언어의 표준 위치에 있거나 최상위 수준의 tests/
디렉터리에 있을 수 있습니다.
예(선택사항)
사용자에게 규칙을 사용할 수 있는 몇 가지 기본 방법을 보여주는 examples/
디렉터리가 있으면 유용합니다.
CI/CD
많은 규칙 집합에서 GitHub Actions를 사용합니다. bazel-contrib org에 호스팅된 '재사용 가능한 워크플로'를 사용하여 간소화된 rules-template 저장소에 사용된 구성을 참고하세요. ci.yaml
는 각 PR 및 main
커밋에 테스트를 실행하고 release.yaml
는 저장소에 태그를 푸시할 때마다 실행됩니다.
자세한 내용은 rules-template 저장소의 댓글을 참고하세요.
저장소가 bazelbuild 조직에 있는 경우 ci.bazel.build에 추가해 달라고 요청할 수 있습니다.
문서
문서가 자동으로 생성될 수 있도록 규칙에 주석을 추가하는 방법에 관한 안내는 Stardoc 문서를 참고하세요.
rules-template docs/ 폴더는 Starlark 파일이 업데이트될 때 docs/
폴더의 마크다운 콘텐츠가 항상 최신 상태인지 확인하는 간단한 방법을 보여줍니다.
FAQ
기본 Bazel GitHub 저장소에 규칙을 추가할 수 없는 이유는 무엇인가요?
규칙을 Bazel 출시에서 최대한 분리하려고 합니다. 개별 규칙의 소유자가 명확해져 Bazel 개발자의 부담이 줄어듭니다. 사용자는 분리를 통해 규칙을 더 쉽게 수정, 업그레이드, 다운그레이드, 교체할 수 있습니다. 규칙에 기여하는 것은 해당 GitHub 저장소에 대한 전체 제출 액세스 권한을 포함하여 규칙에 따라 Bazel에 기여하는 것보다 가벼울 수 있습니다. Bazel 자체에 제출 액세스 권한을 얻는 것은 훨씬 더 복잡한 프로세스입니다.
단점은 사용자를 위한 일회성 설치 프로세스가 더 복잡하다는 것입니다. 사용자가 MODULE.bazel
파일에 규칙 세트 종속 항목을 추가해야 합니다.
이전에는 Bazel 저장소 (//tools/build_rules
또는 //tools/build_defs
아래)에 모든 규칙이 있었습니다. 아직 몇 가지 규칙이 있지만 나머지 규칙을 이동하는 작업을 진행하고 있습니다.