การสร้างมาโครเชิงสัญลักษณ์

สำคัญ: บทแนะนำนี้มีไว้สำหรับมาโครสัญลักษณ์ ซึ่งเป็นระบบมาโครใหม่ที่เปิดตัวใน Bazel 8 หากต้องการรองรับ Bazel เวอร์ชันเก่า คุณจะต้องเขียนมาโครเดิมแทน โปรดดูการสร้างมาโครเดิม

สมมติว่าคุณต้องเรียกใช้เครื่องมือเป็นส่วนหนึ่งของการสร้าง เช่น คุณอาจต้องการสร้างหรือประมวลผลไฟล์ต้นฉบับก่อน หรือบีบอัดไฟล์ไบนารี ในบทแนะนำนี้ คุณจะได้สร้างมาโครเชิงสัญลักษณ์ที่จะปรับขนาดรูปภาพ

มาโครเหมาะสำหรับงานง่ายๆ หากต้องการทําอะไรที่ซับซ้อนขึ้น เช่น เพิ่มการรองรับภาษาโปรแกรมใหม่ ให้ลองสร้างกฎ กฎช่วยให้คุณควบคุมและมีความยืดหยุ่นมากขึ้น

วิธีที่ง่ายที่สุดในการสร้างมาโครที่ปรับขนาดรูปภาพคือการใช้ genrule

genrule(
    name = "logo_miniature",
    srcs = ["logo.png"],
    outs = ["small_logo.png"],
    cmd = "convert $< -resize 100x100 $@",
)

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    data = [":logo_miniature"],
)

หากต้องการปรับขนาดรูปภาพเพิ่มเติม คุณอาจต้องนำรหัสดังกล่าวมาใช้ซ้ำ โดยให้กำหนดฟังก์ชันการใช้งานและประกาศมาโครในไฟล์ .bzl แยกต่างหาก แล้วเรียกไฟล์ miniature.bzl ดังนี้

# Implementation function
def _miniature_impl(name, visibility, src, size, **kwargs):
    native.genrule(
        name = name,
        visibility = visibility,
        srcs = [src],
        outs = [name + "_small_" + src.name],
        cmd = "convert $< -resize " + size + " $@",
        **kwargs,
    )

# Macro declaration
miniature = macro(
    doc = """Create a miniature of the src image.

    The generated file name will be prefixed with `name + "_small_"`.
    """,
    implementation = _miniature_impl,
    # Inherit most of genrule's attributes (such as tags and testonly)
    inherit_attrs = native.genrule,
    attrs = {
        "src": attr.label(
            doc = "Image file",
            allow_single_file = True,
            # Non-configurable because our genrule's output filename is
            # suffixed with src's name. (We want to suffix the output file with
            # srcs's name because some tools that operate on image files expect
            # the files to have the right file extension.)
            configurable = False,
        ),
        "size": attr.string(
            doc = "Output size in WxH format",
            default = "100x100",
        ),
        # Do not allow callers of miniature() to set srcs, cmd, or outs -
        # _miniature_impl overrides their values when calling native.genrule()
        "srcs": None,
        "cmd": None,
        "outs": None,
    },
)

หมายเหตุบางประการมีดังนี้

• ฟังก์ชันการใช้งานมาโครเชิงสัญลักษณ์ต้องมีพารามิเตอร์ name และ visibility ควรใช้กับเป้าหมายหลักของมาโคร

• หากต้องการบันทึกลักษณะการทํางานของมาโครเชิงสัญลักษณ์ ให้ใช้พารามิเตอร์ doc สำหรับ macro() และแอตทริบิวต์

• หากต้องการเรียก genrule หรือกฎเนทีฟอื่นๆ ให้ใช้ native.

• ใช้ **kwargs เพื่อส่งต่ออาร์กิวเมนต์ที่รับค่ามาเพิ่มเติมไปยัง genrule ที่อยู่เบื้องหลัง (ทำงานเหมือนกับใน Python) ซึ่งมีประโยชน์เพื่อให้ผู้ใช้ตั้งค่าแอตทริบิวต์มาตรฐานได้ เช่น tags หรือ testonly

ตอนนี้ให้ใช้มาโครจากไฟล์ BUILD โดยทำดังนี้

load("//path/to:miniature.bzl", "miniature")

miniature(
    name = "logo_miniature",
    src = "image.png",
)

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    data = [":logo_miniature"],
)