tindakan

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

Pelanggan

args

Args actions.args()

Menampilkan objek Args yang dapat digunakan untuk membuat 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 menghasilkan direktori. Konten direktori tidak dapat diakses secara langsung dari Starlark, tetapi dapat diperluas dalam perintah tindakan dengan Args.add_all().

Parameter

Parameter Deskripsi
filename diperlukan
Jika tidak ada 'sibling' yang disediakan, jalur direktori baru, relatif terhadap paket saat ini. Jika tidak, nama dasar untuk file ('saudara' mendefinisikan direktori).
sibling File; or None; default = Tidak ada
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 akan 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 juga harus membuat tindakan yang memunculkan file secara terpisah. Untuk membuat tindakan tersebut, Anda harus meneruskan objek File yang ditampilkan ke fungsi konstruksi tindakan.

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

Parameter

Parameter Deskripsi
filename diperlukan
Jika tidak ada 'saudara' yang disediakan, jalur file baru, relatif terhadap paket saat ini. Jika tidak, nama dasar untuk file ('saudara' menentukan direktori).
sibling File; or None; default = Tidak ada
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)

Eksperimental. Parameter ini bersifat eksperimental dan dapat berubah kapan saja. Jangan bergantung padanya. Fitur ini dapat diaktifkan secara eksperimental dengan menetapkan --experimental_allow_unresolved_symlinks

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 membatalkan symlink ini dan akan memindahkannya kata demi kata ke sandbox atau eksekutor jarak jauh.

Parameter

Parameter Deskripsi
filename diperlukan
Jika tidak ada 'sibling' yang disediakan, jalur symlink baru, relatif terhadap paket saat ini. Jika tidak, nama dasar untuk file ('saudara' mendefinisikan direktori).
sibling File; or None; default = 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 tindakan satu kata, misalnya, CppCompile atau GoLink.
inputs sequence of Files; or depset; default = []
Daftar file input tindakan.

expand_template

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

Membuat tindakan perluasan template. Ketika dieksekusi, tindakan akan menghasilkan file berdasarkan template. Bagian-bagian template akan diganti menggunakan kamus substitutions, dengan urutan substitusi yang ditentukan. Setiap kali kunci kamus muncul di template (atau hasil dari substitusi 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 diperlukan
File template, yang merupakan file teks berenkode UTF-8.
output diperlukan
File output, yang merupakan file teks berenkode UTF-8.
substitutions default = {}
Substitusi yang akan dibuat saat memperluas template.
is_executable default = False
Apakah file output harus dapat dieksekusi.
computed_substitutions TemplateDict; default = tidak terikat
Eksperimental. Parameter ini bersifat eksperimental dan dapat berubah kapan saja. Jangan bergantung padanya. Fitur ini dapat diaktifkan secara eksperimental dengan menetapkan --+experimental_lazy_template_expansion
Eksperimental: Substitusi yang dilakukan saat memperluas template.

run

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

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

Parameter

Parameter Deskripsi
outputs sequence of Files; wajib
Daftar file output tindakan.
inputs sequence of Files; or depset; default = []
Daftar atau dependensi file input tindakan.
unused_inputs_list File; or None; default = Tidak ada
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 eksekusi tindakan secara keseluruhan. Perubahan apa pun dalam file tersebut tidak boleh memengaruhi output tindakan dengan cara apa pun.

executable File; or string; or FilesToRunProvider; wajib
File yang dapat dieksekusi yang akan dipanggil oleh tindakan.
tools sequence; or depset; default = tidak terikat
Daftar atau penghentian alat apa pun yang diperlukan oleh tindakan. Alat adalah input dengan runfile tambahan yang otomatis tersedia untuk tindakan. Daftar yang disediakan dapat berupa koleksi File yang heterogen, instance FilesToRunProvider, atau dependensi Files. File yang berada secara langsung dalam daftar dan berasal dari ctx.executable akan ditambahkan runfile-nya secara otomatis. Jika dependensi disediakan, dependensi hanya boleh berisi File. Dalam kedua kasus tersebut, file dalam dependensi tidak direferensikan silang dengan ctx.executable untuk runfile.
arguments sequence; default = []
Argumen command line tindakan. Harus berupa daftar string atau objek actions.args().
mnemonic string; or None; default = Tidak ada
Deskripsi tindakan satu kata, misalnya, CppCompile atau GoLink.
progress_message string; or None; default = None
Pesan progres untuk ditampilkan kepada pengguna selama proses build, misalnya, "Mengompilasi foo.cc untuk membuat foo.o". Pesan dapat berisi pola %{label}, %{input}, atau %{output}, yang masing-masing diganti dengan string label, jalur input pertama, atau jalur output. Memilih untuk menggunakan pola daripada string statis, karena yang pertama lebih efisien.
use_default_shell_env default = False
Apakah tindakan harus menggunakan lingkungan shell bawaan atau tidak.
env dict; or None; default = Tidak ada
Menetapkan kamus variabel lingkungan.
execution_requirements dict; or None; default = Tidak ada
Informasi untuk menjadwalkan tindakan. Lihat tag untuk mengetahui kunci yang berguna.
input_manifests sequence; or None; default = None
(Eksperimental) menetapkan metadata runfile input; biasanya dihasilkan oleh resolve_command.
exec_group string; or None; default = Tidak ada
Menjalankan tindakan pada platform eksekusi grup eksekutif yang ditentukan. Jika tidak ada, platform eksekusi default target akan digunakan.
shadowed_action Action; default = Tidak ada
Menjalankan tindakan menggunakan input dan lingkungan tindakan bayangan tertentu yang ditambahkan ke daftar input dan lingkungan tindakan. Lingkungan tindakan dapat menimpa variabel lingkungan tindakan bayangan. Jika tidak ada, hanya input tindakan dan lingkungan tertentu yang akan digunakan.
resource_set callable; or None; default = Tidak ada
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 untuk 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 disetel ke None atau jika --experimental_action_resource_set bernilai salah, nilai default akan digunakan.

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

toolchain Label; or string; or None; default = Tidak ada

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

Saat ini tidak ada pengoperasian, tetapi sebaiknya setel saat toolchain digunakan, karena toolchain akan diperlukan dalam rilis Bazel mendatang.

Perhatikan bahwa aturan yang membuat tindakan ini perlu menentukan 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 nilai 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=None)

