thao tác

Mô-đun cung cấp các hàm để tạo thao tác. 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 khía cạnh tạo một thư mục có tên đã cho trong gói hiện tại. Bạn phải tạo một thao tác tạo thư mục. Bạn không thể truy cập trực tiếp vào nội dung của thư mục từ Starlark, nhưng có thể mở rộng trong lệnh hành động bằng Args.add_all().

Thông số

Thông số Mô tả
filename bắt buộc
Nếu không cung cấp "anh em", đường dẫn của thư mục mới, tương ứng với gói hiện tại. Nếu không, tên cơ sở cho một tệp ('anh em' xác định một thư mục).
sibling File; or None; mặc định = Không có
Một 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 khía cạnh tạo một tệp có tên tệp đã cho. Nếu không chỉ định sibling, tên tệp sẽ tương ứng với thư mục gói, nếu không 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 hành động phát ra 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 đó.

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

Thông số

Thông số Mô tả
filename bắt buộc
Nếu không có "đồng cấp" đã 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ở cho tệp ('anh em' xác định thư mục).
sibling File; or None; mặc định = Không
Một 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. Tham số 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 đừng phụ thuộc vào tính năng 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_allow_unresolved_symlinks

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

Thông số

Thông số Mô tả
filename bắt buộc
Nếu không cung cấp "anh em", đường dẫn của đường liên kết tượng trưng mới, tương ứng với gói hiện tại. Nếu không, tên cơ sở cho tệp ('ương đồng' xác định một thư mục).
sibling File; or None; mặc định = Không
Một 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 rất hữu ích khi chèn "thao tác bổ sung".

Thông số

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

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 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 các mục thay thế. Bất cứ khi nào một 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ị có liên quan. Không có cú pháp đặc biệt cho khoá. Ví dụ: bạn có thể sử dụng dấu ngoặc nhọn để tránh xung đột (ví dụ: {KEY}). Xem ví dụ về cách sử dụng.

Thông số

Thông số Mô tả
template bắt buộc
Tệp mẫu là một 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 default = {}
Nội dung 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 hay không.
computed_substitutions TemplateDict; mặc định = không liên kết
Thử nghiệm. Thông số 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 đừng phụ thuộc vào tính năng này. Bạn có thể bật tính năng này trong thử nghiệm bằng cách đặt --+experimental_lazy_template_expansion
Thử nghiệm: Phép thay thế cần thực hiện khi mở rộng mẫu.

chạy

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 một tệp thực thi. Xem ví dụ về cách sử dụng.

Thông số

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

Nội dung của tệp này (thường là một trong các kết quả của hành động) 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 đó đều không được ảnh hưởng đến kết quả của hành động.

executable File; or string; or FilesToRunProvider; bắt buộc
Tệp thực thi sẽ được hành động gọi.
tools sequence; or depset; mặc định = không liên kết
Liệt kê hoặc gỡ bỏ mọi công cụ cần thiết cho hành động. Công cụ là dữ liệu đầu vào có các tệp chạy bổ sung được cung cấp tự động cho thao tác. Khi được cung cấp, danh sách có thể là một tập hợp không đồng nhất gồm các Tệp, thực thể FilesToRunProvider hoặc các nhóm phụ thuộc của Tệp. Các tệp nằm ngay trong danh sách và đến từ ctx.executable sẽ tự động được thêm các tệp chạy bộ của chúng. Khi được cung cấp, depset chỉ được chứa Tệp. Trong cả hai trường hợp, các tệp trong bộ phân tích đều không được tham chiếu chéo với ctx.executable cho các tệp chạy.
arguments sequence; mặc định = []
Đối số dòng lệnh của thao tác. Phải là danh sách các 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ề hành động, ví dụ: CppCompile hoặc GoLink.
progress_message string; or None; mặc định = Không có
Thông báo về tiến trình sẽ hiển thị cho 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 báo có thể chứa các mẫu %{label}, %{input} hoặc %{output}, được thay thế bằng chuỗi nhãn, dữ liệu đầu vào đầu tiên hoặc đường dẫn của dữ liệu đầu ra tương ứng. Ưu tiên sử dụng mẫu thay vì chuỗi tĩnh, vì mẫu 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 sẵn hay không.
env dict; or None; mặc định = Không có
Thiết lập từ điển cho các biến môi trường.
execution_requirements dict; or None; default = None
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; mặc định = Không
(Thử nghiệm) đặt siêu dữ liệu tệp chạy đầu vào; các siêu dữ liệu này thường được tạo bằng resolve_command.
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 nhất định. 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 dữ liệu đầu vào và môi trường của hành động bị đổ bóng đã 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 dữ liệu đầu vào của thao tác và môi trường đã cho.
resource_set callable; or None; mặc định = Không có
Hàm callback trả về từ điển nhóm tài nguyên, 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 hai đố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 dữ liệu đầu vào cho thao tác. Từ điển được trả về có thể chứa các mục sau, mỗi mục có thể là float hoặc int:

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

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

