thao tác

Báo cáo vấn đề Xem nguồn Nightly · 7.4 .

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 để tạo 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 khung hình sẽ tạo thư mục có tên cho trước 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(). 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 manifest_directory.

Thông số

Thông số Mô tả
filename string; bắt buộc
Nếu không có "con" (đồ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ở cho một tệp ('anh em' 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 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 thì tệp sẽ ở 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 đó. Để tạo hành động đó, bạn cần truyền đối tượng File được trả về đến hàm khởi 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; bắt buộc
Nếu không có "con đồ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ở cho tệp ("child") sẽ xác định thư mục.
sibling Tệp; hoặc None; giá trị mặc định là 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)

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 đườ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. Hiện tại, hệ thống không hỗ trợ đường liên kết ký hiệu bên trong cấu phần phần mềm cây.

Thông số

Thông số Mô tả
filename string; bắt buộc
Nếu không có "con đồng cấp" nào được cung cấp, đườ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ở cho một tệp ('anh em' xác định một thư mục).
sibling Tệp; hoặc None; mặc định là 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 khai báo.

do_nothing

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

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

Thông số

Thông số Mô tả
mnemonic string; bắt buộc
Nội dung mô tả một từ về hành động, ví dụ: CppCompile hoặc GoLink.
inputs trình tự của Tệp; hoặc phần phụ thuộc; mặc định là []
Danh sách các tệp đầu vào của thao tác.

expand_template

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

Tạo một 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ự đượ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 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 nào cho các 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 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à một tệp văn bản được mã hoá UTF-8.
substitutions dict; giá trị mặc định là {}
. Các giá trị thay thế cần thực hiện khi mở rộng mẫu.
is_executable bool; giá trị mặc định là False
. Liệu tệp đầu ra có thể thực thi được hay không.
computed_substitutions TemplateDict; giá trị mặc định là unbound
Các giá trị 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 trình tự của Tệp; bắt buộc
Danh sách tệp đầu ra của thao tác.
inputs trình tự của Tệp; hoặc nhóm phần phụ thuộc; mặc định là []
Danh sách hoặc nhóm phần phụ thuộc của các tệp đầu vào của thao tác.
unused_inputs_list File; hoặc None; mặc định là None
Tệp chứa danh sách dữ liệu đầu vào mà hành động không dùng đến.

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 sử 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 kết quả của hành động.

executable File; hoặc string; hoặc FilesToRunProvider; bắt buộc
Tệp thực thi được gọi bằng thao tác.
tools sequence; hoặc depset; mặc định là unbound
Danh sách hoặc phần tách của 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 tự động cung cấp cho thao tác. Khi một danh sách được cung cấp, đó có thể là một tập hợp các tệp không đồng nhất, các phiên bản FilesToRunProvider hoặc phần phụ thuộc của các tệp. Các tệp nằm trực tiếp trong danh sách và đến từ ctx.executable sẽ tự động được thêm vào tệp chạy. Khi được cung cấp, depset chỉ được chứa Tệp. Trong cả hai trường hợp, các tệp trong depset không được tham chiếu chéo với ctx.executable cho runfiles.
arguments trình tự; giá trị mặc định là []
đố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; 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ị với người dùng trong quá trình tạo, 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 bool; mặc định là False
Liệu hành động có nên sử dụng môi trường shell mặc định (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 đặt thông qua --action_env) hay khô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 nếu --incompatible_merge_fixed_and_default_shell_env được bật (mặc định). Nếu cờ này không được bật, env sẽ bị bỏ qua.

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 nếu --incompatible_merge_fixed_and_default_shell_env được bật (mặc định). Nếu bạn không bật cờ này, env sẽ bị bỏ qua.

execution_requirements dict; hoặc None; mặc định là None
Thông tin để lên lịch hành động. Xem thẻ để biết các khoá hữu ích.
input_manifests trình tự; hoặc None; giá trị mặc định là None
đối số cũ. Bỏ qua.
exec_group chuỗi; hoặc None; mặc định là 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 Thao tác; giá trị mặc định là None
Chạy thao tác bằng cách sử dụng môi trường và dữ liệu đầu vào của thao tác được che được thêm vào danh sách dữ liệu đầ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 che khuất. 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.
resource_set callable; hoặc None; mặc định là None
Hàm gọi lại trả về một từ điển tập hợp 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à một số thực hoặc một số nguyên:

  • "cpu": số 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 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 ở cấp cao nhất (không được phép sử dụng hàm lambda và hàm lồng nhau).

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

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.

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ụ để hành động 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 hành động này cần xác định chuỗi công cụ này bên trong hàm "rule()".

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ụ.

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 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 trình tự của Tệp; bắt buộc
Danh sách tệp đầu ra của thao tác.
inputs trình tự của Tệp; hoặc nhóm phần phụ thuộc; mặc định là []
Danh sách hoặc nhóm phần phụ thuộc của các tệp đầu vào của thao tác.
tools trình tự của Tệp; hoặc nhóm phần phụ thuộc; mặc định là unbound
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 trình tự; giá trị mặc định là []
đố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ế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ố) kết hợp 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, bạn có thể không 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 chuỗi; hoặc trình tự của chuỗi; 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 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ể do sh -c <command> "" <arguments> thực thi – 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, thì nội dung của các đối tượng đó sẽ được thêm lần lượt vào dòng lệnh, vì vậy $i có thể tham chiếu đến từng chuỗi trong đố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ế 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 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 thực thi đó. 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ị tắt bằng `--incompatible_run_shell_command_string`. Hãy sử dụng cờ này để xác minh mã của bạn có tương thích hay không.