Membuat tindakan yang menjalankan perintah shell. Lihat contoh penggunaan.

Parameter

Parameter Deskripsi
outputs sequence of Files; wajib
Daftar file output tindakan.
inputs sequence of Files; or depset; default = []
Daftar atau dependensi file input tindakan.
tools sequence of Files; or depset; default = tidak terikat
Daftar atau penghentian alat apa pun 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 = []
Argumen command line tindakan. Harus berupa daftar string atau objek actions.args().

Bazel meneruskan elemen dalam atribut ini sebagai argumen ke perintah.Perintah tersebut 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 berukuran tidak pasti.

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

mnemonic string; or None; default = Tidak ada
Deskripsi tindakan satu kata, misalnya, CppCompile atau GoLink.
command string; or sequence of strings; wajib
Perintah shell untuk dijalankan. String ini dapat berupa string (lebih disukai) atau urutan string (tidak digunakan lagi).

Jika command adalah string, kode tersebut akan dieksekusi seolah-olah oleh sh -c <command> "" <arguments> -- yaitu, elemen di arguments tersedia untuk perintah sebagai $1, $2 (atau %1, %2 jika menggunakan batch Windows), dll. Jika arguments berisi objek actions.args() apa pun, kontennya akan ditambahkan satu per satu ke command line, sehingga $i dapat merujuk ke setiap string dalam objek Args. Perlu diketahui 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, penggantian shell $@ (ambil semua argumen) mungkin akan berguna.

(Tidak digunakan lagi) Jika command adalah urutan string, item pertama adalah 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. Fitur ini dinonaktifkan dengan `--incompatible_run_shell_command_string`. Gunakan tanda ini untuk memverifikasi bahwa kode Anda kompatibel.

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

