Để xem tài liệu về bản phát hành ổn định, vui lòng sử dụng trình đơn thả xuống "Tài liệu được tạo phiên bản". Chế độ xem mặc định phản ánh phiên bản mới nhất ở HEAD.

Trang này được dịch bởi Cloud Translation API.

Args

Báo cáo vấn đề Xem nguồn

Đối tượng đóng gói một cách hiệu quả về bộ nhớ những dữ liệu cần thiết để xây dựng một phần hoặc toàn bộ dòng lệnh.

Thông thường, một thao tác cần một dòng lệnh lớn chứa các giá trị tích luỹ từ các phần phụ thuộc bắc cầu. Ví dụ: một dòng lệnh của trình liên kết có thể liệt kê mọi tệp đối tượng mà tất cả các thư viện đang liên kết cần. Cách tốt nhất là lưu trữ dữ liệu chuyển tiếp đó trong depset để có thể chia sẻ dữ liệu theo nhiều mục tiêu. Tuy nhiên, nếu tác giả quy tắc phải chuyển đổi các phần phụ thuộc này thành danh sách các chuỗi để tạo một dòng lệnh hành động, thì điều đó sẽ đánh bại tính năng tối ưu hoá để chia sẻ bộ nhớ.

Vì lý do này, các hàm tạo hành động chấp nhận đối tượng Args ngoài các chuỗi. Mỗi đối tượng Args đại diện cho một chuỗi nối với các chuỗi và phần phụ thuộc, với các phép biến đổi không bắt buộc để thao tác dữ liệu. Các đối tượng Args không xử lý các phần phụ thuộc mà chúng đóng gói cho đến giai đoạn thực thi, khi đến lúc tính toán dòng lệnh. Điều này giúp trì hoãn mọi hoạt động sao chép tốn kém cho đến khi giai đoạn phân tích hoàn tất. Xem trang Tối ưu hóa hiệu suất để biết thêm thông tin.

Args được xây dựng bằng cách gọi ctx.actions.args(). Chúng có thể được chuyển dưới dạng tham số arguments của ctx.actions.run() hoặc ctx.actions.run_shell(). Mỗi đột biến của một đối tượng Args sẽ thêm các giá trị vào dòng lệnh cuối cùng.

Tính năng map_each cho phép bạn tuỳ chỉnh cách chuyển đổi các mục thành chuỗi. Nếu bạn không cung cấp hàm map_each, thì lượt chuyển đổi chuẩn như sau:

Các giá trị đã là chuỗi sẽ được giữ nguyên.
Các đối tượng File được chuyển thành giá trị File.path.
Tất cả các loại khác được chuyển thành chuỗi theo cách không xác định. Vì lý do này, bạn nên tránh truyền các giá trị không thuộc chuỗi hoặc thuộc loại File cho add(). Nếu chuyển các giá trị này cho add_all() hoặc add_joined(), thì bạn nên cung cấp hàm map_each.

Khi sử dụng định dạng chuỗi (tham số format, format_each và format_joined của phương thức add*()), mẫu định dạng được diễn giải theo cách tương tự như % thay thế trên các chuỗi, ngoại trừ việc mẫu phải có chính xác một trình giữ chỗ thay thế và phải là %s. Phần trăm theo nghĩa đen có thể được thoát dưới dạng %%. Định dạng được áp dụng sau khi giá trị được chuyển đổi thành một chuỗi như trên.

Mỗi phương thức add*() có một biểu mẫu thay thế chấp nhận một tham số vị trí thừa, một chuỗi "arg name" để chèn trước các đối số còn lại. Đối với add_all và add_joined, chuỗi thừa sẽ không được thêm vào nếu chuỗi trống. Ví dụ: việc sử dụng tương tự có thể thêm --foo val1 val2 val3 --bar hoặc chỉ --bar vào dòng lệnh, tuỳ thuộc vào việc trình tự đã cho có chứa val1..val3 hay trống.

Nếu kích thước dòng lệnh có thể lớn hơn kích thước tối đa mà hệ thống cho phép, thì các đối số có thể được chuyển sang tệp thông số. Xem use_param_file() và set_param_file_format().

Ví dụ: Giả sử chúng ta muốn tạo dòng lệnh:

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz

Chúng ta có thể sử dụng đối tượng Args như sau:

# 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],
  ...
)

Thành viên

thêm
thêm_tất cả
add_join
set_param_file_format (set_param_file_format)
use_param_file

thêm

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

Thêm một đối số vào dòng lệnh này.

Các tham số

