file .bzl

Laporkan masalah Nightly · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Metode global yang tersedia di semua file .bzl.

Anggota

analysis_test_transition

transition analysis_test_transition(settings)

Membuat transisi konfigurasi yang akan diterapkan pada dependensi aturan pengujian analisis. Transisi ini hanya dapat diterapkan pada atribut aturan dengan analysis_test = True. Kemampuan aturan tersebut dibatasi (misalnya, ukuran hierarki dependensinya terbatas), sehingga transisi yang dibuat menggunakan fungsi ini memiliki cakupan potensial yang terbatas dibandingkan dengan transisi yang dibuat menggunakan transition().

Fungsi ini terutama dirancang untuk memfasilitasi library inti Analysis Test Framework. Lihat dokumentasi (atau penerapannya) untuk mengetahui praktik terbaik.

Parameter

Parameter Deskripsi
settings dict; required
Kamus yang berisi informasi tentang setelan konfigurasi yang harus ditetapkan oleh transisi konfigurasi ini. Kunci adalah label setelan build dan nilainya adalah nilai baru setelah transisi. Semua setelan lainnya tidak berubah. Gunakan ini untuk mendeklarasikan setelan konfigurasi tertentu yang harus ditetapkan oleh pengujian analisis agar lulus.

aspek

Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], fragments=[], host_fragments=[], toolchains=[], incompatible_use_toolchain_transition=False, doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[])

Membuat aspek baru. Hasil fungsi ini harus disimpan dalam nilai global. Lihat pengantar Aspek untuk mengetahui detail selengkapnya.

Parameter

Parameter Deskripsi
implementation function; required
Fungsi Starlark yang menerapkan aspek ini, dengan tepat dua parameter: Target (target tempat aspek diterapkan) dan ctx (konteks aturan tempat target dibuat). Atribut target tersedia melalui kolom ctx.rule. Fungsi ini dievaluasi selama fase analisis untuk setiap penerapan aspek ke target.
attr_aspects urutan string; default adalah []
Daftar nama atribut. Aspek ini diperluas bersama dependensi yang ditentukan dalam atribut target dengan nama ini. Nilai umum di sini mencakup deps dan exports. Daftar ini juga dapat berisi satu string "*" untuk disebarkan ke semua dependensi target.
toolchains_aspects sequence; default adalah []
Daftar jenis toolchain. Aspek ini di-propagate ke toolchain target yang cocok dengan jenis toolchain ini.
attrs dict; default adalah {}
Kamus yang mendeklarasikan semua atribut aspek. Fungsi ini memetakan dari nama atribut ke objek atribut, seperti attr.label atau attr.string (lihat modul attr). Atribut aspek tersedia untuk fungsi implementasi sebagai kolom parameter ctx.

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.
required_providers sequence; default adalah []
Atribut ini memungkinkan aspek membatasi penyebarannya hanya ke target yang aturannya mengiklankan penyedia yang diperlukan. Nilai harus berupa daftar yang berisi setiap penyedia atau daftar penyedia, tetapi tidak keduanya. Misalnya, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] adalah nilai yang valid, sedangkan [FooInfo, BarInfo, [BazInfo, QuxInfo]] tidak valid.

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.

required_aspect_providers sequence; default adalah []
Atribut ini memungkinkan aspek ini memeriksa aspek lain. Nilai harus berupa daftar yang berisi setiap penyedia atau daftar penyedia, tetapi tidak keduanya. Misalnya, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] adalah nilai yang valid, sedangkan [FooInfo, BarInfo, [BazInfo, QuxInfo]] tidak valid.

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.

provides sequence; default adalah []
Daftar penyedia yang harus ditampilkan oleh fungsi implementasi.

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.