Bazel sử dụng cùng một shell để 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 xây 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, đường dẫn đầu vào 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 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 đặt 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 nếu --incompatible_merge_fixed_and_default_shell_env được bật (mặc định). Nếu bạn không bật cờ này, env sẽ bị bỏ qua.

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 nếu --incompatible_merge_fixed_and_default_shell_env được bật (mặc định). Nếu cờ này không được bật, env sẽ bị bỏ qua.

execution_requirements dict; hoặc None; mặc định là None
Thông tin để lên lịch hành động. Xem thẻ để biết các khoá hữu ích.
input_manifests trình tự; hoặc None; giá trị mặc định là None
đối số cũ. Bỏ qua.
exec_group chuỗi; hoặc None; mặc định là 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 Thao tác; mặc định là None
Chạy thao tác bằng cách sử dụng các dữ liệu đầu vào đã phát hiện của thao tác bị đổ bóng đã thêm vào danh sách đầu vào của thao tác. Nếu không có, chỉ sử dụng dữ liệu đầu vào của hành động.
resource_set có thể gọi; hoặc None; mặc định là 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 Nhãn; hoặc chuỗi; hoặc None; giá trị mặc định là unbound

Loại chuỗi công cụ của tệp thực thi hoặc công cụ được dùng trong hành động 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ụ để hành động 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 hành động này cần xác định chuỗi công cụ này bên trong hàm "rule()".

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

Hàm này phải được gọi bằng chính xác một trong số 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 sẽ khiến đường liên kết tượng trưng trỏ đến target_file. Bazel sẽ vô hiệu hoá kết quả 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 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 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 biệt, 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ủng lẳng.

Thông số

Thông số Mô tả
output Tệp; bắt buộc
Kết quả của thao tác này.
target_file Tệp; hoặc None; mặc định là None
Tệp mà đường liên kết tượng trưng đầu ra sẽ trỏ đến.
target_path string; hoặc None; mặc định là None
Đường dẫn chính xác mà đường liên kết tượng trưng đầu ra sẽ trỏ đến. Không áp dụng quy trình chuẩn hoá hoặc xử lý nào khác.
is_executable bool; mặc định là 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ể thực thi mà chỉ là không có quá trình 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; 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 bản dựng.

template_dict

TemplateDict actions.template_dict()

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

write

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 Tệp; bắt buộc
Tệp đầu ra.
content string; hoặc 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 bool; giá trị mặc định là False
. Liệu tệp đầu ra có thể thực thi được hay không.