thao tác

Mô-đun cung cấp các hàm để tạo hành động. Truy cập vào mô-đun này bằng ctx.actions.

Hội viên

args

Args actions.args()

Trả về một đối tượng Args có thể dùng để xây dựng các dòng lệnh tiết kiệm bộ nhớ.

declare_directory

File actions.declare_directory(filename, *, sibling=None)

Khai báo rằng quy tắc hoặc thành phần sẽ tạo một thư mục có tên cụ thể trong gói hiện tại. Bạn phải tạo một thao tác tạo thư mục. Không thể trực tiếp truy cập nội dung của thư mục này qua Starlark, nhưng bạn có thể mở rộng nội dung của thư mục này trong một lệnh hành động bằng Args.add_all().

Các tham số

Thông số Nội dung mô tả
filename bắt buộc
Nếu không có "đồng cấp" nào được cung cấp, đường dẫn của thư mục mới, so với gói hiện tại. Nếu không, tên cơ sở của một tệp ('đồng cấp' sẽ định nghĩa một thư mục).
sibling File; or None; mặc định = Không có
Tệp nằm trong cùng thư mục với thư mục mới khai báo. Tệp phải nằm trong gói hiện tại.

declare_file

File actions.declare_file(filename, *, sibling=None)

Khai báo rằng quy tắc hoặc thành phần sẽ tạo một tệp có tên tệp đã cho. Nếu bạn không chỉ định sibling thì tên tệp sẽ tương ứng với thư mục gói, nếu không thì tệp sẽ nằm trong cùng thư mục với sibling. Không thể tạo tệp bên ngoài gói hiện tại.

Hãy nhớ rằng ngoài việc khai báo tệp, bạn phải tạo riêng một thao tác kích hoạt tệp đó. Khi tạo thao tác đó, bạn sẽ phải truyền đối tượng File được trả về đến hàm xây dựng của thao tác đó.

Lưu ý rằng các tệp đầu ra được khai báo trước không cần phải (và không thể) khai báo bằng hàm này. Bạn có thể lấy các đối tượng File của các đối tượng này từ ctx.outputs. Xem ví dụ về cách sử dụng.

Các tham số

Thông số Nội dung mô tả
filename bắt buộc
Nếu không có "đồng cấp" nào được cung cấp, đường dẫn của tệp mới, so với gói hiện tại. Nếu không, tên cơ sở của một tệp (tức là "đồng cấp" sẽ xác định một thư mục).
sibling File; or None; mặc định = Không
Tệp nằm trong cùng thư mục với tệp mới tạo. Tệp phải nằm trong gói hiện tại. 

File actions.declare_symlink(filename, *, sibling=None)

Thử nghiệm. Đây là thông số thử nghiệm và có thể thay đổi bất cứ lúc nào. Vui lòng không phụ thuộc vào công cụ này. Tính năng này có thể bật trên cơ sở thử nghiệm bằng cách đặt --experimental_allow_unresolved_symlinks

Khai báo rằng quy tắc hoặc thành phần sẽ tạo một đường liên kết tượng trưng với tên đã cho trong gói hiện tại. Bạn phải tạo một hành động tạo ra đường liên kết tượng trưng này. Bazel sẽ không bao giờ huỷ tham chiếu đến mối liên kết tượng trưng này và sẽ chuyển chính xác mối liên kết này sang các hộp cát hoặc thực thi thực thi từ xa.

Các tham số

Thông số Nội dung mô tả
filename bắt buộc
Nếu không cung cấp "đường liên kết tượng trưng" nào, đường dẫn của đường liên kết tượng trưng mới, so với gói hiện tại. Nếu không, tên cơ sở của một tệp ('đồng cấp' sẽ định nghĩa một thư mục).
sibling File; or None; mặc định = Không
Tệp nằm trong cùng thư mục với đường liên kết tượng trưng mới khai báo.

do_nothing

None actions.do_nothing(mnemonic, inputs=[])

Tạo một thao tác trống không thực thi lệnh cũng như không tạo ra kết quả nào, nhưng điều này rất hữu ích cho việc chèn "thao tác bổ sung".

Các tham số

Thông số Nội dung mô tả
mnemonic bắt buộc
Nội dung mô tả một từ về thao tác, ví dụ: CppCompile hoặc GoLink.
inputs sequence of Files; or depset; mặc định = []
Danh sách tệp đầu vào của hành động.

