일반 규칙

규칙

• 별칭
• config_setting
• 파일 그룹
• genquery
• genrule
• test_suite

alias

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

alias 규칙은 이 규칙을 참조할 수 있는 다른 이름을 생성합니다.

에일리어싱은 '일반' 대상에서만 작동합니다. 특히 package_group 및 test_suite는 별칭을 지정할 수 없습니다.

별칭 규칙에는 고유한 공개 상태 선언이 있습니다. 다른 모든 측면에서는 규칙이 참조하는 규칙 (예: 별칭 은 무시됨, 무시됨, 참조된 규칙의 테스트 전용이 사용됨)이 일부 사소한 예외를 제외하고 작동합니다.

• 명령줄에서 별칭이 언급되면 테스트가 실행되지 않습니다. 참조된 테스트를 실행하는 별칭을 정의하려면 tests 속성에 단일 대상을 갖는 test_suite 규칙을 사용합니다.
• 환경 그룹을 정의할 때 environment 규칙의 별칭은 지원되지 않습니다. --target_environment 명령줄 옵션에서도 지원되지 않습니다.

예

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

인수

config_setting

config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

구성 가능한 속성을 트리거하기 위한 예상 구성 상태 (빌드 플래그 또는 플랫폼 제약조건으로 표현됨)와 일치합니다. 이 규칙을 사용하는 방법은 선택을, 일반 기능의 개요는 구성 가능한 속성을 참고하세요.

예

다음은 --compilation_mode=opt 또는 -c opt (명령줄에서 명시적으로 또는 .bazelrc 파일에서 암시적으로)를 설정하는 모든 빌드와 일치합니다.

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

다음은 ARM을 타겟팅하고 맞춤 정의 FOO=bar (예: bazel build --cpu=arm --define FOO=bar ...)를 적용하는 모든 빌드와 일치합니다.

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )
  

다음은 명령줄을 통해 또는 .bazelrc 파일에서 암시적으로 사용자 정의 플래그 --//custom_flags:foo=1를 설정하는 모든 빌드와 일치합니다.

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

다음은 라벨이 //example:glibc_2_25 있는 constraint_value이 존재한다는 가정 하에 x86_64 아키텍처 및 glibc 버전 2.25로 플랫폼을 타겟팅하는 모든 빌드와 일치합니다. 이 두 가지 이상의 추가 제약 조건 값을 정의하는 경우 플랫폼은 계속 일치됩니다.

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  

메모

• 여러 개의 config_setting가 현재 구성 상태와 일치하면 어떤 일이 발생하는지 알아보려면 선택을 참고하세요.
• 약식 양식을 지원하는 플래그 (예: --compilation_mode vs. -c)의 경우 values 정의는 전체 양식을 사용해야 합니다. 두 양식 중 하나를 사용하여 호출을 자동으로 일치시킵니다.
• 플래그가 여러 값을 사용하는 경우 (예: --copt=-Da --copt=-Db 또는 목록 유형의 Starlark 플래그) "a"는 실제 목록의 어떤 위치에든 있는 경우 일치합니다.

  values = { "myflag": "a,b" }도 동일하게 작동합니다. 즉, --myflag=a --myflag=b, --myflag=a --myflag=b --myflag=c, --myflag=a,b, --myflag=c,b,a와 일치합니다. 정확한 의미 체계는 플래그마다 다릅니다. 예를 들어 --copt는 동일 인스턴스의 여러 값을 지원하지 않습니다. --copt=a,b는 ["a,b"]을 생성하지만 --copt=a --copt=b은 ["a", "b"]을 생성하므로 values = { "copt": "a,b" }는 전자와 일치하지만 후자는 그렇지 않습니다. 하지만 --ios_multi_cpus (Apple 규칙의 경우)는 합니다. -ios_multi_cpus=a,b와 ios_multi_cpus=a --ios_multi_cpus=b 모두 ["a", "b"]을 생성합니다. 플래그 정의를 확인하고 조건을 신중하게 테스트하여 정확한 기대치를 확인하세요.