progress_message string; or None; default = None
Pesan progres untuk ditampilkan kepada pengguna selama proses build, misalnya, "Mengompilasi foo.cc untuk membuat foo.o". Pesan dapat berisi pola %{label}, %{input}, atau %{output}, yang masing-masing diganti dengan string label, jalur input pertama, atau jalur output. Memilih untuk menggunakan pola daripada string statis, karena yang pertama lebih efisien.
use_default_shell_env default = False
Apakah tindakan harus menggunakan lingkungan shell bawaan atau tidak.
env dict; or None; default = Tidak ada
Menetapkan kamus variabel lingkungan.
execution_requirements dict; or None; default = Tidak ada
Informasi untuk menjadwalkan tindakan. Lihat tag untuk mengetahui kunci yang berguna.
input_manifests sequence; or None; default = None
(Eksperimental) menetapkan metadata runfile input; biasanya dihasilkan oleh resolve_command.
exec_group string; or None; default = Tidak ada
Menjalankan tindakan pada platform eksekusi grup eksekutif yang ditentukan. Jika tidak ada, platform eksekusi default target akan digunakan.
shadowed_action Action; default = Tidak ada
Menjalankan tindakan menggunakan input yang ditemukan tindakan bayangan tertentu yang ditambahkan ke daftar input tindakan. Jika tidak ada, hanya input tindakan yang akan digunakan.
resource_set callable; or None; default = Tidak ada
Fungsi callback untuk memperkirakan penggunaan resource jika dijalankan secara lokal. Lihatctx.actions.run().
toolchain Label; or string; or None; default = Tidak ada

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

Saat ini tidak ada pengoperasian, tetapi sebaiknya setel saat toolchain digunakan, karena toolchain akan diperlukan dalam rilis Bazel mendatang.

Perhatikan bahwa aturan yang membuat tindakan ini perlu menentukan 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 target_file atau target_path yang ditentukan.

Saat Anda menggunakan target_file, deklarasikan output dengan declare_file() atau declare_directory() dan cocokkan jenis target_file. Tindakan ini membuat symlink mengarah ke target_file. Bazel 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 akan mengarah ke target_path. Bazel tidak pernah me-resolve symlink dan output tindakan ini menjadi tidak valid hanya jika konten teks symlink (yaitu, nilai readlink()) berubah. Secara khusus, hal ini dapat digunakan untuk membuat symlink yang menggantung.

Parameter

Parameter Deskripsi
output diperlukan
Output dari tindakan ini.
target_file File; or None; default = None
File yang akan menjadi tujuan symlink output.
target_path string; or None; default = Tidak ada
(Eksperimental) Jalur persis yang akan dituju oleh symlink output. Tidak ada normalisasi atau pemrosesan lainnya yang diterapkan. Akses ke fitur ini memerlukan setelan --experimental_allow_unresolved_symlinks.
is_executable default = Salah
Hanya dapat digunakan dengan target_file, bukan target_path. Jika true (benar), saat tindakan dijalankan, jalur target_file akan diperiksa untuk mengonfirmasi bahwa tindakan tersebut dapat dijalankan, dan error akan dilaporkan jika tidak. Menyetel is_executable ke Salah (False) bukan berarti target tidak dapat dieksekusi, hanya saja tidak ada verifikasi yang dilakukan.

Fitur ini tidak dapat digunakan untuk target_path karena symlink yang menggantung mungkin tidak ada pada waktu build.
progress_message string; or None; default = Tidak ada
Pesan progres untuk ditampilkan kepada pengguna selama proses build.

template_dict

TemplateDict actions.template_dict()

Eksperimental. API ini bersifat eksperimental dan dapat berubah kapan saja. Jangan bergantung padanya. Fitur ini dapat diaktifkan secara eksperimental dengan menetapkan --+experimental_lazy_template_expansion
Eksperimental: Menampilkan objek TemplateDict untuk perluasan template yang hemat memori.

write

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

Membuat tindakan tulis file. Ketika dieksekusi, tindakan ini akan menulis konten yang diberikan ke file. Ini digunakan untuk menghasilkan {i>file<i} menggunakan informasi yang tersedia pada fase analisis. Jika file berukuran besar dan berisi banyak konten statis, pertimbangkan untuk menggunakan expand_template.

Parameter

Parameter Deskripsi
output diperlukan
File output.
content string; or Args; memerlukan
isi file. Dapat berupa string atau objek actions.args().
is_executable default = False
Apakah file output harus dapat dieksekusi.