expand_template

None actions.expand_template(template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)

Tạo hành động mở rộng mẫu. Khi được thực thi, thao tác này sẽ tạo một tệp dựa trên mẫu. Các phần của mẫu sẽ được thay thế bằng từ điển substitutions, theo thứ tự chỉ định thay thế. Bất cứ khi nào khoá của từ điển xuất hiện trong mẫu (hoặc kết quả của một lần thay thế trước đó), khoá đó sẽ được thay thế bằng giá trị liên quan. Không có cú pháp đặc biệt cho các khoá này. Chẳng hạn, bạn có thể sử dụng dấu ngoặc nhọn để tránh xung đột (ví dụ như {KEY}). Xem ví dụ về cách sử dụng.

Các tham số

Thông số Nội dung mô tả
template bắt buộc
Tệp mẫu, là tệp văn bản được mã hoá UTF-8.
output bắt buộc
Tệp đầu ra, là tệp văn bản được mã hoá UTF-8.
substitutions mặc định = {}
Các giá trị thay thế cần thực hiện khi mở rộng mẫu.
is_executable mặc định = Sai
Liệu tệp đầu ra có thể thực thi được hay không.
computed_substitutions TemplateDict; mặc định = không liên kết
Thử nghiệm. Đây là thông số thử nghiệm và có thể thay đổi bất cứ lúc nào. Vui lòng không phụ thuộc vào công cụ này. Bạn có thể bật tính năng này trên cơ sở thử nghiệm bằng cách đặt --+experimental_lazy_template_expansion
Thử nghiệm: Thay thế cần thực hiện khi mở rộng mẫu.

run

None actions.run(outputs, inputs=[], unused_inputs_list=None, executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=None)

Tạo một thao tác chạy tệp thực thi. Xem ví dụ về cách sử dụng.

Các tham số

Thông số Nội dung mô tả
outputs sequence of Files; bắt buộc
Danh sách tệp đầu ra của hành động.
inputs sequence of Files; or depset; default = []
Danh sách hoặc phần phụ thuộc của tệp đầu vào của thao tác.
unused_inputs_list File; or None; mặc định = Không có
Tệp chứa danh sách đầu vào mà hành động không sử dụng.

Nội dung của tệp này (thường là một trong các đầu ra của tác vụ) tương ứng với danh sách các tệp đầu vào không được sử dụng trong toàn bộ quá trình thực thi hành động. Mọi thay đổi trong các tệp đó không được ảnh hưởng theo bất kỳ cách nào đến kết quả của hành động.

executable File; or string; or FilesToRunProvider; bắt buộc
Tệp thực thi để hành động gọi ra.
tools sequence; or depset; mặc định = không liên kết
Liệt kê hoặc tập hợp các công cụ cần thiết cho thao tác. Công cụ là dữ liệu đầu vào với các tệp runfile bổ sung được tự động cung cấp cho hành động. Khi một danh sách được cung cấp, đó có thể là một tập hợp các thực thể Files, FilesToRunProvider hoặc các phần phụ thuộc khác nhau của Files. Các tệp trực tiếp có trong danh sách và đến từ ctx.executable sẽ được tự động thêm các tệp chạy của chúng. Khi được cung cấp, phần phụ thuộc chỉ được chứa Files. Trong cả hai trường hợp, các tệp trong phần phụ thuộc không được tham chiếu chéo với ctx.executable cho runfile.
arguments sequence; mặc định = []
Đối số dòng lệnh của thao tác. Phải là một danh sách chuỗi hoặc đối tượng actions.args().
mnemonic string; or None; mặc định = Không có
Nội dung mô tả một từ về thao tác, ví dụ: CppCompile hoặc GoLink.
progress_message string; or None; mặc định = Không có
Thông báo tiến trình sẽ hiển thị với người dùng trong quá trình tạo bản dựng, ví dụ: "Biên dịch foo.cc để tạo foo.o". Thông điệp có thể chứa các mẫu %{label}, %{input} hoặc %{output}, được thay thế bằng chuỗi nhãn, đường dẫn của giá trị đầu vào hoặc đầu ra tương ứng. Ưu tiên sử dụng mẫu thay vì chuỗi tĩnh, vì mẫu cũ hiệu quả hơn.
use_default_shell_env mặc định = Sai
Liệu hành động có nên sử dụng môi trường shell tích hợp hay không.
env dict; or None; mặc định = Không
Đặt từ điển của các biến môi trường.
execution_requirements dict; or None; mặc định = Không
Thông tin để lên lịch hành động. Xem thẻ để biết các khoá hữu ích.
input_manifests sequence; or None; default = Không
(Thử nghiệm) thiết lập siêu dữ liệu runfile đầu vào; các tệp này thường do resolve_command tạo.
exec_group string; or None; mặc định = Không có
Chạy hành động trên nền tảng thực thi của nhóm thực thi đã cho. Nếu không có, hãy sử dụng nền tảng thực thi mặc định của mục tiêu.
shadowed_action Action; mặc định = Không
Chạy hành động bằng cách sử dụng đầu vào và môi trường của hành động bị ẩn đã thêm vào danh sách đầu vào và môi trường của hành động đó. Môi trường hành động có thể ghi đè mọi biến môi trường của hành động bị ẩn. Nếu không có, chỉ sử dụng thông tin đầu vào của hành động và môi trường nhất định.
resource_set callable; or None; mặc định = Không
Hàm callback trả về từ điển nhóm tài nguyên, được dùng để ước tính mức sử dụng tài nguyên tại thời điểm thực thi nếu hành động này được chạy cục bộ.

