.bzl 파일

_로 시작하는 암시적 속성에는 기본값이 있어야 하며 유형은 label 또는 label_list여야 합니다.

명시적 속성은 유형이 string이어야 하며 values 제한을 사용해야 합니다. 명시적 속성은 제한사항에 따라 동일한 이름, 유형, 유효한 값의 속성이 있는 규칙에만 사용되도록 측정기준을 제한합니다.

선언된 속성은 None를 기본값으로 변환합니다.

중첩되지 않은 제공업체 목록은 제공업체 목록 1개가 포함된 목록으로 자동 변환됩니다. 즉, [FooInfo, BarInfo]가 자동으로 [[FooInfo, BarInfo]]로 변환됩니다.

일부 규칙 (예: some_rule) 타겟을 측정기준에 표시하려면 some_rule가 필수 제공업체 목록 중 하나 이상에서 모든 제공업체를 광고해야 합니다. 예를 들어 측정의 required_providers가 [[FooInfo], [BarInfo], [BazInfo, QuxInfo]]인 경우 이 측정은 some_rule가 FooInfo, 또는 BarInfo, 또는 BazInfo 및 QuxInfo을 모두 제공하는 경우에만 some_rule 타겟을 볼 수 있습니다.

중첩되지 않은 제공업체 목록은 제공업체 목록 1개가 포함된 목록으로 자동 변환됩니다. 즉, [FooInfo, BarInfo]가 자동으로 [[FooInfo, BarInfo]]로 변환됩니다.

다른 측면 (예: other_aspect)을 이 측면에 표시하려면 other_aspect가 하나 이상의 목록에서 모든 제공업체를 제공해야 합니다. [[FooInfo], [BarInfo], [BazInfo, QuxInfo]]의 예에서 이 측면은 other_aspect가 FooInfo, 또는 BarInfo, 또는 BazInfo 및 QuxInfo를 모두 제공하는 경우에만 other_aspect를 볼 수 있습니다.

구현 함수가 여기에 나열된 제공자 유형 중 하나를 반환 값에서 생략하면 오류가 발생합니다. 그러나 구현 함수는 여기에 나열되지 않은 추가 제공업체를 반환할 수 있습니다.

목록의 각 요소는 provider()에서 반환된 *Info 객체입니다. 단, 기존 제공업체는 문자열 이름으로 대신 표시됩니다. 규칙의 타겟이 필수 제공업체를 선언하는 타겟의 종속 항목으로 사용되는 경우 여기에서 해당 제공업체를 지정할 필요가 없습니다. 구현 함수가 반환하면 됩니다. 하지만 필수사항은 아니지만 지정하는 것이 좋습니다. 그러나 측정항목의 required_providers 필드에는 제공업체를 여기에서 지정해야 합니다.

예를 들어 측면이 속성 `deps` 를 통해 전이적으로 전파되고 타겟 `alpha`에 적용된다고 가정해 보겠습니다. `alpha` 에 `deps = [':beta_output']`가 있다고 가정해 보겠습니다. 여기서 `beta_output` 은 타겟 `beta`의 선언된 출력입니다. `beta` 에 타겟 `charlie` 가 `deps` 중 하나로 있다고 가정해 보겠습니다. 측면의 `apply_to_generating_rules=True` 인 경우 측면이 `alpha`, `beta`, `charlie`를 통해 전파됩니다. False인 경우 측면은 `alpha`로만 전파됩니다.

기본값은 false입니다.

관례에 따라 구현 함수에는 매크로가 '기본'이 아닌 타겟을 검사, 수정 또는 전달해야 하는 모든 속성에 이름이 지정된 매개변수가 있어야 합니다. 반면 '기본' 타겟에 변경되지 않은 상태로 전달되는 '대량' 상속 속성은 **kwargs로 전달됩니다.

구현 함수는 값을 반환해서는 안 됩니다. 대신 구현 함수는 규칙 또는 매크로 기호를 호출하여 타겟을 선언합니다.

