tindakan

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6
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 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. Isi direktori tidak dapat diakses langsung dari Starlark, tetapi dapat diperluas dalam perintah tindakan dengan Args.add_all(). Hanya file dan direktori biasa yang dapat berada dalam konten yang diperluas dari declare_directory.

Parameter

Parameter Deskripsi
filename string; wajib diisi
Jika tidak ada 'sibling' yang diberikan, jalur direktori 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 direktori yang baru dideklarasikan. File harus ada 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 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 memancarkan file secara terpisah. Membuat tindakan tersebut akan memerlukan penerusan objek File yang ditampilkan ke fungsi pembuatan tindakan.

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

Parameter

Parameter Deskripsi
filename string; required
Jika tidak ada 'sibling' yang diberikan, jalur file 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 file yang baru dibuat. File harus ada 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 melakukan dereferensi pada link simbolis ini dan akan mentransfernya kata demi kata ke sandbox atau eksekutor jarak jauh. Link simbolik di dalam artefak hierarki saat ini tidak didukung.

Parameter

Parameter Deskripsi
filename string; wajib diisi
Jika tidak ada 'sibling' yang diberikan, jalur symlink baru, relatif terhadap paket saat ini. Jika tidak, nama dasar untuk file ('sibling' menentukan direktori).
sibling File; atau None; defaultnya adalah None
File yang berada di direktori yang sama dengan link simbolis yang baru dideklarasikan.

do_nothing

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

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

Parameter

Parameter Deskripsi
mnemonic string; wajib
Deskripsi tindakan satu kata, misalnya, CppCompile atau GoLink.
inputs sequence dari 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 dijalankan, tindakan ini akan membuat file berdasarkan template. Bagian template akan diganti menggunakan kamus substitutions, sesuai urutan penggantian yang ditentukan. Setiap kali kunci kamus muncul dalam template (atau hasil substitusi sebelumnya), kunci tersebut akan diganti dengan nilai terkait. Tidak ada sintaks khusus untuk kunci. Misalnya, Anda dapat menggunakan tanda kurung kurawal untuk menghindari konflik (misalnya, {KEY}). Lihat contoh penggunaan.

Parameter

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

map_directory

None actions.map_directory(*, input_directories, additional_inputs={}, output_directories, tools, additional_params={}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation)

Membuat beberapa tindakan berdasarkan file dalam satu atau beberapa direktori input, untuk menghasilkan satu atau beberapa direktori output.

Parameter

Parameter Deskripsi
input_directories dict dari File; required
Pemetaan kamus string ke direktori input, seperti yang dideklarasikan oleh ctx.actions.declare_directory() (hanya direktori yang diizinkan sebagai nilai di sini). Nilai tersebut menentukan direktori yang ingin kita perluas untuk mengakses file di fungsi penerapan. Kunci (string) berfungsi sebagai ID untuk dengan mudah mereferensikan direktori tertentu dalam fungsi penerapan.
additional_inputs dict; default adalah {}
Kamus pemetaan string ke input tambahan (hanya file, FilesToRunProvider, dan Depset yang diizinkan di sini). Nilai menentukan input tambahan yang ingin kita buat dapat diakses oleh tindakan yang dibuat oleh fungsi implementasi. Kunci (string) berfungsi sebagai ID untuk memudahkan referensi input tertentu dari dalam fungsi penerapan.
output_directories dict dari File; wajib
Pemetaan kamus string ke direktori output, seperti yang dideklarasikan oleh ctx.actions.declare_directory(). Nilai menentukan direktori output yang ingin kita buat oleh tindakan yang dibuat oleh fungsi implementasi. Kunci (string) berfungsi sebagai ID untuk memudahkan pereferensian direktori output tertentu dari dalam fungsi penerapan.
tools dict; required
Pemetaan kamus string ke alat (hanya file, FilesToRunProvider, dan Depset yang diizinkan di sini). Nilai ini menentukan alat yang ingin kita buat dapat diakses oleh tindakan yang dibuat oleh fungsi penerapan. Kunci (string) berfungsi sebagai ID untuk memudahkan referensi alat tertentu dari dalam fungsi penerapan.
additional_params dict; default adalah {}
Pemetaan string ke parameter tambahan (hanya nilai string, boolean, dan bilangan bulat yang diizinkan di sini). Nilai menentukan parameter tambahan yang ingin kita buat dapat diakses oleh fungsi penerapan yang dapat digunakan untuk memengaruhi perilakunya. Kunci (string) berfungsi sebagai ID untuk dengan mudah mereferensikan parameter tertentu dari dalam fungsi penerapan.
execution_requirements dict; atau None; defaultnya adalah None
Informasi untuk menjadwalkan tindakan yang dibuat. Lihat tag untuk kunci yang berguna.
exec_group string; atau None; default adalah None
Jalankan tindakan yang dibuat di platform eksekusi grup exec yang diberikan. Jika tidak ada, gunakan platform eksekusi default target.
toolchain Label; atau string; atau None; defaultnya adalah None

