thao tác

Báo cáo vấn đề Xem nguồn Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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 cách sử dụng ctx.actions.

Hội viên

args

Args actions.args()

Trả về một đối tượng Args có thể dùng để tạo 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 sẽ 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 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 mở rộng của một declare_directory.

Thông số

Thông số Mô tả
filename string; required
Nếu không có "sibling" nào, thì đây là đườ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, đây là tên cơ sở của một tệp ("sibling" xác định một thư mục).
sibling File; hoặc None; mặc định là None
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 ra một 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 một tệp, bạn phải tạo riêng một thao tác phát tệp đó. Để tạo hành động đó, bạn sẽ cần truyền đối tượng File được trả về vào hàm tạo của hành động.

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 string; required
Nếu không có "sibling", đường dẫn của tệp mới, tương ứng với gói hiện tại. Nếu không, đây là tên cơ sở cho một tệp ("sibling" xác định một thư mục).
sibling File; hoặc None; mặc định là None
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)

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 symlink này. Bazel sẽ không bao giờ huỷ tham chiếu symlink này và sẽ chuyển nguyên trạng symlink này đến các hộp cát hoặc trình thực thi từ xa. Hiện không hỗ trợ các đường liên kết tượng trưng bên trong các cấu phần phần mềm dạng cây.

Thông số

Thông số Mô tả
filename string; required
Nếu không có "sibling" nào được cung cấp, thì đường dẫn của symlink mới, tương ứng với gói hiện tại. Nếu không, đây là tên cơ sở của một tệp ("sibling" xác định một thư mục).
sibling File; hoặc None; mặc định là None
Một tệp nằm trong cùng thư mục với symlink 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 bất kỳ đầu ra nào, nhưng hữu ích cho việc chèn "các thao tác bổ sung".

Thông số

Thông số Mô tả
mnemonic string; required
Nội dung mô tả một từ về hành động, ví dụ: CppCompile hoặc GoLink.
inputs sequence của File; hoặc depset; mặc định là []
Danh sách các 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 một thao tác 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ự mà các nội dung thay thế được chỉ định. 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 kết. Không có cú pháp đặc biệt cho các khoá. Ví dụ: bạn có thể 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 Tệp; bắt buộc
Tệp mẫu, là một tệp văn bản được mã hoá UTF-8.
output Tệp; bắt buộc
Tệp đầu ra là tệp văn bản được mã hoá UTF-8.
substitutions dict; default is {}
Substitutions to make when expanding the template.
is_executable bool; default is False
Whether the output file should be executable.
computed_substitutions TemplateDict; mặc định là unbound
Các mục 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 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 của Files; bắt buộc
Danh sách các tệp đầu ra của thao tác.
inputs sequence của File; hoặc depset; mặc định là []
Danh sách hoặc depset của các tệp đầu vào của hành động.
unused_inputs_list File; hoặc None; mặc định là None
Tệp chứa danh sách các đầ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 đầu ra của thao tác) tương ứng với danh sách các tệp đầu vào không được dùng trong toàn bộ quá trình thực thi thao tác. Mọi thay đổi trong các tệp đó đều không được ảnh hưởng đến đầu ra của thao tác.

executable File; hoặc string; hoặc FilesToRunProvider; required
Tệp thực thi mà thao tác sẽ gọi.
tools sequence; hoặc depset; mặc định là unbound
Danh sách hoặc depset của mọi công cụ cần thiết cho hành động. Công cụ là các đầu vào có thể thực thi và có thể có các tệp chạy riêng, được tự động cung cấp 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:

  • File giây
  • FilesToRunProvider trường hợp
  • depset giây của File giây
File từ ctx.executable và FilesToRunProvider trực tiếp trong danh sách sẽ tự động được thêm runfile. Tất cả các công cụ đều được thêm ngầm dưới dạng dữ liệu đầu vào.

arguments sequence; mặc định là []
Đố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; hoặc None; mặc định là None
Nội dung mô tả một từ về hành động, ví dụ: CppCompile hoặc GoLink.
progress_message string; hoặc None; mặc định là None
Thông báo tiến trình hiển thị cho người dùng trong quá trình tạo, ví dụ: "Đang 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}, lần lượt được thay thế bằng chuỗi nhãn, đầu vào đầu tiên hoặc đường dẫn của đầu ra. Nên sử dụng các mẫu thay vì chuỗi tĩnh, vì các mẫu hiệu quả hơn.
use_default_shell_env bool; mặc định là False
Liệu thao tác có nên sử dụng môi trường shell mặc định hay không. Môi trường này bao gồm một số biến phụ thuộc vào hệ điều hành cũng như các biến được thiết lập thông qua --action_env.

