이 페이지에서는 Starlark의 기본 스타일 가이드라인을 다루며 매크로 및 규칙에 관한 정보도 포함되어 있습니다.
Starlark는 소프트웨어 빌드 방법을 정의하는 언어이므로 프로그래밍 언어이자 구성 언어입니다.
Starlark를 사용하여 BUILD 파일, 매크로, 빌드 규칙을 작성합니다. 매크로와 규칙은 본질적으로 메타 언어입니다. BUILD 파일을 작성하는 방법을 정의합니다.
BUILD 파일은 간단하고 반복적으로 작성할 수 있도록 고안되었습니다.
모든 소프트웨어는 쓰는 것보다 읽는 빈도가 더 높습니다. 이는 특히 Starlark의 경우 해당됩니다. 엔지니어가 BUILD 파일을 읽어 타겟의 종속 항목과 빌드 세부정보를 파악하기 때문입니다. 이러한 읽기는 종종 부수적으로, 급하게, 또는 다른 작업을 완료하는 동시에 이루어집니다. 따라서 사용자가 BUILD 파일을 빠르게 파싱하고 이해할 수 있도록 단순성과 가독성이 매우 중요합니다.
사용자가 BUILD 파일을 열면 파일의 타겟 목록을 빠르게 확인하거나, 해당 C++ 라이브러리의 소스 목록을 검토하거나, 해당 Java 바이너리에서 종속 항목을 삭제하려고 합니다. 추상화 계층을 추가할 때마다 사용자가 이러한 작업을 더 어렵게 수행하게 됩니다.
BUILD 파일은 여러 도구에서 분석 및 업데이트됩니다. 추상화를 사용하는 경우 도구에서 BUILD 파일을 수정하지 못할 수 있습니다. BUILD 파일을 간단하게 유지하면 더 나은 도구를 사용할 수 있습니다. 코드베이스가 커짐에 따라 라이브러리를 업데이트하거나 정리하기 위해 여러 BUILD 파일을 변경하는 일이 점점 더 빈번해집니다.
일반 도움말
- Buildifier를 형식 지정 도구 및 린터로 사용합니다.
- 테스트 가이드라인을 따릅니다.
스타일
Python 스타일
확실하지 않은 경우 가능한 경우 PEP 8 스타일 가이드를 따르세요. 특히 Python 규칙에 따라 들여쓰기에 공백 2개가 아닌 4개를 사용하세요.
Starlark는 Python이 아니므로 Python 스타일의 일부 측면은 적용되지 않습니다. 예를 들어 PEP 8에서는 싱글톤과의 비교는 Starlark의 연산자가 아닌 is로 실행해야 한다고 권장합니다.
문자열
docstring을 사용하여 파일 및 함수를 문서화합니다.
각 .bzl 파일 상단에 문자열 문서를 사용하고 각 공개 함수에 문자열 문서를 사용합니다.
문서 규칙 및 측면
규칙 및 측면과 그 속성, 제공자 및 필드는 doc 인수를 사용하여 문서화해야 합니다.
이름 지정 규칙
- 변수 및 함수 이름은
cc_library와 같이 밑줄 ([a-z][a-z0-9_]*)로 구분된 단어를 소문자로 사용합니다. - 최상위 비공개 값은 밑줄 1개로 시작합니다. Bazel은 비공개 값을 다른 파일에서 사용할 수 없도록 적용합니다. 로컬 변수는 밑줄 접두사를 사용해서는 안 됩니다.
행 길이
BUILD 파일과 마찬가지로 라벨이 길어질 수 있으므로 엄격한 줄 길이 제한은 없습니다.
가능하면 한 줄에 최대 79자 (Python 스타일 가이드 PEP 8 참고)를 사용하세요. 이 가이드라인은 엄격하게 적용해서는 안 됩니다. 편집기는 80개가 넘는 열을 표시해야 하고, 자동 변경으로 인해 줄이 더 길어지는 경우가 많으며, 사람이 이미 읽을 수 있는 줄을 나누는 데 시간을 들이지 않아야 합니다.
키워드 인수
키워드 인수에서는 등호 주위에 공백을 사용하는 것이 좋습니다.
def fct(name, srcs):
filtered_srcs = my_filter(source = srcs)
native.cc_library(
name = name,
srcs = filtered_srcs,
testonly = True,
)
부울 값
불리언 값에 1 및 0 대신 True 및 False 값을 사용하는 것이 좋습니다(예: 규칙에서 불리언 속성을 사용할 때).
디버깅에만 print 사용
프로덕션 코드에서 print() 함수를 사용하지 마세요. 디버깅 전용이며 .bzl 파일의 모든 직접 및 간접 사용자에게 스팸을 보냅니다. 유일한 예외는 print()가 기본적으로 사용 중지되어 있고 소스를 수정하여야만 사용 설정할 수 있는 경우 print()를 사용하는 코드를 제출할 수 있다는 점입니다. 예를 들어 DEBUG가 False로 하드코딩된 경우 print()의 모든 사용이 if DEBUG:로 보호되는 경우입니다. 이러한 설명이 가독성에 미치는 영향을 정당화할 만큼 유용한지 고려하세요.
매크로
매크로는 로드 단계 중에 하나 이상의 규칙을 인스턴스화하는 함수입니다. 일반적으로 매크로 대신 규칙을 사용하는 것이 좋습니다. 사용자에게 표시되는 빌드 그래프는 빌드 중에 Bazel에서 사용하는 그래프와 다릅니다. 매크로는 Bazel에서 빌드 그래프 분석을 실행하기 전에 확장됩니다.
따라서 문제가 발생하면 사용자가 빌드 문제를 해결하기 위해 매크로의 구현을 이해해야 합니다. 또한 결과에 표시되는 타겟은 매크로 확장에서 가져오므로 bazel
query 결과를 해석하기 어려울 수 있습니다. 마지막으로, 측면은 매크로를 인식하지 않으므로 측면에 종속된 도구 (IDE 등)가 실패할 수 있습니다.
매크로를 안전하게 사용하는 방법은 Bazel CLI 또는 BUILD 파일에서 직접 참조할 추가 타겟을 정의하는 것입니다. 이 경우 해당 타겟의 최종 사용자만 이를 알아야 하며 매크로로 인해 발생하는 모든 빌드 문제는 매크로 사용과 밀접한 관련이 있습니다.
생성된 타겟을 정의하는 매크로 (CLI에서 참조되어서는 안 되거나 해당 매크로에 의해 인스턴스화되지 않은 타겟에서 종속되어서는 안 되는 매크로의 구현 세부정보)의 경우 다음 권장사항을 따르세요.
- 매크로는
name인수를 사용하고 이 이름으로 타겟을 정의해야 합니다. 이 대상이 해당 매크로의 기본 대상이 됩니다. - 생성된 타겟(즉, 매크로로 정의된 다른 모든 타겟)은 다음을 충족해야 합니다.
- 이름 앞에
<name>또는_<name>가 붙습니다. 예를 들어name = '%s_bar' % (name)을 사용합니다. - 공개 상태가 제한됨 (
//visibility:private) - 와일드 카드 타겟 (
:all,...,:*등)의 확장을 방지하기 위한manual태그가 있습니다.
- 이름 앞에
name는 매크로에 의해 정의된 타겟의 이름을 파생하는 데만 사용해야 하며 다른 용도로는 사용하면 안 됩니다. 예를 들어 매크로 자체에서 생성되지 않은 종속 항목이나 입력 파일을 파생하는 데 이름을 사용하지 마세요.- 매크로에서 생성된 모든 타겟은 어떤 방식으로든 기본 타겟에 연결되어야 합니다.
- 매크로의 매개변수 이름을 일관되게 유지합니다. 매개변수가 속성 값으로 기본 타겟에 전달되는 경우 이름을 동일하게 유지합니다. 매크로 매개변수가
deps와 같은 공통 규칙 속성과 동일한 목적을 수행하는 경우 속성과 동일하게 이름을 지정합니다 (아래 참고). - 매크로를 호출할 때는 키워드 인수만 사용하세요. 이렇게 하면 규칙과 일치하고 가독성이 크게 개선됩니다.
엔지니어는 규칙이 Bazel 내에서 네이티브 코드로 정의되어 있는지 또는 Starlark로 정의되어 있는지에 관계없이 관련 규칙의 Starlark API가 특정 사용 사례에 충분하지 않은 경우 종종 매크로를 작성합니다. 이 문제가 발생하면 규칙 작성자에게 목표를 달성하기 위해 API를 확장할 수 있는지 문의하세요.
일반적으로 매크로가 규칙과 유사할수록 좋습니다.
매크로도 참고하세요.
규칙
- 규칙, 측면, 속성은 lower_case 이름 ('뱀 문자')을 사용해야 합니다.
- 규칙 이름은 종속 항목 (또는 리프 규칙의 경우 사용자)의 관점에서 규칙에서 생성되는 주요 아티팩트 유형을 설명하는 명사입니다. 반드시 파일 확장자가 아닐 수도 있습니다. 예를 들어 Python 확장 프로그램으로 사용하기 위한 C++ 아티팩트를 생성하는 규칙은
py_extension라고 할 수 있습니다. 대부분의 언어의 일반적인 규칙은 다음과 같습니다.*_library- 컴파일 단위 또는 '모듈'입니다.*_binary- 실행 파일 또는 배포 단위를 생성하는 타겟입니다.*_test: 테스트 대상입니다. 여기에는 여러 테스트가 포함될 수 있습니다.*_test타겟의 모든 테스트가 동일한 테마의 변형(예: 단일 라이브러리 테스트)이라고 예상합니다.*_import: 사전 컴파일된 아티팩트(예:.jar) 또는 컴파일 중에 사용되는.dll를 캡슐화하는 타겟입니다.
- 속성에 일관된 이름과 유형을 사용합니다. 일반적으로 적용할 수 있는 속성은 다음과 같습니다.
srcs:label_list: 파일 허용: 일반적으로 사람이 작성한 소스 파일입니다.deps:label_list, 일반적으로 파일을 허용하지 않음: 컴파일 종속 항목data:label_list: 파일 허용: 테스트 데이터와 같은 데이터 파일runtime_deps:label_list: 컴파일에 필요하지 않은 런타임 종속 항목입니다.
- 명확하지 않은 동작이 있는 속성 (예: 특수 대체가 있는 문자열 템플릿 또는 특정 요구사항으로 호출되는 도구)의 경우 속성 선언 (
attr.label_list()또는 유사)에doc키워드 인수를 사용하여 문서를 제공합니다. - 규칙 구현 함수는 거의 항상 비공개 함수여야 합니다(이름 앞에 밑줄이 표시됨). 일반적인 스타일은
myrule의 구현 함수에_myrule_impl라는 이름을 지정하는 것입니다. - 잘 정의된 제공자 인터페이스를 사용하여 규칙 간에 정보를 전달합니다. 제공업체 필드를 선언하고 문서화합니다.
- 확장성을 염두에 두고 규칙을 설계하세요. 다른 규칙이 내 규칙과 상호작용하고, 제공업체에 액세스하고, 내가 만든 작업을 재사용하려고 할 수 있습니다.
- 규칙에서 성능 가이드라인을 따르세요.