Jenis toolchain dari executable atau alat yang digunakan oleh tindakan yang dibuat.

Jika file yang dapat dieksekusi dan alat tidak berasal dari toolchain, tetapkan parameter ini ke None.

Jika file yang dapat dieksekusi dan alat berasal dari toolchain, jenis toolchain harus ditetapkan agar tindakan yang dibuat dieksekusi di platform eksekusi yang benar.

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

Jika parameter toolchain dan exec_group ditetapkan, exec_group akan digunakan. Error akan muncul jika exec_group tidak menentukan toolchain yang sama.
use_default_shell_env bool; default adalah False
Apakah tindakan yang dibuat 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 disetel ke True, nilai yang ditetapkan di env akan menggantikan lingkungan shell default.

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

Jika use_default_shell_env dan env disetel ke True, nilai yang ditetapkan di env akan menggantikan lingkungan shell default.

mnemonic string; atau None; default adalah None
Deskripsi satu kata dari tindakan yang dibuat, misalnya, CppCompile atau GoLink.
implementation function; required
Fungsi Starlark yang dipanggil setelah direktori input dibuat untuk menghasilkan tindakan yang menghasilkan file ke direktori output yang ditentukan. Fungsi ini meneruskan argumen berikut:
  • template_ctx (posisional): Objek template_ctx yang dapat digunakan untuk membuat tindakan.
  • input_directories (khusus kata kunci): Pemetaan kamus dari kunci string argumen input_directories dari actions.map_directory() ke objek ExpandedDirectory yang sesuai dengan nilai.
  • output_directories (khusus kata kunci): Nilai argumen output_directories dari actions.map_directory(); pemetaan kamus dari string ke direktori output.
  • additional_inputs (khusus kata kunci): Nilai argumen additional_inputs dari actions.map_directory(); pemetaan kamus dari string ke file input.
  • tools (khusus kata kunci): Nilai argumen tools dari actions.map_directory(); pemetaan kamus dari string ke alat.
  • additional_params (khusus kata kunci): Nilai argumen additional_params dari actions.map_directory(); pemetaan kamus dari string ke string, boolean, atau bilangan bulat.
Fungsi ini harus berupa fungsi tingkat teratas, yaitu lambda dan fungsi bertingkat tidak diizinkan.

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 sequence dari File; required
Daftar file output tindakan.
inputs urutan File; atau depset; default adalah []
Daftar atau depset file input tindakan.
unused_inputs_list File; atau None; defaultnya adalah None
File yang berisi daftar input yang tidak digunakan oleh tindakan.

Konten file ini (biasanya salah satu output tindakan) sesuai dengan daftar file input yang tidak digunakan selama keseluruhan 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 yang diperlukan oleh tindakan. Alat adalah input yang dapat dieksekusi yang mungkin memiliki file run sendiri yang otomatis tersedia untuk tindakan.

