Makro

Halaman ini membahas dasar-dasar penggunaan makro dan menyertakan kasus penggunaan, proses debug, dan konvensi umum.

Makro adalah fungsi yang dipanggil dari file BUILD yang dapat membuat instance aturan. Makro terutama digunakan untuk enkapsulasi dan penggunaan kembali kode dari aturan yang ada dan makro lainnya.

Makro terdiri dari dua ragam: makro simbolis, yang dijelaskan di halaman ini, dan makro lama. Jika memungkinkan, sebaiknya gunakan makro simbolis untuk kejelasan kode.

Makro simbolis menawarkan argumen yang diketik (konversi string ke label, relatif terhadap tempat makro dipanggil) dan kemampuan untuk membatasi serta menentukan visibilitas target yang dibuat. Fungsi ini dirancang agar dapat menerima evaluasi lambat (yang akan ditambahkan dalam rilis Bazel mendatang). Makro simbolis tersedia secara default di Bazel 8. Jika dokumen ini menyebutkan macros, dokumen tersebut mengacu pada makro simbolis.

Contoh makro simbolis yang dapat dieksekusi dapat ditemukan di repositori contoh.

Penggunaan

Makro ditentukan dalam file .bzl dengan memanggil fungsi macro() dengan dua parameter yang diperlukan: attrs dan implementation.

Atribut

attrs menerima kamus nama atribut ke jenis atribut, yang mewakili argumen ke makro. Dua atribut umum – name dan visibility – ditambahkan secara implisit ke semua makro dan tidak disertakan dalam kamus yang diteruskan ke attrs.

# macro/macro.bzl
my_macro = macro(
    attrs = {
        "deps": attr.label_list(mandatory = True, doc = "The dependencies passed to the inner cc_binary and cc_test targets"),
        "create_test": attr.bool(default = False, configurable = False, doc = "If true, creates a test target"),
    },
    implementation = _my_macro_impl,
)

Deklarasi jenis atribut menerima parameter, mandatory, default, dan doc. Sebagian besar jenis atribut juga menerima parameter configurable, yang menentukan apakah atribut menerima select. Jika atributnya adalah configurable, atribut tersebut akan mengurai nilai non-select sebagai select yang tidak dapat dikonfigurasi – "foo" akan menjadi select({"//conditions:default": "foo"}). Pelajari lebih lanjut di pilihan.

Pewarisan atribut

Makro sering kali dimaksudkan untuk menggabungkan aturan (atau makro lain), dan penulis makro sering kali ingin meneruskan sebagian besar atribut simbol yang digabungkan tanpa perubahan, menggunakan **kwargs, ke target utama makro (atau makro dalam utama).

Untuk mendukung pola ini, makro dapat mewarisi atribut dari aturan atau makro lain dengan meneruskan aturan atau simbol makro ke argumen inherit_attrs macro(). (Anda juga dapat menggunakan string khusus "common" bukan aturan atau simbol makro untuk mewarisi atribut umum yang ditentukan untuk semua aturan build Starlark.) Hanya atribut publik yang diwarisi, dan atribut dalam kamus attrs makro itu sendiri akan menggantikan atribut yang diwarisi dengan nama yang sama. Anda juga dapat menghapus atribut yang diwarisi dengan menggunakan None sebagai nilai dalam kamus attrs:

# macro/macro.bzl
my_macro = macro(
    inherit_attrs = native.cc_library,
    attrs = {
        # override native.cc_library's `local_defines` attribute
        local_defines = attr.string_list(default = ["FOO"]),
        # do not inherit native.cc_library's `defines` attribute
        defines = None,
    },
    ...
)

Nilai default atribut turunan yang tidak wajib selalu diganti menjadi None, terlepas dari nilai default definisi atribut asli. Jika Anda perlu memeriksa atau mengubah atribut non-wajib yang diwarisi – misalnya, jika Anda ingin menambahkan tag ke atribut tags yang diwarisi – Anda harus memastikan untuk menangani kasus None dalam fungsi penerapan makro:

# macro/macro.bzl
_my_macro_implementation(name, visibility, tags, **kwargs):
    # Append a tag; tags attr is an inherited non-mandatory attribute, and
    # therefore is None unless explicitly set by the caller of our macro.
    my_tags = (tags or []) + ["another_tag"]
    native.cc_library(
        ...
        tags = my_tags,
        **kwargs,
    )
    ...

Penerapan

