thao tác

Báo cáo vấn đề Xem nguồn

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

Thành viên

args

Args actions.args()

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

khai báo_thư mục

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

Khai báo quy tắc hoặc khía cạnh tạo thư mục có tên đã cho trong gói hiện tại. Bạn phải tạo hành động tạo thư mục. Không thể truy cập trực tiếp nội dung của thư mục này từ Starlark, nhưng bạn có thể mở rộng nội dung này trong lệnh hành động bằng Args.add_all(). Chỉ các tệp và thư mục thông thường mới có thể nằm trong nội dung được mở rộng của khai báo_thư mục.

Các tham số

Thông số Nội dung mô tả
filename bắt buộc
Nếu không có 'anh chị em' nào được cung cấp, đường dẫn của thư mục mới, liên quan đến gói hiện tại. Nếu không, tên cơ sở dành cho một tệp ('anh chị em' xác định thư mục).
sibling File; or None; default = None
Một tệp nằm trong cùng thư mục với thư mục mới được khai báo. Tệp này phải nằm trong gói hiện tại.

khai báo_tệp

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

Khai báo quy tắc hoặc khía cạnh tạo tệp có tên tệp đã cho. Nếu bạn 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 hành động tạo ra tệp. Việc tạo hành động đó sẽ yêu cầu truyền đối tượng File được trả về đến hàm xây dựng của hành động.

Xin lưu ý rằng bạn không cần (và không thể khai báo) 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 đối tượng File 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ó 'anh chị em' nào được cung cấp, đường dẫn của tệp mới, liên quan đến gói hiện tại. Nếu không, tên cơ sở cho một tệp ("anh chị em" sẽ xác định thư mục).
sibling File; or None; default = None
Một tệp nằm trong cùng thư mục với tệp mới tạo. Tệp này phải nằm trong gói hiện tại. 

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

Thông số này là thử nghiệm và có thể thay đổi bất cứ lúc nào. Tính năng này có thể bị tắt bằng cách đặt --noexperimental_allow_unresolved_symlinks

Khai báo quy tắc hoặc khía cạnh tạo đườ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 hành động tạo liên kết tượng trưng này. Bazel sẽ không bao giờ hủy tham chiếu đường liên kết tượng trưng này và sẽ chuyển nó nguyên văn cho hộp cát hoặc người thực thi từ xa. Liên kết tượng trưng bên trong cấu phần phần mềm cây hiện không được hỗ trợ.

Các tham số

Thông số Nội dung mô tả
filename bắt buộc
Nếu không có 'anh chị em' nào được cung cấp, đường dẫn của liên kết tượng trưng mới, liên quan đến gói hiện tại. Nếu không, tên cơ sở dành cho một tệp ('anh chị em' xác định thư mục).
sibling File; or None; default = None
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 được khai báo.

không làm gì

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

Tạo một hành động trống không thực thi lệnh hay tạo ra bất kỳ kết quả nào, nhưng cũng hữu ích khi chèn 'extra actions'.

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ừ chỉ hành động, chẳng hạn như CppCompile hoặc GoLink.
inputs sequence of Files; or depset; default = []
Danh sách các tệp đầu vào của thao tác.

mẫu_mở rộng

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

Tạo hành động mở rộng mẫu. Khi 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ự thay thế được chỉ định. Bất cứ khi nào một khóa của từ điển xuất hiện trong mẫu (hoặc kết quả của thay thế trước), khóa đó được thay thế bằng giá trị được liên kết. Không có cú pháp đặc biệt cho các khóa. 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.

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ã hóa UTF-8.
output bắt buộc
Tệp đầu ra, là tệp văn bản được mã hóa UTF-8.
substitutions default = {}
Việc thay thế khi mở rộng mẫu.
is_executable default = False
Liệu tệp đầu ra có thể thực thi hay không.
computed_substitutions TemplateDict; default = unbound
Thử nghiệm. Thông số này là thử nghiệm và có thể thay đổi bất cứ lúc nào. Xin đừng cho phép. 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.

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=unbound)