Hàm này chấp nhận 2 đối số vị trí: một chuỗi đại diện cho tên hệ điều hành (ví dụ: "osx") và một số nguyên đại diện cho số lượng đầu vào cho tác vụ. Từ điển được trả về có thể chứa các mục nhập sau, mỗi mục nhập có thể là một số thực hoặc một số nguyên:

  • "cpu": số lượng CPU; mặc định là 1
  • "memory": tính bằng MB; mặc định là 250
  • "local_test": số lượng bài kiểm thử cục bộ; mặc định là 1

Nếu tham số này được đặt thành None hoặc nếu --experimental_action_resource_set sai, thì giá trị mặc định sẽ được sử dụng.

Lệnh gọi lại phải ở cấp cao nhất (không được dùng hàm lambda và hàm lồng nhau).

toolchain Label; or string; or None; mặc định = Không có

Loại chuỗi công cụ của tệp thực thi hoặc công cụ dùng trong hành động này. Bạn phải đặt tham số để hành động được thực thi trên đúng nền tảng thực thi.

Tính năng này hiện không hoạt động, nhưng bạn nên thiết lập khi sử dụng chuỗi công cụ, vì đây là yêu cầu bắt buộc trong các bản phát hành Bazel sau này.

Lưu ý rằng quy tắc tạo hành động này cần xác định chuỗi công cụ này bên trong hàm "Rules()".

Khi bạn đặt cả thông số "toolchain" và "exec_group", hệ thống sẽ sử dụng "exec_group". Sẽ xảy ra lỗi trong trường hợp "exec_group" không chỉ định thông tin tương tự.

run_shell

None actions.run_shell(outputs, inputs=[], tools=unbound, arguments=[], mnemonic=None, command, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=None)

Tạo một thao tác chạy lệnh shell. Xem ví dụ về cách sử dụng.

Các tham số

Thông số Nội dung mô tả
outputs sequence of Files; bắt buộc
Danh sách tệp đầu ra của hành động.
inputs sequence of Files; or depset; default = []
Danh sách hoặc phần phụ thuộc của tệp đầu vào của thao tác.
tools sequence of Files; or depset; mặc định = không liên kết
Liệt kê hoặc tập hợp các công cụ cần thiết cho thao tác. Công cụ là dữ liệu đầu vào với các tệp runfile bổ sung được tự động cung cấp cho hành động. Danh sách này có thể chứa các thực thể Files hoặc FilesToRunProvider.
arguments sequence; mặc định = []
Đối số dòng lệnh của thao tác. Phải là một danh sách chuỗi hoặc đối tượng actions.args().

