การสร้างมาโครเดิม

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

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

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

วิธีที่ง่ายที่สุดในการสร้างมาโครที่ปรับขนาดรูปภาพคือการใช้ 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

def miniature(name, src, size = "100x100", **kwargs):
    """Create a miniature of the src image.

    The generated file is prefixed with 'small_'.
    """
    native.genrule(
        name = name,
        srcs = [src],
        # Note that the line below will fail if `src` is not a filename string
        outs = ["small_" + src],
        cmd = "convert $< -resize " + size + " $@",
        **kwargs
    )

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

• ตามธรรมเนียมแล้ว มาโครเดิมจะมีอาร์กิวเมนต์ name เช่นเดียวกับกฎ

• หากต้องการบันทึกลักษณะการทำงานของมาโครเดิม ให้ใช้ docstring เช่นเดียวกับใน Python

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

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

ตอนนี้ให้ใช้มาโครจากไฟล์ 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"],
)

สุดท้ายคือหมายเหตุคําเตือน: มาโครจะถือว่า src เป็นสตริงชื่อไฟล์ (ไม่เช่นนั้น outs = ["small_" + src] จะใช้งานไม่ได้) ดังนั้น src = "image.png" จึงใช้งานได้ แต่จะเกิดอะไรขึ้นหากไฟล์ BUILD ใช้ src = "//other/package:image.png" หรือแม้แต่ src = select(...) แทน

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