Args

Objek yang mengenkapsulasi, dengan cara yang hemat memori, data yang diperlukan untuk mem-build sebagian atau semua command line.

Sering terjadi tindakan memerlukan command line besar yang berisi nilai yang terakumulasi dari dependensi transitif. Misalnya, command line penaut mungkin mencantumkan setiap file objek yang dibutuhkan oleh semua library yang ditautkan. Praktik terbaiknya adalah menyimpan data transitif tersebut di depset, sehingga data tersebut dapat dibagikan oleh beberapa target. Namun, jika pembuat aturan harus mengonversi dependensi tersebut menjadi daftar string untuk menyusun baris perintah tindakan, tindakan tersebut akan mengalahkan pengoptimalan berbagi memori ini.

Karena alasan ini, fungsi pembuatan tindakan menerima objek Args selain string. Setiap objek Args mewakili penyambungan string dan dependensi, dengan transformasi opsional untuk memanipulasi data. Objek Args tidak memproses dependensi yang dienkapsulasi hingga fase eksekusi, saat tiba waktunya untuk menghitung command line. Langkah ini membantu menunda penyalinan data yang memerlukan banyak biaya hingga fase analisis selesai. Lihat halaman Mengoptimalkan Performa untuk informasi selengkapnya.

Args dibuat dengan memanggil ctx.actions.args(). Parameter 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 memberikan fungsi map_each, konversi standarnya adalah sebagai berikut:

  • Nilai yang sudah menjadi string dibiarkan apa adanya.
  • Objek File diubah menjadi nilai File.path.
  • Semua jenis lain diubah menjadi string dengan cara yang tidak ditentukan. Karena alasan ini, Anda harus menghindari penerusan nilai yang bukan dari string atau jenis File ke add(), dan jika Anda meneruskannya ke add_all() atau add_joined(), Anda harus menyediakan 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 substitusi % pada string, kecuali template harus memiliki tepat satu placeholder substitusi dan harus %s. Persen literal dapat di-escape sebagai %%. Pemformatan diterapkan setelah nilai dikonversi ke string seperti yang sesuai di atas.

Setiap metode add*() memiliki bentuk alternatif yang menerima parameter posisi tambahan, string "nama argumen" yang akan disisipkan sebelum argumen lainnya. Untuk add_all dan add_joined, string tambahan tidak akan ditambahkan jika urutan 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 dapat bertambah lebih panjang dari ukuran maksimum yang diizinkan oleh sistem, argumen dapat tersebar menjadi 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

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, hal 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 = tidak terikat
Objek yang akan ditambahkan. String 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; or None; default = 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)

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:

  1. Setiap item direktori File diganti dengan semua File secara berulang yang terdapat dalam direktori tersebut.
  2. Jika map_each diberikan, nilai tersebut akan diterapkan ke setiap item, dan daftar string yang dihasilkan digabungkan untuk membentuk daftar argumen awal. Jika tidak, daftar argumen awal adalah hasil dari penerapan konversi standar untuk setiap item.
  3. Setiap argumen dalam daftar diformat dengan format_each, jika ada.
  4. Jika uniquify bernilai benar, argumen duplikat akan dihapus. Kejadian pertama adalah yang tersisa.
  5. Jika string before_each diberikan, string tersebut akan disisipkan sebagai argumen baru sebelum setiap argumen yang ada dalam daftar. Tindakan ini secara efektif menggandakan jumlah argumen yang akan ditambahkan dengan titik ini.
  6. Kecuali jika daftar kosong dan omit_if_empty bernilai benar (default), nama arg dan terminate_with masing-masing 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 wajib
Jika dua parameter posisi diteruskan, hal ini akan ditafsirkan sebagai nama arg. Nama argumen ditambahkan sebelum values 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 tersebut akan ditafsirkan sebagai values (lihat di bawah).
values sequence; or depset; default = unbound
Daftar, tuple, atau depset yang itemnya akan ditambahkan.
map_each callable; or None; default = Tidak ada
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 disediakan adalah fungsi yang ditentukan pengguna (bukan bawaan) dan mendeklarasikan lebih dari satu parameter.

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

  • Dalam kasus umum ketika setiap item berubah menjadi satu string, fungsi ini harus menampilkan string tersebut.
  • Jika item akan difilter sepenuhnya, fungsi ini harus menampilkan None.
  • Jika item berubah menjadi beberapa string, fungsi akan menampilkan daftar string tersebut.