Nếu cả use_default_shell_env và env đều được đặt thành True, thì các giá trị được đặt trong env sẽ ghi đè môi trường shell mặc định.

env dict; hoặc None; mặc định là None
Đặt từ điển của các biến môi trường.

Nếu cả use_default_shell_env và env đều được đặt thành True, thì các giá trị được đặt trong env sẽ ghi đè môi trường shell mặc định.

execution_requirements dict; hoặc None; mặc định là None
Thông tin về việc lên lịch cho hành động. Hãy xem các thẻ để biết các khoá hữu ích.
input_manifests sequence; hoặc None; mặc định là None
Đối số cũ. Bỏ qua.
exec_group string; hoặc None; mặc định là None
Chạy thao tác trên nền tảng thực thi của nhóm exec đã 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; theo mặc định là None
Chạy thao tác bằng cách sử dụng các đầu vào và môi trường của thao tác được che khuất đã cho được 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 đè mọi biến môi trường của hành động được che. Nếu không có, chỉ sử dụng các đầu vào của thao tác và môi trường đã cho.
resource_set có thể gọi; hoặc None; mặc định là None
Một hàm callback trả về từ điển tập hợp tài nguyên, được dùng để ước tính mức sử dụng tài nguyên tại thời gian thực thi nếu thao tác 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 biểu thị tên hệ điều hành (ví dụ: "osx") và một số nguyên biểu thị 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 đây, mỗi mục có thể là một số thực hoặc 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 kiểm thử cục bộ; mặc định là 1

Nếu bạn đặt tham số này thành None , thì các giá trị mặc định sẽ được dùng.

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

toolchain Nhãn; hoặc chuỗi; hoặc None; mặc định là unbound

Loại chuỗi công cụ của tệp thực thi hoặc các công cụ được dùng trong thao tác này.

Nếu tệp thực thi và công cụ không đến từ một chuỗi công cụ, hãy đặt tham số này thành "None".

Nếu tệp thực thi và công cụ đến từ một chuỗi công cụ, thì bạn phải đặt loại chuỗi công cụ để thao tác thực thi trên nền tảng thực thi chính xác.

Xin lưu ý rằng quy tắc tạo thao tác này cần xác định chuỗi công cụ này trong hàm "rule()".

Khi cả hai tham số "toolchain" và "exec_group" đều được đặt, "exec_group" sẽ được 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ụ.

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

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

Thông số

Thông số Mô tả
outputs sequence của Files; bắt buộc
Danh sách các tệp đầu ra của thao tác.
inputs sequence của File; hoặc depset; mặc định là []
Danh sách hoặc depset của các tệp đầu vào của hành động.
tools sequence của File; hoặc depset; mặc định là unbound
List hoặc depset của mọi công cụ mà thao tác cần. Công cụ là các đầu vào có thể thực thi và có thể có các tệp chạy riêng, được tự động cung cấp 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:

  • File giây
  • FilesToRunProvider trường hợp
  • depset giây của File giây
File từ ctx.executable và FilesToRunProvider trực tiếp trong danh sách sẽ tự động được thêm runfile. Tất cả các công cụ đều được thêm ngầm dưới dạng dữ liệu đầu vào.