Thông số	Nội dung mô tả
`arg_name_or_value`	bắt buộc Nếu bạn chuyển hai tham số vị trí, đây được hiểu là tên đối số. Tên đối số được thêm vào trước giá trị mà không có bất kỳ quá trình xử lý nào. Nếu chỉ có một tham số vị trí được truyền thì tham số đó sẽ được hiểu là `value` (xem bên dưới).
`value`	default = unbound Đối tượng cần thêm. Chuỗi này sẽ được chuyển đổi thành một chuỗi bằng cách sử dụng lượt chuyển đổi chuẩn nêu trên. Do không có tham số `map_each` cho hàm này nên `value` phải là một chuỗi hoặc một `File`. Danh sách, bộ dữ liệu, bộ đệm hoặc thư mục `File` phải được truyền đến `add_all()` hoặc `add_joined()` thay vì phương thức này.
`format`	`string; or None`; default = None Mẫu chuỗi định dạng sẽ được áp dụng cho phiên bản đã phân thành chuỗi của `value`.

thêm_tất cả

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)

Thêm nhiều đối số vào dòng lệnh này. Các mục được xử lý từng phần trong giai đoạn thực thi.

Hầu hết quá trình xử lý diễn ra trên danh sách các đối số cần được thêm vào theo các bước sau:

Mỗi mục File của thư mục sẽ được thay thế bằng tất cả các File có đệ quy trong thư mục đó.
Nếu bạn cung cấp map_each, thì giá trị này sẽ được áp dụng cho từng mục và danh sách các chuỗi kết quả được nối với nhau để tạo thành danh sách đối số ban đầu. Nếu không, danh sách đối số ban đầu là kết quả của việc áp dụng lượt chuyển đổi chuẩn cho từng mục.
Mỗi đối số trong danh sách được định dạng bằng format_each (nếu có).
Nếu uniquify là đúng, các đối số trùng lặp sẽ bị xoá. Lần xuất hiện đầu tiên là trường hợp còn lại.
Nếu bạn cho sẵn một chuỗi before_each, thì chuỗi đó sẽ được chèn làm đối số mới trước mỗi đối số hiện có trong danh sách. Điều này giúp tăng gấp đôi số lượng đối số sẽ được thêm vào bằng điểm này.
Ngoại trừ trường hợp danh sách trống và omit_if_empty là đúng (mặc định), tên đối số và terminate_with sẽ được chèn lần lượt làm đối số đầu tiên và cuối cùng nếu được cung cấp.

Xin lưu ý rằng các chuỗi trống là các đối số hợp lệ tuân theo tất cả các bước xử lý này.

Các tham số