• 기본 제공 빌드 플래그로 모델링되지 않는 조건을 정의해야 한다면 Starlark 정의 플래그를 사용하세요. --define를 사용할 수도 있지만 이 경우 지원이 약화되므로 권장되지 않습니다. 자세한 내용은 여기를 참고하세요.
• 여러 패키지에서 동일한 config_setting 정의를 반복하지 마세요. 대신 표준 패키지에 정의된 공통 config_setting를 참고하세요.
• values, define_values, constraint_values는 동일한 config_setting에서 어떤 조합으로든 사용할 수 있지만 지정된 config_setting에 하나 이상 설정해야 합니다.

인수

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })
          

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })
          

파일 그룹

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

filegroup를 사용하여 대상 컬렉션에 편리한 이름을 지정합니다. 그런 다음 다른 규칙에서 참조할 수 있습니다.

디렉터리를 직접 참조하는 대신 filegroup를 사용하는 것이 좋습니다. 빌드 시스템은 디렉터리 아래의 모든 파일에 관해 완전히 알지 못하므로 이러한 파일이 변경되면 파일이 다시 빌드되지 않을 수 있습니다. filegroup를 glob와 결합하면 모든 파일이 빌드 시스템에 명시적으로 알려지도록 할 수 있습니다.

예

두 개의 소스 파일로 구성된 filegroup를 만들려면 다음을 실행합니다.

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

또는 glob를 사용하여 testdata 디렉터리를 수정합니다.

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

이러한 정의를 사용하려면 filegroup를 규칙의 라벨과 함께 참조합니다.

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

인수

젠 쿼리

