.bzl 스타일 가이드

<ph type="x-smartling-placeholder"></ph> 문제 신고 소스 보기 1박 · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

이 페이지에서는 Starlark의 기본 스타일 가이드라인을 다루며 정보를 제공하는 데 사용됩니다.

Starlark는 소프트웨어의 빌드 방식을 정의하는 언어이며, 따라서 프로그래밍 및 구성 언어입니다.

Starlark를 사용하여 BUILD 파일, 매크로, 빌드 규칙을 작성합니다. 매크로 및 규칙은 기본적으로 메타 언어입니다. 즉, BUILD 파일이 작성되는 방식을 정의합니다. BUILD 파일은 단순하고 반복하기 위한 것입니다.

모든 소프트웨어는 작성된 것보다 더 자주 읽힙니다. 이는 특히 Starlark, 엔지니어가 BUILD 파일을 읽고 대상과 빌드의 세부정보를 볼 수 있습니다 이 판독값은 종종 서두르게 하든, 동시에 다른 작업을 완수하기 위해 해야 할 수도 있습니다. 따라서 단순성과 가독성이 매우 중요합니다. 그래야 사용자가 BUILD 파일을 빠르게 이해할 수 있습니다.

사용자는 BUILD 파일을 열 때 파일이고 또는 해당 C++ 라이브러리의 소스 목록을 검토합니다. 또는 종속 항목을 제거합니다. 추상화 계층을 추가할 때마다 사용자가 이러한 작업을 수행하기 어렵게 만듭니다.

또한 BUILD 파일은 다양한 도구로 분석되고 업데이트됩니다. 도구가 추상화를 사용하는 경우 BUILD 파일을 수정할 수 있어야 합니다. BUILD 유지 더 나은 도구를 얻을 수 있습니다. 코드베이스가 증가함에 따라 많은 BUILD 파일에 걸쳐 변경사항을 점점 더 자주 라이브러리를 업데이트하거나 정리해야 합니다.

일반 도움말

스타일

Python 스타일

확실하지 않은 경우 가능한 경우 PEP 8 스타일 가이드를 참고하세요. 특히 들여쓰기에 두 개가 아닌 4개의 공백을 사용하여 Python 규칙을 따릅니다.

이후 Starlark는 Python이 아님 Python 스타일의 일부 측면이 적용되지 않습니다. 예를 들어 PEP 8은 싱글톤에 대한 비교는 is을 사용하여 수행됩니다. 이는 스타라크.

문서 문자열

docstring을 사용하여 문서 파일 및 함수 각 .bzl 파일의 맨 위에 docstring 및 각 공개 파일에 docstring 사용 함수를 사용하세요.

문서화 규칙 및 관점

규칙과 관점, 속성, 제공업체 및 필드는 doc 인수를 사용하여 문서화되어야 합니다.

이름 지정 규칙

  • 변수 및 함수 이름은 소문자를 사용하고 단어는 밑줄([a-z][a-z0-9_]*)(예: cc_library)
  • 최상위 비공개 값은 밑줄 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() 함수를 사용하지 마세요. Kubernetes는 .bzl 파일의 직간접 사용자에게 모두 스팸을 보냅니다. 이 단, 사용 중지된 경우 print()를 사용하는 코드를 제출할 수 있습니다. 기본적으로 소스 수정을 통해서만 사용 설정할 수 있습니다. 예를 들어 print() 사용은 if DEBUG:에 의해 보호됩니다. 여기서 DEBUG는 다음과 같이 하드코딩됩니다. False입니다. 이러한 진술이 타당성을 입증할 만큼 유용한지 가독성에 미치는 영향을 확인할 수 있습니다.

매크로

매크로는 로드되는 동안 하나 이상의 규칙을 인스턴스화하는 함수입니다. 준비 단계입니다 가능한 한 매크로 대신 규칙을 사용합니다. 빌드 사용자가 보게 되는 그래프는 해당 기간 동안 Bazel이 사용한 그래프와 Bazel이 빌드 그래프 분석을 수행하기 전에 매크로가 확장됩니다.

그렇기 때문에 문제가 발생하면 사용자는 매크로의 구현을 확인하여 빌드 문제를 해결할 수 있습니다. 또한 결과에 타겟이 표시되기 때문에 bazel query 결과를 해석하기 어려울 수 있습니다. 매크로 확장에서 비롯됩니다 마지막으로 관점은 매크로를 인식하지 못하므로 여러 측면 (IDE 등)에 따라 실패할 수 있습니다.

매크로의 안전한 용도는 Bazel CLI 또는 BUILD 파일에서 직접 참조됩니다. 이 경우에는 이러한 대상의 최종 사용자가 이를 알아야 하며 빌드 문제가 있는 경우 자주 사용됩니다.

생성된 타겟 (매크로 구현 세부정보)을 정의하는 매크로 CLI에서 참조되거나 대상에 의해 의존해서는 안 되는 대상 해당 매크로로 인스턴스화되지 않음) 다음 권장사항을 따르세요.

  • 매크로는 name 인수를 사용하고 그 이름으로 타겟을 정의해야 합니다. 이 타겟이 매크로의 기본 타겟이 됩니다.
  • 생성된 타겟(매크로에 의해 정의된 다른 모든 타겟)은 다음과 같아야 합니다. <ph type="x-smartling-placeholder">
      </ph>
    • 이름 앞에 <name> 또는 _<name>를 붙입니다. 예를 들어 name = '%s_bar' % (name)
    • 공개 상태가 제한된 경우 (//visibility:private)
    • 와일드 카드 타겟 (:all,manual ..., :* 등).
  • name는 매크로로 처리되어야 합니다. 예를 들어 매크로 자체에 의해 생성되지 않은 종속성 또는 입력 파일이 있을 수 있습니다.
  • 매크로에서 생성된 모든 타겟은 어떤 방식으로든 주요 표적입니다.
  • 매크로의 매개변수 이름을 일관되게 유지합니다. 매개변수가 전달되는 경우 속성 값으로 사용하는 경우 이름을 동일하게 유지하세요. 매크로가 매개변수는 deps은 속성과 같은 이름입니다 (아래 참고).
  • 매크로를 호출할 때는 키워드 인수만 사용하세요. 이것은 가독성이 크게 향상됩니다.

엔지니어는 관련 규칙의 Starlark API가 특정 사용 사례에는 충분하지 않습니다. Bazel 내에서 또는 Starlark에서 정의됩니다. 이 문제가 발생하면 규칙 작성자에게 목표를 달성할 수 있습니다.

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

매크로도 참고하세요.

규칙

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