Thông số	Nội dung mô tả
`arg_name_or_values`	bắt buộc Nếu bạn chuyển hai tham số vị trí, đây được hiểu là tên đối số. Tên đối số được thêm trước `values` làm đối số riêng biệt mà không có bất kỳ quá trình xử lý nào. Tên đối số này sẽ không được thêm nếu `omit_if_empty` là đúng (mặc định) và không có mục nào khác được nối (như khi xảy ra trường hợp `values` trống hoặc tất cả các mục của bộ lọc). Nếu chỉ có một tham số vị trí được truyền thì tham số đó sẽ được hiểu là `values` (xem bên dưới).
`values`	`sequence; or depset`; default = unbound Danh sách, bộ dữ liệu hoặc bộ chứa có mục sẽ được thêm vào.
`map_each`	`callable; or None`; default = None Một hàm chuyển đổi từng mục thành 0 hoặc nhiều chuỗi. Hàm này có thể được xử lý thêm trước khi thêm vào. Nếu bạn không cung cấp thông số này, thì hệ thống sẽ sử dụng lượt chuyển đổi chuẩn. Hàm truyền một hoặc hai đối số vị trí: mục cần chuyển đổi, theo sau là `DirectoryExpander` (không bắt buộc). Đối số thứ hai sẽ chỉ được truyền nếu hàm đã cho do người dùng xác định (không được tích hợp sẵn) và khai báo nhiều hơn một tham số. Loại giá trị trả về phụ thuộc vào số lượng đối số được tạo cho mặt hàng: Trong trường hợp phổ biến khi mỗi mục biến thành một chuỗi, hàm sẽ trả về chuỗi đó. Nếu bị lọc ra hoàn toàn mục, hàm sẽ trả về `None`. Nếu một mục biến thành nhiều chuỗi, hàm sẽ trả về danh sách các chuỗi đó. Việc trả về một chuỗi hoặc `None` có tác dụng tương tự như việc trả về một danh sách có độ dài lần lượt là 1 hoặc 0. Tuy nhiên, cách này sẽ hiệu quả và dễ đọc hơn để tránh tạo danh sách khi không cần thiết. Thông thường, các mục là thư mục sẽ tự động được mở rộng đến nội dung của chúng khi bạn đặt `expand_directories=True`. Tuy nhiên, thao tác này sẽ không mở rộng thư mục chứa trong các giá trị khác -- ví dụ: khi các mục là cấu trúc có thư mục làm trường. Trong trường hợp này, bạn có thể áp dụng đối số `DirectoryExpander` để lấy các tệp của một thư mục nhất định theo cách thủ công. Để tránh việc lưu giữ ngoài ý muốn các cấu trúc dữ liệu giai đoạn phân tích lớn vào giai đoạn thực thi, hàm `map_each` phải được khai báo bằng câu lệnh `def` cấp cao nhất; hàm này có thể không phải là hàm đóng lồng theo mặc định. Cảnh báo: Câu lệnh `print()` được thực thi trong lệnh gọi đến `map_each` sẽ không tạo ra kết quả nào.
`format_each`	`string; or None`; default = None Mẫu chuỗi định dạng không bắt buộc, áp dụng cho từng chuỗi do hàm `map_each` trả về. Chuỗi định dạng phải có chính xác một trình giữ chỗ '%s'.
`before_each`	`string; or None`; default = None Đối số không bắt buộc sẽ được thêm vào trước khi từng đối số thu được từ `values` được thêm vào.
`omit_if_empty`	default = True Nếu là true, nếu không có đối số nào từ `values` được nối, thì toàn bộ quá trình xử lý sẽ bị chặn và dòng lệnh sẽ không thay đổi. Nếu sai, tên arg và `terminate_with` (nếu được cung cấp) sẽ vẫn được thêm vào bất kể có đối số nào khác hay không.
`uniquify`	default = False Nếu là true, các đối số trùng lặp được lấy từ `values` sẽ bị bỏ qua. Hệ thống chỉ lưu giữ lần xuất hiện đầu tiên của mỗi đối số. Thông thường, tính năng này không cần thiết vì các phần phụ thuộc đã bỏ qua các phần trùng lặp nhưng có thể hữu ích nếu `map_each` tạo ra cùng một chuỗi cho nhiều mục.
`expand_directories`	default = True Nếu đúng, bất kỳ thư mục nào trong `values` cũng sẽ được mở rộng thành danh sách tệp phẳng. Điều này xảy ra trước khi áp dụng `map_each`.
`terminate_with`	`string; or None`; default = None Một đối số không bắt buộc cần thêm sau tất cả các đối số khác. Đối số này sẽ không được thêm vào nếu `omit_if_empty` là đúng (mặc định) và không có mục nào khác được nối (như khi xảy ra trường hợp `values` trống hoặc tất cả các mục đều được lọc).
`allow_closure`	default = False Nếu là true, cho phép sử dụng các lệnh đóng trong tham số hàm như `map_each`. Thông thường, việc này không cần thiết và có nguy cơ giữ lại các cấu trúc dữ liệu lớn của giai đoạn phân tích cho giai đoạn thực thi.

đã thêm_tham gia

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)

Thêm một đối số vào dòng lệnh này bằng cách ghép nhiều giá trị với nhau bằng dấu phân tách. Các mục được xử lý từng phần trong giai đoạn thực thi.

Quá trình xử lý cũng tương tự như add_all(), nhưng danh sách các đối số thu được từ values sẽ được kết hợp thành một đối số duy nhất như thể join_with.join(...), sau đó được định dạng bằng mẫu chuỗi format_joined đã cho. Không giống như add_all(), không có tham số before_each hoặc terminate_with vì các tham số này thường không hữu ích khi các mục được kết hợp thành một đối số duy nhất.

Nếu sau khi lọc, không có chuỗi nào tham gia vào một đối số và nếu omit_if_empty là true (mặc định), thì sẽ không có quá trình xử lý nào được thực hiện. Ngược lại, nếu không có chuỗi nào để kết hợp nhưng omit_if_empty là false, chuỗi đã liên kết sẽ là một chuỗi trống.

Các tham số

