빌드 스타일 가이드

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

BUILD 파일 형식 지정은 Go와 동일한 접근 방식을 따릅니다. 즉, 표준화된 도구가 대부분의 서식 문제를 해결해 줍니다. Buildifier는 빌드 함수를 파싱하고 표준 스타일로 소스 코드를 내보냅니다. 따라서 모든 BUILD 파일은 자동으로 서식이 지정되므로 서식하는 동안 문제가 되지 않습니다. 살펴보겠습니다 또한 도구를 사용하면 도구를 쉽게 이해, 수정, BUILD 파일을 생성합니다.

BUILD 파일 형식은 buildifier의 출력과 일치해야 합니다.

형식 지정 예

# Test code implementing the Foo controller.
package(default_testonly = True)

py_test(
    name = "foo_test",
    srcs = glob(["*.py"]),
    data = [
        "//data/production/foo:startfoo",
        "//foo",
        "//third_party/java/jdk:jdk-k8",
    ],
    flaky = True,
    deps = [
        ":check_bar_lib",
        ":foo_data_check",
        ":pick_foo_port",
        "//pyglib",
        "//testing/pybase",
    ],
)

파일 구조

권장사항: 다음 순서를 사용하세요 (모든 요소는 선택사항임).

패키지 설명 (댓글)
전체 load() 문
package() 함수
규칙 및 매크로 호출

Buildifier가 독립형 댓글과 댓글을 구별함 알 수 있습니다. 주석이 특정 요소에 첨부되지 않은 경우 그 뒤에 빈 줄이 있어야 합니다. 자동화 작업을 실행할 때는 (예: 규칙을 삭제할 때 댓글 유지 또는 삭제)

# Standalone comment (such as to make a section in a file)

# Comment for the cc_library below
cc_library(name = "cc")

현재 패키지의 대상에 대한 참조

패키지 디렉터리를 기준으로 한 상대 경로로 파일을 참조해야 합니다. (.. 같은 상위 참조를 사용하지 않음) 생성된 파일은 ':' 접두사 를 사용합니다. 소스 파일 : 접두사를 사용하면 안 됩니다. 규칙에는 : 프리픽스를 붙여야 합니다. 대상 예를 들어 x.cc를 소스 파일이라고 가정합니다.

cc_library(
    name = "lib",
    srcs = ["x.cc"],
    hdrs = [":gen_header"],
)

genrule(
    name = "gen_header",
    srcs = [],
    outs = ["x.h"],
    cmd = "echo 'int x();' > $@",
)

대상 이름 지정

대상 이름은 설명적이어야 합니다. 대상에 하나의 소스 파일이 포함된 경우 대상은 일반적으로 해당 소스에서 파생된 이름을 가져야 합니다 (예: cc_library은 chat.cc로, chat는 java_library으로 지정할 수 있습니다. DirectMessage.java의 이름을 direct_message로 지정할 수 있음).

패키지의 동일한 타겟( 포함)에서 설명하는 기능을 제공해야 합니다. 디렉터리 이름 이러한 대상이 없다면 이름을 익명 이름으로 만들지 마세요. 있습니다.

