file .bzl

Atribut implisit yang dimulai dengan _ harus memiliki nilai default, dan memiliki jenis label atau label_list.

Atribut eksplisit harus memiliki jenis string, dan harus menggunakan batasan values. Atribut eksplisit membatasi aspek agar hanya digunakan dengan aturan yang memiliki atribut dengan nama, jenis, dan nilai yang valid yang sama sesuai dengan batasan.

Daftar penyedia yang tidak bertingkat akan otomatis dikonversi ke daftar yang berisi satu daftar penyedia. Artinya, [FooInfo, BarInfo] akan otomatis dikonversi menjadi [[FooInfo, BarInfo]].

Agar beberapa target aturan (misalnya, some_rule) terlihat oleh aspek, some_rule harus mengiklankan semua penyedia dari minimal salah satu daftar penyedia yang diwajibkan. Misalnya, jika required_providers dari suatu aspek adalah [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], aspek ini dapat melihat target some_rule jika dan hanya jika some_rule menyediakan FooInfo, atau BarInfo, atau BazInfo dan QuxInfo.

Daftar penyedia yang tidak bertingkat akan otomatis dikonversi menjadi daftar yang berisi satu daftar penyedia. Artinya, [FooInfo, BarInfo] akan otomatis dikonversi menjadi [[FooInfo, BarInfo]].

Untuk membuat aspek lain (misalnya, other_aspect) terlihat pada aspek ini, other_aspect harus menyediakan semua penyedia dari setidaknya salah satu daftar. Pada contoh [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], aspek ini dapat melihat other_aspect jika dan hanya jika other_aspect menyediakan FooInfo, atau BarInfo, atau BazInfo dan QuxInfo.

Muncul error jika fungsi implementasi menghilangkan salah satu jenis penyedia yang tercantum di sini dari nilai yang ditampilkannya. Namun, fungsi implementasi mungkin menampilkan penyedia tambahan yang tidak tercantum di sini.

Setiap elemen daftar adalah objek *Info yang ditampilkan oleh provider(), kecuali bahwa penyedia lama diwakili oleh nama stringnya. Jika target aturan digunakan sebagai dependensi untuk target yang mendeklarasikan penyedia yang diperlukan, Anda tidak perlu menentukan penyedia tersebut di sini. Fungsi implementasi cukup menampilkannya. Namun, praktik terbaiknya adalah menentukannya, meskipun hal ini tidak diwajibkan. Namun, kolom required_providers dari aspek mengharuskan penyedia tersebut ditentukan di sini.

Misalnya, aspek menyebar secara transitif melalui atribut `deps` dan diterapkan ke target `alpha`. Misalnya `alpha` memiliki `deps = [':beta_output']`, dengan `beta_output` adalah output yang dideklarasikan dari target `beta`. Misalkan `beta` memiliki target `charlie` sebagai salah satu `deps`-nya. Jika `apply_to_created_rules=True`, aspek `alpha` hanya akan disebarkan ke aspek `alpha`.

Salah secara default.

• daftar kolom:
  

  provider(fields = ['a', 'b'])

• nama bidang kamus -> dokumentasi:
  

  provider(
         fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })

Berikut deskripsi yang tepat; lihat Aturan (Inisialisasi kustom bagi penyedia) untuk mengetahui diskusi dan kasus penggunaan yang intuitif.

Anggap P adalah simbol penyedia yang dibuat dengan memanggil provider(). Secara konseptual, instance P dihasilkan dengan memanggil fungsi konstruktor default c(*args, **kwargs), yang melakukan hal berikut:

• Jika args tidak kosong, error akan terjadi.
• Jika parameter fields ditentukan saat provider() dipanggil, dan jika kwargs berisi kunci yang tidak tercantum dalam fields, error akan terjadi.
• Jika tidak, c akan menampilkan instance baru yang memiliki, untuk setiap entri k: v di kwargs, kolom bernama k dengan nilai v.

MyInfo = provider()
m = MyInfo(foo = 1)

Namun, jika init ditentukan, panggilan P(*args, **kwargs) akan melakukan langkah-langkah berikut:

