tindakan

Laporkan masalah Lihat sumber Nightly · 7.4 .

Modul yang menyediakan fungsi untuk membuat tindakan. Akses modul ini menggunakan ctx.actions.

Anggota

args

Args actions.args()

Menampilkan objek Args yang dapat digunakan untuk membangun command line yang hemat memori.

declare_directory

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

Mendeklarasikan bahwa aturan atau aspek membuat direktori dengan nama yang diberikan, dalam paket saat ini. Anda harus membuat tindakan yang membuat direktori. Konten direktori tidak dapat diakses langsung dari Starlark, tetapi dapat diperluas dalam perintah tindakan dengan Args.add_all(). Hanya file dan direktori reguler yang dapat berada dalam konten yang diperluas dari declare_directory.

Parameter

Parameter Deskripsi
filename wajib
Jika tidak ada 'saudara' yang diberikan, jalur direktori baru, yang sesuai dengan paket saat ini. Jika tidak, nama dasar untuk file ('sibling' menentukan direktori).
sibling File; atau None; default adalah None
File yang berada di direktori yang sama dengan direktori yang baru dideklarasikan. File harus berada dalam paket saat ini.

declare_file

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

Mendeklarasikan bahwa aturan atau aspek membuat file dengan nama file yang diberikan. Jika sibling tidak ditentukan, nama file bersifat relatif terhadap direktori paket. Jika tidak, file akan berada di direktori yang sama dengan sibling. File tidak dapat dibuat di luar paket saat ini.

Ingat bahwa selain mendeklarasikan file, Anda harus membuat tindakan yang memunculkan file secara terpisah. Membuat tindakan tersebut akan memerlukan penerusan objek File yang ditampilkan ke fungsi konstruksi tindakan.

Perhatikan bahwa file output yang telah dideklarasikan sebelumnya tidak perlu (dan tidak dapat) dideklarasikan menggunakan fungsi ini. Sebagai gantinya, Anda bisa mendapatkan objek File dari ctx.outputs. Lihat contoh penggunaan.

Parameter

Parameter Deskripsi
filename wajib
Jika 'sibling' tidak diberikan, jalur file baru, yang sesuai dengan paket saat ini. Jika tidak, nama dasar untuk file ('sibling' menentukan direktori).
sibling File; atau None; default adalah None
File yang berada di direktori yang sama dengan file yang baru dibuat. File harus berada dalam paket saat ini. 

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

Mendeklarasikan bahwa aturan atau aspek membuat symlink dengan nama yang diberikan dalam paket saat ini. Anda harus membuat tindakan yang menghasilkan symlink ini. Bazel tidak akan pernah mendereferensikan symlink ini dan akan mentransfernya secara verbatim ke sandbox atau eksekutor jarak jauh. Link simbolis di dalam artefak hierarki saat ini tidak didukung.

Parameter

Parameter Deskripsi
filename required
Jika tidak ada 'sibling' yang disediakan, jalur symlink baru, relatif terhadap paket saat ini. Jika tidak, nama dasar untuk file ('sibling' menentukan direktori).
sibling File; atau None; default adalah None
File yang berada di direktori yang sama dengan symlink yang baru dideklarasikan.

do_nothing

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

Membuat tindakan kosong yang tidak mengeksekusi perintah atau menghasilkan output apa pun, tetapi berguna untuk menyisipkan 'tindakan tambahan'.

Parameter

Parameter Deskripsi
mnemonic wajib
Deskripsi satu kata tentang tindakan, misalnya, CppCompile atau GoLink.
inputs urutan File; atau depset; default adalah []
Daftar file input tindakan.

expand_template

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

Membuat tindakan perluasan template. Saat dieksekusi, tindakan ini akan menghasilkan file berdasarkan template. Bagian-bagian template akan diganti menggunakan kamus substitutions, sesuai urutan substitusi yang ditentukan. Setiap kali kunci kamus muncul dalam template (atau hasil penggantian sebelumnya), kunci tersebut akan diganti dengan nilai yang terkait. Tidak ada sintaksis khusus untuk kunci. Misalnya, Anda dapat menggunakan tanda kurung kurawal untuk menghindari konflik (misalnya, {KEY}). Lihat contoh penggunaan.

Parameter

Parameter Deskripsi
template wajib
File template, yang merupakan file teks berenkode UTF-8.
output wajib
File output, yang merupakan file teks berenkode UTF-8.
substitutions defaultnya adalah {}
Substitusi yang akan dibuat saat meluaskan template.
is_executable default adalah False
Apakah file output harus dapat dieksekusi.
computed_substitutions TemplateDict; default-nya adalah unbound
Penggantian yang akan dilakukan saat memperluas template.