Lệnh gọi lại phải là cấp cao nhất (không được phép sử dụng các 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ụ được dùng trong thao tác này. Bạn phải đặt tham số để hành động thực thi trên đúng nền tảng thực thi.

Hiện tại, tính năng này không hoạt động, nhưng bạn nên đặt chuỗi công cụ này khi sử dụng chuỗi công cụ, vì bạn sẽ phải đặt chuỗi công cụ này trong các bản phát hành Bazel trong tương lai.

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

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

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 hành động chạy lệnh shell. Xem ví dụ về cách sử dụng.

Thông số

Thông số Mô tả
outputs sequence of Files; bắt buộc
Danh sách các tệp đầu ra của thao tác.
inputs sequence of Files; or depset; default = []
Danh sách hoặc depset của các tệp đầu vào của hành động.
tools sequence of Files; or depset; mặc định = không ràng buộc
Danh sách hoặc nhóm phần phụ thuộc của mọi công cụ mà thao tác cần đến. Công cụ là dữ liệu đầu vào có các tệp chạy bổ sung được tự động cung cấp cho thao tác. 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ố đến lệnh. Lệnh có thể truy cập vào các đối số này bằng cách sử dụng các tham số thay thế biến shell như $1, $2, v.v. Xin 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ên 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ể đoán trước. 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 các chuỗi, thì không nên sử 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ề hành động, ví dụ: CppCompile hoặc GoLink.
command string; or sequence of strings; bắt buộc
Lệnh shell để thực thi. Đây có thể là một chuỗi (ưu tiên) hoặc một chuỗi (không dùng nữa).

Nếu command là một chuỗi, thì nó sẽ được thực thi như thể bằng 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 đối tượng này sẽ được nối lần lượt từng dòng lệnh để $i có thể tham chiếu đến từng chuỗi trong một đố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 như một phần của arguments, thì các chuỗi sẽ nằm tại 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ả cá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 sẽ chạy và các mục còn lại là đối số của nó. Nếu sử dụng biểu mẫu này, bạn 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á. Lệnh này bị tắt bằng lệnh "--incompatible_run_shell_command_string". Sử 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 như đối với genrules.

progress_message string; or None; mặc định = Không có
Thông báo về tiến trình sẽ hiển thị cho 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 báo có thể chứa các mẫu %{label}, %{input} hoặc %{output}, được thay thế bằng chuỗi nhãn, đầu vào đầu tiên hoặc đường dẫn đầu ra tương ứng. Ưu tiên sử dụng mẫu thay vì chuỗi tĩnh, vì mẫu hiệu quả hơn.
use_default_shell_env mặc định = False
Liệu thao tác 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 có
Thiết lập từ điển cho các biến môi trường.
execution_requirements dict; or None; default = None
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; mặc định = Không có
(Thử nghiệm) thiết lập siêu dữ liệu các tệp runfile đầu vào; chúng thường được tạo bằng resolve_command.
exec_group string; or None; default = None
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 đã phát hiện của hành động bị đổ bóng đượ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 dữ liệu đầu vào của hành động.
resource_set callable; or None; default = None
Hàm gọi lại để ước tính mức sử dụng tài nguyên nếu chạy cục bộ. Xemctx.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ụ được dùng trong thao tác này. Bạn phải đặt tham số này để hành động này sẽ thực thi trên đúng nền tảng thực thi.

Hiện tại, tính năng này không hoạt động, nhưng bạn nên đặt chuỗi công cụ này khi sử dụng chuỗi công cụ, vì bạn sẽ phải đặt chuỗi công cụ này trong các bản phát hành Bazel trong tương lai.

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

Khi bạn đặt cả thông số `toolchain` và `exec_group`, `exec_group` sẽ được sử dụng. Lỗi sẽ xảy ra 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 để viết một đường liên kết tượng trưng trong hệ thống tệp.

Bạn phải gọi hàm này bằng đúng một trong hai thuộc tính target_file hoặc target_path được 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à khớp với loại target_file. Thao tác này sẽ khiến đường liên kết tượng trưng trỏ đến target_file. Bazel vô hiệu hoá đầu ra của thao tác này bất cứ khi nào mục tiêu của đường liên kết tượng trưng hoặc nội dung trong đó 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 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 thao tác này chỉ mất hiệu lực 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 treo lơ lửng.

Thông số

Thông số 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 có
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 có
(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. Không chuẩn hoá hoặc xử lý khác được áp dụng. Bạn cần thiết lập --experimental_allow_unresolved_symlinks để truy cập vào tính năng này.
is_executable mặc định = False
Chỉ có thể sử dụng với target_file, không phải target_path. Nếu đúng, khi thực thi thao tác, đường dẫn của target_file sẽ được kiểm tra để xác nhận rằng đường dẫn đó có thể thực thi được và báo lỗi nếu không. Việc đặt is_executable thành False không có nghĩa là mục tiêu không thực thi được, mà chỉ là không có xác minh nào được thực hiện.

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 lơ lửng có thể không tồn tại tại thời điểm tạo bản dựng.
progress_message string; or None; mặc định = Không
Thông báo tiến trình 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 đừng phụ thuộc vào tính năng 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 hiệu quả về 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 sẽ ghi nội dung đã cấp vào một tệp. Phương thức 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à chứa nhiều nội dung tĩnh, hãy cân nhắc sử dụng expand_template.

Thông số

Thông số Mô tả
output bắt buộc
Tệp đầu ra.
content string; or Args; bắt buộc
nội dung của tệp. Có thể là một 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 hay không.