인수

문제 신고 소스 보기 Nightly · 7.4 .

명령줄의 일부 또는 전체를 빌드하는 데 필요한 데이터를 메모리 효율적인 방식으로 캡슐화하는 객체입니다.

작업에 전이 종속성에서 누적된 값이 포함된 큰 명령줄이 필요한 경우가 많습니다. 예를 들어 링커 명령줄에는 연결되는 모든 라이브러리에 필요한 모든 객체 파일이 나열될 수 있습니다. 이러한 전이 데이터를 여러 대상에서 공유할 수 있도록 depset에 저장하는 것이 좋습니다. 그러나 규칙 작성자가 작업 명령줄을 구성하기 위해 이러한 depset을 문자열 목록으로 변환해야 한다면 이 메모리 공유 최적화가 무효화됩니다.

따라서 작업 구성 함수는 문자열 외에도 Args 객체를 허용합니다. 각 Args 객체는 데이터를 조작하기 위한 선택적 변환과 함께 문자열 및 depset의 연결을 나타냅니다. Args 객체는 명령줄을 계산할 때가 되어 실행 단계가 될 때까지 캡슐화하는 depset을 처리하지 않습니다. 따라서 분석 단계가 완료될 때까지 비용이 많이 드는 복사를 지연하는 데 도움이 됩니다. 자세한 내용은 성능 최적화 페이지를 참고하세요.

Argsctx.actions.args()를 호출하여 구성됩니다. ctx.actions.run() 또는 ctx.actions.run_shell()arguments 매개변수로 전달할 수 있습니다. Args 객체의 각 변형은 최종 명령줄에 값을 추가합니다.

map_each 기능을 사용하면 항목이 문자열로 변환되는 방식을 맞춤설정할 수 있습니다. map_each 함수를 제공하지 않으면 표준 변환은 다음과 같습니다.

  • 이미 문자열인 값은 그대로 유지됩니다.
  • File 객체는 File.path 값으로 변환됩니다.
  • Label 객체는 기본 저장소의 컨텍스트에서 확인될 때 동일한 객체로 다시 확인되는 문자열 표현으로 변환됩니다. 가능한 경우 문자열 표현은 저장소의 표시 이름을 저장소의 표준 이름보다 우선하여 사용합니다. 따라서 이 표현은 BUILD 파일에 사용하기에 적합합니다. 표현의 정확한 형식은 보장되지 않지만 //foo:bar, @repo//foo:bar, @@canonical_name~//foo:bar.bzl가 일반적인 예입니다.
  • 다른 모든 유형은 지정되지 않은 방식으로 문자열로 변환됩니다. 따라서 문자열 또는 File 유형이 아닌 값을 add()에 전달하지 않아야 하며, add_all() 또는 add_joined()에 전달하는 경우 map_each 함수를 제공해야 합니다.

문자열 형식 지정 (add*() 메서드의 format, format_each, format_joined 매개변수)을 사용하는 경우 형식 템플릿은 문자열의 % 대체와 동일한 방식으로 해석됩니다. 단, 템플릿에는 대체 자리표시자가 정확히 하나 있어야 하며 %s여야 합니다. 리터럴 퍼센트는 %%로 이스케이프 처리할 수 있습니다. 서식은 위와 같이 값이 문자열로 변환된 후에 적용됩니다.

add*() 메서드에는 추가 위치 매개변수(나머지 인수 앞에 삽입할 '인수 이름' 문자열)를 허용하는 대체 형식이 있습니다. add_alladd_joined의 경우 시퀀스가 비어 있으면 추가 문자열이 추가되지 않습니다. 예를 들어 동일한 사용법은 지정된 시퀀스에 val1..val3가 포함되어 있는지 또는 비어 있는지에 따라 명령줄에 --foo val1 val2 val3 --bar 또는 --bar만 추가할 수 있습니다.

명령줄의 크기가 시스템에서 허용하는 최대 크기보다 더 길게 커질 수 있는 경우, 인수가 매개변수 파일로 스필링될 수 있습니다. use_param_file()set_param_file_format()를 참고하세요.