Jika disediakan daftar, daftar tersebut dapat berupa kumpulan heterogen dari:

  • File dtk
  • FilesToRunProvider instance
  • depset detik File
Files dari ctx.executable dan FilesToRunProviders yang langsung ada dalam daftar akan ditambahkan runfilenya secara otomatis. Semua alat ditambahkan secara implisit sebagai input.

arguments sequence; default adalah []
Argumen command line dari tindakan. Harus berupa daftar string atau objek actions.args().
mnemonic string; atau None; default adalah None
Deskripsi tindakan dalam satu kata, 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 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 bool; 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 disetel ke True, nilai yang ditetapkan di env akan menggantikan lingkungan shell default.

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

Jika use_default_shell_env dan env disetel ke True, nilai yang ditetapkan di env akan menggantikan lingkungan shell default.

execution_requirements dict; atau None; defaultnya adalah None
Informasi untuk menjadwalkan tindakan. Lihat tag untuk kunci yang berguna.
input_manifests sequence; atau None; defaultnya adalah None
Argumen lama. Diabaikan.
exec_group string; atau None; default adalah None
Menjalankan tindakan di platform eksekusi grup exec yang diberikan. Jika tidak ada, gunakan platform eksekusi default target.
shadowed_action Action; default is None
Menjalankan tindakan menggunakan input dan lingkungan tindakan yang dibayangi yang diberikan yang ditambahkan ke daftar input dan lingkungan tindakan. Lingkungan tindakan dapat menggantikan variabel lingkungan tindakan yang dibayangi. Jika tidak ada, hanya menggunakan input tindakan dan lingkungan yang diberikan.
resource_set dapat dipanggil; atau None; default adalah None
Fungsi callback yang menampilkan kamus set resource, yang digunakan untuk memperkirakan penggunaan resource pada waktu eksekusi jika tindakan ini dijalankan secara lokal.

Fungsi ini menerima dua argumen posisi: string yang merepresentasikan nama OS (misalnya, "osx"), dan bilangan bulat yang merepresentasikan 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 disetel ke None , nilai default akan digunakan.

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

toolchain Label; atau string; atau None; defaultnya adalah unbound

Jenis toolchain dari executable atau alat yang digunakan dalam tindakan ini.

Jika file yang dapat dieksekusi dan alat tidak berasal dari toolchain, tetapkan parameter ini ke `None`.

Jika file yang dapat dieksekusi dan alat berasal dari toolchain, jenis toolchain harus ditetapkan agar tindakan dieksekusi di platform eksekusi yang benar.

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

Jika parameter `toolchain` dan `exec_group` ditetapkan, `exec_group` akan digunakan. Error akan muncul jika `exec_group` tidak menentukan toolchain 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 sequence dari File; required
Daftar file output tindakan.
inputs urutan File; atau depset; default adalah []
Daftar atau depset file input tindakan.
tools urutan File; atau depset; defaultnya adalah unbound
Daftar atau depset alat apa pun yang diperlukan oleh tindakan. Alat adalah input yang dapat dieksekusi yang mungkin memiliki file run sendiri yang otomatis tersedia untuk tindakan.

Jika disediakan daftar, daftar tersebut dapat berupa kumpulan heterogen dari:

  • File dtk
  • FilesToRunProvider instance
  • depset detik File
Files dari ctx.executable dan FilesToRunProviders yang langsung ada dalam daftar akan ditambahkan runfilenya secara otomatis. Semua alat ditambahkan secara implisit sebagai input.

arguments sequence; default adalah []
Argumen command line dari 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 pada indeks yang tidak dapat diprediksi. Anda dapat menggunakan $@ (untuk mengambil semua argumen) bersama dengan objek Args berukuran tidak ditentukan.

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