requires urutan Aspek; default adalah []
Daftar aspek yang harus disebarkan sebelum aspek ini.
fragments urutan string; default adalah []
Daftar nama fragmen konfigurasi yang diperlukan aspek dalam konfigurasi target.
host_fragments urutan string; default adalah []
Daftar nama fragmen konfigurasi yang diperlukan aspek dalam konfigurasi host.
toolchains sequence; default-nya adalah []
Jika ditetapkan, kumpulan toolchain yang diperlukan aspek ini. Daftar dapat berisi objek String, Label, atau StarlarkToolchainTypeApi, dalam kombinasi apa pun. Toolchain akan ditemukan dengan memeriksa platform saat ini, dan disediakan ke implementasi aspek melalui ctx.toolchain.
incompatible_use_toolchain_transition bool; default adalah False
Tidak digunakan lagi, ini tidak lagi digunakan dan harus dihapus.
doc string; atau None; default adalah None
Deskripsi aspek yang dapat diekstrak oleh alat pembuat dokumentasi.
apply_to_generating_rules bool; default adalah False
Jika benar, aspek akan, saat diterapkan ke file output, diterapkan ke aturan pembuatan file output.

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.
exec_compatible_with urutan string; default adalah []
Daftar batasan pada platform eksekusi yang berlaku untuk semua instance aspek ini.
exec_groups dict; atau None; default adalah None
Dict nama grup eksekusi (string) ke exec_groups. Jika ditetapkan, memungkinkan aspek menjalankan tindakan di beberapa platform eksekusi dalam satu instance. Lihat dokumentasi grup eksekusi untuk mengetahui info selengkapnya.
subrules urutan Subaturan; default adalah []
Eksperimental: daftar subaturan yang digunakan oleh aspek ini.

configuration_field

LateBoundDefault configuration_field(fragment, name)

Mereferensikan nilai default yang terikat lambat untuk atribut berjenis label. Nilai 'terikat lambat' jika memerlukan konfigurasi untuk dibuat sebelum menentukan nilai. Setiap atribut yang menggunakan ini sebagai nilai harus pribadi.

Contoh penggunaan:

Menentukan atribut aturan: 

'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain'))

Mengakses dalam penerapan aturan: 

  def _rule_impl(ctx):
    foo_info = ctx.attr._foo
    ...

Parameter

Parameter Deskripsi
fragment string; required
Nama fragmen konfigurasi yang berisi nilai yang terikat terlambat.
name string; required
Nama nilai yang akan diperoleh dari fragmen konfigurasi.

depset

depset depset(direct=None, order="default", *, transitive=None)

Membuat depset. Parameter direct adalah daftar elemen langsung depset, dan parameter transitive adalah daftar depset yang elemennya menjadi elemen tidak langsung depset yang dibuat. Urutan elemen yang ditampilkan saat depset dikonversi menjadi daftar ditentukan oleh parameter order. Lihat Ringkasan depset untuk mengetahui informasi selengkapnya.

Semua elemen (langsung dan tidak langsung) depset harus memiliki jenis yang sama, seperti yang diperoleh oleh ekspresi type(x).

Karena set berbasis hash digunakan untuk menghilangkan duplikat selama iterasi, semua elemen depset harus dapat di-hash. Namun, invarian ini saat ini tidak diperiksa secara konsisten di semua konstruktor. Gunakan flag --incompatible_always_check_depset_elements untuk mengaktifkan pemeriksaan yang konsisten; ini akan menjadi perilaku default dalam rilis mendatang; lihat Masalah 10313.

Selain itu, elemen saat ini tidak boleh diubah, meskipun pembatasan ini akan dilonggarkan pada masa mendatang.

Urutan depset yang dibuat harus kompatibel dengan urutan depset transitive-nya. Urutan "default" kompatibel dengan urutan lainnya, semua urutan lainnya hanya kompatibel dengan dirinya sendiri.

Parameter

Parameter Deskripsi
direct sequence; atau None; defaultnya adalah None
Daftar elemen direct dari depset.
order string; default adalah "default"
Strategi traversal untuk depset baru. Lihat di sini untuk mengetahui kemungkinan nilai.
transitive urutan depset; atau None; default adalah None
Daftar depset yang elemennya akan menjadi elemen tidak langsung depset.

exec_group

exec_group exec_group(toolchains=[], exec_compatible_with=[])