예를 들어 다음 명령줄을 생성하려고 한다고 가정해 보겠습니다.

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
다음 Args 객체를 사용할 수 있습니다.
# foo_deps and bar_deps are depsets containing
# File objects for the foo and bar .txt files.
args = ctx.actions.args()
args.add_all("--foo", foo_deps)
args.add_joined("--bar", bar_deps, join_with=",")
args.add("--baz")
ctx.actions.run(
  ...
  arguments = [args],
  ...
)

회원

추가

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

이 명령줄에 인수를 추가합니다.

매개변수

매개변수 설명
arg_name_or_value 필수
두 개의 위치 매개변수가 전달되면 이는 인수 이름으로 해석됩니다. arg 이름은 처리 없이 값 앞에 추가됩니다. 위치 매개변수가 하나만 전달되면 value로 해석됩니다 (아래 참고).
value 기본값은 unbound입니다.
추가할 객체입니다. 위에 언급된 표준 변환을 사용하여 문자열로 변환됩니다. 이 함수에는 map_each 매개변수가 없으므로 value는 문자열 또는 File여야 합니다. 목록, 튜플, depset 또는 디렉터리 File는 이 메서드 대신 add_all() 또는 add_joined()에 전달해야 합니다.
format string 또는 None. 기본값은 None입니다.
value의 문자열화된 버전에 적용할 형식 문자열 패턴입니다.

add_all

Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)

이 명령줄에 여러 인수를 추가합니다. 항목은 실행 단계에서 지연 처리됩니다.

대부분의 처리는 다음 단계에 따라 추가할 인수 목록에서 발생합니다.

  1. 각 디렉터리 File 항목은 해당 디렉터리에 재귀적으로 포함된 모든 File로 대체됩니다.
  2. map_each가 제공되면 각 항목에 적용되고 그 결과 문자열 목록이 연결되어 초기 인수 목록을 형성합니다. 그렇지 않으면 초기 인수 목록은 각 항목에 표준 변환을 적용한 결과입니다.
  3. 목록의 각 인수는 format_each(있는 경우)로 형식이 지정됩니다.
  4. uniquify가 true이면 중복 인수가 삭제됩니다. 첫 번째 발생이 유지됩니다.
  5. before_each 문자열이 제공되면 목록의 각 기존 인수 앞에 새 인수로 삽입됩니다. 이렇게 하면 이 시점에 추가되는 인수의 수가 사실상 두 배가 됩니다.
  6. 목록이 비어 있고 omit_if_empty가 true (기본값)인 경우를 제외하고, arg 이름과 terminate_with가 주어지면 각각 첫 번째 인수와 마지막 인수로 삽입됩니다.
빈 문자열은 이러한 모든 처리 단계가 적용되는 유효한 인수입니다.

매개변수

매개변수 설명
arg_name_or_values 필수
두 개의 위치 매개변수가 전달되면 이는 인수 이름으로 해석됩니다. 인수 이름은 처리 없이 values 앞에 별도의 인수로 추가됩니다. omit_if_empty가 true (기본값)이고 다른 항목이 추가되지 않으면 (values가 비어 있거나 모든 항목이 필터링된 경우) 이 인수 이름이 추가되지 않습니다. 위치 매개변수를 하나만 전달하면 values로 해석됩니다 (아래 참고).
values sequence 또는 depset: 기본값은 unbound입니다.
항목이 추가될 목록, 튜플 또는 depset입니다.
map_each 호출 가능 함수 또는 None. 기본값은 None입니다.
각 항목을 0개 이상의 문자열로 변환하는 함수로, 추가하기 전에 추가로 처리될 수 있습니다. 이 매개변수를 제공하지 않으면 표준 전환이 사용됩니다.

이 함수에는 하나 또는 두 개의 위치 인수(변환할 항목, 그 뒤에 선택적 DirectoryExpander)가 전달됩니다. 두 번째 인수는 제공된 함수가 기본 제공이 아닌 사용자 정의 함수이고 둘 이상의 매개변수를 선언하는 경우에만 전달됩니다.