Bazel truyền các phần tử trong thuộc tính này dưới dạng đối số cho lệnh. Lệnh này có thể truy cập các đối số này bằng cách sử dụng các thay thế biến shell như $1, $2, v.v. Lưu ý rằng vì các đối tượng Args được làm phẳng trước khi lập chỉ mục, nếu có một đối tượng Args có kích thước không xác định thì tất cả các chuỗi tiếp theo sẽ ở các chỉ mục không thể dự đoán. Bạn nên sử dụng $@ (để truy xuất tất cả đối số) cùng với các đối tượng Args có kích thước không xác định.

Trong trường hợp command là một danh sách chuỗi, bạn không thể dùng tham số này.

mnemonic string; or None; mặc định = Không có
Nội dung mô tả một từ về thao tác, ví dụ: CppCompile hoặc GoLink.
command string; or sequence of strings; bắt buộc
Có lệnh Shell để thực thi. Đây có thể là một chuỗi (ưu tiên) hoặc một chuỗi chuỗi (không dùng nữa).

Nếu command là một chuỗi, thì nó được thực thi như thể bởi sh -c <command> "" <arguments> – tức là các phần tử trong arguments được cung cấp cho lệnh dưới dạng $1, $2 (hoặc %1, %2 nếu sử dụng lô Windows), v.v. Nếu arguments chứa bất kỳ đối tượng actions.args() nào, nội dung của các phần tử này sẽ được thêm từng đối tượng vào dòng lệnh, do đó $i có thể tham chiếu đến các chuỗi riêng lẻ trong đối tượng Args. Lưu ý rằng nếu một đối tượng Args có kích thước không xác định được truyền dưới dạng một phần của arguments, thì các chuỗi sẽ ở chỉ mục không xác định; trong trường hợp này, việc thay thế shell $@ (truy xuất tất cả đối số) có thể hữu ích.

(Không dùng nữa) Nếu command là một chuỗi chuỗi, thì mục đầu tiên là tệp thực thi để chạy và các mục còn lại là đối số của mục đó. Nếu biểu mẫu này được sử dụng, thì không được cung cấp tham số arguments. Xin lưu ý rằng biểu mẫu này không được dùng nữa và sẽ sớm bị xoá. Tính năng này đã bị vô hiệu hoá do lỗi "--incompatible_run_shell_command_string". Hãy dùng cờ này để xác minh rằng mã của bạn tương thích.

Bazel sử dụng cùng một shell để thực thi lệnh giống như với genrules.

progress_message string; or None; mặc định = Không có
Thông báo tiến trình sẽ hiển thị với người dùng trong quá trình tạo bản dựng, ví dụ: "Biên dịch foo.cc để tạo foo.o". Thông điệp có thể chứa các mẫu %{label}, %{input} hoặc %{output}, được thay thế bằng chuỗi nhãn, đường dẫn của giá trị đầu vào hoặc đầu ra tương ứng. Ưu tiên sử dụng mẫu thay vì chuỗi tĩnh, vì mẫu cũ hiệu quả hơn.
use_default_shell_env mặc định = Sai
Liệu hành động có nên sử dụng môi trường shell tích hợp hay không.
env dict; or None; mặc định = Không
Đặt từ điển của các biến môi trường.
execution_requirements dict; or None; mặc định = Không
Thông tin để lên lịch hành động. Xem thẻ để biết các khoá hữu ích.
input_manifests sequence; or None; default = Không
(Thử nghiệm) thiết lập siêu dữ liệu runfile đầu vào; các tệp này thường do resolve_command tạo.
exec_group string; or None; mặc định = Không có
Chạy hành động trên nền tảng thực thi của nhóm thực thi đã cho. Nếu không có, hãy sử dụng nền tảng thực thi mặc định của mục tiêu.
shadowed_action Action; mặc định = Không có
Chạy hành động bằng cách sử dụng các dữ liệu đầu vào đã được phát hiện của hành động bị ẩn được thêm vào danh sách dữ liệu đầu vào của hành động đó. Nếu không có, chỉ sử dụng thông tin đầu vào của hành động.
resource_set callable; or None; mặc định = Không
Hàm callback để ước tính mức sử dụng tài nguyên nếu chạy cục bộ. Hãy xem ctx.actions.run().
toolchain Label; or string; or None; mặc định = Không có

Loại chuỗi công cụ của tệp thực thi hoặc công cụ dùng trong hành động này. Bạn phải đặt tham số để hành động được thực thi trên đúng nền tảng thực thi.