lari

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)

Membuat tindakan yang menjalankan file yang dapat dieksekusi. Lihat contoh penggunaan.

Parameter

Parameter Deskripsi
outputs urutan File; diperlukan
Daftar file output tindakan.
inputs urutan File; atau depset; default adalah []
Daftar atau depset file input tindakan.
unused_inputs_list File; atau None; default-nya adalah None
File yang berisi daftar input yang tidak digunakan oleh tindakan.

Konten file ini (umumnya salah satu output tindakan) sesuai dengan daftar file input yang tidak digunakan selama seluruh eksekusi tindakan. Setiap perubahan pada file tersebut tidak boleh memengaruhi output tindakan dengan cara apa pun.

executable File; atau string; atau FilesToRunProvider; wajib
File yang dapat dieksekusi yang akan dipanggil oleh tindakan.
tools sequence; atau depset; default adalah unbound
Daftar atau depset alat apa pun yang diperlukan oleh tindakan. Alat adalah input dengan runfile tambahan yang otomatis tersedia untuk tindakan. Jika disediakan, daftar dapat berupa kumpulan file, instance FilesToRunProvider, atau depset File yang heterogen. File yang langsung ada dalam daftar dan berasal dari ctx.executable akan otomatis menambahkan runfile. Jika depset diberikan, depset tersebut hanya boleh berisi Files. Dalam kedua kasus tersebut, file dalam depset tidak dirujuk silang dengan ctx.executable untuk runfile.
arguments sequence; default adalah []
Argumen command line tindakan. Harus berupa daftar string atau objek actions.args().
mnemonic string; atau None; default adalah None
Deskripsi satu kata tentang tindakan, misalnya, CppCompile atau GoLink.
progress_message string; atau None; default adalah None
Pesan progres yang akan ditampilkan kepada pengguna selama build, misalnya, "Mengompilasi foo.cc untuk membuat foo.o". Pesan ini dapat berisi pola %{label}, %{input}, atau %{output}, yang diganti dengan string label, input pertama, atau jalur output. Lebih baik gunakan pola, bukan string statis, karena pola lebih efisien.
use_default_shell_env defaultnya adalah False
Apakah tindakan harus menggunakan lingkungan shell default, yang terdiri dari beberapa variabel bergantung OS serta variabel yang ditetapkan melalui --action_env.

Jika use_default_shell_env dan env ditetapkan ke True, nilai yang ditetapkan di env akan menimpa lingkungan shell default jika --incompatible_merge_fixed_and_default_shell_env diaktifkan (default). Jika tanda tidak diaktifkan, env akan diabaikan.

env dict; atau None; default-nya adalah None
Menetapkan kamus variabel lingkungan.

Jika use_default_shell_env dan env ditetapkan ke True, nilai yang ditetapkan di env akan menimpa lingkungan shell default jika --incompatible_merge_fixed_and_default_shell_env diaktifkan (default). Jika flag tidak diaktifkan, env akan diabaikan.

execution_requirements dict; atau None; defaultnya adalah None
Informasi untuk menjadwalkan tindakan. Lihat tag untuk kunci yang berguna.
input_manifests sequence; atau None; default adalah None
(Eksperimental) menetapkan metadata runfile input; biasanya dihasilkan oleh resolve_command.
exec_group string; atau None; default-nya adalah None
Menjalankan tindakan pada platform eksekusi grup exec yang ditentukan. Jika tidak ada, gunakan platform eksekusi default target.
shadowed_action Action; default-nya adalah None
Menjalankan tindakan menggunakan input dan lingkungan tindakan dibayangi yang ditambahkan ke daftar input dan lingkungan tindakan. Lingkungan tindakan dapat menimpa variabel lingkungan tindakan yang dibayangi. Jika tidak ada, hanya gunakan input tindakan dan lingkungan yang diberikan.
resource_set callable; atau None; default adalah None
Fungsi callback yang menampilkan kamus kumpulan resource, yang digunakan untuk memperkirakan penggunaan resource pada waktu eksekusi jika tindakan ini dijalankan secara lokal.

Fungsi ini menerima dua argumen posisi: string yang mewakili nama OS (misalnya "osx"), dan bilangan bulat yang mewakili jumlah input ke tindakan. Kamus yang ditampilkan dapat berisi entri berikut, yang masing-masing dapat berupa float atau int:

  • "cpu": jumlah CPU; default 1
  • "memory": dalam MB; default 250
  • "local_test": jumlah pengujian lokal; default 1

Jika parameter ini ditetapkan ke None atau jika --experimental_action_resource_set bernilai salah (false), nilai default akan digunakan.

Callback harus berupa tingkat atas (lambda dan fungsi bertingkat tidak diizinkan).