기호 매크로 (매크로의 구현 함수가 전이적으로 호출하는 모든 Starlark 함수 포함)에 의해 선언된 타겟 또는 내부 기호 매크로의 이름은 name('기본' 타겟이라고 함)과 같거나 name로 시작하고 구분자 문자 ("_", "-" 또는 ".")와 문자열 접미사가 이어져야 합니다. 이 이름 지정 체계를 위반하는 타겟은 선언할 수 있지만 빌드, 구성 또는 종속할 수는 없습니다.

기본적으로 기호 매크로 (매크로의 구현 함수가 전이적으로 호출하는 모든 Starlark 함수 포함)로 선언된 타겟은 매크로를 정의하는 .bzl 파일이 포함된 패키지에만 표시됩니다. 기호 매크로 호출자를 포함하여 외부에 표시되는 타겟을 선언하려면 구현 함수가 visibility를 적절하게 설정해야 합니다. 일반적으로 호출되는 규칙 또는 매크로 기호에 visibility = visibility를 전달합니다.

매크로 구현 함수와 이 함수가 전이적으로 호출하는 모든 Starlark 함수 내에서는 다음 API를 사용할 수 없습니다.

• package(), licenses()
• environment_group()
• native.glob() – 대신 라벨 목록 속성을 통해 매크로에 글로브를 전달할 수 있습니다.
• native.subpackages()
• (규칙 최종 처리기에서만 허용됨, 아래 finalizer 참고) native.existing_rules(), native.existing_rule()
• (WORKSPACE 스레드의 경우) workspace(), register_toolchains(), register_execution_platforms(), bind(), 저장소 규칙 인스턴스화

특수 name 속성은 사전에서 선언되며 사전에 포함되어서는 안 됩니다. visibility 속성 이름은 예약되어 있으며 사전에 포함되어서는 안 됩니다.

이름이 _로 시작하는 속성은 비공개입니다. 규칙의 호출 위치에서 전달할 수 없습니다. 이러한 속성은 기본값 (예: attr.label(default="//pkg:foo"))을 할당하여 라벨에 대한 암시적 종속 항목을 만들 수 있습니다.

메모리 사용량을 제한하기 위해 선언할 수 있는 속성 수에 한도가 있습니다.

inherit_attrs가 문자열 "common"로 설정되면 매크로는 모든 Starlark 규칙에서 사용하는 공통 규칙 속성 정의를 상속합니다.

rule() 또는 macro()의 반환 값이 .bzl 파일의 전역 변수에 할당되지 않은 경우 이러한 값은 규칙 또는 매크로 기호로 등록되지 않았으므로 inherit_attrs에 사용할 수 없습니다.

상속 메커니즘은 다음과 같이 작동합니다.

1. 특수 name 및 visibility 속성은 상속되지 않습니다.
2. 숨겨진 속성 (이름이 "_"로 시작하는 속성)은 상속되지 않습니다.
3. 이름이 이미 attrs 사전에 정의된 속성은 상속되지 않습니다 (attrs의 항목이 우선 적용됨). 해당 이름의 속성이 매크로에 정의되지 않도록 하려면 항목을 None로 설정할 수 있습니다.
4. 다른 모든 속성은 규칙 또는 매크로에서 상속되며 효과적으로 attrs 사전으로 병합됩니다.

필수가 아닌 속성이 상속되면 속성의 기본값은 원래 규칙 또는 매크로에서 지정된 내용과 관계없이 None로 재정의됩니다. 이렇게 하면 매크로가 수정되지 않은 **kwargs를 전달하는 등 래핑된 규칙 또는 매크로의 인스턴스에 속성 값을 전달할 때 외부 매크로 호출에 없던 값이 내부 규칙 또는 매크로 호출에도 없게 됩니다 (None를 속성에 전달하는 것이 속성을 생략하는 것과 동일하게 취급되기 때문). 이는 속성을 생략하는 것이 표시된 기본값을 전달하는 것과 미묘하게 다른 시맨틱을 가지기 때문에 중요합니다. 특히 생략된 속성은 일부 bazel query 출력 형식에 표시되지 않으며 계산된 기본값은 값이 생략된 경우에만 실행됩니다. 상속된 속성을 검사하거나 수정해야 하는 매크로(예: 상속된 tags 속성에 값 추가)의 경우 매크로의 구현 함수에서 None 사례를 처리해야 합니다.

