.bzl 스타일 가이드

문제 신고 소스 보기

이 페이지에는 Starlark의 기본 스타일 가이드라인과 매크로 및 규칙에 대한 정보가 포함되어 있습니다.

Starlark는 소프트웨어 빌드 방법을 정의하는 언어이므로 프로그래밍 언어와 구성 언어입니다.

Starlark를 사용하여 BUILD 파일, 매크로, 빌드 규칙을 작성합니다. 매크로와 규칙은 기본적으로 메타 언어입니다. BUILD 파일 작성 방법을 정의합니다. BUILD 파일은 단순하며 반복적이어야 합니다.

모든 소프트웨어가 작성된 것보다 더 자주 판독됩니다. Starlark의 경우 엔지니어가 BUILD 파일을 읽고 타겟의 종속 항목과 빌드 세부정보를 이해하기 때문에 특히 그렇습니다. 이러한 읽기는 다른 작업을 완수하는 데 지나가거나 서두르거나 동시에 일어나는 경우가 많습니다. 따라서 사용자가 BUILD 파일을 빠르게 파싱하고 이해할 수 있도록 단순성과 가독성이 매우 중요합니다.

사용자는 BUILD 파일을 열 때 파일의 타겟 목록을 빠르게 파악하거나 C++ 라이브러리의 소스 목록을 검토하거나 자바 바이너리에서 종속 항목을 삭제하려고 합니다. 추상화 레이어를 추가할 때마다 사용자가 이러한 작업을 수행하기가 더 어려워집니다.

BUILD 파일도 여러 다양한 도구로 분석 및 업데이트됩니다. BUILD 파일을 추상화하는 경우에는 도구에서 파일을 수정하지 못할 수 있습니다. BUILD 파일을 단순하게 유지하면 도구를 더 잘 활용할 수 있습니다. 코드베이스가 커질수록 라이브러리를 업데이트하거나 정리하기 위해 여러 BUILD 파일에 변경사항을 적용하는 경우가 점점 더 많아지고 있습니다.

일반 도움말

스타일을 살리면서도

Python 스타일

확실하지 않은 경우 가능하면 PEP 8 스타일 가이드를 따르세요. 특히 들여쓰기 간격에 2개가 아닌 4개의 공백을 사용하여 Python 규칙을 따르세요.

Starlark는 Python이 아니므로 Python 스타일의 일부 측면은 적용되지 않습니다. 예를 들어, PEP 8은 Starlark의 연산자가 아닌 is로 싱글톤을 비교하도록 조언합니다.

문서 문자열

docstring을 사용하여 파일 및 함수를 문서화합니다. 각 .bzl 파일 상단에 있는 docstring과 각 공개 함수에 docstring을 사용합니다.

문서 규칙 및 측면

제공자, 필드, 규칙, 특성은 doc 인수를 사용하여 문서화되어야 합니다.

이름 지정 규칙

  • 변수와 함수 이름은 밑줄([a-z][a-z0-9_]*)로 구분된 단어(예: cc_library)와 함께 소문자를 사용합니다.
  • 최상위 수준의 비공개 값은 밑줄 1개로 시작합니다. Bazel은 다른 파일에서 비공개 값을 사용할 수 없도록 합니다. 로컬 변수에서는 밑줄 프리픽스를 사용하면 안 됩니다.

행 길이

BUILD 파일에서와 마찬가지로 라벨은 길 수 있으므로 행 길이 제한이 없습니다. 가능하면 Python의 스타일 가이드인 PEP 8을 따라 한 줄당 최대 79자 (영문 기준)를 사용해 보세요. 이 가이드라인을 엄격하게 시행해서는 안 됩니다. 편집자는 80개가 넘는 열을 표시해야 하고 자동화된 변경사항으로 인해 더 긴 줄이 생기게 됩니다. 또한 사람이 이미 읽을 수 있는 행을 분할하는 데 시간을 보내서는 안 됩니다.

키워드 인수

키워드 인수에서는 등호 주변의 공백을 사용하는 것이 좋습니다.