Tạo một hành động chạy một 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 các tệp đầu ra của hành động.
inputs sequence of Files; or depset; default = []
Liệt kê hoặc depset các tệp đầu vào của thao tác đó.
unused_inputs_list File; or None; default = None
Tệp chứa danh sách dữ liệu nhập mà hành động không sử dụng.

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

executable File; or string; or FilesToRunProvider; bắt buộc
Tệp thực thi sẽ được gọi bởi hành động.
tools sequence; or depset; default = unbound
Liệt kê hoặc gỡ bỏ bất kỳ công cụ nào 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 tự động cung cấp cho thao tác. Khi danh sách được cung cấp, danh sách đó có thể là một tập hợp không đồng nhất của các thực thể Files, FilesToRunProvider hoặc phần phụ thuộc của Files. Các tệp nằm ngay trong danh sách và đến từ ctx.executable sẽ được tự động thêm các tệp chạy. Khi được cung cấp, tệp depset chỉ được chứa các tệp. 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 các tệp chạy.
arguments sequence; default = []
Các đối số dòng lệnh của hành động. Phải là danh sách chuỗi hoặc đối tượng actions.args().
mnemonic string; or None; default = None
Thông tin mô tả một hành động, ví dụ: CppCompile hoặc GoLink.
progress_message string; or None; default = None
Thông báo tiến trình để hiển thị cho người dùng trong quá trình xây dựng, ví dụ: "Biên dịch foo.cc để tạo foo.o". Thông báo này có thể chứa các mẫu %{label}, %{input} hoặc %{output} (được thay thế bằng chuỗi nhãn, giá trị nhập vào đầu tiên hoặc đường dẫn của đầu ra) tương ứng. Ưu tiên sử dụng mẫu thay vì chuỗi tĩnh, vì chuỗi trước hiệu quả hơn.
use_default_shell_env default = False
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; default = None
Đặt từ điển của các biến môi trường.
execution_requirements dict; or None; default = None
Thông tin để lên lịch cho hành động. Xem thẻ để biết các khóa hữu ích.
input_manifests sequence; or None; default = None
(Thử nghiệm) đặt siêu dữ liệu runfiles đầu vào; các tệp này thường được tạo bằng resolution_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 trước. 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; default = None
Chạy thao tác bằng cách sử dụng dữ liệu đầu vào của hành động bị ẩn và môi trường đã thêm vào danh sách đầu vào và môi trường của thao tác. Môi trường hành động có thể ghi đè bất kỳ biến môi trường nào của hành động được tô bóng. Nếu không có, chỉ sử dụng dữ liệu đầu vào của hành động và môi trường cho trước.
resource_set callable; or None; mặc định = Không có
Hàm gọi lại (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 thao tác này được thực thi 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 thao tác. Từ điển được trả về có thể chứa các mục nhập sau, mỗi mục có thể là một số thực hoặc một số nguyên:

  • "cpu": số lượng CPU; mặc định 1
  • "memory": tính bằng MB; mặc định là 250
  • "local_test": số lần thử nghiệm 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 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 phép sử dụng hàm lambda và hàm lồng nhau).

toolchain Label; or string; or None; mặc định = không liên kết

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

Hiện tại, phương thức này không hoạt động. Tuy nhiên, bạn nên đặt phương thức này khi sử dụng chuỗi công cụ, vì thông tin này sẽ cần thiết 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 phải xác định chuỗi công cụ này bên trong hàm 'rule()'.

Khi cả hai thông số `chainchain` và `exec_group` đều được thiết lập, `exec_group` sẽ được sử dụng. Lỗi sẽ xảy ra trong trường hợp `exec_group` không chỉ định giống nhau.

vỏ_chạy

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=unbound)

Tạo một hành động chạy một 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 các tệp đầu ra của hành động.
inputs sequence of Files; or depset; default = []
Liệt kê hoặc depset các tệp đầu vào của thao tác đó.
tools sequence of Files; or depset; default = unbound
Liệt kê hoặc gỡ bỏ bất kỳ công cụ nào 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 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; default = []
Các đối số dòng lệnh của hành động. Phải là 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 làm đố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 hàm thay thế biến shell, chẳng hạn như $1, $2, v.v. Lưu ý rằng vì các đối tượng Args sẽ được làm phẳng trước khi lập chỉ mục, nên nếu có một đối tượng Args không xác định kích thước thì tất cả các chuỗi tiếp theo sẽ ở 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à danh sách các chuỗi, thì tham số này có thể không được sử dụng.

