Args

Per malam · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7
Objek yang merangkum, dengan cara yang hemat memori, data yang diperlukan untuk membuat sebagian atau seluruh command line.

Sering kali, tindakan memerlukan command line besar yang berisi nilai yang dikumpulkan dari dependensi transitif. Misalnya, command line linker dapat mencantumkan setiap file objek yang diperlukan oleh semua pustaka yang ditautkan. Sebaiknya simpan data transitif tersebut di depset, sehingga dapat dibagikan oleh beberapa target. Namun, jika penulis aturan harus mengonversi depsets ini menjadi daftar string untuk membuat command line tindakan, hal ini akan membatalkan pengoptimalan berbagi memori ini.

Oleh karena itu, fungsi pembuatan tindakan menerima objek Args selain string. Setiap objek Args merepresentasikan penggabungan string dan depsets, dengan transformasi opsional untuk memanipulasi data. Objek Args tidak memproses depsets yang dienkapsulasinya hingga fase eksekusi, saat tiba waktunya untuk menghitung command line. Tindakan ini membantu menunda penyalinan yang mahal hingga setelah fase analisis selesai. Lihat halaman Mengoptimalkan Performa untuk mengetahui informasi selengkapnya.

Args dibuat dengan memanggil ctx.actions.args(). Variabel ini dapat diteruskan sebagai parameter arguments dari ctx.actions.run() atau ctx.actions.run_shell(). Setiap mutasi objek Args menambahkan nilai ke command line akhir.

Fitur map_each memungkinkan Anda menyesuaikan cara item diubah menjadi string. Jika Anda tidak menyediakan fungsi map_each, konversi standar adalah sebagai berikut:

  • Nilai yang sudah berupa string akan dibiarkan apa adanya.
  • Objek File diubah menjadi nilai File.path-nya.
  • Objek Label diubah menjadi representasi string yang diselesaikan kembali ke objek yang sama saat diselesaikan dalam konteks repositori utama. Jika memungkinkan, representasi string menggunakan nama repositori yang terlihat, bukan nama kanonis repositori, sehingga representasi ini cocok untuk digunakan dalam file BUILD. Meskipun bentuk representasi yang tepat tidak dijamin, contoh umumnya adalah //foo:bar, @repo//foo:bar, dan @@canonical_name+//foo:bar.bzl.
  • Semua jenis lainnya diubah menjadi string dengan cara yang tidak ditentukan. Karena itu, Anda harus menghindari penerusan nilai yang bukan berjenis string atau File ke add(), dan jika Anda meneruskannya ke add_all() atau add_joined(), Anda harus memberikan fungsi map_each.

Saat menggunakan pemformatan string (parameter format, format_each, dan format_joined dari metode add*()), template format ditafsirkan dengan cara yang sama seperti penggantian % pada string, kecuali template harus memiliki tepat satu placeholder penggantian dan harus berupa %s. Persen literal dapat di-escape sebagai %%. Pemformatan diterapkan setelah nilai dikonversi menjadi string seperti di atas.

Setiap metode add*() memiliki bentuk alternatif yang menerima parameter posisional tambahan, string "nama argumen" untuk disisipkan sebelum argumen lainnya. Untuk add_all dan add_joined, string tambahan tidak akan ditambahkan jika ternyata urutannya kosong. Misalnya, penggunaan yang sama dapat menambahkan --foo val1 val2 val3 --bar atau hanya --bar ke command line, bergantung pada apakah urutan yang diberikan berisi val1..val3 atau kosong.

Jika ukuran command line dapat bertambah lebih panjang dari ukuran maksimum yang diizinkan oleh sistem, argumen dapat dilimpahkan ke file parameter. Lihat use_param_file() dan set_param_file_format().

Contoh: Misalkan kita ingin membuat command line: 

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
Kita dapat menggunakan objek Args berikut: 
# foo_deps and bar_deps are depsets containing
# File objects for the foo and bar .txt files.
args = ctx.actions.args()
args.add_all("--foo", foo_deps)
args.add_joined("--bar", bar_deps, join_with=",")
args.add("--baz")
ctx.actions.run(
  ...
  arguments = [args],
  ...
)

