file .bzl

Atribut implisit yang diawali 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.

Atribut yang dideklarasikan akan mengonversi None ke nilai default.

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

Agar beberapa target aturan (misalnya some_rule) terlihat oleh suatu aspek, some_rule harus mengiklankan semua penyedia dari setidaknya salah satu daftar penyedia yang diperlukan. 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]].

Agar aspek lain (misalnya other_aspect) terlihat oleh aspek ini, other_aspect harus menyediakan semua penyedia dari setidaknya salah satu daftar. Dalam 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.

Akan terjadi error jika fungsi implementasi menghilangkan salah satu jenis penyedia yang tercantum di sini dari nilai yang ditampilkannya. Namun, fungsi implementasi dapat 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. Cukup dengan fungsi implementasi yang menampilkannya. Namun, praktik terbaiknya adalah menentukannya, meskipun hal ini tidak diwajibkan. Namun, kolom required_providers dari aspek mengharuskan penyedia ditentukan di sini.

Misalnya, aspek disebarkan 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`. Misalnya, `beta` memiliki target `charlie` sebagai salah satu `deps`-nya. Jika `apply_to_generating_rules=True` untuk aspek, aspek akan disebarkan melalui `alpha`, `beta`, dan `charlie`. Jika False, aspek hanya akan disebarkan ke `alpha`.

Salah secara default.

Secara konvensional, fungsi implementasi harus memiliki parameter bernama untuk atribut apa pun yang perlu diperiksa, diubah, atau diteruskan oleh makro ke target non-"utama", sedangkan atribut yang diwarisi "massal" yang akan diteruskan ke target "utama" tanpa perubahan akan diteruskan sebagai **kwargs.

Fungsi implementasi tidak boleh menampilkan nilai. Sebagai gantinya, fungsi implementasi mendeklarasikan target dengan memanggil simbol aturan atau makro.

Nama target atau makro simbolis dalam yang dideklarasikan oleh makro simbolis (termasuk oleh fungsi Starlark apa pun yang dipanggil secara transitif oleh fungsi implementasi makro) harus sama dengan name (ini disebut sebagai target "utama") atau diawali dengan name, diikuti dengan karakter pemisah ("_", "-", atau ".") dan akhiran string. (Target yang melanggar skema penamaan ini diizinkan untuk dideklarasikan, tetapi tidak dapat di-build, dikonfigurasi, atau diandalkan.)

Secara default, target yang dideklarasikan oleh makro simbolis (termasuk oleh fungsi Starlark apa pun yang dipanggil secara transitif oleh fungsi implementasi makro) hanya terlihat dalam paket yang berisi file .bzl yang menentukan makro. Untuk mendeklarasikan target yang terlihat secara eksternal, termasuk kepada pemanggil makro simbolis, fungsi implementasi harus menetapkan visibility dengan tepat – biasanya, dengan meneruskan visibility = visibility ke aturan atau simbol makro yang dipanggil.

API berikut tidak tersedia dalam fungsi implementasi makro dan fungsi Starlark apa pun yang dipanggil secara transitif:

• package(), licenses()
• environment_group()
• native.glob() – sebagai gantinya, Anda dapat meneruskan glob ke makro melalui atribut daftar label
• native.subpackages()
• (hanya diizinkan di finalisasi aturan, lihat finalizer di bawah) native.existing_rules(), native.existing_rule()
• (untuk thread WORKSPACE) workspace(), register_toolchains(), register_execution_platforms(), bind(), pembuatan instance aturan repositori

Atribut name khusus telah dideklarasikan sebelumnya dan tidak boleh disertakan dalam kamus. Nama atribut visibility dicadangkan dan tidak boleh disertakan dalam kamus.

Atribut yang namanya diawali dengan _ bersifat pribadi -- tidak dapat diteruskan di situs panggilan aturan. Atribut tersebut dapat diberi nilai default (seperti dalam attr.label(default="//pkg:foo")) untuk membuat dependensi implisit pada label.

Untuk membatasi penggunaan memori, ada batas jumlah atribut yang dapat dideklarasikan.

Jika inherit_attrs ditetapkan ke string "common", makro akan mewarisi definisi atribut aturan umum yang digunakan oleh semua aturan Starlark.

Perhatikan bahwa jika nilai yang ditampilkan dari rule() atau macro() tidak ditetapkan ke variabel global dalam file .bzl, nilai tersebut belum terdaftar sebagai simbol aturan atau makro, sehingga tidak dapat digunakan untuk inherit_attrs.

Mekanisme pewarisan berfungsi sebagai berikut:

1. Atribut name dan visibility khusus tidak pernah diwarisi;
2. Atribut tersembunyi (yang namanya diawali dengan "_") tidak pernah diwarisi;
3. Atribut yang namanya sudah ditentukan dalam kamus attrs tidak pernah diwarisi (entri di attrs lebih diutamakan; perhatikan bahwa entri dapat ditetapkan ke None untuk memastikan tidak ada atribut dengan nama tersebut yang ditentukan di makro);
4. Semua atribut lainnya diwarisi dari aturan atau makro dan digabungkan secara efektif ke dalam dict attrs.

Jika atribut non-wajib diwariskan, nilai default atribut akan diganti menjadi None, apa pun yang ditentukan dalam aturan atau makro asli. Hal ini memastikan bahwa saat makro meneruskan nilai atribut ke instance aturan atau makro yang digabungkan – seperti dengan meneruskan **kwargs yang tidak diubah – nilai yang tidak ada dari panggilan makro luar juga tidak akan ada dalam panggilan aturan atau makro dalam (karena meneruskan None ke atribut diperlakukan sama seperti menghapus atribut). Hal ini penting karena menghilangkan atribut memiliki semantik yang sedikit berbeda dengan meneruskan nilai default yang terlihat. Secara khusus, atribut yang dihilangkan tidak ditampilkan dalam beberapa format output bazel query, dan default yang dihitung hanya dieksekusi jika nilai dihilangkan. Jika makro perlu memeriksa atau mengubah atribut yang diwarisi – misalnya, untuk menambahkan nilai ke atribut tags yang diwarisi – Anda harus memastikan untuk menangani kasus None dalam fungsi implementasi makro.

Misalnya, makro berikut mewarisi semua atribut dari native.cc_library, kecuali cxxopts (yang dihapus dari daftar atribut) dan copts (yang diberi definisi baru). Fungsi ini juga memeriksa nilai None default dari atribut tags yang diwarisi sebelum menambahkan tag tambahan.

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

Jika inherit_attrs ditetapkan, fungsi implementasi makro harus memiliki parameter kata kunci residual **kwargs.

Secara konvensional, makro harus meneruskan atribut yang diwariskan dan tidak diganti tanpa perubahan ke aturan "utama" atau simbol makro yang digabungkan oleh makro. Biasanya, sebagian besar atribut yang diwarisi tidak akan memiliki parameter dalam daftar parameter fungsi penerapan, dan hanya akan diteruskan melalui **kwargs. Fungsi implementasi akan lebih mudah jika memiliki parameter eksplisit untuk beberapa atribut yang diwarisi (paling umum, tags dan testonly) jika makro perlu meneruskan atribut tersebut ke target "utama" dan non-"utama" – tetapi jika makro juga perlu memeriksa atau memanipulasi atribut tersebut, Anda harus berhati-hati untuk menangani nilai default None dari atribut yang diwarisi dan tidak wajib.

Tidak seperti makro simbolis biasa, finalis aturan dapat memanggil native.existing_rule() dan native.existing_rules() untuk membuat kueri kumpulan target aturan non-finalis yang ditentukan dalam paket saat ini. Perhatikan bahwa native.existing_rule() dan native.existing_rules() tidak dapat mengakses target yang ditentukan oleh finalisasi aturan apa pun, termasuk aturan ini.

• daftar kolom:
  

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

• nama kolom kamus -> dokumentasi:
  

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

Berikut adalah deskripsi yang akurat; lihat Aturan (Inisialisasi kustom penyedia) untuk diskusi dan kasus penggunaan yang intuitif.

Anggap P adalah simbol penyedia yang dibuat dengan memanggil provider(). Secara konseptual, instance P dibuat 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 P baru dibuat seolah-olah dengan memanggil konstruktor default dengan entri d sebagai argumen kata kunci, seperti dalam 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 pengabaian daftar fields yang diizinkan.

Jika init ditentukan, nilai yang ditampilkan dari provider() 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 = ...)

Atribut yang dideklarasikan akan mengonversi None ke nilai default.

Atribut yang dideklarasikan akan mengonversi None ke nilai default.

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

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.

Setiap entri dalam kamus membuat output yang telah dideklarasikan sebelumnya dengan kunci sebagai ID dan nilai sebagai 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 dihasilkan dengan mengganti setiap placeholder dalam bentuk "%{ATTR}" dengan string yang dibentuk dari nilai atribut ATTR:

• Atribut berjenis string diganti secara verbatim.
• Atribut yang diketik 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-daftar (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", dict output {"bin": "%{name}.exe"} mendeklarasikan output bernama foo.exe yang dapat diakses dalam fungsi implementasi sebagai ctx.outputs.bin.

Akan terjadi error jika fungsi implementasi menghilangkan salah satu jenis penyedia yang tercantum di sini dari nilai yang ditampilkannya. Namun, fungsi implementasi dapat 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. Cukup dengan fungsi implementasi yang menampilkannya. Namun, praktik terbaiknya adalah menentukannya, meskipun hal ini 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 aturan ditentukan sebagai aturan pengujian analisis, aturan tersebut diizinkan untuk menggunakan transisi konfigurasi yang ditentukan menggunakan analysis_test_transition pada atributnya, tetapi memilih untuk mengikuti beberapa batasan:

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

Fungsi ini dipanggil pada waktu pemuatan untuk setiap instance aturan. Metode ini dipanggil dengan name dan nilai atribut publik yang ditentukan oleh aturan (bukan dengan atribut generik, 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.

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

Demikian pula, jika parameter dalam tanda tangan penginisialisasi tidak memiliki default, parameter tersebut akan menjadi wajib. Sebaiknya hapus setelan default/wajib pada definisi atribut dalam kasus tersebut.

Sebaiknya gunakan **kwargs untuk atribut yang tidak ditangani.

Dalam kasus aturan yang diperluas, semua penginisialisasi dipanggil dari turunan ke ancestor. Setiap penginisialisasi hanya diteruskan atribut publik yang diketahuinya.

Subaturan hanya boleh memiliki atribut pribadi yang berjenis label (yaitu label atau daftar label). Nilai yang di-resolve yang sesuai dengan label ini secara otomatis diteruskan oleh Bazel ke fungsi implementasi subaturan sebagai argumen bernama (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

Perhatikan bahwa tidak seperti rule(), aspect(), dan repository_rule(), atribut yang dideklarasikan tidak akan mengonversi None ke nilai default. Agar default dapat digunakan, atribut harus dihilangkan sepenuhnya oleh pemanggil.

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 subpaketnya.
• "public" atau "private": semua paket atau tidak ada paket

Sintaksis "@" tidak diizinkan; semua spesifikasi ditafsirkan 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 akan diperlakukan seolah-olah merupakan 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".