Objek yang mengenkapsulasi, dengan cara yang hemat memori, data yang diperlukan untuk mem-build sebagian atau seluruh command line.
Sering kali terjadi bahwa tindakan memerlukan command line besar yang berisi nilai yang diakumulasikan dari dependensi transitif. Misalnya, command line penaut dapat mencantumkan setiap file objek yang diperlukan oleh semua library yang ditautkan. Praktik terbaiknya adalah menyimpan data transitif tersebut di depset
, sehingga dapat dibagikan oleh beberapa target. Namun, jika penulis aturan harus mengonversi depset ini menjadi daftar string untuk membuat command line tindakan, hal ini akan mengalahkan pengoptimalan berbagi memori ini.
Oleh karena itu, 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, ketika sudah waktunya untuk menghitung command line. Tindakan 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()
. Parameter tersebut 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 memberikan fungsi map_each
, konversi standarnya adalah sebagai berikut:
- Nilai yang sudah berupa string akan dibiarkan apa adanya.
- Objek
File
diubah menjadi nilaiFile.path
-nya. - Objek
Label
diubah menjadi representasi string yang di-resolve kembali ke objek yang sama saat di-resolve dalam konteks repositori utama. Jika memungkinkan, representasi string menggunakan nama repositori yang terlihat, bukan nama kanonis repositori, yang membuat 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 akan diubah menjadi string dengan cara yang tidak ditentukan. Karena itu, Anda harus menghindari penerusan nilai yang bukan dari jenis string atau
File
keadd()
, dan jika Anda meneruskannya keadd_all()
atauadd_joined()
, Anda harus menyediakan fungsimap_each
.
Saat menggunakan pemformatan string (param format
, format_each
, dan format_joined
dari metode add*()
), template format ditafsirkan dengan cara yang sama seperti penggantian %
pada string, kecuali bahwa template harus memiliki tepat satu placeholder penggantian dan harus berupa %s
. Persen literal dapat di-escape sebagai %%
. Format diterapkan setelah nilai dikonversi menjadi string seperti di atas.
Setiap metode add*()
memiliki bentuk alternatif yang menerima parameter posisional tambahan, string "arg name" yang akan disisipkan sebelum argumen lainnya. Untuk add_all
dan add_joined
, string tambahan tidak akan ditambahkan jika urutan tersebut ternyata 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 bisa bertambah lebih panjang dari ukuran maksimum yang diizinkan oleh sistem, argumen dapat disebarkan 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 --baz
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)
Parameter
Parameter | Deskripsi |
---|---|
arg_name_or_value
|
required Jika dua parameter posisional diteruskan, ini akan ditafsirkan sebagai nama arg. Nama arg ditambahkan sebelum nilai tanpa pemrosesan apa pun. Jika hanya satu parameter posisi yang diteruskan, parameter tersebut akan ditafsirkan sebagai value (lihat di bawah).
|
value
|
default adalah unbound Objek yang akan ditambahkan. Nilai ini 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 ;
default-nya adalah None Pola string format, yang akan diterapkan ke versi string 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)
Sebagian besar pemrosesan terjadi pada daftar argumen yang akan ditambahkan, sesuai dengan langkah-langkah berikut:
- Setiap item
File
direktori diganti dengan semuaFile
yang terdapat secara rekursif dalam direktori tersebut. - Jika
map_each
diberikan, kode 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 penerapan konversi standar ke setiap item. - Setiap argumen dalam daftar diformat dengan
format_each
, jika ada. - Jika
uniquify
benar, argumen duplikat akan dihapus. Kejadian pertama adalah yang tetap ada. - 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 arg danterminate_with
akan disisipkan sebagai argumen pertama dan terakhir, jika diberikan.
Parameter
Parameter | Deskripsi |
---|---|
arg_name_or_values
|
required Jika dua parameter posisional diteruskan, ini akan ditafsirkan sebagai nama arg. Nama arg ditambahkan sebelum values sebagai argumen terpisah tanpa pemrosesan apa pun. Nama argumen ini tidak akan ditambahkan jika omit_if_empty bernilai benar (true) (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 akan ditafsirkan sebagai values (lihat di bawah).
|
values
|
sequence; atau depset;
defaultnya adalah unbound Daftar, tuple, atau depset yang itemnya akan ditambahkan. |
map_each
|
callable; 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 diteruskan 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, lebih efisien dan mudah dibaca jika Anda tidak membuat daftar yang tidak diperlukan.Biasanya, item yang merupakan direktori secara otomatis diperluas ke kontennya saat Untuk menghindari retensi struktur data fase analisis besar yang tidak disengaja ke dalam fase eksekusi, fungsi Peringatan: Pernyataan |
format_each
|
string; atau None ;
default adalah None Pola string format opsional, yang diterapkan ke setiap string yang ditampilkan oleh fungsi map_each . String format harus memiliki 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
|
default adalah True Jika benar, jika tidak ada argumen yang berasal dari values untuk ditambahkan, semua pemrosesan lebih lanjut akan dinonaktifkan dan command line tidak akan berubah. Jika salah (false), nama arg dan terminate_with , jika diberikan, akan tetap ditambahkan terlepas dari apakah ada argumen lain atau tidak.
|
uniquify
|
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 depset sudah menghilangkan duplikat, tetapi dapat berguna jika map_each memunculkan string yang sama untuk beberapa item.
|
expand_directories
|
defaultnya adalah True Jika benar, direktori apa pun di values akan diperluas ke 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 bernilai benar (default) dan tidak ada item lain yang ditambahkan (seperti yang terjadi jika values kosong atau semua itemnya difilter).
|
allow_closure
|
defaultnya adalah False Jika benar, memungkinkan 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)
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 ke dalam argumen, dan jika omit_if_empty
bernilai benar (default), tidak ada pemrosesan yang dilakukan. Sebaliknya jika tidak ada string yang akan digabungkan, tetapi omit_if_empty
bernilai salah, string gabungan akan berupa string kosong.
Parameter
Parameter | Deskripsi |
---|---|
arg_name_or_values
|
required Jika dua parameter posisional diteruskan, ini akan ditafsirkan sebagai nama arg. Nama arg 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 akan ditafsirkan sebagai values (lihat di bawah).
|
values
|
sequence; atau depset;
default adalah unbound Daftar, tuple, atau depset yang itemnya akan digabungkan. |
join_with
|
required 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; 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 yang digabungkan. String format harus memiliki satu placeholder '%s'. |
omit_if_empty
|
default adalah True Jika benar, jika tidak ada string yang akan digabungkan (baik karena values kosong atau semua itemnya difilter), semua pemrosesan lebih lanjut akan dinonaktifkan dan command line tidak akan berubah. Jika false, meskipun tidak ada string yang akan digabungkan, dua argumen akan ditambahkan: nama arg diikuti dengan string kosong (yang merupakan penggabungan logis dari string nol).
|
uniquify
|
default-nya adalah False Sama seperti untuk add_all .
|
expand_directories
|
default adalah True Sama seperti untuk add_all .
|
allow_closure
|
default adalah False Sama seperti untuk add_all .
|
set_param_file_format
Args Args.set_param_file_format(format)
Parameter
Parameter | Deskripsi |
---|---|
format
|
required Harus berupa salah satu dari:
Jika tidak dipanggil, format default-nya adalah "shell". |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)
Bazel dapat memilih untuk menghapus penulisan 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
|
required String format dengan satu "%s". Jika argumen ditransfer ke file params, argumen tersebut akan diganti dengan argumen yang terdiri dari string ini yang diformat dengan jalur file params. Misalnya, jika arg ditransfer ke file params "params.txt", menentukan "--file=%s" akan menyebabkan command line tindakan berisi "--file=params.txt". |
use_always
|
default adalah False Apakah akan selalu menumpahkan argumen ke file parameter. Jika salah, bazel akan memutuskan apakah argumen perlu di-spill berdasarkan sistem dan panjang arg Anda. |