Anggota

tambahkan

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

Menambahkan argumen ke command line ini.

Parameter

Parameter Deskripsi
arg_name_or_value required
Jika dua parameter posisional diteruskan, parameter ini ditafsirkan sebagai nama argumen. Nama argumen ditambahkan sebelum nilai tanpa pemrosesan apa pun. Jika hanya satu parameter posisi yang diteruskan, parameter tersebut ditafsirkan sebagai value (lihat di bawah).
value default adalah unbound
Objek yang akan ditambahkan. Nilai tersebut akan dikonversi menjadi string menggunakan konversi standar yang disebutkan di atas. Karena tidak ada parameter map_each untuk fungsi ini, value harus berupa string atau File. Daftar, tuple, depset, atau direktori File harus diteruskan ke add_all() atau add_joined(), bukan metode ini.
format string; atau None; defaultnya adalah None
Pola string format, yang akan diterapkan ke versi string dari value.

add_all

Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)

Menambahkan beberapa argumen ke command line ini. Item diproses secara lambat selama fase eksekusi.

Sebagian besar pemrosesan terjadi melalui daftar argumen yang akan ditambahkan, seperti langkah-langkah berikut:

  1. Setiap item direktori File diganti dengan semua File yang secara rekursif ada dalam direktori tersebut.
  2. Jika map_each diberikan, map_each akan diterapkan ke setiap item, dan daftar string yang dihasilkan akan digabungkan untuk membentuk daftar argumen awal. Jika tidak, daftar argumen awal adalah hasil penerapan konversi standar ke setiap item.
  3. Setiap argumen dalam daftar diformat dengan format_each, jika ada.
  4. Jika uniquify benar, argumen duplikat akan dihapus. Kemunculan pertama adalah yang tetap ada.
  5. Jika string before_each diberikan, string tersebut akan disisipkan sebagai argumen baru sebelum setiap argumen yang ada dalam daftar. Hal ini secara efektif menggandakan jumlah argumen yang akan ditambahkan pada titik ini.
  6. Kecuali jika daftar kosong dan omit_if_empty adalah benar (default), nama argumen dan terminate_with akan disisipkan sebagai argumen pertama dan terakhir, jika diberikan.
Perhatikan bahwa string kosong adalah argumen valid yang tunduk pada semua langkah pemrosesan ini.

Parameter

Parameter Deskripsi
arg_name_or_values required
Jika dua parameter posisional diteruskan, parameter ini ditafsirkan sebagai nama argumen. Nama argumen ditambahkan sebelum values sebagai argumen terpisah tanpa pemrosesan apa pun. Nama argumen ini tidak akan ditambahkan jika omit_if_empty benar (default) dan tidak ada item lain yang ditambahkan (seperti yang terjadi jika values kosong atau semua itemnya difilter). Jika hanya satu parameter posisi yang diteruskan, parameter tersebut ditafsirkan sebagai values (lihat di bawah).
values sequence; atau depset; default adalah unbound
Daftar, tuple, atau depset yang itemnya akan ditambahkan.
map_each dapat dipanggil; atau None; default adalah None
Fungsi yang mengonversi setiap item menjadi nol atau beberapa string, yang dapat diproses lebih lanjut sebelum ditambahkan. Jika parameter ini tidak diberikan, konversi standar akan digunakan.

Fungsi ini meneruskan satu atau dua argumen posisi: item yang akan dikonversi, diikuti dengan DirectoryExpander opsional. Argumen kedua hanya akan diteruskan jika fungsi yang diberikan ditentukan pengguna (bukan bawaan) dan mendeklarasikan lebih dari satu parameter.