implementation menerima fungsi yang berisi logika makro. Fungsi implementasi sering membuat target dengan memanggil satu atau beberapa aturan, dan biasanya bersifat pribadi (diberi nama dengan garis bawah di awal). Secara konvensional, namanya sama dengan makronya, tetapi diawali dengan _ dan diakhiri dengan _impl.

Tidak seperti fungsi penerapan aturan, yang menggunakan satu argumen (ctx) yang berisi referensi ke atribut, fungsi penerapan makro menerima parameter untuk setiap argumen.

# macro/macro.bzl
def _my_macro_impl(name, visibility, deps, create_test):
    cc_library(
        name = name + "_cc_lib",
        deps = deps,
    )

    if create_test:
        cc_test(
            name = name + "_test",
            srcs = ["my_test.cc"],
            deps = deps,
        )

Jika makro mewarisi atribut, fungsi implementasinya harus memiliki parameter kata kunci residual **kwargs, yang dapat diteruskan ke panggilan yang memanggil aturan atau submakro yang diwarisi. (Tindakan ini membantu memastikan bahwa makro Anda tidak akan rusak jika aturan atau makro yang diwarisi menambahkan atribut baru.)

Pernyataan

Makro dideklarasikan dengan memuat dan memanggil definisinya dalam file BUILD. ```starlark

pkg/BUILD

my_macro( name = "macro_instance", deps = ["src.cc"] + select( { "//config_setting:special": ["special_source.cc"], "//conditions:default": [], }, ), create_tests = True, ) ```

Tindakan ini akan membuat target //pkg:macro_instance_cc_lib dan//pkg:macro_instance_test.

Sama seperti dalam panggilan aturan, jika nilai atribut dalam panggilan makro ditetapkan ke None, atribut tersebut akan diperlakukan seolah-olah dihilangkan oleh pemanggil makro. Misalnya, dua panggilan makro berikut setara:

# pkg/BUILD
my_macro(name = "abc", srcs = ["src.cc"], deps = None)
my_macro(name = "abc", srcs = ["src.cc"])

Hal ini umumnya tidak berguna dalam file BUILD, tetapi berguna saat menggabungkan makro secara terprogram di dalam makro lain.

Detail

Konvensi penamaan untuk target yang dibuat

Nama target atau submakro apa pun yang dibuat oleh makro simbolis harus cocok dengan parameter name makro atau harus diawali dengan name, diikuti dengan _ (lebih disukai), ., atau -. Misalnya, my_macro(name = "foo") hanya boleh membuat file atau target bernama foo, atau diawali dengan foo_, foo-, atau foo., misalnya, foo_bar.

Target atau file yang melanggar konvensi penamaan makro dapat dideklarasikan, tetapi tidak dapat di-build dan tidak dapat digunakan sebagai dependensi.

File dan target non-makro dalam paket yang sama dengan instance makro harus tidak memiliki nama yang bertentangan dengan nama target makro potensial, meskipun eksklusivitas ini tidak diterapkan. Kami sedang dalam proses menerapkan evaluasi lambat sebagai peningkatan performa untuk makro Simbolik, yang akan terganggu dalam paket yang melanggar skema penamaan.

Pembatasan

Makro simbolis memiliki beberapa batasan tambahan dibandingkan dengan makro lama.

Makro simbolis

  • harus menggunakan argumen name dan argumen visibility
  • harus memiliki fungsi implementation
  • mungkin tidak menampilkan nilai
  • tidak boleh memutasi argumennya
  • tidak boleh memanggil native.existing_rules() kecuali jika merupakan makro finalizer khusus
  • mungkin tidak memanggil native.package()
  • mungkin tidak memanggil glob()
  • mungkin tidak memanggil native.environment_group()
  • harus membuat target yang namanya mematuhi skema penamaan
  • tidak dapat merujuk ke file input yang tidak dideklarasikan atau diteruskan sebagai argumen
  • tidak dapat merujuk ke target pribadi pemanggilnya (lihat visibilitas dan makro untuk detail selengkapnya).

Visibilitas dan makro

Sistem visibilitas membantu melindungi detail implementasi makro (simbolik) dan pemanggilnya.

Secara default, target yang dibuat dalam makro simbolis terlihat dalam makro itu sendiri, tetapi tidak selalu terlihat oleh pemanggil makro. Makro dapat "mengekspor" target sebagai API publik dengan meneruskan nilai atribut visibility-nya sendiri, seperti dalam some_rule(..., visibility = visibility).