genquery(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery()는 Blaze 쿼리 언어로 지정된 쿼리를 실행하고 결과를 파일로 덤프합니다.

빌드를 일관적으로 유지하기 위해 이 쿼리는 scope 속성에 지정된 타겟의 전이적 클로저만 방문할 수 있도록 허용합니다. strict이 지정되지 않거나 true인 경우 실행 중에 이 규칙을 위반하는 쿼리가 실패합니다 (strict가 false인 경우 범위 외 타겟은 경고와 함께 건너뜀). 이러한 일이 발생하지 않도록 하는 가장 쉬운 방법은 쿼리 표현식과 동일한 범위에서 범위를 언급하는 것입니다.

여기에 허용되는 쿼리와 명령줄에서 유일하게 다른 점은 와일드 카드 타겟 사양 (예: //pkg:* 또는 //pkg:all)이 포함된 쿼리는 여기에서 허용되지 않는다는 것입니다. 이유는 genquery가 쿼리의 전이적 닫힌 범위를 벗어나는 출력에 영향을 주지 않도록 범위를 지정해야 하기 때문입니다. 둘째, BUILD 파일은 와일드 카드 종속 항목을 지원하지 않으므로 (예: deps=["//a/..."]은 허용되지 않음) 두 가지 이유가 있습니다.

genquery 출력은 확정적 출력을 적용하기 위해 --order_output=full를 사용하여 정렬됩니다.

출력 파일의 이름은 규칙의 이름입니다.

예

이 예시에서는 지정된 대상의 임시 클로저에 있는 라벨 목록을 파일에 씁니다.

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

인수

Genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exec_tools, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule는 사용자 정의 Bash 명령어를 사용하여 하나 이상의 파일을 생성합니다.

Genrule은 작업에 대한 특정 규칙이 없는 경우 사용할 수 있는 일반 빌드 규칙입니다. 예를 들어 Bash 한 줄자를 실행할 수 있습니다. 하지만 C++ 파일을 컴파일해야 하는 경우 모든 복잡한 작업이 이미 완료되었으므로 기존 cc_* 규칙을 준수하세요.

genrule을 사용하려면 셸이 명령어 인수를 해석해야 합니다. 또한 PATH에서 사용 가능한 임의의 프로그램을 쉽게 참조할 수 있지만, 이로 인해 명령어가 밀폐되지 않고 재현되지 않을 수 있습니다. 단일 도구만 실행해야 하는 경우에는 대신 run_binary를 사용해 보세요.

테스트 실행에 genrule을 사용하지 마세요. 테스트 및 테스트 결과에 관한 특수한 배치(예: 캐싱 정책 및 환경 변수)가 있습니다. 테스트는 일반적으로 빌드가 완료된 후 타겟 아키텍처에서 실행되어야 하지만 genrule은 빌드 중에 그리고 실행 아키텍처에서 실행됩니다 (두 가지는 다를 수 있음). 범용 테스트 규칙이 필요한 경우 sh_test를 사용하세요.

크로스 컴파일 고려사항

크로스 컴파일에 관한 자세한 내용은 사용자 설명서를 참고하세요.

genrule은 빌드 중에 실행되지만 출력은 빌드 또는 배포 또는 테스트용으로 자주 사용됩니다. 마이크로 컨트롤러용 C 코드를 컴파일하는 예를 생각해 보세요. 컴파일러는 C 소스 파일을 허용하고 마이크로 컨트롤러에서 실행되는 코드를 생성합니다. 생성된 코드는 코드를 빌드하는 데 사용된 CPU에서는 분명히 실행할 수 없지만 C 컴파일러 (소스에서 컴파일된 경우) 자체는 실행해야 합니다.

빌드 시스템은 실행 구성을 사용하여 빌드가 실행되는 머신을 설명하고 대상 구성을 사용하여 빌드의 출력을 출력해야 하는 머신을 설명합니다. 각각을 구성하는 옵션을 제공하고 충돌을 방지하기 위해 해당 파일을 별도의 디렉터리로 분리합니다.

genrule의 경우 빌드 시스템이 종속 항목이 적절하게 빌드되도록 합니다. srcs는 target 구성에 맞게 빌드되고, tools는 exec 구성에 대해 빌드되며, 출력은 target 구성에 사용되는 것으로 간주됩니다. 또한 genrule 명령어가 해당하는 도구에 전달할 수 있는 'Make' 변수도 제공합니다.

genrule에 deps 속성은 정의되지 않도록 하는 것이 중요합니다. 다른 기본 제공 규칙은 규칙 간에 전달된 언어 종속 메타 정보를 사용하여 종속 규칙을 처리하는 방법을 자동으로 결정하지만, genrule의 경우 이러한 수준의 자동화가 불가능합니다. Genrule은 파일 및 runfile 수준에서만 작동합니다.

특수 사례

Exec-exec 컴파일: 빌드 시스템에서 빌드 중에 출력을 실행할 수 있도록 genrule을 실행해야 하는 경우도 있습니다. 예를 들어 genrule이 나중에 다른 genrule에서 사용하는 맞춤 컴파일러를 빌드하는 경우 첫 번째 컴파일러는 exec 구성에 관한 출력을 생성해야 합니다. 이 위치에서 컴파일러가 다른 genrule에서 실행되기 때문입니다. 이 경우 빌드 시스템이 올바른 작업을 자동으로 실행합니다. 빌드 구성에서는 대상 구성 대신 첫 번째 genrule의 srcs 및 outs를 빌드합니다. 자세한 내용은 사용자 설명서를 참조하세요.

JDK 및 C++ 도구: JDK 또는 C++ 컴파일러 도구 모음의 도구를 사용하기 위해 빌드 시스템은 사용할 변수 세트를 제공합니다. 자세한 내용은 'Make' 변수를 참고하세요.

Genrule 환경

genrule 명령어는 set -e -o pipefail를 사용하여 명령어 또는 파이프라인이 실패할 때 실패하도록 구성된 Bash 셸에서 실행됩니다.

빌드 도구는 PATH, PWD, TMPDIR 및 기타 몇 가지 핵심 변수만 정의하는 정리된 프로세스 환경에서 Bash 명령어를 실행합니다. 빌드를 재현할 수 있도록 사용자의 셸 환경에 정의된 대부분의 변수는 genrule의 명령어에 전달되지 않습니다. 그러나 Bazel (Blaze 아님)은 사용자의 PATH 환경 변수 값을 전달합니다. PATH 값을 변경하면 다음 빌드에서 Bazel이 명령어를 다시 실행합니다.

genrule 명령어는 네트워크에 시행되어서는 안 됩니다. 단, 명령어 시행의 하위 요소인 연결 프로세스는 예외입니다.

빌드 시스템은 기존 출력 파일을 자동으로 삭제하지만, genrule을 실행하기 전에 필요한 상위 디렉터리를 만듭니다. 또한 실패 시 모든 출력 파일을 삭제합니다.

일반 조언

• genrule이 실행하는 도구는 확정적이고 밀폐되어 있어야 합니다. 또한 출력에 타임스탬프를 기록해서는 안 되며 세트와 맵에 안정적인 순서를 사용해야 하며 절대 경로가 아닌 상대 파일 경로만 출력에 작성해야 합니다. 이 규칙을 따르지 않으면 예기치 않은 빌드 동작 (Bazel이 생각했던 genrule을 다시 빌드하지 않음)이 발생하며 캐시 성능이 저하됩니다.
• 출력, 도구, 소스에 $(location)를 광범위하게 사용합니다. 다양한 구성의 출력 파일이 분리되어 있으므로 genrule은 하드 코딩 또는 절대 경로에 의존할 수 없습니다.
• 동일하거나 매우 유사한 genrule이 여러 위치에서 사용되는 경우 공통 Starlark 매크로를 작성하세요. genrule이 복잡한 경우 스크립트 또는 Starlark 규칙으로 구현하는 것이 좋습니다. 이렇게 하면 가독성과 테스트 가능성이 향상됩니다.
• 종료 코드가 genrule의 성공 또는 실패를 올바르게 나타내는지 확인합니다.
• stdout 또는 stderr에 정보 메시지를 쓰지 마세요. 디버깅에는 유용하지만 쉽게 노이즈가 될 수 있습니다. 성공적인 genrule은 음소거됩니다. 반면 실패한 genrule은 올바른 오류 메시지를 내보내야 합니다.
• $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x)
• 심볼릭 링크와 디렉터리를 만들지 마세요. Bazel이 genrule에 의해 생성된 디렉터리/심볼릭 링크 구조를 복사하지 않으며 디렉터리의 종속 항목 검사는 적절하지 않습니다.
• 다른 규칙에서 genrule을 참조할 때 genrule의 라벨 또는 개별 출력 파일의 라벨을 사용할 수 있습니다. 한 가지 접근 방식은 다른 것을 더 쉽게 읽을 수 있지만 다른 하나는 소비 규칙의 srcs에서 이름으로 출력을 참조하면 의도치 않게 genrule의 다른 출력을 선택하는 것을 방지할 수 있지만 genrule이 여러 개의 출력을 생성하는 경우 지루한 작업이 될 수 있습니다.

예

이 예시에서는 foo.h를 생성합니다. 이 명령어는 입력을 취하지 않으므로 소스가 없습니다. 명령어로 실행되는 'binary'는 genrule과 동일한 패키지에 있는 Perl 스크립트입니다.

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

다음 예에서는 filegroup 사용 방법과 다른 genrule의 출력을 보여줍니다. 명시적인 $(location) 지시어 대신 $(SRCS)를 사용해도 됩니다. 이 예에서는 시연을 위해 후자를 사용합니다.

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

인수

test_suite

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

test_suite는 사람에게 '유용'하다고 간주되는 테스트 집합을 정의합니다. 이를 통해 프로젝트에서 '체크인 전에 실행해야 하는 테스트', '프로젝트의 스트레스 테스트' 또는 '모든 소규모 테스트'와 같은 테스트 세트를 정의할 수 있습니다. blaze test 명령어는 이러한 종류의 조직을 따릅니다. blaze test //some/test:suite와 같은 호출의 경우 Blaze는 먼저 //some/test:suite 타겟에 전이적으로 포함된 모든 테스트 대상을 열거한 다음 (이를 'test_suite 확장'이라고 함), Blaze는 이러한 대상을 빌드하고 테스트합니다.

예

현재 패키지에서 모든 소규모 테스트를 실행하는 테스트 모음

test_suite(
    name = "small_tests",
    tags = ["small"],
)

지정된 테스트 세트를 실행하는 테스트 모음:

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

현재 패키지에서 불안정하지 않은 모든 테스트를 실행하는 테스트 모음입니다.

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

인수