Membuat grup eksekusi yang dapat digunakan untuk membuat tindakan bagi platform eksekusi tertentu selama penerapan aturan.

Parameter

Parameter Deskripsi
toolchains sequence; default adalah []
Kumpulan toolchain yang diperlukan grup eksekusi ini. Daftar dapat berisi objek String, Label, atau StarlarkToolchainTypeApi, dalam kombinasi apa pun.
exec_compatible_with urutan string; default adalah []
Daftar batasan pada platform eksekusi.

exec_transition

transition exec_transition(implementation, inputs, outputs)

Versi khusus transition() yang digunakan untuk menentukan transisi eksekusi. Lihat dokumentasi (atau penerapannya) untuk mengetahui praktik terbaik. Hanya dapat digunakan dari bawaan Bazel.

Parameter

Parameter Deskripsi
implementation callable; required
inputs urutan string; wajib
outputs urutan string; wajib

makro

macro macro(implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None)

Menentukan makro simbolis, yang dapat dipanggil dalam file atau makro BUILD (lama atau simbolik) untuk menentukan target – mungkin beberapa target.

Nilai yang ditampilkan oleh macro(...) harus ditetapkan ke variabel global dalam file .bzl; nama variabel global akan menjadi nama simbol makro.

Lihat Makro untuk panduan lengkap tentang cara menggunakan makro simbolis.

Parameter

Parameter Deskripsi
implementation function; required
Fungsi Starlark yang menerapkan makro ini. Nilai atribut makro diteruskan ke fungsi implementasi sebagai argumen kata kunci. Fungsi implementasi harus memiliki minimal dua parameter bernama, name dan visibility, dan jika makro mewarisi atribut (lihat inherit_attrs di bawah), makro harus memiliki parameter kata kunci residu **kwargs.

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 menjadi dependensi.)

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:

attrs dict; default adalah {}
Kamus atribut yang didukung makro ini, yang analog dengan rule.attrs. Kunci adalah nama atribut, dan nilainya adalah objek atribut seperti attr.label_list(...) (lihat modul attr), atau None. Entri None berarti makro tidak memiliki atribut dengan nama tersebut, meskipun makro tersebut akan mewarisi atribut melalui inherit_attrs (lihat di bawah).

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.

inherit_attrs rule; atau macro; atau string; atau None; default adalah None
Simbol aturan, simbol makro, atau nama daftar atribut umum bawaan (lihat di bawah) yang akan digunakan makro untuk mewarisi atribut.

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 diwarisi, 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 menghilangkan 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.

finalizer bool; default adalah False
Apakah makro ini adalah finalisasi aturan, yang merupakan makro yang, terlepas dari posisinya dalam file BUILD, dievaluasi di akhir pemuatan paket, setelah semua target non-finalisasi telah ditentukan.

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, termasuk aturan ini.

doc string; atau None; default adalah None
Deskripsi makro yang dapat diekstrak oleh alat pembuat dokumentasi.

module_extension

unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)

Membuat ekstensi modul baru. Simpan dalam nilai global, sehingga dapat diekspor dan digunakan dalam file MODULE.bazel dengan use_extension.

Parameter

Parameter Deskripsi
implementation callable; required
Fungsi yang mengimplementasikan ekstensi modul ini. Harus menggunakan satu parameter, module_ctx. Fungsi ini dipanggil sekali di awal build untuk menentukan kumpulan repo yang tersedia.
tag_classes dict; default adalah {}
Kamus untuk mendeklarasikan semua class tag yang digunakan oleh ekstensi. Class ini memetakan dari nama class tag ke objek tag_class.
doc string; atau None; default adalah None
Deskripsi ekstensi modul yang dapat diekstrak oleh alat pembuat dokumentasi.
environ urutan string; default adalah []
Memberikan daftar variabel lingkungan yang menjadi dependensi ekstensi modul ini. Jika variabel lingkungan dalam daftar tersebut berubah, ekstensi akan dievaluasi ulang.
os_dependent bool; defaultnya adalah False
Menunjukkan apakah ekstensi ini bergantung pada OS atau tidak
arch_dependent bool; defaultnya adalah False
Menunjukkan apakah ekstensi ini bergantung pada arsitektur atau tidak

