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
- declare_directory
- declare_file
- declare_symlink
- do_nothing
- expand_template
- chạy
- run_shell
- symlink
- template_dict
- write
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 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()
. 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 declare_directory.
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
|
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 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 cung cấp "anh em", đường dẫn của tệp mới, tương ứng 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
|
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 phải nằm trong gói hiện tại. |
declare_symlink
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 tượng trưng đó nguyên văn 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
|
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 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 đườ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
|
bắt buộc Nội dung mô tả hành động bằng một từ, ví dụ: CppCompile hoặc GoLink. |
inputs
|
trình tự của Tệp; hoặc depset;
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 một lần thay thế trước đó), khoá đó sẽ được thay thế bằng giá trị liên kết. 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
|
mặc định là {} Nội dung thay thế cần thực hiện khi mở rộng mẫu. |
is_executable
|
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 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 các 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
|
Tệp; hoặc None ;
mặc định là None 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 gây ảnh hưởng đến kết quả của thao tác. |
executable
|
Tệp; hoặc chuỗi; hoặc FilesToRunProvider;
bắt buộc Tệp thực thi mà thao tác sẽ gọi. |
tools
|
trình tự; hoặc nhóm phần phụ thuộc; giá trị 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à hành động 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. 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ần 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 cung cấp phần phụ thuộc, phần phụ thuộc đó 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
|
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ả hành động bằng một từ, 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 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
|
mặc định là False Liệu hành động có nên sử dụng môi trường shell mặc định hay không, 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ả |
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ả |
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
|
sequence; hoặc None ; giá trị mặc định là None (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; 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 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
|
Thao tác; mặc định là None Chạy thao tác bằng cách sử dụng đầu vào và môi trường của thao tác được đổ bóng, đượ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 đè 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 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 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, mỗi mục có thể là float hoặc int:
Nếu tham số này được đặt thành 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
|
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. 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, bạn không cần thiết lập giá trị này, nhưng bạn nên thiết lập giá trị này khi sử dụng chuỗi công cụ vì giá trị này sẽ bắt buộc trong các bản phát hành Bazel trong tương lai. 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 như vậy. |
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 các tệp đầu ra của thao tác. |
inputs
|
trình tự của Tệp; hoặc phần phụ thuộc; mặc định là [] Danh sách hoặc tập hợp 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
|
sequence; 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ư Trong trường hợp |
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 (không dùng nữa). Nếu (Không dùng nữa) Nếu 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
|
mặc định là False Liệu hành động có nên sử dụng môi trường shell mặc định hay không, 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ả |
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ả |
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 khoá hữu ích. |
input_manifests
|
sequence; hoặc None ; giá trị mặc định là None (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
|
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 dữ liệu đầu vào đã khám phá của thao tác được che được 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 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ộ. Hãy xem ctx.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. 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, bạn không cần thiết lập giá trị này, nhưng bạn nên thiết lập giá trị này khi sử dụng chuỗi công cụ vì giá trị này sẽ bắt buộc trong các bản phát hành Bazel trong tương lai. 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ụ. |
liên kết tượng trưng
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 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à 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 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
|
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 chuẩn hoá hoặc xử lý khác được áp dụng. |
is_executable
|
mặc định là False Chỉ có thể sử dụng với target_file , không phải target_path . Nếu đúng thì 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à báo cáo lỗi 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, 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 |
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
|
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
|
mặc định là False Liệu tệp đầu ra có thể thực thi được hay không. |