def fct(name, srcs):
    filtered_srcs = my_filter(source = srcs)
    native.cc_library(
        name = name,
        srcs = filtered_srcs,
        testonly = True,
    )

부울 값

부울 값(예: 규칙에 부울 속성을 사용하는 경우)에는 10 대신 TrueFalse 값을 사용합니다.

프로덕션 코드에는 print() 함수를 사용하지 마세요. 이 함수는 디버깅 용도로만 사용되며 .bzl 파일의 모든 직간접 사용자를 대상으로 스팸을 보냅니다. 유일한 예외는 print()를 사용하는 코드를 제출할 수 있다는 점입니다. 기본적으로 사용 중지되어 있고 소스를 수정해야만 사용 설정할 수 있습니다. 예를 들어 print()의 모든 사용이 if DEBUG:에 의해 보호되는 경우 DEBUGFalse에 하드코딩됩니다. 이러한 내용이 가독성에 미치는 영향을 정당화할 만큼 유용한지 명심하세요.

매크로

매크로는 로드 단계 중에 하나 이상의 규칙을 인스턴스화하는 함수입니다. 일반적으로 매크로 대신 가능한 한 규칙을 사용하세요. 사용자에게 표시되는 빌드 그래프는 빌드 중에 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를 확장할 수 있는지 문의하세요.

일반적으로 규칙과 유사한 매크로가 많을수록 좋습니다.

매크로도 참고하세요.

규칙

  • 규칙, 측면 및 속성의 경우 소문자로 된 이름('뱀 사례')을 사용해야 합니다.
  • 규칙 이름은 종속 항목 (또는 리프 규칙의 경우 사용자)의 관점에서 규칙으로 생성된 기본 아티팩트의 유형을 설명하는 명사입니다. 이는 반드시 파일 접미사일 필요는 없습니다. 예를 들어 Python 확장 프로그램으로 사용하기 위한 C++ 아티팩트를 생성하는 규칙의 이름은 py_extension일 수 있습니다. 대부분의 언어에서 일반적인 규칙은 다음과 같습니다.
    • *_library: 컴파일 단위 또는 '모듈'입니다.
    • *_binary - 실행 파일 또는 배포 단위를 생성하는 대상
    • *_test: 테스트 대상입니다. 여기에는 여러 테스트가 포함될 수 있습니다. *_test 타겟의 모든 테스트는 동일한 테마의 변형일 것입니다(예: 단일 라이브러리 테스트).
    • *_import: 사전 컴파일된 아티팩트(예: .jar 또는 컴파일 중에 사용되는 .dll)를 캡슐화하는 타겟입니다.
  • 속성에 일관된 이름과 유형을 사용합니다. 일반적으로 적용되는 속성은 다음과 같습니다.
    • srcs: label_list, files: 소스 파일(일반적으로 사람이 작성)
    • deps: label_list, 일반적으로 파일을 허용하지 않음: 컴파일 종속 항목
    • data: label_list, 테스트 데이터 등의 데이터 파일을 허용합니다.
    • runtime_deps: label_list: 컴파일에 필요하지 않은 런타임 종속 항목입니다.
  • 동작이 명확하지 않은 속성 (예: 특수 대체품이 있는 문자열 템플릿 또는 특정 요구사항을 통해 호출되는 도구)의 경우 doc 키워드 인수를 속성 선언(attr.label_list() 또는 이와 유사한)에 사용하여 문서를 제공합니다.
  • 규칙 구현 함수는 거의 항상 비공개 함수(선행 밑줄로 이름이 지정됨)여야 합니다. 일반적인 스타일은 myrule의 구현 함수에 _myrule_impl 이름을 지정하는 것입니다.
  • 잘 정의된 provider 인터페이스를 사용하여 규칙 간에 정보를 전달합니다. 제공자 필드를 선언하고 문서화합니다.
  • 확장성을 고려하여 규칙을 설계합니다. 다른 규칙으로 규칙과 상호작용하고 제공업체에 액세스하며 개발자가 만든 작업을 재사용하고자 할 수도 있습니다.
  • 규칙의 실적 가이드라인을 따릅니다.