Jenis nilai yang ditampilkan bergantung pada jumlah argumen yang akan dihasilkan untuk item:

  • Dalam kasus umum saat setiap item berubah menjadi satu string, fungsi harus menampilkan string tersebut.
  • Jika item akan difilter sepenuhnya, fungsi harus menampilkan None.
  • Jika item berubah menjadi beberapa string, fungsi akan menampilkan daftar string tersebut.
Menampilkan satu string atau None memiliki efek yang sama dengan menampilkan daftar dengan panjang 1 atau panjang 0. Namun, lebih efisien dan mudah dibaca jika tidak membuat daftar jika tidak diperlukan.

Biasanya, item yang berupa direktori akan otomatis diperluas ke kontennya saat expand_directories=True disetel. Namun, hal ini tidak akan memperluas direktori yang ada di dalam nilai lain -- misalnya, saat item adalah struct yang memiliki direktori sebagai kolom. Dalam situasi ini, argumen DirectoryExpander dapat diterapkan untuk mendapatkan file direktori tertentu secara manual.

Untuk menghindari retensi struktur data fase analisis yang tidak diinginkan ke dalam fase eksekusi, fungsi map_each harus dideklarasikan oleh pernyataan def tingkat teratas; fungsi ini tidak boleh berupa penutupan fungsi bertingkat secara default.

Peringatan: Pernyataan print() yang dieksekusi selama panggilan ke map_each tidak akan menghasilkan output yang terlihat.

format_each string; atau None; default adalah None
Pola string format opsional, diterapkan ke setiap string yang ditampilkan oleh fungsi map_each. String format harus memiliki tepat satu placeholder '%s'.
before_each string; atau None; default adalah None
Argumen opsional yang akan ditambahkan sebelum setiap argumen yang berasal dari values ditambahkan.
omit_if_empty bool; default adalah True
Jika benar (true), jika tidak ada argumen yang berasal dari values untuk ditambahkan, maka semua pemrosesan lebih lanjut akan dihentikan dan command line tidak akan berubah. Jika salah (false), nama argumen dan terminate_with, jika diberikan, akan tetap ditambahkan terlepas dari apakah ada argumen lain atau tidak.
uniquify bool; default adalah False
Jika benar, argumen duplikat yang berasal dari values akan dihilangkan. Hanya kemunculan pertama setiap argumen yang akan tetap ada. Biasanya fitur ini tidak diperlukan karena depsets sudah menghilangkan duplikat, tetapi fitur ini dapat berguna jika map_each memancarkan string yang sama untuk beberapa item.
expand_directories bool; default adalah True
Jika benar, semua direktori di values akan diuraikan menjadi daftar file datar. Hal ini terjadi sebelum map_each diterapkan.
terminate_with string; atau None; default adalah None
Argumen opsional untuk ditambahkan setelah semua argumen lainnya. Argumen ini tidak akan ditambahkan jika omit_if_empty benar (default) dan tidak ada item lain yang ditambahkan (seperti yang terjadi jika values kosong atau semua itemnya difilter).
allow_closure bool; defaultnya adalah False
Jika benar, mengizinkan penggunaan penutupan dalam parameter fungsi seperti map_each. Biasanya hal ini tidak diperlukan dan berisiko mempertahankan struktur data fase analisis yang besar ke dalam fase eksekusi.

add_joined

Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)

Menambahkan argumen ke command line ini dengan menggabungkan beberapa nilai menggunakan pemisah. Item diproses secara lambat selama fase eksekusi.

Pemrosesan mirip dengan add_all(), tetapi daftar argumen yang berasal dari values digabungkan menjadi satu argumen seolah-olah oleh join_with.join(...), lalu diformat menggunakan template string format_joined yang diberikan. Tidak seperti add_all(), tidak ada parameter before_each atau terminate_with karena parameter ini umumnya tidak berguna saat item digabungkan menjadi satu argumen.

Jika setelah pemfilteran tidak ada string yang akan digabungkan menjadi argumen, dan jika omit_if_empty benar (default), tidak ada pemrosesan yang dilakukan. Jika tidak ada string yang akan digabungkan, tetapi omit_if_empty bernilai salah (false), string yang digabungkan akan menjadi string kosong.