이름이 같은 타겟 (//x)을 언급할 때는 짧은 이름을 사용하는 것이 좋습니다. (//x:x 대신) 같은 패키지에 있는 경우 현지 배송 상품 참조 (//x 대신 :x)

'예약됨'을 사용하지 마세요. 특별한 의미가 있는 대상 이름을 사용할 수 있습니다. 여기에는 all, __pkg__ 및 __subpackages__ 같은 이름은 사용할 때 혼란을 야기하고 예기치 않은 동작을 유발할 수 있습니다.

우세한 팀 협약이 없는 한, 이러한 규정은 법적 구속력이 Google에서 널리 사용되는 권장사항:

일반적으로 "snake_case"를 사용합니다. <ph type="x-smartling-placeholder">
- src가 하나인 java_library의 경우 확장자가 없는 파일 이름과 같음
- Java *_binary 및 *_test 규칙의 경우 다음을 사용합니다. "Upper CamelCase". 이렇게 하면 대상 이름이 src 중 하나와 일치할 수 있습니다. 대상 java_test를 사용하면 test_class 속성을 타겟의 이름에서 추론됩니다.
특정 타겟에 여러 변형이 있는 경우 명확하지 않음 (예: :foo_dev, :foo_prod 또는 :bar_x86, :bar_x64)
_test 대상에 _test, _unittest, Test 또는 Tests 접미사를 추가합니다.
_lib 또는 _library과 같이 무의미한 접미사는 피합니다( _library 타겟과 이에 상응하는 _binary 간의 충돌 방지)
proto 관련 대상의 경우: <ph type="x-smartling-placeholder">
- proto_library 대상의 이름은 _proto(으)로 끝나야 합니다.
- 언어별 *_proto_library 규칙은 기본 규칙과 일치해야 함 proto 대신 _proto를 다음과 같은 언어별 접미사로 대체합니다. <ph type="x-smartling-placeholder">
  - cc_proto_library: _cc_proto
  - java_proto_library: _java_proto
  - java_lite_proto_library: _java_proto_lite

공개 상태

가시성은 최대한 철저하게 액세스를 허용하면서 범위를 지정해야 합니다. 종속 항목을 반전시킬 수 있습니다. 다음으로 __pkg__ 및 __subpackages__ 사용 있습니다.

default_visibility 패키지를 //visibility:public로 설정하지 마세요. //visibility:public은(는) 다음의 타겟에 대해서만 개별적으로 설정해야 합니다. API에 액세스할 수 있습니다 이들은 종속 항목을 사용하도록 설계된 라이브러리일 수 있습니다. 외부 프로젝트나 외부 프로젝트의 리소스에서 사용할 수 있는 바이너리가 빌드할 수 있습니다

종속 항목

종속 항목은 직접 종속 항목 (종속 항목)으로 제한되어야 함 규칙 목록에 있는 소스에서 필요로 합니다. 전이 종속 항목을 나열하지 않습니다.

패키지 로컬 종속 항목이 먼저 나열되고 다음과 같은 방식으로 참조되어야 함 호환되는 현재 패키지의 타겟 참조 섹션을 참조하세요 (절대적인 패키지 이름이 아님).

종속 항목을 단일 목록으로 직접 나열하는 것이 좋습니다. '공통'이라는 단어를 여러 타겟의 종속 항목을 변수로 변환하면 유지관리성이 줄어들고 도구가 대상의 종속성을 변경하는 것이 불가능하며 도움이 될 수 있습니다

Glob

'타겟 없음' 표시 []를 사용합니다. 아무것도 일치하지 않는 glob은 사용하지 마세요. 빈 목록보다 오류가 발생하기 쉽고 덜 명확합니다.

재귀적

재귀 glob을 사용하여 소스 파일을 일치시키지 마세요 (예: glob(["**/*.java"]))을 입력합니다.

재귀 glob은 BUILD 파일을 건너뛰므로 추론하기 어렵게 만듭니다. BUILD 파일이 포함된 하위 디렉터리입니다.

재귀 glob은 일반적으로 BUILD 파일이 그 사이에 종속 항목 그래프가 정의된 디렉터리를 사용하면 원격 캐싱 및 동시 로드를 지원합니다

각 디렉터리에 BUILD 파일을 작성하고 종속 항목 그래프를 생성합니다.

비재귀

비재귀 glob은 일반적으로 허용됩니다.

기타 규칙

대문자와 밑줄을 사용하여 상수 (예: GLOBAL_CONSTANT)를 선언합니다. 소문자와 밑줄을 사용하여 변수를 선언합니다 (예: my_variable).
라벨은 79자(영문 기준)를 초과하더라도 분할해서는 안 됩니다. 라벨은 가능한 한 문자열 리터럴이어야 합니다. 근거: 쉽게 찾아 바꿀 수 있습니다 또한 가독성도 향상됩니다.
이름 속성의 값은 리터럴 상수 문자열이어야 합니다( 에 있는)입니다. 사유: 외부 도구는 name 속성을 사용하여 있습니다. 코드를 해석하지 않고도 규칙을 찾아야 합니다.
불리언 유형 속성을 설정할 때는 정수 값이 아닌 불리언 값을 사용하세요. 기존 이유로 인해 규칙은 필요에 따라 여전히 정수를 불리언으로 변환합니다. 그러나 이는 권장되지 않습니다. 근거: flaky = 1을 다음과 같이 잘못 읽을 수 있습니다. "한 번 재실행하여 이 대상을 무력화하십시오." flaky = True의 말이 모호함 '이 테스트는 불안정합니다.'

Python 스타일 가이드와의 차이점

호환성이 Python 스타일 가이드 하지만 다음과 같은 몇 가지 차이점이 있습니다.

엄격한 행 길이 제한이 없습니다. 긴 댓글과 긴 문자열은 자주 분할됨 최대 79개 열까지 입력할 수 있지만 필수는 아닙니다. 코드에 적용해서는 안 됩니다. 사전 제출 스크립트를 사용할 수 있습니다 사유: 라벨은 이 값을 초과할 수 있습니다. 있습니다. BUILD 파일은 일반적으로 도구로 생성하거나 수정합니다. 잘 맞지 않습니다.
암시적 문자열 연결은 지원되지 않습니다. + 연산자를 사용합니다. 사유: BUILD 파일에 많은 문자열 목록이 포함되어 있습니다. 중요한 것은 쉼표를 사용하면 완전히 다른 결과가 나타납니다. 이로 인해 많은 버그가 발생함 선택할 수 있습니다 이 토론도 참고하세요.
규칙에서 키워드 인수에 = 기호 주위에 공백을 사용합니다. 근거: 명명된 인수는 Python보다 훨씬 더 자주 사용되며 항상 넣으세요. 공백은 가독성을 개선합니다. 이 관례는 전래되어 왔으며 기존 BUILD 파일을 모두 수정할 필요는 없습니다.
기본적으로 문자열에는 큰따옴표를 사용합니다. 근거: 는 Python 스타일 가이드에 명시되어 있지만 일관성을 권장합니다. 그래서 우리는 큰따옴표로 묶은 문자열만 사용하기로 결정했습니다. 많은 언어에서 큰따옴표를 사용함 - 문자열 리터럴의 경우
두 개의 최상위 정의 사이에 빈 줄을 한 줄을 사용합니다. 근거: BUILD 파일의 구조는 일반적인 Python 파일과 다릅니다. Kubernetes는 최상위 수준 서술문입니다. 빈 줄을 사용하면 BUILD 파일이 더 짧아집니다.