mnemonic string; atau None; default adalah None
Deskripsi tindakan dalam satu kata, misalnya, CppCompile atau GoLink.
command string; atau urutan string; wajib
Perintah shell yang akan dijalankan. Nilai ini dapat berupa string (lebih disukai) atau urutan string (tidak digunakan lagi).

Jika command adalah string, maka string tersebut akan dieksekusi seolah-olah oleh sh -c <command> "" <arguments> -- yaitu, elemen dalam arguments akan tersedia 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 berukuran tidak diketahui diteruskan sebagai bagian dari arguments, string akan berada pada indeks yang tidak diketahui; dalam hal ini, penggantian 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 yang tersisa adalah argumennya. Jika formulir ini digunakan, parameter arguments tidak boleh diberikan. Perhatikan bahwa formulir ini sudah 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 yang dilakukannya untuk genrules.

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 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 bool; 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 disetel ke True, nilai yang ditetapkan di env akan menggantikan lingkungan shell default.

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

Jika use_default_shell_env dan env disetel ke True, nilai yang ditetapkan di env akan menggantikan lingkungan shell default.

execution_requirements dict; atau None; defaultnya adalah None
Informasi untuk menjadwalkan tindakan. Lihat tag untuk kunci yang berguna.
input_manifests sequence; atau None; defaultnya adalah None
Argumen lama. Diabaikan.
exec_group string; atau None; default adalah None
Menjalankan tindakan di platform eksekusi grup exec yang diberikan. Jika tidak ada, gunakan platform eksekusi default target.
shadowed_action Tindakan; default adalah None
Menjalankan tindakan menggunakan input yang ditemukan dari tindakan yang di-shadow yang diberikan dan ditambahkan ke daftar input tindakan. Jika tidak ada, hanya menggunakan input tindakan.
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 executable atau alat yang digunakan dalam tindakan ini.

Jika file yang dapat dieksekusi dan alat tidak berasal dari toolchain, tetapkan parameter ini ke `None`.

Jika file yang dapat dieksekusi dan alat berasal dari toolchain, jenis toolchain harus ditetapkan agar tindakan dieksekusi di platform eksekusi yang benar.

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

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 dalam 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 jenis target_file. Hal ini membuat symlink mengarah ke target_file. Bazel membatalkan validasi output tindakan ini setiap kali target symlink atau isinya berubah.

Jika tidak, saat Anda menggunakan target_path, deklarasikan output dengan declare_symlink()). Dalam hal ini, symlink mengarah ke target_path. Bazel tidak pernah menyelesaikan symlink dan output tindakan ini dibatalkan hanya jika konten teks symlink (yaitu, nilai readlink()) berubah. Khususnya, hal ini dapat digunakan untuk membuat symlink yang tidak tertaut.

Parameter

Parameter Deskripsi
output File; wajib diisi
Output tindakan ini.
target_file File; atau None; default adalah None
File yang akan dituju oleh 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 bool; defaultnya adalah False
Hanya dapat digunakan dengan target_file, bukan target_path. Jika benar, saat tindakan dijalankan, jalur target_file diperiksa untuk mengonfirmasi bahwa jalur tersebut dapat dieksekusi, dan error akan dilaporkan jika tidak. Menyetel is_executable ke False tidak berarti target tidak dapat dieksekusi, hanya saja tidak ada verifikasi yang dilakukan.

Fitur ini tidak masuk akal untuk target_path karena symlink yang tidak terhubung mungkin tidak ada pada waktu build.
progress_message string; atau None; defaultnya 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, *, mnemonic=None)

Membuat tindakan penulisan file. Saat tindakan dijalankan, tindakan akan menulis konten yang diberikan ke file. Hal ini digunakan untuk membuat 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 File; wajib diisi
File output.
content string; atau Args; wajib
isi file. Dapat berupa string atau objek actions.args().
is_executable bool; default adalah False
Apakah file output harus dapat dieksekusi.
mnemonic string; atau None; default adalah None
Deskripsi tindakan dalam satu kata, misalnya, CppCompile atau GoLink.