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