Args

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

Thường thì một thao tác sẽ 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ụ: dòng lệnh 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 cần được liên kết. Tốt nhất là bạn nên 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 nhóm phần phụ thuộc này thành danh sách chuỗi để tạo một dòng lệnh hành động, thì việc này sẽ làm mất hiệu quả tối ưu hoá việc chia sẻ bộ nhớ này.

Vì lý do này, các hàm xây dựng hành động chấp nhận cả đối tượng Args ngoài chuỗi. Mỗi đối tượng Args đại diện cho một chuỗi các chuỗi và nhóm phần phụ thuộc, với các phép biến đổi không bắt buộc để thao tác với dữ liệu. Các đối tượng Args không xử lý các nhóm 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. Cách 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 lần đột biến của đố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 các mục được chuyển đổi 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 sẽ như sau:

• Các giá trị đã là chuỗi vẫn được giữ nguyên.
• Các đối tượng File được chuyển thành giá trị File.path.
• Các đối tượng Label được chuyển thành một chuỗi đại diện phân giải trở lại cùng một đối tượng khi được phân giải trong ngữ cảnh của kho lưu trữ chính. Nếu có thể, cách trình bày chuỗi sẽ sử dụng tên rõ ràng của kho lưu trữ thay vì tên chuẩn của kho lưu trữ. Điều này giúp cách trình bày này phù hợp để sử dụng trong các tệp BUILD. Mặc dù chúng tôi không đảm bảo hình thức trình bày chính xác, nhưng có thể kể đến một số ví dụ điển hình như //foo:bar, @repo//foo:bar và @@canonical_name~//foo:bar.bzl.
• Tất cả các loại khác đều đượ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 phải kiểu chuỗi hoặc File đến add(). Nếu truyền các giá trị đó đến add_all() hoặc add_joined(), 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ư phép thay thế % trên chuỗi, ngoại trừ việc mẫu phải có đúng một phần giữ chỗ thay thế và phải là %s. Bạn có thể thoát phần trăm cố định dưới dạng %%. Định dạng được áp dụng sau khi giá trị được chuyển đổi thành chuỗi theo cách trên.

Mỗi phương thức add*() đều có một dạng thay thế chấp nhận một tham số vị trí bổ sung, 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 bổ sung sẽ không được thêm nếu trình tự đó 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 trình tự đã cho có chứa val1..val3 hay khô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, các đối số có thể bị tràn vào các tệp tham số. Hãy 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

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

Hội viên

• thêm
• add_all
• add_joined
• set_param_file_format
• use_param_file

thêm

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

Thông số

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)

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

1. Mỗi mục File của thư mục được thay thế bằng tất cả File đệ quy có trong thư mục đó.
2. 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à các danh sách 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 phép chuyển đổi chuẩn cho từng mục.
3. Mỗi đối số trong danh sách được định dạng bằng format_each, nếu có.
4. Nếu uniquify là true, các đối số trùng lặp sẽ bị xoá. Lần xuất hiện đầu tiên là lần xuất hiện còn lại.
5. Nếu bạn cung cấp một chuỗi before_each, chuỗi này 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. Điều này làm tăng gấp đôi số lượng đối số cần thêm vào thời điểm này.
6. Ngoại trừ trường hợp danh sách trống và omit_if_empty là true (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ó.

Thông số

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)

Quá trình xử lý tương tự như add_all(), nhưng danh sách đối số bắt nguồn từ values được kết hợp thành một đối số duy nhất như thể bằng 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 để nối vào một đối số và nếu omit_if_empty là true (đú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à false, thì chuỗi đã kết hợp sẽ là một chuỗi trống.

Thông số

set_param_file_format

Args Args.set_param_file_format(format)

Thông số

use_param_file

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

Bazel có thể chọn bỏ qua việc ghi tệp tham số vào cây đầu ra trong quá trình thực thi để tăng 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 truyền --materialize_param_files vào bản dựng.

Thông số