mnemonic string; or None; default = None
Thông tin mô tả một 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 chuỗi (không dùng nữa).

Nếu command là một chuỗi, thì sh -c <command> "" <arguments> được thực thi như thể 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ử đó sẽ được nối tiếp với một dòng lệnh để $i có thể tham chiếu đến từng chuỗi 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 vào như một phần của arguments, thì các chuỗi sẽ nằm ở chỉ mục không xác định; trong trường hợp này, hàm thay thế shell $@ (truy xuất tất cả đối số) có thể hữu ích.

(Ngưng sử dụng) Nếu command là một chuỗi chuỗi, thì mục đầu tiên sẽ là tệp thực thi để chạy và các mục còn lại là đối số. Nếu sử dụng biểu mẫu này, bạn không được cung cấp thông 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ị xóa. Tệp này bị vô hiệu hóa với `--incompatible_run_shell_command_string`. Hãy 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 giống như đối với genrules.

progress_message string; or None; default = None
Thông báo tiến trình để hiển thị cho người dùng trong quá trình xây dựng, ví dụ: "Biên dịch foo.cc để tạo foo.o". Thông báo này có thể chứa các mẫu %{label}, %{input} hoặc %{output} (được thay thế bằng chuỗi nhãn, giá trị nhập vào đầu tiên hoặc đường dẫn của đầu ra) tương ứng. Ưu tiên sử dụng mẫu thay vì chuỗi tĩnh, vì chuỗi trước hiệu quả hơn.
use_default_shell_env default = False
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; default = None
Đặt từ điển của các biến môi trường.
execution_requirements dict; or None; default = None
Thông tin để lên lịch cho hành động. Xem thẻ để biết các khóa hữu ích.
input_manifests sequence; or None; default = None
(Thử nghiệm) đặt siêu dữ liệu runfiles đầu vào; các tệp này thường được tạo bằng resolution_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 trước. 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; default = None
Chạy thao tác này bằng cách sử dụng dữ liệu đầu vào đã phát hiện của thao tác ẩn nhất định đã thêm vào danh sách dữ liệu đầu vào của thao tác. 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; default = None
Một hàm callback dùng để ướ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 liên kết

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

Hiện tại, phương thức này không hoạt động. Tuy nhiên, bạn nên đặt phương thức này khi sử dụng chuỗi công cụ, vì thông tin này sẽ cần thiết 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 phải xác định chuỗi công cụ này bên trong hàm 'rule()'.

Khi cả hai thông số `chainchain` và `exec_group` đều được thiết lập, `exec_group` sẽ được sử dụng. Một lỗi sẽ xảy ra trong trường hợp `nhóm exec_group` không chỉ định cùng 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 hành động 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 với đúng một trong 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() rồi khớp với loại target_file. Điều này làm cho điểm liên kết tượng trưng trỏ đến target_file. Bazel sẽ làm mất hiệu lực đầu ra của hành động 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 của đường liên kết này thay đổi.

Ngược lại, 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 chỉ đế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ỉ 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 biệt, công cụ này có thể dùng để tạo đường liên kết tượng trư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; default = None
Tệp mà đường liên kết tượng trưng đầu ra sẽ trỏ đến.
target_path string; or None; default = None
Đường dẫn chính xác mà đường liên kết đầu ra đó sẽ trỏ đến. Không có chuẩn hóa hoặc xử lý nào khác được áp dụng.
is_executable default = False
Chỉ được dùng với target_file chứ không dùng 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 hành động đó có thể thực thi và sẽ có thông 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 sẽ không thể thực thi, chỉ là không có quá trình xác minh hoàn tất.

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

mẫu_tính năng

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. Xin đừng cho phép. 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 thao tác ghi tệp. Khi thực thi, thao tác sẽ ghi nội dung đã cho vào tệp. Thuộc tính 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.

Các tham số

Thông số Nội dung mô tả
output required
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 một đối tượng actions.args().
is_executable default = False
Liệu tệp đầu ra có thể thực thi hay không.