provider

unknown provider(doc=None, *, fields=None, init=None)

Menentukan simbol penyedia. Nilai yang dihasilkan dari fungsi ini harus disimpan dalam nilai global agar dapat digunakan dalam penerapan aturan atau aspek. Penyedia dapat dibuat instance-nya dengan memanggil nilai yang dihasilkan sebagai fungsi, atau digunakan langsung sebagai kunci indeks untuk mengambil instance penyedia tersebut dari target. Contoh:
MyInfo = provider()
...
def _my_library_impl(ctx):
    ...
    my_info = MyInfo(x = 2, y = 3)
    # my_info.x == 2
    # my_info.y == 3
    ...

Lihat Aturan (Penyedia) untuk panduan komprehensif tentang cara menggunakan penyedia.

Menampilkan nilai yang dapat dipanggil Provider jika init tidak ditentukan.

Jika init ditentukan, akan menampilkan tuple dari 2 elemen: nilai yang dapat dipanggil Provider dan nilai yang dapat dipanggil konstruktor mentah. Lihat Aturan (Inisialisasi kustom penyedia kustom) dan diskusi tentang parameter init di bawah untuk mengetahui detailnya.

Parameter

Parameter Deskripsi
doc string; atau None; default adalah None
Deskripsi penyedia yang dapat diekstrak oleh alat pembuat dokumentasi.
fields urutan string; atau dict; atau None; defaultnya adalah None
Jika ditentukan, akan membatasi kumpulan kolom yang diizinkan.
Nilai yang mungkin adalah:
  • daftar kolom:
    provider(fields = ['a', 'b'])

  • nama kolom kamus -> dokumentasi:
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
Semua kolom bersifat opsional.
init callable; atau None; default adalah None
Callback opsional untuk memproses dan memvalidasi nilai kolom penyedia selama pembuatan instance. Jika init ditentukan, provider() akan menampilkan tuple dari 2 elemen: simbol penyedia normal dan konstruktor mentah.

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.
Jika callback init tidak diberikan, panggilan ke simbol P itu sendiri akan bertindak sebagai panggilan ke fungsi konstruktor default c; dengan kata lain, P(*args, **kwargs) menampilkan c(*args, **kwargs). Misalnya,
MyInfo = provider()
m = MyInfo(foo = 1)
akan membuatnya secara langsung sehingga m adalah instance MyInfo dengan m.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 = ...)

repository_rule

callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None)

Membuat aturan repositori baru. Simpan dalam nilai global, sehingga dapat dimuat dan dipanggil dari fungsi implementasi module_extension(), atau digunakan oleh use_repo_rule().

Parameter

Parameter Deskripsi
implementation callable; required
fungsi yang menerapkan aturan ini. Harus memiliki satu parameter, repository_ctx. Fungsi ini dipanggil selama fase pemuatan untuk setiap instance aturan.
attrs dict; atau None; default adalah None
Kamus untuk mendeklarasikan semua atribut aturan repositori. Pemetaan ini dilakukan dari nama atribut ke objek atribut (lihat modul attr). Atribut yang diawali dengan _ bersifat pribadi, dan dapat digunakan untuk menambahkan dependensi implisit pada label ke file (aturan repositori tidak dapat bergantung pada artefak yang dihasilkan). Atribut name ditambahkan secara implisit dan tidak boleh ditentukan.