반환 값의 유형은 항목에 생성할 인수의 수에 따라 다릅니다.

  • 각 항목이 하나의 문자열로 변환되는 일반적인 경우 함수는 이 문자열을 반환해야 합니다.
  • 항목을 완전히 필터링하려면 함수가 None을 반환해야 합니다.
  • 항목이 여러 문자열로 변환되면 함수는 이러한 문자열의 목록을 반환합니다.
단일 문자열 또는 None을 반환하면 각각 길이가 1 또는 0인 목록을 반환하는 것과 동일한 효과가 있습니다. 그러나 필요하지 않은 목록을 만들지 않는 것이 더 효율적이고 읽기 쉽습니다.

일반적으로 디렉터리인 항목은 expand_directories=True이 설정되면 콘텐츠로 자동 확장됩니다. 그러나 이 방법은 다른 값 내에 포함된 디렉터리는 확장하지 않습니다. 예를 들어 항목이 디렉터리를 필드로 갖는 구조체인 경우 확장되지 않습니다. 이 경우 DirectoryExpander 인수를 적용하여 지정된 디렉터리의 파일을 수동으로 가져올 수 있습니다.

대규모 분석 단계 데이터 구조가 실행 단계에 의도치 않게 유지되지 않도록 하려면 map_each 함수를 최상위 def 식으로 선언해야 합니다. 기본적으로 중첩 함수 폐쇄가 아닐 수 있습니다.

경고: map_each 호출 중에 실행되는 print() 문이 표시되는 출력을 생성하지 않습니다.

format_each string 또는 None(기본값: None)
map_each 함수에서 반환하는 각 문자열에 적용되는 선택적 형식 문자열 패턴입니다. 형식 문자열에는 '%s' 자리표시자가 정확히 하나 있어야 합니다.
before_each string 또는 None; 기본값은 None입니다.
values에서 파생된 각 인수를 추가하기 전에 추가할 선택적 인수입니다.
omit_if_empty 기본값은 True입니다.
true인 경우 추가할 values에서 파생된 인수가 없으면 모든 추가 처리가 억제되고 명령줄이 변경되지 않습니다. false인 경우 다른 인수가 있는지 여부와 관계없이 인수 이름과 terminate_with(제공된 경우)가 계속 추가됩니다.
uniquify 기본값은 False입니다.
true이면 values에서 파생된 중복 인수가 생략됩니다. 각 인수의 첫 번째 항목만 유지됩니다. 일반적으로 이 기능은 필요하지 않습니다. depset이 이미 중복을 생략하기 때문입니다. 하지만 map_each가 여러 항목에 동일한 문자열을 내보내는 경우에는 유용할 수 있습니다.
expand_directories 기본값은 True입니다.
true인 경우 values의 모든 디렉터리가 단층 파일 목록으로 확장됩니다. 이는 map_each가 적용되기 전에 발생합니다.
terminate_with string 또는 None; 기본값은 None입니다.
다른 모든 인수 뒤에 추가할 선택적 인수입니다. omit_if_empty가 true (기본값)이고 다른 항목이 추가되지 않은 경우 (values가 비어 있거나 모든 항목이 필터링된 경우) 이 인수가 추가되지 않습니다.
allow_closure 기본값은 False
true이면 map_each와 같은 함수 매개변수에서 클로저를 사용할 수 있습니다. 일반적으로 이는 필요하지 않으며 대규모 분석 단계 데이터 구조를 실행 단계에 유지할 위험이 있습니다.

add_joined

Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)

구분자를 사용하여 여러 값을 연결하여 이 명령줄에 인수를 추가합니다. 항목이 실행 단계 중에 느리게 처리됩니다.

처리는 add_all()와 유사하지만 values에서 파생된 인수 목록은 join_with.join(...)를 사용하는 것처럼 단일 인수로 결합된 후 지정된 format_joined 문자열 템플릿을 사용하여 형식이 지정됩니다. add_all()와 달리 before_each 또는 terminate_with 매개변수는 없습니다. 이러한 매개변수는 항목이 단일 인수로 결합될 때 일반적으로 유용하지 않기 때문입니다.