Menampilkan string tunggal atau None memiliki efek yang sama dengan menampilkan daftar dengan panjang 1 atau panjang 0 masing-masing. Namun, cara ini lebih efisien dan mudah dibaca untuk menghindari pembuatan daftar yang tidak diperlukan.

Biasanya, item yang merupakan direktori otomatis diperluas ke kontennya saat expand_directories=True ditetapkan. Namun, ini tidak akan memperluas direktori yang terdapat di dalam nilai lain -- misalnya, jika 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 yang tidak diinginkan dari struktur data fase analisis yang besar ke dalam fase eksekusi, fungsi map_each harus dideklarasikan oleh pernyataan def tingkat atas; fungsi ini mungkin bukan penutupan fungsi bertingkat secara default.

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

format_each string; or None; default = 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; or None; default = None
String 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 untuk ditambahkan, semua pemrosesan lebih lanjut akan dihentikan dan command line tidak akan berubah. Jika salah, nama argumen dan terminate_with, jika disediakan, akan tetap ditambahkan, terlepas dari apakah ada argumen lain atau tidak.
uniquify default = False
Jika benar, argumen duplikat yang berasal dari values akan dihilangkan. Hanya kemunculan pertama setiap argumen yang akan tetap. Biasanya fitur ini tidak diperlukan karena dependensi sudah menghilangkan duplikat, tetapi dapat berguna jika map_each memunculkan string yang sama untuk beberapa item.
expand_directories default = True
Jika true, setiap direktori di values akan diperluas ke daftar file tetap. Hal ini terjadi sebelum map_each diterapkan.
terminate_with string; or None; default = Tidak ada
String opsional yang akan ditambahkan setelah semua argumen lainnya. String 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, mengizinkan penggunaanclosure 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 dengan lambat selama fase eksekusi.

Pemrosesannya mirip dengan add_all(), tetapi daftar argumen yang berasal dari values digabungkan menjadi satu argumen seolah-olah dengan 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 umumnya tidak berguna saat item digabungkan menjadi satu argumen.

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

Parameter

Parameter Deskripsi
arg_name_or_values wajib
Jika dua parameter posisi diteruskan, hal ini akan ditafsirkan sebagai nama arg. Nama argumen ditambahkan sebelum values tanpa pemrosesan apa pun. Arg 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 tersebut akan ditafsirkan sebagai values (lihat di bawah).
values sequence; or depset; default = unbound
Daftar, tuple, atau depset yang itemnya akan digabungkan.
join_with wajib
String pembatas yang digunakan untuk menggabungkan string yang diperoleh dengan menerapkan map_each dan format_each, dengan cara yang sama seperti string.join().
map_each callable; or None; default = Tidak ada
Sama seperti untuk add_all.
format_each string; or None; default = Tidak ada
Sama seperti untuk add_all.
format_joined string; or None; default = None
Pola string format opsional yang diterapkan pada 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 false, meskipun tidak ada string untuk digabungkan, dua argumen akan ditambahkan: nama arg diikuti dengan string kosong (yang merupakan join logis dari 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.

set_param_file_format

Args Args.set_param_file_format(format)

Menetapkan format file parameter, jika file digunakan

Parameter

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

Jika tidak dipanggil, format defaultnya adalah "shell".

use_param_file

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

Menumpahkan argumen ke file params, menggantinya dengan pointer ke file param. Gunakan saat argumen Anda mungkin terlalu besar untuk batas panjang perintah sistem.

Bazel dapat memilih untuk tidak menulis file parameter ke hierarki output selama eksekusi demi 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 diteruskan ke file params, argumen tersebut akan diganti dengan argumen yang terdiri dari string yang diformat dengan jalur file params.

Misalnya, jika argumen diteruskan ke file params "params.txt", menentukan "--file=%s" akan menyebabkan command line tindakan berisi "--file=params.txt".

use_always default = False
Apakah akan selalu menumpahkan argumen ke file params. Jika salah, bazel akan memutuskan apakah argumen perlu dihapus berdasarkan sistem dan panjang argumen Anda.