Atribut yang dideklarasikan akan mengonversi None ke nilai default.
local bool; default adalah False
Menunjukkan bahwa aturan ini mengambil semua dari sistem lokal dan harus dievaluasi ulang pada setiap pengambilan.
environ urutan string; defaultnya adalah []
Tidak digunakan lagi. Parameter ini tidak digunakan lagi. Migrasikan ke repository_ctx.getenv.
Menyediakan daftar variabel lingkungan yang menjadi dependensi aturan repositori ini. Jika variabel lingkungan dalam daftar tersebut berubah, repositori akan diambil ulang.
configure bool; default adalah False
Menunjukkan bahwa repositori memeriksa sistem untuk tujuan konfigurasi
remotable bool; default-nya adalah False
Eksperimental. Parameter ini bersifat eksperimental dan dapat berubah sewaktu-waktu. Jangan bergantung pada hal ini. Fitur ini dapat diaktifkan secara eksperimental dengan menetapkan --experimental_repo_remote_exec
Kompatibel dengan eksekusi jarak jauh
doc string; atau None; default adalah None
Deskripsi aturan repositori yang dapat diekstrak oleh alat pembuat dokumentasi.

aturan

callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])

Membuat aturan baru, yang dapat dipanggil dari file BUILD atau makro untuk membuat target.

Aturan harus ditetapkan ke variabel global dalam file .bzl; nama variabel global adalah nama aturan.

Aturan pengujian harus memiliki nama yang diakhiri dengan _test, sedangkan semua aturan lainnya tidak boleh memiliki akhiran ini. (Pembatasan ini hanya berlaku untuk aturan, bukan untuk targetnya.)

Parameter

Parameter Deskripsi
implementation function; required
fungsi Starlark yang menerapkan aturan ini, harus memiliki tepat satu parameter: ctx. Fungsi ini dipanggil selama fase analisis untuk setiap instance aturan. Fungsi ini dapat mengakses atribut yang diberikan oleh pengguna. Fungsi ini harus membuat tindakan untuk menghasilkan semua output yang dideklarasikan.
test bool; default adalah unbound
Apakah aturan ini adalah aturan pengujian, yaitu apakah aturan ini dapat menjadi subjek perintah blaze test. Semua aturan pengujian otomatis dianggap executable; Anda tidak perlu (dan tidak disarankan) menetapkan executable = True secara eksplisit untuk aturan pengujian. Nilai defaultnya adalah False. Lihat halaman Aturan untuk mengetahui informasi selengkapnya.
attrs dict; default adalah {}
Kamus untuk mendeklarasikan semua atribut aturan. Pemetaan ini dilakukan dari nama atribut ke objek atribut (lihat modul attr). Atribut yang diawali dengan _ bersifat pribadi, dan dapat digunakan untuk menambahkan dependensi implisit pada label. Atribut name ditambahkan secara implisit dan tidak boleh ditentukan. Atribut visibility, deprecation, tags, testonly, dan features ditambahkan secara implisit dan tidak dapat diganti. Sebagian besar aturan hanya memerlukan beberapa atribut. Untuk membatasi penggunaan memori, ada batas jumlah atribut yang dapat dideklarasikan.

Atribut yang dideklarasikan akan mengonversi None ke nilai default.
outputs dict; atau None; atau function; default adalah None
Tidak digunakan lagi. Parameter ini tidak digunakan lagi dan akan segera dihapus. Jangan bergantung pada hal ini. Fitur ini dinonaktifkan dengan --incompatible_no_rule_outputs_param. Gunakan tanda ini untuk memverifikasi bahwa kode Anda kompatibel dengan penghapusannya yang akan segera dilakukan.
Parameter ini tidak digunakan lagi. Migrasikan aturan untuk menggunakan OutputGroupInfo atau attr.output.

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 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.

executable bool; default adalah unbound
Apakah aturan ini dianggap dapat dieksekusi, yaitu apakah aturan ini dapat menjadi subjek perintah blaze run. Nilai defaultnya adalah False. Lihat halaman Aturan untuk mengetahui informasi selengkapnya.
output_to_genfiles bool; default adalah False
Jika true, file akan dibuat di direktori genfiles, bukan direktori bin. Kecuali jika Anda memerlukannya untuk kompatibilitas dengan aturan yang ada (misalnya, saat membuat file header untuk C++), jangan tetapkan tanda ini.
fragments urutan string; default adalah []
Daftar nama fragmen konfigurasi yang diperlukan aturan dalam konfigurasi target.
host_fragments urutan string; default adalah []
Daftar nama fragmen konfigurasi yang diperlukan aturan dalam konfigurasi host.
_skylark_testable bool; default adalah False
(Eksperimental)