toolchain Label; atau string; atau None; default-nya adalah unbound

Jenis toolchain dari file yang dapat dieksekusi atau alat yang digunakan dalam tindakan ini. Parameter ini harus ditetapkan, sehingga tindakan dieksekusi di platform eksekusi yang benar.

Untuk saat ini tidak ada pengoperasian, tetapi sebaiknya setel jika toolchain digunakan, karena akan diperlukan pada rilis Bazel mendatang.

Perhatikan bahwa aturan yang membuat tindakan ini perlu mendefinisikan toolchain ini di dalam fungsi 'rule()'-nya.

Jika parameter `toolchain` dan `exec_group` ditetapkan, `exec_group` akan digunakan. Error akan muncul jika `exec_group` tidak menentukan hal yang sama.

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)

Membuat tindakan yang menjalankan perintah shell. Lihat contoh penggunaan.

Parameter

Parameter Deskripsi
outputs Urutan File; wajib ada
Daftar file output tindakan.
inputs Urutan File; atau depset; defaultnya adalah []
Daftar atau depset file input tindakan.
tools Urutan File; atau depset; defaultnya adalah unbound
Daftar atau depset alat yang diperlukan oleh tindakan. Alat adalah input dengan runfile tambahan yang otomatis tersedia untuk tindakan. Daftar dapat berisi instance Files atau FilesToRunProvider.
arguments sequence; default adalah []
Argumen command line tindakan. Harus berupa daftar string atau objek actions.args().

Bazel meneruskan elemen dalam atribut ini sebagai argumen ke perintah.Perintah dapat mengakses argumen ini menggunakan penggantian variabel shell seperti $1, $2, dll. Perhatikan bahwa karena objek Args diratakan sebelum pengindeksan, jika ada objek Args dengan ukuran yang tidak diketahui, semua string berikutnya akan berada di indeks yang tidak dapat diprediksi. Sebaiknya gunakan $@ (untuk mengambil semua argumen) bersama dengan objek Args yang ukurannya tidak ditentukan.

Jika command adalah daftar string, parameter ini mungkin tidak digunakan.

mnemonic string; atau None; default adalah None
Deskripsi satu kata tentang tindakan, misalnya, CppCompile atau GoLink.
command string; atau urutan string; diperlukan
perintah Shell untuk dieksekusi. Ini dapat berupa string (lebih disukai) atau urutan string (tidak digunakan lagi).

Jika command adalah string, string tersebut akan dieksekusi seolah-olah oleh sh -c <command> "" <arguments> -- yaitu, elemen dalam arguments disediakan untuk perintah sebagai $1, $2 (atau %1, %2 jika menggunakan batch Windows), dll. Jika arguments berisi objek actions.args(), kontennya akan ditambahkan satu per satu ke command line, sehingga $i dapat merujuk ke setiap string dalam objek Args. Perhatikan bahwa jika objek Args dengan ukuran yang tidak diketahui diteruskan sebagai bagian dari arguments, string akan berada pada indeks yang tidak diketahui; dalam hal ini, substitusi shell $@ (mengambil semua argumen) mungkin berguna.

(Tidak digunakan lagi) Jika command adalah urutan string, item pertama adalah file yang dapat dieksekusi untuk dijalankan dan item lainnya adalah argumennya. Jika formulir ini digunakan, parameter arguments tidak boleh diberikan. Perhatikan bahwa formulir ini tidak digunakan lagi dan akan segera dihapus. Flag ini dinonaktifkan dengan `--incompatible_run_shell_command_string`. Gunakan flag ini untuk memverifikasi bahwa kode Anda kompatibel.

Bazel menggunakan shell yang sama untuk menjalankan perintah seperti yang dilakukan untuk genrules.

progress_message string; atau None; default-nya adalah None
Pesan progres yang akan ditampilkan kepada pengguna selama build, misalnya, "Mengompilasi foo.cc to create foo.o". Pesan dapat berisi pola %{label}, %{input}, atau %{output}, yang masing-masing diganti dengan string label, input pertama, atau jalur output. Lebih baik gunakan pola, bukan string statis, karena pola lebih efisien.
use_default_shell_env default adalah False
Apakah tindakan harus menggunakan lingkungan shell default, yang terdiri dari beberapa variabel yang bergantung pada OS serta variabel yang ditetapkan melalui --action_env.

Jika use_default_shell_env dan env ditetapkan ke True, nilai yang ditetapkan di env akan menimpa lingkungan shell default jika --incompatible_merge_fixed_and_default_shell_env diaktifkan (default). Jika flag tidak diaktifkan, env akan diabaikan.

env dict; atau None; defaultnya adalah None
Menetapkan kamus variabel lingkungan.