arguments sequence; mặc định là []
Đố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().

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 có thể truy cập vào các đối số này bằng cách sử dụng các phép 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 dự đoán được. Bạn nên sử dụng $@ (để truy xuất tất cả cá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, bạn không thể sử dụng tham số này.

mnemonic string; hoặc None; mặc định là None
Nội dung mô tả một từ về hành động, ví dụ: CppCompile hoặc GoLink.
command string; hoặc sequence của strings; required
Lệnh shell cần thực thi. Đây có thể là một chuỗi (nên dùng) hoặc một chuỗi các chuỗi (không dùng nữa).

Nếu command là một chuỗi, thì chuỗi đó 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 tệp hàng loạt 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 đó sẽ được thêm từng đối tượng một vào dòng lệnh, vì vậy $i có thể tham chiếu đến các chuỗi riêng lẻ trong một đối tượng Args. Xin 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ẽ ở các chỉ mục không xác định; trong trường hợp này, việc thay thế bằng trình bao $@ (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 các 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 tệp đó. 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á. Cờ này bị vô hiệu hoá bằng `--incompatible_run_shell_command_string`. Hãy dùng cờ này để xác minh rằng mã của bạn có tương thích hay không.

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

progress_message string; hoặc None; mặc định là None
Thông báo tiến trình hiển thị cho người dùng trong quá trình tạo, ví dụ: "Đang 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}, lần lượt được thay thế bằng chuỗi nhãn, đầu vào đầu tiên hoặc đường dẫn của đầu ra. Nên sử dụng các mẫu thay vì chuỗi tĩnh, vì các mẫu hiệu quả hơn.
use_default_shell_env bool; mặc định là False
Liệu thao tác có nên sử dụng môi trường shell mặc định hay không. Môi trường này bao gồm một số biến phụ thuộc vào hệ điều hành cũng như các biến được thiết lập thông qua --action_env.

Nếu cả use_default_shell_env và env đều được đặt thành True, thì các giá trị được đặt trong env sẽ ghi đè môi trường shell mặc định.

env dict; hoặc None; mặc định là None
Đặt từ điển của các biến môi trường.

Nếu cả use_default_shell_env và env đều được đặt thành True, thì các giá trị được đặt trong env sẽ ghi đè môi trường shell mặc định.

execution_requirements dict; hoặc None; mặc định là None
Thông tin về việc lên lịch cho hành động. Hãy xem các thẻ để biết các khoá hữu ích.
input_manifests sequence; hoặc None; mặc định là None
Đối số cũ. Bỏ qua.
exec_group string; hoặc None; mặc định là None
Chạy thao tác trên nền tảng thực thi của nhóm exec đã 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 Thao tác; mặc định là None
Chạy thao tác bằng cách sử dụng các đầu vào đã phát hiện của thao tác được che khuất đã cho, được thêm vào danh sách đầu vào của thao tác. Nếu không có, chỉ sử dụng các đầu vào của thao tác.
resource_set có thể gọi; hoặc None; mặc định là None
Một hàm callback để ước tính mức sử dụng tài nguyên nếu chạy cục bộ. Xem ctx.actions.run().
toolchain Nhãn; hoặc chuỗi; hoặc None; mặc định là unbound

Loại chuỗi công cụ của tệp thực thi hoặc các công cụ được dùng trong thao tác này.

Nếu tệp thực thi và công cụ không đến từ một chuỗi công cụ, hãy đặt tham số này thành "None".

Nếu tệp thực thi và công cụ đến từ một chuỗi công cụ, thì bạn phải đặt loại chuỗi công cụ để thao tác thực thi trên nền tảng thực thi chính xác.

Xin lưu ý rằng quy tắc tạo thao tác này cần xác định chuỗi công cụ này trong hàm "rule()".

Khi cả hai tham số "toolchain" và "exec_group" đều được đặt, "exec_group" sẽ được 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 ghi đườ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 khi chỉ định chính xác một trong hai thuộc tính target_file hoặc target_path.

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 sẽ vô hiệu hoá đầu ra của hành động này bất cứ khi nào đích của đường liên kết tượng trưng hoặc nội dung của đích 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, symlink sẽ trỏ đến target_path. Bazel không bao giờ phân giải đường liên kết tượng trưng và đầu ra 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ụ thể, bạn có thể dùng phương thức này để tạo một symlink không hợp lệ.

Thông số

Thông số Mô tả
output Tệp; bắt buộc
Đầu ra của thao tác này.
target_file File; hoặc None; mặc định là None
Tệp mà symlink đầu ra sẽ trỏ đến.
target_path string; hoặc None; mặc định là None
Đường dẫn chính xác mà symlink đầu ra sẽ trỏ đến. Không có quá trình chuẩn hoá hoặc xử lý nào khác được áp dụng.
is_executable bool; mặc định là False
Chỉ có thể dùng với target_file, không dùng với target_path. Nếu đúng, khi thao tác được thực thi, đườ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 và một lỗi sẽ được báo cáo nếu đường dẫn đó không thực thi được. Việc đặt is_executable thành False không có nghĩa là mục tiêu không thể thực thi, mà chỉ là không có quy trình xác minh nào được thực hiện.

Tính năng này không có ý nghĩa đối với target_path vì các symlink treo có thể không tồn tại tại thời điểm tạo.
progress_message string; hoặc None; mặc định là None
Thông báo tiến trình mà người dùng nhìn thấy trong quá trình tạo.

template_dict

TemplateDict actions.template_dict()

Trả về một đối tượng TemplateDict để mở rộng mẫu tiết kiệm bộ nhớ.

viết

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

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. Thao tá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 Tệp; bắt buộc
Tệp đầu ra.
content string; hoặc Args; required
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 bool; default is False
Whether the output file should be executable.
mnemonic string; hoặc None; mặc định là None
Nội dung mô tả một từ về hành động, ví dụ: CppCompile hoặc GoLink.