Jika benar, aturan ini akan mengekspos tindakannya untuk diperiksa oleh aturan yang bergantung padanya melalui penyedia Actions. Penyedia juga tersedia untuk aturan itu sendiri dengan memanggil ctx.created_actions().

Ini hanya boleh digunakan untuk menguji perilaku waktu analisis aturan Starlark. Tanda ini dapat dihapus pada masa mendatang.
toolchains sequence; default-nya adalah []
Jika ditetapkan, kumpulan toolchain yang diperlukan aturan ini. Daftar dapat berisi objek String, Label, atau StarlarkToolchainTypeApi, dalam kombinasi apa pun. Toolchain akan ditemukan dengan memeriksa platform saat ini, dan diberikan ke implementasi aturan melalui ctx.toolchain.
incompatible_use_toolchain_transition bool; default adalah False
Tidak digunakan lagi, ini tidak lagi digunakan dan harus dihapus.
doc string; atau None; default adalah None
Deskripsi aturan yang dapat diekstrak oleh alat pembuat dokumentasi.
provides sequence; default adalah []
Daftar penyedia yang harus ditampilkan oleh fungsi implementasi.

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.

dependency_resolution_rule bool; defaultnya adalah False
Jika ditetapkan, aturan dapat menjadi dependensi melalui atribut yang juga ditandai sebagai tersedia di materializer. Setiap atribut aturan dengan flag yang ditetapkan ini juga harus ditandai sebagai tersedia di materializer. Hal ini agar aturan yang ditandai tidak dapat bergantung pada aturan yang tidak ditandai.
exec_compatible_with urutan string; default adalah []
Daftar batasan pada platform eksekusi yang berlaku untuk semua target jenis aturan ini.
analysis_test bool; default adalah False
Jika benar, aturan ini akan diperlakukan sebagai pengujian analisis.

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). Nilai ini menggantikan nilai test
  • Fungsi penerapan aturan mungkin tidak mendaftarkan tindakan. Sebagai gantinya, aplikasi harus mendaftarkan hasil lulus/gagal melalui penyediaan AnalysisTestResultInfo.
build_setting BuildSetting; atau None; default-nya adalah None
Jika ditetapkan, menjelaskan jenis build setting aturan ini. Lihat modul config. Jika ditetapkan, atribut wajib bernama "build_setting_default" akan otomatis ditambahkan ke aturan ini, dengan jenis yang sesuai dengan nilai yang diteruskan di sini.
cfg default adalah None
Jika ditetapkan, akan mengarah ke transisi konfigurasi yang akan diterapkan aturan ke konfigurasinya sendiri sebelum analisis.
exec_groups dict; atau None; default adalah None
Dict nama grup eksekusi (string) ke exec_groups. Jika ditetapkan, aturan dapat menjalankan tindakan di beberapa platform eksekusi dalam satu target. Lihat dokumentasi grup eksekusi untuk mengetahui info selengkapnya.
initializer default adalah None
Eksperimental: fungsi Stalark yang melakukan inisialisasi atribut aturan.

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.

parent default adalah None
Eksperimental: aturan Stalark yang diperluas. Saat ditetapkan, atribut publik akan digabungkan serta penyedia yang diiklankan. Aturan cocok dengan executable dan test dari induk. Nilai fragments, toolchains, exec_compatible_with, dan exec_groups digabungkan. Parameter lama atau yang tidak digunakan lagi tidak boleh ditetapkan. Transisi konfigurasi masuk cfg induk diterapkan setelah konfigurasi masuk thisrule.
extendable bool; atau Label; atau string; atau None; defaultnya adalah None
Eksperimental: Label daftar yang diizinkan yang menentukan aturan mana yang dapat memperluas aturan ini. Nilai ini juga dapat ditetapkan ke True/False untuk selalu mengizinkan/melarang perpanjangan. Bazel secara default selalu mengizinkan ekstensi.
subrules urutan Subaturan; default adalah []
Eksperimental: Daftar subaturan yang digunakan oleh aturan ini.

