Trường hợp này thường xảy ra việc một thao tác yêu cầu một dòng lệnh lớn chứa các giá trị được 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 được liên kết cần đến. Tốt nhất là bạn nên lưu trữ dữ liệu chuyển tiếp như vậy trong depset
để nhiều mục tiêu có thể chia sẻ chúng. 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ì quá trình tối ưu hoá việc chia sẻ bộ nhớ này sẽ không thành công.
Vì lý do này, các hàm xây dựng hành động còn 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 nối và các 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. Đố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, cũng như đế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 lớp 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
, thì lượt chuyển đổi chuẩn sẽ như sau:
- Các giá trị đã là chuỗi vẫn được giữ nguyên.
- Đố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 chuyển các giá trị không phải là chuỗi hoặc loại
File
vàoadd()
. Nếu chuyển các giá trị đó đếnadd_all()
hoặcadd_joined()
thì bạn nên cung cấp hàmmap_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ư 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
. Tỷ lệ phần trăm cố định 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ư mô tả ở 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 đố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 trở nên 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 có 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ể trà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 --bazChú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ố | Nội dung mô tả |
---|---|
arg_name_or_value
|
bắt buộc Nếu hai tham số vị trí được truyền thì sẽ đượ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ì nó 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. Do 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 chuyển vào add_all() hoặc add_joined() thay vì phương thức này.
|
format
|
string; or None ;
mặc định = Không cóMẫu chuỗi định dạng sẽ đượ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ý 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 danh sách các đối số cần thêm vào, theo các bước sau:
- Mỗi mục
File
của 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, đối số 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 giá trị
uniquify
là đúng, 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. - 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 sẽ làm tăng gấp đôi số lượng đối số một cách hiệu quả vào điểm này. - Ngoại trừ trường hợp danh sách trống và
omit_if_empty
là giá trị true (mặc định), tên đối số vàterminate_with
sẽ được chèn lần lượt dưới dạng đối số đầu tiên và cuối cùng nếu được đưa ra.
Tham 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ì sẽ đượ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 trong đó đều được lọc). Nếu chỉ có một tham số vị trí được truyền, thì nó sẽ được hiểu là values (xem bên dưới).
|
values
|
sequence; or depset ;
default = unboundDanh 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ôngHàm chuyển đổi từng mục thành 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, thì lượt chuyển đổi chuẩn sẽ được sử dụng. Hàm được truyền một hoặc hai đối số vị trí: mục cần chuyển đổi, theo sau là Loại giá trị trả về phụ thuộc vào số lượng đối số sẽ được tạo cho mụ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, cách này hiệu quả và dễ đọc hơn để tránh 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 theo nội dung của chúng khi bạn đặt Để 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 Cảnh báo: Các câu lệnh |
format_each
|
string; or None ;
default = KhôngMẫ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óThêm một chuỗi không bắt buộc trước khi thêm mỗi đối số bắt nguồn từ values .
|
omit_if_empty
|
mặc định = 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 đều bị chặn và dòng lệnh sẽ không thay đổi. Nếu giá trị là sai, thì tên đối số và terminate_with (nếu được cung cấp) vẫn sẽ đượ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ỉ còn lần xuất hiện đầu tiên của mỗi đối số. Thông thường, bạn không cần dùng tính năng này vì các phần phụ thuộc đã bỏ qua nội dung trùng lặp, nhưng có thể hữu ích nếu map_each phát đi cùng một chuỗi cho nhiều mục.
|
expand_directories
|
default = True Nếu là true, thì mọi thư mục trong values sẽ được mở rộng thành một 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 ;
mặc định = Không cóChuỗi không bắt buộc cần nối sau tất cả các đối số khác. Chuỗi này sẽ không được thêm vào 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 đều được lọc).
|
allow_closure
|
default = False Nếu là true, cho phép sử dụng trường hợp đóng trong các 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 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ị lại 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ý 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ể của join_with.join(...)
, sau đó được định dạng bằng cách sử dụ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ì những 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 vào một đối số và nếu omit_if_empty
là giá trị true (mặc định), thì 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ại giá trị false, thì chuỗi đã kết hợp sẽ là một chuỗi trống.
Tham 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ì sẽ đượ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 của đối số này đều được lọc). Nếu chỉ có một tham số vị trí được truyền, thì nó sẽ được hiểu là values (xem bên dưới).
|
values
|
sequence; or depset ;
default = unboundDanh 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 phân tách 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 ;
mặc định = Không cóTương tự như đối với add_all .
|
format_each
|
string; or None ;
mặc định = Không cóTương tự như đối với add_all .
|
format_joined
|
string; or None ;
default = KhôngMẫu chuỗi định dạng không bắt buộc áp dụng cho chuỗi đã liên kết. 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 đúng, 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 trong đó đều bị lọc), thì tất cả các quá trình xử lý tiếp theo đều 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, 2 đối số sẽ được nối vào: tên đối số theo sau là một chuỗi trống (là phần kết hợp logic của các chuỗi 0).
|
uniquify
|
mặc định = Sai Tương tự như đối với add_all .
|
expand_directories
|
mặc định = True Tương tự như đối với add_all .
|
allow_closure
|
mặc định = Sai 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 tệp này được sử dụng
Tham số
Thông số | Nội dung mô tả |
---|---|
format
|
bắt buộc Phải là một trong các loại sau:
Đị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 ghi tệp tham 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 truyền --materialize_param_files
vào bản dựng.
Tham số
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". Nếu đối số được tràn vào tệp tham số, thì chúng sẽ được thay thế bằng một đối số chứa chuỗi này được định dạng bằng đường dẫn của tệp tham số. Ví dụ: nếu đối số được tràn vào tệp thông số "params.txt", việc chỉ định "--file=%s" sẽ khiến dòng lệnh hành động chứa "--file=params.txt". |
use_always
|
mặc định = Sai Liệu có luôn tràn đối số vào tệp tham số hay không. Nếu giá trị false, bazel sẽ quyết định xem có cần đưa vào đối số hay không dựa trên hệ thống và độ dài của đối số của bạn. |