Parameter

Parameter Deskripsi
arg_name_or_values required
Jika dua parameter posisional diteruskan, parameter ini ditafsirkan sebagai nama argumen. Nama argumen ditambahkan sebelum values tanpa pemrosesan apa pun. Argumen ini tidak akan ditambahkan jika omit_if_empty benar (default) dan tidak ada string yang berasal dari values untuk digabungkan (yang dapat terjadi jika values kosong atau semua itemnya difilter). Jika hanya satu parameter posisi yang diteruskan, parameter tersebut ditafsirkan sebagai values (lihat di bawah).
values sequence; atau depset; defaultnya adalah unbound
Daftar, tuple, atau depset yang itemnya akan digabungkan.
join_with string; wajib
String pembatas yang digunakan untuk menggabungkan string yang diperoleh dari penerapan map_each dan format_each, dengan cara yang sama seperti string.join().
map_each dapat dipanggil; atau None; defaultnya adalah None
Sama seperti untuk add_all.
format_each string; atau None; defaultnya adalah None
Sama seperti untuk add_all.
format_joined string; atau None; default adalah None
Pola string format opsional yang diterapkan ke string gabungan. String format harus memiliki tepat satu placeholder '%s'.
omit_if_empty bool; default adalah True
Jika benar (true), jika tidak ada string yang akan digabungkan (baik karena values kosong atau semua itemnya difilter), maka semua pemrosesan lebih lanjut akan dihentikan dan command line tidak akan berubah. Jika salah (false), maka meskipun tidak ada string yang akan digabungkan, dua argumen akan ditambahkan: nama argumen diikuti dengan string kosong (yang merupakan gabungan logis dari nol string).
uniquify bool; defaultnya adalah False
Sama seperti untuk add_all.
expand_directories bool; defaultnya adalah True
Sama seperti untuk add_all.
allow_closure bool; defaultnya adalah False
Sama seperti untuk add_all.

set_param_file_format

Args Args.set_param_file_format(format)

Menetapkan format file parameter, jika digunakan

Parameter

Parameter Deskripsi
format string; wajib
Harus salah satu dari:
  • "multiline": Setiap item (nama atau nilai argumen) ditulis persis seperti aslinya ke file param dengan karakter baris baru setelahnya.
  • "shell": Sama seperti "multiline", tetapi itemnya dikutip shell
  • "flag_per_line": Sama seperti "multiline", tetapi (1) hanya tanda (yang diawali dengan '--') yang ditulis ke file param, dan (2) nilai tanda, jika ada, ditulis pada baris yang sama dengan pemisah '='. Ini adalah format yang diharapkan oleh library flag Abseil.

Format defaultnya adalah "shell" jika tidak dipanggil.

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

Menumpahkan argumen ke file parameter, menggantinya dengan penunjuk ke file parameter. Gunakan saat argumen Anda mungkin terlalu besar untuk batas panjang perintah sistem.

Bazel dapat memilih untuk tidak menulis file parameter ke pohon output selama eksekusi agar lebih efisien. Jika Anda men-debug tindakan dan ingin memeriksa file parameter, teruskan --materialize_param_files ke build Anda.

Parameter

Parameter Deskripsi
param_file_arg string; wajib diisi
String format dengan satu "%s". Jika argumen diluapkan ke file params, argumen tersebut akan diganti dengan argumen yang terdiri dari string ini yang diformat dengan jalur file params.

Misalnya, jika argumen ditumpahkan ke file parameter "params.txt", maka penentuan "--file=%s" akan menyebabkan command line tindakan berisi "--file=params.txt".

use_always bool; default adalah False
Apakah akan selalu menumpahkan argumen ke file parameter. Jika salah (false), bazel akan memutuskan apakah argumen perlu dipecah berdasarkan sistem dan panjang argumen Anda.