1. Callback dipanggil sebagai init(*args, **kwargs), yaitu, dengan argumen posisional dan kata kunci yang sama persis seperti yang diteruskan ke P.
2. Nilai yang ditampilkan init diharapkan berupa kamus, d, yang kuncinya adalah string nama kolom. Jika tidak, error akan terjadi.
3. Instance baru P dibuat seolah-olah dengan memanggil konstruktor default dengan entri d sebagai argumen kata kunci, seperti di c(**d).

Catatan: langkah-langkah di atas menyiratkan bahwa error terjadi jika *args atau **kwargs tidak cocok dengan tanda tangan init, atau evaluasi isi init gagal (mungkin sengaja melalui panggilan ke fail()), atau jika nilai yang ditampilkan init bukan kamus dengan skema yang diharapkan.

Dengan cara ini, callback init akan memgeneralisasi konstruksi penyedia normal dengan mengizinkan argumen posisional dan logika arbitrer untuk prapemrosesan dan validasi. Tindakan ini tidak memungkinkan pengelakan dari daftar fields yang diizinkan.

Jika init ditentukan, nilai yang ditampilkan provider() akan menjadi tuple (P, r), dengan r adalah konstruktor mentah. Faktanya, perilaku r sama persis dengan fungsi konstruktor default c yang dibahas di atas. Biasanya, r terikat dengan variabel yang namanya diawali dengan garis bawah, sehingga hanya file .bzl saat ini yang memiliki akses langsung ke variabel tersebut:

MyInfo, _new_myinfo = provider(init = ...)

Skema untuk menentukan output yang telah dideklarasikan sebelumnya. Tidak seperti atribut output dan output_list, pengguna tidak menentukan label untuk file tersebut. Lihat halaman Aturan untuk mengetahui informasi selengkapnya tentang output yang telah dideklarasikan.

Nilai argumen ini adalah kamus atau fungsi callback yang menghasilkan kamus. Callback berfungsi mirip dengan atribut dependensi yang dihitung: Nama parameter fungsi dicocokkan dengan atribut aturan, jadi misalnya jika Anda meneruskan outputs = _my_func dengan definisi def _my_func(srcs, deps): ..., fungsi tersebut memiliki akses ke atribut srcs dan deps. Baik kamus ditentukan secara langsung maupun melalui fungsi, kamus akan ditafsirkan sebagai berikut.

Tiap entri dalam kamus membuat output yang telah dideklarasikan sebelumnya, dengan kuncinya adalah ID dan nilainya adalah template string yang menentukan label output. Dalam fungsi penerapan aturan, ID menjadi nama kolom yang digunakan untuk mengakses File output di ctx.outputs. Label output memiliki paket yang sama dengan aturan, dan bagian setelah paket dibuat dengan mengganti setiap placeholder dari bentuk "%{ATTR}" dengan string yang dibentuk dari nilai atribut ATTR:

• Atribut berjenis string diganti secara verbatim.
• Atribut berjenis label menjadi bagian dari label setelah paket, tanpa ekstensi file. Misalnya, label "//pkg:a/b.c" menjadi "a/b".
• Atribut yang diketik output menjadi bagian dari label setelah paket, termasuk ekstensi file (untuk contoh di atas, "a/b.c").
• Semua atribut berjenis daftar (misalnya, attr.label_list) yang digunakan dalam placeholder harus memiliki persis satu elemen. Konversinya sama dengan versi non-daftarnya (attr.label).
• Jenis atribut lainnya mungkin tidak muncul di placeholder.
• Placeholder non-atribut khusus %{dirname} dan %{basename} diperluas ke bagian label aturan tersebut, tidak termasuk paketnya. Misalnya, di "//pkg:a/b.c", dirname adalah a dan basename adalah b.c.

Dalam praktiknya, placeholder penggantian yang paling umum adalah "%{name}". Misalnya, untuk target bernama "foo", output dict {"bin": "%{name}.exe"} mendeklarasikan output bernama foo.exe di awal yang dapat diakses dalam fungsi implementasi sebagai ctx.outputs.bin.

Muncul error jika fungsi implementasi menghilangkan salah satu jenis penyedia yang tercantum di sini dari nilai yang ditampilkannya. Namun, fungsi implementasi mungkin menampilkan penyedia tambahan yang tidak tercantum di sini.

