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

Args

Đối tượng đóng gói dữ liệu cần thiết theo cách tiết kiệm bộ nhớ để tạo một phần hoặc toàn bộ dòng lệnh.

Thường thì một thao tác yêu cầu 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ả thư viện đang liên kết cần đến. Phương pháp hay nhất là lưu trữ dữ liệu bắc cầu như vậy trong depset để nhiều mục tiêu có thể chia sẻ dữ liệ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 chuỗi để tạo dòng lệnh hành động, thì thao tác này sẽ đánh bại phương pháp tối ưu hoá chia sẻ bộ nhớ này.

Vì lý do này, các hàm tạo hành động chấp nhận đối tượng Args ngoài chuỗi. Mỗi đối tượng Args đại diện cho một chuỗi và phần phụ thuộc, kèm theo các phép biến đổi không bắt buộc để thao tác với dữ liệu. Đố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, là thời điểm để tính toán dòng lệnh. Việc 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. Hãy xem trang Tối ưu hoá hiệu suất để biết thêm thông tin.

Args được tạo bằng cách gọi ctx.actions.args(). Bạn có thể truyền các giá trị này dưới dạng tham số arguments của ctx.actions.run() hoặc ctx.actions.run_shell(). Mỗi trường hợp độ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, lượt chuyển đổi chuẩn sẽ diễn ra 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.
Mọi kiểu khác sẽ đượ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 loại chuỗi hoặc File vào add(). Thay vào đó, nếu truyền các giá trị đó đến 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 (các tham số format, format_each và format_joined của phương thức add*()), mẫu định dạng sẽ được diễn giải theo cách tương tự như phương thức thay thế % trên chuỗi, ngoại trừ việc mẫu đó phải có chính xác một phần giữ chỗ thay thế và phải là %s. Phần trăm nguyên văn 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 chuỗi theo quy định ở trên.

Mỗi phương thức add*() đều có một dạng thay thế chấp nhận thêm một tham số vị trí, một chuỗi "arg name" (tên đối số) để chèn vào trước đối số còn lại. Đối với add_all và add_joined, chuỗi bổ sung sẽ không được thêm vào nếu chuỗi bị trống. Ví dụ: cùng một cách sử dụng 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 chuỗi đã cho chứa val1..val3 hay trống.

Nếu kích thước của dòng lệnh có thể dài 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 vào tệp tham 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 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ê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.

Thông số

Thông số	Nội dung mô tả
`arg_name_or_value`	bắt buộc Nếu hai tham số vị trí được truyền thì đâ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ần xử lý. 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`	mặc định = không liên kết Đối tượng cần nối. 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. Vì không có tham số `map_each` cho hàm này nên `value` phải ở dạng chuỗi hoặc `File`. Danh sách, bộ dữ liệu, phần phụ thuộc 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`; mặc định = Không Mẫu chuỗi định dạng sẽ được áp dụng cho phiên bản `value` dạng chuỗi.

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)

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ý đều diễn ra trên một danh sách các đối số cần thêm vào, theo các bước sau:

Mỗi mục File trong thư mục được thay thế bằng tất cả File được chứa đệ quy trong thư mục đó.
Nếu map_each được cung cấp, giá trị này sẽ được áp dụng cho từng mục và danh sách các chuỗi thu được sẽ đượ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à những lần xuất hiện còn lại.
Nếu một chuỗi before_each được cung cấp, chuỗi đó sẽ được chèn dưới dạng một đối số mới trước mỗi đối số hiện có trong danh sách. Thao tác này giúp tăng gấp đôi số lượng đối số cần thêm vào một cách hiệu quả 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), thì tên đối số và terminate_with sẽ được chèn tương ứng dưới dạng đối số đầu tiên và cuối cùng, nếu được đưa ra.

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

Thông số

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

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)

Thêm một đối số vào dòng lệnh này bằng cách nối nhiều giá trị bằng một 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ý tương tự như add_all(), nhưng danh sách các đối số bắt nguồn từ values được kết hợp thành một đối số duy nhất như thể theo 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 kết hợp các mục thành một đối số duy nhất.