Jika use_default_shell_env dan env disetel ke True, nilai yang ditetapkan di env akan menimpa lingkungan shell default jika --incompatible_merge_fixed_and_default_shell_env diaktifkan (default). Jika tanda tidak diaktifkan, env akan diabaikan.

execution_requirements dict; atau None; default-nya adalah None
Informasi untuk menjadwalkan tindakan. Lihat tag untuk kunci yang berguna.
input_manifests sequence; atau None; default adalah None
(Eksperimental) menetapkan metadata runfile input; biasanya dihasilkan oleh resolve_command.
exec_group string; atau None; default adalah None
Menjalankan tindakan di platform eksekusi grup eksekusi yang ditentukan. Jika tidak ada, gunakan platform eksekusi default target.
shadowed_action Action; default adalah None
Menjalankan tindakan menggunakan input yang ditemukan dari tindakan yang dibayangi yang ditambahkan ke daftar input tindakan. Jika tidak ada, hanya input tindakan yang akan digunakan.
resource_set callable; atau None; default adalah None
Fungsi callback untuk memperkirakan penggunaan resource jika dijalankan secara lokal. Lihatctx.actions.run().
toolchain Label; atau string; atau None; defaultnya adalah unbound

Jenis toolchain dari file yang dapat dieksekusi atau alat yang digunakan dalam tindakan ini. Parameter ini harus disetel, agar tindakan dapat dieksekusi di platform eksekusi yang benar.

Untuk saat ini tidak ada pengoperasian, tetapi sebaiknya setel jika toolchain digunakan, karena akan diperlukan pada rilis Bazel mendatang.

Perhatikan bahwa aturan yang membuat tindakan ini perlu mendefinisikan toolchain ini di dalam fungsi 'rule()'-nya.

Jika parameter `toolchain` dan `exec_group` ditetapkan, `exec_group` akan digunakan. Error akan muncul jika `exec_group` tidak menentukan toolchain yang sama.

 

None actions.symlink(output, target_file=None, target_path=None, is_executable=False, progress_message=None)

Membuat tindakan yang menulis symlink di sistem file.

Fungsi ini harus dipanggil dengan tepat salah satu dari target_file atau target_path yang ditentukan.

Saat Anda menggunakan target_file, deklarasikan output dengan declare_file() atau declare_directory() dan cocokkan dengan jenis target_file. Tindakan ini akan membuat symlink mengarah ke target_file. Bazel akan membatalkan output tindakan ini setiap kali target symlink atau kontennya berubah.

Jika tidak, saat Anda menggunakan target_path, deklarasikan output dengan declare_symlink()). Dalam hal ini, symlink mengarah ke target_path. Bazel tidak pernah me-resolve symlink dan output tindakan ini hanya menjadi tidak valid jika konten teks symlink (yaitu, nilai readlink()) berubah. Secara khusus, ini dapat digunakan untuk membuat symlink yang tidak tersambung.

Parameter

Parameter Deskripsi
output required
Output dari tindakan ini.
target_file File; atau None; default-nya adalah None
File yang akan dituju symlink output.
target_path string; atau None; defaultnya adalah None
Jalur persis yang akan dituju oleh symlink output. Tidak ada normalisasi atau pemrosesan lain yang diterapkan.
is_executable default-nya adalah False
Hanya dapat digunakan dengan target_file, bukan target_path. Jika benar, saat tindakan dieksekusi, jalur target_file akan diperiksa untuk mengonfirmasi bahwa jalur tersebut dapat dieksekusi, dan error akan dilaporkan jika tidak. Menetapkan is_executable ke Salah (False) bukan berarti target tidak dapat dieksekusi, hanya saja tidak ada verifikasi yang dilakukan.

Fitur ini tidak masuk akal untuk target_path karena symlink yang menggantung mungkin tidak ada pada waktu build.
progress_message string; atau None; default adalah None
Pesan progres yang akan ditampilkan kepada pengguna selama build.

template_dict

TemplateDict actions.template_dict()

Menampilkan objek TemplateDict untuk perluasan template yang hemat memori.

write

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

Membuat tindakan penulisan file. Saat dieksekusi, tindakan ini akan menulis konten yang diberikan ke file. Ini digunakan untuk menghasilkan file menggunakan informasi yang tersedia dalam fase analisis. Jika file berukuran besar dan memiliki banyak konten statis, pertimbangkan untuk menggunakan expand_template.

Parameter

Parameter Deskripsi
output diperlukan
File output.
content string; atau Args; diperlukan
konten file. Dapat berupa string atau objek actions.args().
is_executable defaultnya adalah False
Apakah file output harus dapat dieksekusi.