Setiap elemen daftar adalah objek *Info yang ditampilkan oleh provider(), tetapi penyedia lama justru diwakili oleh nama stringnya.Jika target aturan digunakan sebagai dependensi untuk target yang mendeklarasikan penyedia wajib, Anda tidak perlu menentukan penyedia tersebut di sini. Cukup dengan fungsi implementasi yang menampilkannya. Namun, menentukannya dianggap sebagai praktik terbaik, meskipun tidak diwajibkan. Namun, kolom required_providers dari aspek mengharuskan penyedia ditentukan di sini.

Catatan: Aturan pengujian analisis terutama ditentukan menggunakan infrastruktur yang disediakan di library Starlark inti. Lihat Pengujian untuk mendapatkan panduan.

Jika sebuah aturan ditetapkan sebagai aturan pengujian analisis, aturan tersebut akan diizinkan untuk menggunakan transisi konfigurasi yang ditentukan menggunakan analysis_test_transition di atributnya, tetapi dapat menerapkan beberapa batasan berikut:

• Jumlah target aturan ini terbatas dalam jumlah dependensi transitif yang mungkin dimilikinya.
• Aturan dianggap sebagai aturan pengujian (seolah-olah test=True ditetapkan). Ini menggantikan nilai test
• Fungsi penerapan aturan tidak boleh mendaftarkan tindakan. Sebagai gantinya, aplikasi harus mendaftarkan hasil lulus/gagal melalui penyediaan AnalysisTestResultInfo.

Fungsi ini dipanggil pada waktu pemuatan untuk setiap instance aturan. Callback ini dipanggil dengan name dan nilai atribut publik yang ditentukan oleh aturan (bukan dengan atribut umum, misalnya tags).

Fungsi ini harus menampilkan kamus dari nama atribut ke nilai yang diinginkan. Atribut yang tidak ditampilkan tidak akan terpengaruh. Menampilkan None sebagai nilai akan menggunakan nilai default yang ditentukan dalam definisi atribut.

Inisialisasi dievaluasi sebelum nilai default yang ditentukan dalam definisi atribut. Akibatnya, jika parameter dalam tanda tangan penginisialisasi berisi nilai default, parameter tersebut akan menimpa nilai default dari definisi atribut (kecuali jika menampilkan None).

Demikian pula, jika parameter dalam tanda tangan penginisialisasi tidak memiliki nilai default, parameter akan menjadi wajib. Dalam kasus semacam ini, sebaiknya hapus setelan default/wajib pada definisi atribut.

Anda sebaiknya menggunakan **kwargs untuk atribut yang tidak ditangani.

Pada aturan yang diperluas, semua penginisialisasi akan dipanggil dari turunan ke ancestor. Setiap penginisialisasi hanya meneruskan atribut publik yang diketahuinya.

Subaturan hanya boleh memiliki atribut pribadi yang berjenis label (yaitu label atau daftar label). Nilai yang di-resolve sesuai dengan label ini secara otomatis diteruskan oleh Bazel ke fungsi penerapan subaturan sebagai argumen yang dinamai (sehingga fungsi implementasi diperlukan untuk menerima parameter bernama yang cocok dengan nama atribut). Jenis nilai ini akan berupa:

• FilesToRunProvider untuk atribut label dengan executable=True
• File untuk atribut label dengan allow_single_file=True
• Target untuk semua atribut label lainnya
• [Target] untuk semua atribut daftar label

Spesifikasi paket mengikuti format yang sama seperti untuk package_group, kecuali bahwa spesifikasi paket negatif tidak diizinkan. Artinya, spesifikasi dapat memiliki bentuk:

• "//foo": paket //foo
• "//foo/...": paket //foo dan semua sub-paketnya.
• "public" atau "private": semua paket atau tidak ada paket

Sintaksis "@" tidak diizinkan; semua spesifikasi ditafsirkan secara relatif terhadap repositori modul saat ini.

Jika value adalah daftar string, kumpulan paket yang diberi visibilitas ke modul ini adalah gabungan paket yang diwakili oleh setiap spesifikasi. (Daftar kosong memiliki efek yang sama dengan private.) Jika value adalah string tunggal, string tersebut diperlakukan seolah-olah itu adalah daftar singleton [value].

Perhatikan bahwa flag --incompatible_package_group_has_public_syntax dan --incompatible_fix_package_group_reporoot_syntax tidak berpengaruh pada argumen ini. Nilai "public" dan "private" selalu tersedia, dan "//..." selalu ditafsirkan sebagai "semua paket dalam repositori saat ini".