Nếu sau khi lọc không có chuỗi nào để kết hợp thành một đối số và nếu omit_if_empty là đúng (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à sai, thì chuỗi đã kết hợp sẽ là một chuỗi trống.

Thông số

Thông số	Nội dung mô tả
`arg_name_or_values`	bắt buộc Nếu hai tham số vị trí được truyền thì đây được hiểu là tên đối số. Tên đối số được thêm trước `values` mà không cần xử lý. Đối số này sẽ không được thêm nếu `omit_if_empty` là giá trị true (mặc định) và không có chuỗi nào bắt nguồn 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 trong đó 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 phần phụ thuộc có cá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 dùng để kết hợp các chuỗi thu được bằng cách áp dụng `map_each` và `format_each`, theo cách tương tự như `string.join()`.
`map_each`	`callable; or None`; mặc định = Không có Giống như đối với `add_all`.
`format_each`	`string; or None`; mặc định = Không có Giống như đối với `add_all`.
`format_joined`	`string; or None`; mặc định = Không có Mẫu chuỗi định dạng không bắt buộc áp dụng cho chuỗi đã kết hợp. Chuỗi định dạng phải có đúng một phần giữ chỗ '%s'.
`omit_if_empty`	mặc định = True Nếu là true, nếu không có chuỗi nào để kết hợp với nhau (do `values` trống hoặc tất cả các mục của chuỗi đã bị lọc), thì mọi quá trình xử lý tiếp theo sẽ bị chặn 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 đối số theo sau là một chuỗi trống (là chuỗi kết hợp logic của các chuỗi 0).
`uniquify`	default = False Tương tự như đối với `add_all`.
`expand_directories`	mặc định = Đúng Tương tự như đối với `add_all`.
`allow_closure`	default = False Tương tự như đối với `add_all`.

set_param_file_format

Args Args.set_param_file_format(format)

Đặt định dạng của tệp tham số nếu sử dụng tệp tham số

Thông 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: "multiline": Mỗi mục (tên hoặc giá trị đối số) được ghi nguyên văn vào tệp tham số với ký tự dòng mới theo sau mục đó. "shell": Giống như "multiline", nhưng các mục được trích dẫn giá trị shell "flag_per_line": Giống 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 tách '='. Đây là định dạng mà thư viện cờ Abseil yêu cầu. Đị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:

"multiline": Mỗi mục (tên hoặc giá trị đối số) được ghi nguyên văn vào tệp tham số với ký tự dòng mới theo sau mục đó.
"shell": Giống như "multiline", nhưng các mục được trích dẫn giá trị shell
"flag_per_line": Giống 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 tách '='. Đây là định dạng mà thư viện cờ Abseil yêu cầu.

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

use_param_file

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

Đưa đối số vào tệp tham số, thay thế chúng bằng một con trỏ đến tệp tham số. Sử dụng khi đối số của bạn 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 loại bỏ việc ghi tệp thông số vào cây đầu ra trong quá trình thực thi để tăng tính hiệu quả. Nếu bạn đang gỡ lỗi các hành động và muốn kiểm tra tệp tham số, hãy chuyển --materialize_param_files vào bản dựng.

Thông số

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

Thông số	Nội dung mô tả
`param_file_arg`	bắt buộc Chuỗi định dạng chứa một "%s". Nếu đối số được tràn vào tệp thông số, thì chúng sẽ được thay thế bằng một đối số chứa chuỗi được định dạng bằng đường dẫn của tệp thông số. Ví dụ: nếu đối số được chuyển vào tệp thông số "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 đưa đối số vào tệp thông số hay không. Nếu giá trị false (sai), bazel sẽ quyết định xem các đối số có cần xuất hiện hay không dựa trên hệ thống và độ dài đối số của bạn.

param_file_arg

bắt buộc
Chuỗi định dạng chứa một "%s". Nếu đối số được tràn vào tệp thông số, thì chúng sẽ được thay thế bằng một đối số chứa chuỗi được định dạng bằng đường dẫn của tệp thông số.

Ví dụ: nếu đối số được chuyển vào tệp thông số "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 đưa đối số vào tệp thông số hay không. Nếu giá trị false (sai), bazel sẽ quyết định xem các đối số có cần xuất hiện hay không dựa trên hệ thống và độ dài đối số của bạn.