예를 들어 다음 매크로는 cxxopts (속성 목록에서 삭제됨) 및 copts(새로운 정의를 부여함)를 제외한 native.cc_library의 모든 속성을 상속합니다. 또한 태그를 추가하기 전에 상속된 tags 속성의 기본 None 값을 확인합니다.

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

inherit_attrs가 설정된 경우 매크로의 구현 함수에는 **kwargs 잔여 키워드 매개변수가 있어야 합니다.

관례에 따라 매크로는 상속된 재정의되지 않은 속성을 변경되지 않은 상태로 매크로가 래핑하는 '기본' 규칙 또는 매크로 기호에 전달해야 합니다. 일반적으로 상속된 대부분의 속성은 구현 함수의 매개변수 목록에 매개변수가 없으며 **kwargs를 통해 전달됩니다. 매크로가 이러한 속성을 '기본' 타겟과 '기본'이 아닌 타겟 모두에 전달해야 하는 경우 구현 함수에 일부 상속 속성 (일반적으로 tags 및 testonly)에 관한 명시적 매개변수가 있는 것이 편리할 수 있습니다. 하지만 매크로가 이러한 속성을 검사하거나 조작해야 하는 경우 필수가 아닌 상속 속성의 None 기본값을 처리해야 합니다.

일반 기호 매크로와 달리 규칙 최종 처리기는 native.existing_rule() 및 native.existing_rules()를 호출하여 현재 패키지에 정의된 최종 처리기가 아닌 규칙 타겟 집합을 쿼리할 수 있습니다. native.existing_rule() 및 native.existing_rules()는 이 규칙 최종 처리자를 포함하여 규칙 최종 처리자가 정의한 타겟에 액세스할 수 없습니다.

• 필드 목록:
  

  provider(fields = ['a', 'b'])

• 사전 필드 이름 -> 문서:
  

  provider(
         fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })

정확한 설명은 다음과 같습니다. 직관적인 설명과 사용 사례는 규칙 (제공자 맞춤 초기화)을 참고하세요.

P는 provider()를 호출하여 생성된 제공업체 기호입니다. 개념적으로 P의 인스턴스는 다음을 실행하는 기본 생성자 함수 c(*args, **kwargs)를 호출하여 생성됩니다.

• args가 비어 있지 않으면 오류가 발생합니다.
• provider()가 호출될 때 fields 매개변수가 지정되었고 kwargs에 fields에 나열되지 않은 키가 포함된 경우 오류가 발생합니다.
• 그 외의 경우에는 c가 kwargs의 각 k: v 항목에 대해 값이 v인 k라는 필드가 있는 새 인스턴스를 반환합니다.

MyInfo = provider()
m = MyInfo(foo = 1)

하지만 init가 지정된 경우에는 P(*args, **kwargs) 호출이 대신 다음 단계를 실행합니다.

1. 콜백은 init(*args, **kwargs)로 호출되며, 즉 P에 전달된 것과 정확히 동일한 위치 및 키워드 인수를 사용합니다.
2. init의 반환 값은 키가 필드 이름 문자열인 사전 d이어야 합니다. 그렇지 않으면 오류가 발생합니다.
3. P의 새 인스턴스는 c(**d)에서와 같이 d의 항목을 키워드 인수로 사용하여 기본 생성자를 호출하는 것처럼 생성됩니다.

참고: 위 단계는 *args 또는 **kwargs가 init의 서명과 일치하지 않거나 init의 본문 평가가 실패하거나 (의도적으로 fail() 호출을 통해 실패할 수 있음) init의 반환 값이 예상되는 스키마가 있는 사전이 아닌 경우 오류가 발생함을 의미합니다.

이렇게 하면 init 콜백은 전처리 및 유효성 검사를 위한 위치 인수와 임의 로직을 허용하여 일반 제공자 구성을 일반화합니다. 허용된 fields 목록을 우회할 수 없습니다.