필터링 후 인수로 조인할 문자열이 없고 omit_if_empty가 true (기본값)이면 처리가 완료되지 않습니다. 조인할 문자열이 없지만 omit_if_empty가 false인 경우 조인된 문자열은 빈 문자열이 됩니다.

매개변수

매개변수 설명
arg_name_or_values 필수
두 개의 위치 매개변수가 전달되면 이는 인수 이름으로 해석됩니다. 인수 이름은 처리 없이 values 앞에 추가됩니다. omit_if_empty가 true (기본값)이고 values에서 파생된 문자열이 없으면 이 인수가 추가되지 않습니다 (values이 비어 있거나 모든 항목이 필터링된 경우 발생할 수 있음). 위치 매개변수가 하나만 전달되면 values로 해석됩니다 (아래 참고).
values sequence 또는 depset: 기본값은 unbound입니다.
항목이 조인될 목록, 튜플 또는 depset입니다.
join_with 필수
string.join()와 동일한 방식으로 map_eachformat_each를 적용하여 얻은 문자열을 결합하는 데 사용되는 구분자 문자열입니다.
map_each 호출 가능 또는 None. 기본값은 None입니다.
add_all와 동일합니다.
format_each string 또는 None(기본값: None)
add_all와 동일합니다.
format_joined string 또는 None이며 기본값은 None입니다.
조인된 문자열에 적용되는 형식 문자열 패턴(선택사항)입니다. 형식 문자열에는 '%s' 자리표시자가 정확히 하나 있어야 합니다.
omit_if_empty 기본값은 True입니다.
true인 경우 (values가 비어 있거나 모든 항목이 필터링되어 있기 때문에) 결합할 문자열이 없으면 모든 추가 처리가 억제되고 명령줄이 변경되지 않습니다. false인 경우 결합할 문자열이 없더라도 두 개의 인수가 추가됩니다. 인수 이름 뒤에 빈 문자열 (0개 문자열의 논리적 조인)이 추가됩니다.
uniquify 기본값은 False
add_all와 동일합니다.
expand_directories 기본값은 True입니다.
add_all와 동일합니다.
allow_closure 기본값은 False입니다.
add_all와 동일합니다.

set_param_file_format

Args Args.set_param_file_format(format)

매개변수 파일(사용되는 경우)의 형식을 설정합니다.

매개변수

매개변수 설명
format 필수
다음 중 하나여야 합니다.
  • 'multiline': 각 항목 (인수 이름 또는 값)은 줄바꿈 문자와 함께 param 파일에 그대로 작성됩니다.
  • 'shell': 'multiline'과 동일하지만 항목에 셸 따옴표가 사용됩니다.
  • 'flag_per_line': 'multiline'과 동일하지만 (1) 플래그('--'로 시작)만 param 파일에 쓰이고 (2) 플래그 값(있는 경우)은 '=' 구분자로 같은 줄에 쓰입니다. 이는 Abseil 플래그 라이브러리에서 예상되는 형식입니다.

호출되지 않으면 형식은 기본적으로 'shell'입니다.

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

args를 params 파일에 스필하여 param 파일의 포인터로 대체합니다. args가 시스템의 명령어 길이 제한보다 클 수 있는 경우에 사용합니다.

Bazel은 효율성을 위해 실행 중에 params 파일을 출력 트리에 쓰지 않을 수 있습니다. 작업을 디버그하고 param 파일을 검사하려면 --materialize_param_files를 빌드에 전달합니다.

매개변수

매개변수 설명
param_file_arg 필수
단일 '%s'를 포함하는 형식 문자열입니다. args가 params 파일에 스필되면 params 파일의 경로로 형식이 지정된 이 문자열로 구성된 인수로 대체됩니다.

예를 들어 args가 params 파일 'params.txt'에 스필되면 '--file=%s'를 지정하면 작업 명령줄에 '--file=params.txt'가 포함됩니다.

use_always 기본값은 False입니다.
인수를 항상 매개변수 파일에 분산할지 여부입니다. false인 경우 bazel은 시스템 및 arg 길이를 기반으로 인수를 스필해야 하는지 결정합니다.