Tính năng này hiện không hoạt động, nhưng bạn nên thiết lập khi sử dụng chuỗi công cụ, vì đây là yêu cầu bắt buộc trong các bản phát hành Bazel sau này.

Lưu ý rằng quy tắc tạo hành động này cần xác định chuỗi công cụ này bên trong hàm "Rules()".

Khi bạn đặt cả thông số "toolchain" và "exec_group", hệ thống sẽ sử dụng "exec_group". Sẽ xảy ra lỗi trong trường hợp "exec_group" không chỉ định cùng một chuỗi công cụ.

 

None actions.symlink(output, target_file=None, target_path=None, is_executable=False, progress_message=None)

Tạo một thao tác ghi một đường liên kết tượng trưng trong hệ thống tệp.

Hàm này phải được gọi bằng một trong các target_file hoặc target_path đã chỉ định.

Khi bạn sử dụng target_file, hãy khai báo output bằng declare_file() hoặc declare_directory() và so khớp loại target_file. Thao tác này làm cho đường liên kết tượng trưng trỏ đến target_file. Bazel vô hiệu hoá kết quả của hành động này mỗi khi mục tiêu hoặc nội dung của đường liên kết tượng trưng thay đổi.

Nếu không, khi bạn sử dụng target_path, hãy khai báo output bằng declare_symlink()). Trong trường hợp này, đường liên kết tượng trưng sẽ trỏ đến target_path. Bazel không bao giờ phân giải đường liên kết tượng trưng và kết quả của hành động này chỉ bị vô hiệu hoá khi nội dung văn bản của đường liên kết tượng trưng (tức là giá trị của readlink()) thay đổi. Cụ thể, bạn có thể dùng tính năng này để tạo một đường liên kết tượng trưng lơ lửng.

Các tham số

Thông số Nội dung mô tả
output bắt buộc
Kết quả của hành động này.
target_file File; or None; mặc định = Không
Tệp mà đường liên kết tượng trưng đầu ra sẽ trỏ đến.
target_path string; or None; mặc định = Không
(Thử nghiệm) Đường dẫn chính xác mà đường liên kết tượng trưng đầu ra sẽ trỏ đến. Hệ thống không áp dụng quy trình chuẩn hoá hoặc xử lý nào khác. Bạn phải cài đặt --experimental_allow_unresolved_symlinks để truy cập tính năng này.
is_executable mặc định = Sai
Chỉ dùng được với target_file, không dùng được với target_path. Nếu đúng, khi hành động được thực thi, đường dẫn của target_file sẽ được kiểm tra để xác nhận rằng tệp có thể thực thi và lỗi sẽ được báo cáo nếu không phải. Việc đặt is_executable thành False không có nghĩa là mục tiêu không thực thi được, chỉ là chưa xác minh xong.

Tính năng này không phù hợp với target_path vì các đường liên kết tượng trưng treo có thể không tồn tại trong thời gian xây dựng.
progress_message string; or None; mặc định = Không
Thông báo tiến trình sẽ hiển thị cho người dùng trong quá trình tạo bản dựng.

template_dict

TemplateDict actions.template_dict()

Thử nghiệm. API này đang trong giai đoạn thử nghiệm và có thể thay đổi bất cứ lúc nào. Vui lòng không phụ thuộc vào công cụ này. Bạn có thể bật tính năng này trên cơ sở thử nghiệm bằng cách đặt --+experimental_lazy_template_expansion
Thử nghiệm: Trả về đối tượng TemplateDict để mở rộng mẫu tiết kiệm bộ nhớ.

ghi

None actions.write(output, content, is_executable=False)

Tạo một thao tác ghi tệp. Khi được thực thi, thao tác này sẽ ghi nội dung đã cho vào một tệp. Tính năng này dùng để tạo tệp bằng thông tin có sẵn trong giai đoạn phân tích. Nếu tệp có kích thước lớn và có nhiều nội dung tĩnh, hãy cân nhắc sử dụng expand_template.

Các tham số

Thông số Nội dung mô tả
output required
Tệp đầu ra.
content string; or Args; cần
nội dung của tệp. Có thể ở dạng chuỗi hoặc đối tượng actions.args().
is_executable mặc định = Sai
Liệu tệp đầu ra có thể thực thi được hay không.