init가 지정되면 provider()의 반환 값이 튜플 (P, r)이 됩니다. 여기서 r는 원시 생성자입니다. 실제로 r의 동작은 위에서 설명한 기본 생성자 함수 c의 동작과 정확히 일치합니다. 일반적으로 r는 이름 앞에 밑줄이 붙은 변수에 바인딩되므로 현재 .bzl 파일만 r에 직접 액세스할 수 있습니다.

MyInfo, _new_myinfo = provider(init = ...)

선언된 속성은 None를 기본값으로 변환합니다.

선언된 속성은 None를 기본값으로 변환합니다.

사전 선언된 출력을 정의하기 위한 스키마입니다. output 및 output_list 속성과 달리 사용자는 이러한 파일의 라벨을 지정하지 않습니다. 사전 선언된 출력에 관한 자세한 내용은 규칙 페이지를 참고하세요.

이 인수의 값은 사전 또는 사전을 생성하는 콜백 함수입니다. 콜백은 계산된 종속 항목 속성과 비슷하게 작동합니다. 함수의 매개변수 이름이 규칙의 속성과 일치합니다. 예를 들어 정의 def _my_func(srcs, deps): ...와 함께 outputs = _my_func를 전달하면 함수는 srcs 및 deps 속성에 액세스할 수 있습니다. 사전이 직접 지정되든 함수를 통해 지정되든 다음과 같이 해석됩니다.

사전의 각 항목은 사전 선언된 출력을 만듭니다. 여기서 키는 식별자이고 값은 출력의 라벨을 결정하는 문자열 템플릿입니다. 규칙의 구현 함수에서 식별자는 ctx.outputs에서 출력의 File에 액세스하는 데 사용되는 필드 이름이 됩니다. 출력 라벨은 규칙과 동일한 패키지를 사용하며 패키지 뒤의 부분은 "%{ATTR}" 형식의 각 자리표시자를 속성 ATTR의 값으로부터 형성된 문자열로 대체하여 생성됩니다.

• 문자열 유형의 속성은 그대로 대체됩니다.
• 라벨 유형 속성은 패키지 뒤의 라벨의 일부가 되며 파일 확장자는 제외됩니다. 예를 들어 "//pkg:a/b.c" 라벨은 "a/b"가 됩니다.
• 출력 유형 속성은 파일 확장자 (위 예에서는 "a/b.c")를 포함하여 패키지 뒤의 라벨의 일부가 됩니다.
• 자리표시자에 사용되는 모든 목록 유형 속성 (예: attr.label_list)에는 요소가 정확히 하나 있어야 합니다. 전환은 목록 외 버전 (attr.label)과 동일합니다.
• 다른 속성 유형은 자리표시자에 표시되지 않을 수 있습니다.
• 속성이 아닌 특수 자리표시자 %{dirname} 및 %{basename}는 패키지를 제외하고 규칙 라벨의 해당 부분으로 확장됩니다. 예를 들어 "//pkg:a/b.c"에서 디렉터리 이름은 a이고 기본 이름은 b.c입니다.

실제로 가장 일반적인 대체 자리표시자는 "%{name}"입니다. 예를 들어 'foo'라는 이름의 타겟의 경우 출력 사전 {"bin": "%{name}.exe"}은 구현 함수에서 ctx.outputs.bin로 액세스할 수 있는 foo.exe라는 출력을 미리 선언합니다.

구현 함수가 여기에 나열된 제공자 유형 중 하나를 반환 값에서 생략하면 오류가 발생합니다. 그러나 구현 함수는 여기에 나열되지 않은 추가 제공업체를 반환할 수 있습니다.

목록의 각 요소는 provider()에서 반환된 *Info 객체입니다. 단, 기존 제공업체는 문자열 이름으로 대신 표시됩니다. 규칙의 타겟이 필수 제공업체를 선언하는 타겟의 종속 항목으로 사용되는 경우 여기에서 해당 제공업체를 지정할 필요가 없습니다. 구현 함수가 반환하면 됩니다. 하지만 필수사항은 아니지만 지정하는 것이 좋습니다. 그러나 측정항목의 required_providers 필드에는 제공업체를 여기에서 지정해야 합니다.