pilih

unknown select(x, no_match_error='')

select() adalah fungsi bantuan yang membuat atribut aturan dapat dikonfigurasi. Lihat ensiklopedi build untuk mengetahui detailnya.

Parameter

Parameter Deskripsi
x dict; required
Dict yang memetakan kondisi konfigurasi ke nilai. Setiap kunci adalah Label atau string label yang mengidentifikasi instance config_setting atau constraint_value. Lihat dokumentasi tentang makro untuk mengetahui kapan harus menggunakan Label, bukan string.
no_match_error string; defaultnya adalah ''
Error kustom opsional untuk dilaporkan jika tidak ada kondisi yang cocok.

subaturan

Subrule subrule(implementation, attrs={}, toolchains=[], fragments=[], subrules=[])

Membuat instance baru subaturan. Hasil fungsi ini harus disimpan dalam variabel global sebelum dapat digunakan.

Parameter

Parameter Deskripsi
implementation function; required
Fungsi Starlark yang menerapkan subaturan ini
attrs dict; default adalah {}
Kamus untuk mendeklarasikan semua atribut (pribadi) subaturan.

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
toolchains sequence; default adalah []
Jika ditetapkan, kumpulan toolchain yang diperlukan subaturan ini. Daftar dapat berisi objek String, Label, atau StarlarkToolchainTypeApi, dalam kombinasi apa pun. Toolchain akan ditemukan dengan memeriksa platform saat ini, dan diberikan ke implementasi subaturan melalui ctx.toolchains. Perhatikan bahwa AEG harus diaktifkan pada aturan penggunaan jika parameter ini ditetapkan. Jika Anda belum bermigrasi ke AEG, lihat https://bazel.build/extending/auto-exec-groups#migration-aegs.
fragments urutan string; default adalah []
Daftar nama fragmen konfigurasi yang diperlukan subaturan dalam konfigurasi target.
subrules urutan Subaturan; default-nya adalah []
Daftar subaturan lain yang diperlukan oleh subaturan ini.

tag_class

tag_class tag_class(attrs={}, *, doc=None)

Membuat objek tag_class baru, yang menentukan skema atribut untuk class tag, yang merupakan objek data yang dapat digunakan oleh ekstensi modul.

Parameter

Parameter Deskripsi
attrs dict; default adalah {}
Kamus untuk mendeklarasikan semua atribut class tag ini. Pemetaan ini dilakukan dari nama atribut ke objek atribut (lihat modul attr).

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.
doc string; atau None; default adalah None
Deskripsi class tag yang dapat diekstrak oleh alat pembuat dokumentasi.

visibilitas

None visibility(value)

Menetapkan visibilitas pemuatan modul .bzl yang saat ini sedang diinisialisasi.

Visibilitas pemuatan modul mengatur apakah file BUILD dan .bzl lainnya dapat memuat modul atau tidak. (Hal ini berbeda dengan visibilitas target file sumber .bzl yang mendasarinya, yang mengatur apakah file dapat muncul sebagai dependensi target lain.) Visibilitas pemuatan berfungsi di tingkat paket: Untuk memuat modul, file yang melakukan pemuatan harus berada dalam paket yang telah diberi visibilitas ke modul. Modul selalu dapat dimuat dalam paketnya sendiri, terlepas dari visibilitasnya.

visibility() hanya boleh dipanggil sekali per file .bzl, dan hanya di tingkat teratas, bukan di dalam fungsi. Gaya yang lebih disukai adalah menempatkan panggilan ini tepat di bawah pernyataan load() dan logika singkat yang diperlukan untuk menentukan argumen.

Jika tanda --check_bzl_visibility disetel ke salah (false), pelanggaran visibilitas pemuatan akan memunculkan peringatan, tetapi tidak akan membuat build gagal.

Parameter

Parameter Deskripsi
value required
Daftar string spesifikasi paket, atau satu string spesifikasi paket.

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".