Sering kali terjadi bahwa tindakan memerlukan command line besar yang berisi nilai yang dikumpulkan dari dependensi transitif. Misalnya, command line linker mungkin mencantumkan setiap file objek yang diperlukan oleh semua library yang ditautkan. Sebaiknya simpan data transitif tersebut di depset
, sehingga data tersebut dapat dibagikan oleh beberapa target. Namun, jika penulis aturan harus mengonversi depset ini menjadi daftar string untuk membuat command line tindakan, tindakan ini akan mengalahkan pengoptimalan berbagi memori ini.
Karena alasan ini, fungsi pembuatan tindakan menerima objek Args
selain string. Setiap objek Args
mewakili penyambungan string dan depset, dengan transformasi opsional untuk memanipulasi data. Objek Args
tidak memproses depset yang dienkapsulasi hingga fase eksekusi, saat tiba waktunya menghitung command line. Hal ini membantu menunda penyalinan yang mahal hingga setelah fase analisis selesai. Lihat halaman Mengoptimalkan Performa untuk informasi selengkapnya.
Args
dibuat dengan memanggil ctx.actions.args()
. Class 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 standarnya adalah sebagai berikut:
- Nilai yang sudah menjadi string akan dibiarkan apa adanya.
- Objek
File
diubah menjadi nilaiFile.path
. - Semua jenis lainnya diubah menjadi string dengan cara yang tidak ditentukan. Oleh karena itu, Anda harus menghindari penerusan nilai yang bukan string atau jenis
File
keadd()
, dan jika Anda meneruskannya keadd_all()
atauadd_joined()
, Anda harus menyediakan fungsimap_each
.
Saat menggunakan pemformatan string (parameter format
, format_each
, dan format_joined
dari metode add*()
), template format ditafsirkan dengan cara yang sama seperti substitusi %
pada string, kecuali bahwa template harus memiliki satu placeholder pengganti dan harus %s
. Persentase literal dapat di-escape sebagai %%
. Pemformatan diterapkan setelah nilai dikonversi ke string sesuai dengan yang di atas.
Setiap metode add*()
memiliki bentuk alternatif yang menerima parameter posisi tambahan, string "arg name" untuk disisipkan sebelum argumen lainnya. Untuk add_all
dan add_joined
, string tambahan tidak akan ditambahkan jika urutannya kosong. Misalnya, penggunaan yang sama dapat menambahkan --foo val1 val2 val3 --bar
atau hanya --bar
ke command line, bergantung pada apakah urutan tertentu berisi val1..val3
atau kosong.
Jika ukuran command line dapat bertambah lebih panjang dari ukuran maksimum yang diizinkan oleh sistem, argumen dapat dibagikan ke file parameter. Lihat use_param_file()
dan set_param_file_format()
.
Contoh: Misalnya kita ingin membuat command line:
--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --bazKita 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
add
Args Args.add(arg_name_or_value, value=unbound, *, format=None)Menambahkan argumen ke command line ini.
Parameter
Parameter | Deskripsi |
---|---|
arg_name_or_value
|
wajib Jika dua parameter posisi diteruskan, ini ditafsirkan sebagai nama argumen. Nama argumen ditambahkan sebelum nilai tanpa pemrosesan. Jika hanya satu parameter posisi yang diteruskan, parameter ini akan ditafsirkan sebagai value (lihat di bawah).
|
value
|
default = unbound Objek yang akan ditambahkan. Konversi 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; or None ;
default = NonePola string format, yang akan diterapkan ke versi string value .
|
tambahkan_semua
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 dengan lambat selama fase eksekusi.
Sebagian besar pemrosesan terjadi melalui daftar argumen yang akan ditambahkan, sesuai dengan langkah-langkah berikut:
- Setiap item direktori
File
diganti oleh semuaFile
yang ada dalam direktori tersebut secara rekursif. - Jika
map_each
diberikan, nilai tersebut akan diterapkan ke setiap item, dan daftar string yang dihasilkan akan digabungkan untuk membentuk daftar argumen awal. Jika tidak, daftar argumen awal adalah hasil dari penerapan konversi standar ke setiap item. - Setiap argumen dalam daftar diformat dengan
format_each
, jika ada. - Jika
uniquify
bernilai benar, argumen duplikat akan dihapus. Kejadian pertama adalah kejadian yang tersisa. - 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 oleh titik ini. - Kecuali jika daftar kosong dan
omit_if_empty
bernilai benar (default), nama argumen danterminate_with
masing-masing disisipkan sebagai argumen pertama dan terakhir, jika keduanya diberikan.
Parameter
Parameter | Deskripsi |
---|---|
arg_name_or_values
|
wajib Jika dua parameter posisi diteruskan, 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 bernilai 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 ini akan ditafsirkan sebagai values (lihat di bawah).
|
values
|
sequence; or depset ;
default = unboundDaftar, tuple, atau depset yang itemnya akan ditambahkan. |
map_each
|
callable; or None ;
default = NoneFungsi yang mengonversi setiap item menjadi nol atau beberapa string, yang dapat diproses lebih lanjut sebelum menambahkan. Jika parameter ini tidak disediakan, konversi standar akan digunakan. Fungsi ini diteruskan dengan satu atau dua argumen posisi: item yang akan dikonversi, diikuti dengan Jenis nilai yang ditampilkan bergantung pada jumlah argumen yang akan dihasilkan untuk item:
None memiliki efek yang sama dengan menampilkan daftar dengan panjang 1 atau panjang 0. Namun, akan lebih efisien dan dapat dibaca untuk menghindari pembuatan daftar yang tidak diperlukan.Biasanya, item yang merupakan direktori akan otomatis diperluas ke kontennya saat Untuk menghindari retensi struktur data fase analisis yang besar yang tidak diinginkan ke dalam fase eksekusi, fungsi Peringatan: |
format_each
|
string; or None ;
default = NonePola string format opsional, diterapkan ke setiap string yang ditampilkan oleh fungsi map_each . String format harus memiliki tepat satu placeholder '%s'.
|
before_each
|
string; or None ;
default = NoneArgumen opsional yang akan ditambahkan sebelum setiap argumen yang berasal dari values akan ditambahkan.
|
omit_if_empty
|
default = True Jika benar, jika tidak ada argumen yang berasal dari values yang akan ditambahkan, semua pemrosesan lebih lanjut akan disembunyikan dan command line tidak akan diubah. Jika salah, nama argumen dan terminate_with , jika diberikan, akan tetap ditambahkan, terlepas dari ada argumen lain atau tidak.
|
uniquify
|
default = False Jika true, argumen duplikat yang berasal dari values akan dihilangkan. Hanya kemunculan pertama dari setiap argumen yang akan tetap ada. Biasanya fitur ini tidak diperlukan karena depset sudah menghilangkan duplikat, tetapi dapat berguna jika map_each memunculkan string yang sama untuk beberapa item.
|
expand_directories
|
default = True Jika benar, semua direktori di values akan diperluas ke daftar file datar. Hal ini terjadi sebelum map_each diterapkan.
|
terminate_with
|
string; or None ;
default = NoneArgumen opsional yang akan ditambahkan setelah semua argumen lainnya. Argumen ini tidak akan ditambahkan jika omit_if_empty bernilai benar (default) dan tidak ada item lain yang ditambahkan (seperti yang terjadi jika values kosong atau semua itemnya difilter).
|
allow_closure
|
default = False Jika true (benar), memungkinkan 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.
|
tambahkan_bergabung
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 dengan lambat selama fase eksekusi.
Pemrosesannya mirip dengan add_all()
, tetapi daftar argumen yang berasal dari values
digabungkan menjadi satu argumen seolah-olah join_with.join(...)
, lalu diformat menggunakan template string format_joined
yang ditentukan. Tidak seperti add_all()
, tidak ada parameter before_each
atau terminate_with
karena parameter ini umumnya tidak berguna jika item digabungkan menjadi satu argumen.
Jika setelah pemfilteran tidak ada string yang akan digabungkan ke dalam argumen, dan jika omit_if_empty
disetel ke benar (default), pemrosesan tidak akan dilakukan. Atau, jika tidak ada string untuk digabungkan, tetapi omit_if_empty
bernilai salah, string yang digabungkan akan menjadi string kosong.
Parameter
Parameter | Deskripsi |
---|---|
arg_name_or_values
|
wajib Jika dua parameter posisi diteruskan, ini ditafsirkan sebagai nama argumen. Nama argumen ditambahkan sebelum values tanpa pemrosesan apa pun. Argumen ini tidak akan ditambahkan jika omit_if_empty bernilai 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 ini akan ditafsirkan sebagai values (lihat di bawah).
|
values
|
sequence; or depset ;
default = unboundDaftar, tuple, atau depset yang itemnya akan digabungkan. |
join_with
|
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
|
callable; or None ;
default = Tidak adaSama seperti untuk add_all .
|
format_each
|
string; or None ;
default = Tidak adaSama seperti untuk add_all .
|
format_joined
|
string; or None ;
default = NonePola string format opsional diterapkan ke string yang digabungkan. String format harus memiliki tepat satu placeholder '%s'. |
omit_if_empty
|
default = True Jika benar, jika tidak ada string untuk digabungkan (baik karena values kosong atau semua itemnya difilter), semua pemrosesan lebih lanjut akan disembunyikan dan command line tidak akan berubah. Jika salah, maka meskipun tidak ada string yang akan digabungkan, dua argumen akan ditambahkan: nama argumen diikuti dengan string kosong (yang merupakan gabungan logis string nol).
|
uniquify
|
default = False Sama seperti untuk add_all .
|
expand_directories
|
default = True Sama seperti untuk add_all .
|
allow_closure
|
default = False Sama seperti untuk add_all .
|
format_file_param_set
Args Args.set_param_file_format(format)Menetapkan format file param, jika salah satunya digunakan
Parameter
Parameter | Deskripsi |
---|---|
format
|
wajib Harus salah satu dari:
Jika tidak dipanggil, format defaultnya adalah "shell". |
gunakan_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)Melemahkan args ke file params, menggantinya dengan pointer ke file param. Gunakan jika argumen mungkin terlalu besar untuk batas panjang perintah sistem.
Bazel dapat memilih untuk menuliskan file parameter ke hierarki output selama eksekusi untuk efisiensi. Jika Anda men-debug tindakan dan ingin memeriksa file parameter, teruskan --materialize_param_files
ke build Anda.
Parameter
Parameter | Deskripsi |
---|---|
param_file_arg
|
wajib String format dengan satu "%s". Jika argumen dialihkan ke file parameter, argumen tersebut akan diganti dengan argumen yang terdiri dari string ini yang diformat dengan jalur file parameter. Misalnya, jika argumen dialihkan ke file parameter "params.txt", maka menentukan "--file=%s" akan menyebabkan command line tindakan berisi "--file=params.txt". |
use_always
|
default = False Apakah akan selalu menumpahkan args ke file params. Jika salah, bazel akan menentukan apakah argumen perlu diungkapkan berdasarkan sistem dan panjang argumen Anda. |