참고: 분석 테스트 규칙은 주로 핵심 Starlark 라이브러리에 제공된 인프라를 사용하여 정의됩니다. 안내는 테스트를 참고하세요.

규칙이 분석 테스트 규칙으로 정의된 경우 속성에 analysis_test_transition을 사용하여 정의된 구성 전환을 사용할 수 있지만 몇 가지 제한사항이 적용됩니다.

• 이 규칙의 타겟은 있을 수 있는 전이 종속 항목의 수에 제한이 있습니다.
• 이 규칙은 test=True가 설정된 것처럼 테스트 규칙으로 간주됩니다. 이 값은 test의 값보다 우선 적용됩니다.
• 규칙 구현 함수가 작업을 등록하지 않을 수 있습니다. 대신 AnalysisTestResultInfo를 제공하여 통과/실패 결과를 등록해야 합니다.

이 함수는 규칙의 각 인스턴스 로드 시 호출됩니다. name 및 규칙에 의해 정의된 공개 속성 값으로 호출됩니다(일반 속성(예: tags)이 아님).

속성 이름에서 원하는 값으로의 사전을 반환해야 합니다. 반환되지 않는 속성은 영향을 받지 않습니다. None를 값으로 반환하면 속성 정의에 지정된 기본값이 사용됩니다.

이니셜라이저는 속성 정의에 지정된 기본값보다 먼저 평가됩니다. 따라서 이니셜라이저 서명에 있는 매개변수에 기본값이 포함된 경우 속성 정의의 기본값을 덮어씁니다 (None를 반환하는 경우 제외).

마찬가지로 이니셜라이저 서명에 있는 매개변수에 기본값이 없으면 매개변수가 필수가 됩니다. 이러한 경우 속성 정의에서 기본/필수 설정을 생략하는 것이 좋습니다.

처리되지 않는 속성에는 **kwargs를 사용하는 것이 좋습니다.

확장된 규칙의 경우 모든 이니셜라이저가 하위 요소에서 상위 요소로 진행하면서 호출됩니다. 각 이니셜라이저에는 알고 있는 공개 속성만 전달됩니다.

하위 규칙에는 라벨 유형 (예: 라벨 또는 라벨 목록)의 비공개 속성만 있을 수 있습니다. 이러한 라벨에 해당하는 확인된 값은 Bazel에서 하위 규칙의 구현 함수에 이름이 지정된 인수로 자동 전달됩니다. 따라서 구현 함수는 속성 이름과 일치하는 이름이 지정된 매개변수를 허용해야 합니다. 이러한 값의 유형은 다음과 같습니다.

• executable=True가 있는 라벨 속성의 경우 FilesToRunProvider
• allow_single_file=True가 있는 라벨 속성의 경우 File
• 다른 모든 라벨 속성의 경우 Target
• 모든 라벨 목록 속성의 경우 [Target]

선언된 속성은 rule(), aspect(), repository_rule()와 달리 None를 기본값으로 변환하지 않습니다. 기본값을 사용하려면 호출자가 속성을 완전히 생략해야 합니다.

패키지 사양은 package_group와 동일한 형식을 따르지만, 음수 패키지 사양은 허용되지 않습니다. 즉, 사양은 다음과 같은 형식일 수 있습니다.

• "//foo": 패키지 //foo
• "//foo/...": //foo 패키지 및 모든 하위 패키지입니다.
• "public" 또는 "private": 각각 모든 패키지 또는 패키지 없음

'@' 문법은 허용되지 않습니다. 모든 사양은 현재 모듈의 저장소를 기준으로 해석됩니다.

value가 문자열 목록인 경우 이 모듈에 공개 상태가 부여된 패키지 세트는 각 사양으로 표현된 패키지의 합집합입니다. 빈 목록은 private와 동일한 효과가 있습니다. value이 단일 문자열인 경우 싱글톤 목록 [value]인 것처럼 처리됩니다.

--incompatible_package_group_has_public_syntax 및 --incompatible_fix_package_group_reporoot_syntax 플래그는 이 인수에 영향을 미치지 않습니다. "public" 및 "private" 값은 항상 사용할 수 있으며 "//..."는 항상 '현재 저장소의 모든 패키지'로 해석됩니다.