Ide utama visibilitas makro adalah:

  1. Visibilitas diperiksa berdasarkan makro yang mendeklarasikan target, bukan paket yang memanggil makro.

    • Dengan kata lain, berada dalam paket yang sama tidak akan membuat satu target terlihat oleh target lainnya. Hal ini melindungi target internal makro agar tidak menjadi dependensi makro lain atau target tingkat atas dalam paket.

  2. Semua atribut visibility, baik pada aturan maupun makro, secara otomatis menyertakan tempat aturan atau makro dipanggil.

    • Dengan demikian, target dapat dilihat tanpa syarat oleh target lain yang dideklarasikan dalam makro yang sama (atau file BUILD, jika tidak dalam makro).

Dalam praktiknya, hal ini berarti bahwa saat makro mendeklarasikan target tanpa menetapkan visibility-nya, target akan ditetapkan secara default ke internal makro. (Visibilitas default paket tidak berlaku dalam makro.) Mengekspor target berarti target dapat dilihat oleh apa pun yang ditentukan pemanggil makro dalam atribut visibility makro, ditambah paket pemanggil makro itu sendiri, serta kode makro itu sendiri. Cara lain untuk memahaminya adalah visibilitas makro menentukan siapa saja (selain makro itu sendiri) yang dapat melihat target yang diekspor makro.

# tool/BUILD
...
some_rule(
    name = "some_tool",
    visibility = ["//macro:__pkg__"],
)

# macro/macro.bzl

def _impl(name, visibility):
    cc_library(
        name = name + "_helper",
        ...
        # No visibility passed in. Same as passing `visibility = None` or
        # `visibility = ["//visibility:private"]`. Visible to the //macro
        # package only.
    )
    cc_binary(
        name = name + "_exported",
        deps = [
            # Allowed because we're also in //macro. (Targets in any other
            # instance of this macro, or any other macro in //macro, can see it
            # too.)
            name + "_helper",
            # Allowed by some_tool's visibility, regardless of what BUILD file
            # we're called from.
            "//tool:some_tool",
        ],
        ...
        visibility = visibility,
    )

my_macro = macro(implementation = _impl, ...)

# pkg/BUILD
load("//macro:macro.bzl", "my_macro")
...

my_macro(
    name = "foo",
    ...
)

some_rule(
    ...
    deps = [
        # Allowed, its visibility is ["//pkg:__pkg__", "//macro:__pkg__"].
        ":foo_exported",
        # Disallowed, its visibility is ["//macro:__pkg__"] and
        # we are not in //macro.
        ":foo_helper",
    ]
)

Jika my_macro dipanggil dengan visibility = ["//other_pkg:__pkg__"], atau jika paket //pkg telah menetapkan default_visibility ke nilai tersebut, maka //pkg:foo_exported juga dapat digunakan dalam //other_pkg/BUILD atau dalam makro yang ditentukan di //other_pkg:defs.bzl, tetapi //pkg:foo_helper akan tetap dilindungi.

Makro dapat mendeklarasikan bahwa target terlihat oleh paket teman dengan meneruskan visibility = ["//some_friend:__pkg__"] (untuk target internal) atau visibility = visibility + ["//some_friend:__pkg__"] (untuk target yang diekspor). Perhatikan bahwa makro yang mendeklarasikan target dengan visibilitas publik (visibility = ["//visibility:public"]) adalah antipola. Hal ini karena makro tersebut membuat target terlihat oleh setiap paket tanpa syarat, meskipun pemanggil menentukan visibilitas yang lebih terbatas.

Semua pemeriksaan visibilitas dilakukan sehubungan dengan makro simbolis paling dalam yang saat ini berjalan. Namun, ada mekanisme delegasi visibilitas: Jika makro meneruskan label sebagai nilai atribut ke makro dalam, setiap penggunaan label dalam makro dalam akan diperiksa sehubungan dengan makro luar. Lihat halaman visibilitas untuk mengetahui detail selengkapnya.

Ingat bahwa makro lama sepenuhnya transparan untuk sistem visibilitas, dan berperilaku seolah-olah lokasinya adalah file BUILD atau makro simbolis tempat makro tersebut dipanggil.

Memilih

Jika atribut adalah configurable (default) dan nilainya bukan None, fungsi implementasi makro akan melihat nilai atribut sebagai digabungkan dalam select biasa. Hal ini memudahkan penulis makro untuk menemukan bug saat mereka tidak mengantisipasi bahwa nilai atribut dapat berupa select.

Misalnya, pertimbangkan makro berikut:

