이 페이지는 다른 사용자에게 규칙을 제공하려는 규칙 작성자를 위한 페이지입니다.
템플릿 저장소(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 파일에서 플랫폼별 로직을 실행합니다 (예: 선택 사용).
커스텀 제약조건을 사용하면 전체 Bazel 생태계에서 사용할 언어를 정의할 수 있습니다.
Runfiles 라이브러리
규칙이 런파일에 액세스하기 위한 표준 라이브러리를 제공하는 경우 //<LANG>/runfiles (//<LANG>/runfiles:runfiles의 약어)에 있는 라이브러리 타겟 형식이어야 합니다. 데이터 종속 항목에 액세스해야 하는 사용자 타겟은 일반적으로 이 타겟을 deps 속성에 추가합니다.
저장소 규칙
종속 항목
규칙에 외부 종속 항목이 있을 수 있으며, 이 경우 MODULE.bazel 파일에서 지정해야 합니다.
도구 모음 등록
규칙은 툴체인을 등록할 수도 있으며, 툴체인은 MODULE.bazel 파일에서도 지정할 수 있습니다.
분석 단계에서 도구 모음을 확인하려면 Bazel에서 등록된 모든 toolchain 타겟을 분석해야 합니다. Bazel은 toolchain.toolchain 속성에서 참조하는 모든 타겟을 분석할 필요가 없습니다. 도구 모음을 등록하기 위해 저장소에서 복잡한 계산을 실행해야 하는 경우 toolchain 타겟이 있는 저장소를 <LANG>_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/ 폴더의 Markdown 콘텐츠가 항상 최신 상태를 유지하도록 하는 간단한 방법이 나와 있습니다.
FAQ
기본 Bazel GitHub 저장소에 규칙을 추가할 수 없는 이유는 무엇인가요?
규칙을 Bazel 출시에서 최대한 분리하고자 합니다. 개별 규칙을 소유한 사용자가 더 명확해져 Bazel 개발자의 부담이 줄어듭니다. 사용자의 경우 결합 해제하면 규칙을 더 쉽게 수정, 업그레이드, 다운그레이드, 교체할 수 있습니다. 규칙에 기여하는 것은 규칙에 따라 Bazel에 기여하는 것보다 가벼울 수 있으며, 여기에는 해당 GitHub 저장소에 대한 전체 제출 액세스 권한이 포함됩니다. Bazel 자체에 대한 제출 액세스 권한을 얻는 것은 훨씬 더 복잡한 절차입니다.
단점은 사용자에게 더 복잡한 일회성 설치 프로세스가 필요하다는 점입니다. MODULE.bazel 파일에 규칙 집합에 대한 종속 항목을 추가해야 합니다.
이전에는 모든 규칙이 Bazel 저장소 (//tools/build_rules 또는 //tools/build_defs 아래)에 있었습니다. 아직 몇 가지 규칙이 있지만 나머지 규칙을 옮기기 위해 노력하고 있습니다.