Args

Báo cáo vấn đề Xem nguồn Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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 tạo hành động chấp nhận cá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. Đ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. 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 sẽ đượ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 biểu diễn 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 biểu diễn này phù hợp để sử dụng trong các tệp BUILD. Mặc dù không đảm bảo hình thức chính xác của nội dung trình bày, nhưng các ví dụ điển hình là //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 (các 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 giống như việc 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ần giữ chỗ đó 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 nội dung ở 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 "tên đối số" để 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ể 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 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],
  ...
)

Hội viên

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.

Tham số

Thông số Mô tả
arg_name_or_value bắt buộc
Nếu hai tham số vị trí được truyền, thì tham số này sẽ được diễn giải 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ỉ truyền một tham số vị trí, tham số đó sẽ được diễn giải là value (xem bên dưới).
value mặc định là unbound
Đối tượng cần nối. Giá trị này sẽ được chuyển đổi thành một chuỗi bằng cách sử dụng phương thức chuyển đổi chuẩn được đề cập ở trên. Vì không có tham số map_each cho hàm này, nên value phải là một chuỗi hoặc File. Bạn phải truyền danh sách, bộ dữ liệu, nhóm phần phụ thuộc hoặc thư mục File vào add_all() hoặc add_joined() thay vì phương thức này.
format string; hoặc None; mặc định là None
Một mẫu chuỗi định dạng, được áp dụng cho phiên bản chuỗi của 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)

Thêm nhiều đối số vào dòng lệnh này. Các mục được xử lý theo kiểu trì hoãn trong giai đoạn thực thi.

Hầu hết quá trình xử lý diễn ra trên một danh sách đố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ó.
Xin lưu ý rằng chuỗi trống là đối số hợp lệ phải tuân theo tất cả các bước xử lý này.

Tham số

Thông số Mô tả
arg_name_or_values bắt buộc
Nếu hai tham số vị trí được truyền, thì tham số này sẽ được diễn giải là tên đối số. Tên đối số được thêm vào trước values dưới dạng một đối số riêng biệt 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 nó đều bị lọc). Nếu chỉ truyền một tham số vị trí, tham số đó sẽ được diễn giải là values (xem bên dưới).
values trình tự; hoặc nhóm phần phụ thuộc; mặc định là unbound
Danh sách, bộ dữ liệu hoặc nhóm phần phụ thuộc có các mục sẽ được thêm vào.
map_each callable; hoặc None; mặc định là None
Một hàm chuyển đổi mỗi mục thành không có hoặc có nhiều chuỗi, có thể được xử lý thêm trước khi nối. Nếu bạn không cung cấp tham số này, thì lượt 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 được cung cấp là do người dùng xác định (không tích hợp sẵn) và khai báo nhiều tham số.

Loại của giá trị trả về phụ thuộc vào số lượng đối số cần 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 sẽ trả về chuỗi đó.
  • Nếu bạn muốn lọc ra hoàn toàn mục đó, hàm sẽ 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 hoặc None có tác dụng tương tự như việc trả về một danh sách có độ dài 1 hoặc độ dài 0 tương ứng. Tuy nhiên, bạn nên tránh tạo danh sách khi không cần thiết để đảm bảo hiệu quả và dễ đọc.

Thông thường, các mục là thư mục sẽ tự động mở rộng thành nội dung của các 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 có trong các giá trị khác – ví dụ: khi các mục là cấu trúc có thư mục dưới dạng 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 giữ lại không mong muốn các cấu trúc dữ liệu lớn trong giai đoạn phân tích 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; theo mặc định, hàm này không được là một hàm đóng lồng.

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ả nào hiển thị.

format_each string; hoặc None; mặc định là None
Một mẫu chuỗi định dạng không bắt buộc, đượ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; hoặc None; mặc định là None
Một đối số không bắt buộc để nối trước khi mỗi đối số bắt nguồn từ values được nối.
omit_if_empty bool; mặc định là True
Nếu đúng, nếu không có đối số nào bắt nguồn từ values để thêm vào, thì tất cả các 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, tên đối số và terminate_with (nếu có) sẽ vẫn được thêm vào bất kể có đối số nào khác hay không.
uniquify bool; giá trị mặc định là False
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ố mới được giữ lại. Thông thường, bạn không cần tính năng này vì các nhóm phần phụ thuộc đã bỏ qua các mục trùng lặp, nhưng tính năng này 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 bool; giá trị mặc định là True
Nếu đúng, mọi thư mục trong values sẽ được mở rộng thành một danh sách tệp phẳng. Việc này xảy ra trước khi áp dụng map_each.
terminate_with string; hoặc None; mặc định là None
Một đối số không bắt buộc để nối sau tất cả các đối số khác. Đối số này sẽ không được thêm nếu omit_if_empty là true (đúng theo 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 nó đều bị lọc).
allow_closure bool; mặc định là False
Nếu đúng, cho phép sử dụng các hàm đóng trong các tham số hàm như map_each. Thông thường, việc này là không cần thiết và có nguy cơ giữ lại các cấu trúc dữ liệu lớn trong giai đoạn phân tích vào 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ị với nhau bằng dấu phân cách. Các mục được xử lý theo kiểu trì hoãn trong giai đoạn thực thi.

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 (mặc định), thì sẽ không có quá trình xử lý nào được thực hiện. Nếu không, nếu không có chuỗi nào để nối nhưng omit_if_empty là sai, thì chuỗi được nối sẽ là một chuỗi trống.

Tham số

Thông số Mô tả
arg_name_or_values bắt buộc
Nếu hai tham số vị trí được truyền, tham số này sẽ được diễn giải là tên đối số. Tên đối số được thêm vào 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à 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 của nó đều bị lọc). Nếu chỉ truyền một tham số vị trí, tham số đó sẽ được diễn giải là values (xem bên dưới).
values trình tự; hoặc nhóm phần phụ thuộc; giá trị mặc định là unbound
Danh sách, bộ dữ liệu hoặc nhóm phần phụ thuộc có các mục sẽ được nối.
join_with string; bắt buộc
Một chuỗi dấu phân cách dùng để nối 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 có thể gọi; hoặc None; giá trị mặc định là None
giống như đối với add_all.
format_each chuỗi; hoặc None; mặc định là None
Tương tự như đối với add_all.
format_joined string; hoặc None; mặc định là None
Một mẫu chuỗi định dạng không bắt buộc được áp dụng cho chuỗi đã nối. Chuỗi định dạng phải có đúng một phần giữ chỗ "%s".
omit_if_empty bool; mặc định là True
Nếu đúng, nếu không có chuỗi nào để nối với nhau (do values trống hoặc tất cả các mục của chuỗi này đều bị lọc), thì tất cả các 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 để nối với nhau, hai đối số sẽ được thêm vào: tên đối số theo sau là một chuỗi trống (đây là phép nối logic của 0 chuỗi).
uniquify bool; mặc định là False
Tương tự như đối với add_all.
expand_directories bool; mặc định là True
Tương tự như đối với add_all.
allow_closure bool; mặc định là 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 param, nếu có sử dụng tệp này

Tham số

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

Đị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)

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

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.

Tham số

Thông số Mô tả
param_file_arg string; bắt buộc
Một chuỗi định dạng có một "%s" duy nhất. Nếu các đối số được chuyển sang tệp params, thì các đối số đó 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 các đối số được chuyển sang tệp tham 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 bool; mặc định là False
Liệu có luôn đổ các đối số vào tệp tham số hay không. Nếu giá trị là false, bazel sẽ quyết định xem có cần chuyển các đối số hay không dựa trên hệ thống và độ dài đối số của bạn.