my_macro = macro(
    attrs = {"deps": attr.label_list()},  # configurable unless specified otherwise
    implementation = _my_macro_impl,
)

Jika my_macro dipanggil dengan deps = ["//a"], hal itu akan menyebabkan _my_macro_impl dipanggil dengan parameter deps-nya ditetapkan ke select({"//conditions:default": ["//a"]}). Jika hal ini menyebabkan fungsi implementasi gagal (misalnya, karena kode mencoba mengindeks ke nilai seperti dalam deps[0], yang tidak diizinkan untuk select), penulis makro kemudian dapat membuat pilihan: mereka dapat menulis ulang makro agar hanya menggunakan operasi yang kompatibel dengan select, atau mereka dapat menandai atribut sebagai tidak dapat dikonfigurasi (attr.label_list(configurable = False)). Opsi kedua memastikan bahwa pengguna tidak diizinkan untuk meneruskan nilai select.

Target aturan membalikkan transformasi ini, dan menyimpan select biasa sebagai nilai tanpa syaratnya; dalam contoh di atas, jika _my_macro_impl mendeklarasikan target aturan my_rule(..., deps = deps), deps target aturan tersebut akan disimpan sebagai ["//a"]. Hal ini memastikan bahwa penggabungan select tidak menyebabkan nilai select sepele disimpan di semua target yang dibuat instance-nya oleh makro.

Jika nilai atribut yang dapat dikonfigurasi adalah None, nilai tersebut tidak digabungkan dalam select. Hal ini memastikan bahwa pengujian seperti my_attr == None masih berfungsi, dan bahwa saat atribut diteruskan ke aturan dengan default yang dihitung, aturan tersebut akan berperilaku dengan benar (yaitu, seolah-olah atribut tidak diteruskan sama sekali). Atribut tidak selalu dapat menggunakan nilai None, tetapi hal ini dapat terjadi untuk jenis attr.label(), dan untuk atribut non-wajib yang diwarisi.

Finalizers

Finalizer aturan adalah makro simbolis khusus yang – terlepas dari posisi leksikalnya dalam file BUILD – dievaluasi pada tahap akhir pemuatan paket, setelah semua target non-finalizer telah ditentukan. Tidak seperti makro simbolis biasa, finalisasi dapat memanggil native.existing_rules(), yang berperilaku sedikit berbeda dengan makro lama: hanya menampilkan kumpulan target aturan non-finalisasi. Finalizer dapat menyatakan status set tersebut atau menentukan target baru.

Untuk mendeklarasikan finalisasi, panggil macro() dengan finalizer = True:

def _my_finalizer_impl(name, visibility, tags_filter):
    for r in native.existing_rules().values():
        for tag in r.get("tags", []):
            if tag in tags_filter:
                my_test(
                    name = name + "_" + r["name"] + "_finalizer_test",
                    deps = [r["name"]],
                    data = r["srcs"],
                    ...
                )
                continue

my_finalizer = macro(
    attrs = {"tags_filter": attr.string_list(configurable = False)},
    implementation = _impl,
    finalizer = True,
)

Kemalasan

PENTING: Kami sedang dalam proses menerapkan perluasan dan evaluasi makro lambat. Fitur ini belum tersedia.

Saat ini, semua makro dievaluasi segera setelah file BUILD dimuat, yang dapat berdampak negatif pada performa untuk target dalam paket yang juga memiliki makro yang tidak terkait dan mahal. Di masa mendatang, makro simbolis non-finalizer hanya akan dievaluasi jika diperlukan untuk build. Skema penamaan awalan membantu Bazel menentukan makro mana yang akan diperluas berdasarkan target yang diminta.

Pemecahan masalah migrasi

Berikut adalah beberapa masalah umum terkait migrasi dan cara memperbaikinya.

  • Panggilan makro lama glob()

Pindahkan panggilan glob() ke file BUILD Anda (atau ke makro lama yang dipanggil dari file BUILD), dan teruskan nilai glob() ke makro simbolis menggunakan atribut daftar label:

# BUILD file
my_macro(
    ...,
    deps = glob(...),
)
  • Makro lama memiliki parameter yang bukan jenis attr starlark yang valid.

Tarik sebanyak mungkin logika ke dalam makro simbolis bertingkat, tetapi tetapkan makro tingkat teratas sebagai makro lama.

  • Makro lama memanggil aturan yang membuat target yang melanggar skema penamaan

Tidak apa-apa, jangan bergantung pada target "yang menyinggung". Pemeriksaan penamaan akan diabaikan secara diam-diam.