Thông số	Nội dung mô tả
`arg_name_or_values`	bắt buộc Nếu bạn chuyển hai tham số vị trí, đây được hiểu là tên đối số. Tên đối số được thêm trước `values` mà không có quy trình xử lý nào. Đối số này sẽ không được thêm nếu `omit_if_empty` là đúng (mặc định) và không có chuỗi nào lấy từ `values` để kết hợp với nhau (điều này có thể xảy ra nếu `values` trống hoặc tất cả các mục của bộ lọc). Nếu chỉ có một tham số vị trí được truyền thì tham số đó sẽ được hiểu là `values` (xem bên dưới).
`values`	`sequence; or depset`; default = unbound Danh sách, bộ dữ liệu hoặc bộ chứa có mục sẽ được kết hợp.
`join_with`	bắt buộc Một chuỗi dấu phân tách được dùng để kết hợp các chuỗi thu được từ việc áp dụng `map_each` và `format_each`, theo cách tương tự như `string.join()`.
`map_each`	`callable; or None`; default = None Tương tự như đối với `add_all`.
`format_each`	`string; or None`; default = None Tương tự như đối với `add_all`.
`format_joined`	`string; or None`; default = None Mẫu chuỗi định dạng không bắt buộc được áp dụng cho chuỗi liên kết. Chuỗi định dạng phải có chính xác một trình giữ chỗ '%s'.
`omit_if_empty`	default = True Nếu là true, nếu không có chuỗi nào để kết hợp với nhau (vì `values` trống hoặc tất cả các mục đều được lọc), thì toàn bộ quá trình xử lý sẽ bị chặn lại và dòng lệnh sẽ không thay đổi. Nếu giá trị là false thì ngay cả khi không có chuỗi nào để kết hợp với nhau, hai đối số sẽ được nối vào: tên arg, theo sau là chuỗi trống (là tổ hợp logic của 0 chuỗi).
`uniquify`	default = False Tương tự đối với `add_all`.
`expand_directories`	default = True Tương tự như đối với `add_all`.
`allow_closure`	default = False Tương tự đối với `add_all`.

set_param_file_format

Args Args.set_param_file_format(format)

Đặt định dạng của tệp thông số, nếu tệp được sử dụng

Các tham số

Thông số Nội dung mô tả

Thông số	Nội dung mô tả
`format`	bắt buộc Phải là một trong: "nhiều dòng": Mỗi mục (tên hoặc giá trị của đối số) được ghi nguyên văn vào tệp thông số có ký tự dòng mới theo sau nó. "shell": Tương tự như "multiline", nhưng các mục được trích dẫn trong shell "flag_per_line": Tương tự như "multiline", nhưng (1) chỉ cờ (bắt đầu bằng '--') được ghi vào tệp tham số và (2) giá trị của cờ, nếu có, được viết trên cùng một dòng với dấu phân cách '='. Đây là định dạng được thư viện cờ Abseil mong đợi. Định dạng mặc định là "shell" nếu không được gọi.

format

bắt buộc
Phải là một trong:

"nhiều dòng": Mỗi mục (tên hoặc giá trị của đối số) được ghi nguyên văn vào tệp thông số có ký tự dòng mới theo sau nó.
"shell": Tương tự như "multiline", nhưng các mục được trích dẫn trong shell
"flag_per_line": Tương tự như "multiline", nhưng (1) chỉ cờ (bắt đầu bằng '--') được ghi vào tệp tham số và (2) giá trị của cờ, nếu có, được viết trên cùng một dòng với dấu phân cách '='. Đây là định dạng được thư viện cờ Abseil mong đợi.

Định dạng mặc định là "shell" nếu không được gọi.

sử dụng tệp_param_param

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

Đưa các đối số vào tệp tham số, thay thế các đối số đó bằng một con trỏ tới tệp tham số. Sử dụng khi đối số có thể quá lớn so với giới hạn độ dài lệnh của hệ thống.

Bazel có thể chọn để ghi tệp params vào cây đầu ra trong quá trình thực thi để đảm bảo hiệu quả. Nếu bạn đang gỡ lỗi cho các hành động và muốn kiểm tra tệp thông số, hãy chuyển --materialize_param_files vào bản dựng.

Các tham số

Thông số Nội dung mô tả

Thông số	Nội dung mô tả
`param_file_arg`	bắt buộc Một chuỗi định dạng có một "%s" duy nhất. Nếu args được truyền vào tệp params thì chúng sẽ được thay thế bằng một đối số bao gồm chuỗi này được định dạng bằng đường dẫn của tệp params. Ví dụ: nếu args bị tràn vào tệp "params.txt", thì việc chỉ định "--file=%s" sẽ khiến dòng lệnh hành động chứa "--file=params.txt".
`use_always`	default = False Liệu có luôn hiển thị đối số vào tệp thông số hay không. Nếu đặt là false, thì bazel sẽ quyết định xem có cần đổ các đối số vào hay không dựa trên hệ thống và độ dài đối số.

param_file_arg

bắt buộc
Một chuỗi định dạng có một "%s" duy nhất. Nếu args được truyền vào tệp params thì chúng sẽ được thay thế bằng một đối số bao gồm chuỗi này được định dạng bằng đường dẫn của tệp params.

Ví dụ: nếu args bị tràn vào tệp "params.txt", thì việc chỉ định "--file=%s" sẽ khiến dòng lệnh hành động chứa "--file=params.txt".

use_always default = False
Liệu có luôn hiển thị đối số vào tệp thông số hay không. Nếu đặt là false, thì bazel sẽ quyết định xem có cần đổ các đối số vào hay không dựa trên hệ thống và độ dài đối số.