लेगसी मैक्रो बनाना

अहम जानकारी: यह ट्यूटोरियल, लेगसी मैक्रो के लिए है. अगर आपको सिर्फ़ 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 आर्ग्युमेंट होता है.

• किसी लेगसी मैक्रो के काम करने के तरीके को दस्तावेज़ में शामिल करने के लिए, Python की तरह docstring का इस्तेमाल करें.

• genrule या किसी अन्य नेटिव नियम को कॉल करने के लिए, उसके पहले native. लगाएं.

• अतिरिक्त आर्ग्युमेंट को genrule पर फ़ॉरवर्ड करने के लिए, **kwargs का इस्तेमाल करें (यह ठीक वैसे ही काम करता है जैसे कि 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(...) का इस्तेमाल किया जाता है, तो क्या होगा?

आपको अपने मैक्रो के दस्तावेज़ में ऐसी मान्यताओं का एलान करना चाहिए. माफ़ करें, लेगसी मैक्रो, खास तौर पर बड़े मैक्रो, काम के नहीं होते, क्योंकि आपके कोड में ऐसी सभी मान्यताओं को नोटिस करना और उन्हें दस्तावेज़ में शामिल करना मुश्किल हो सकता है. साथ ही, मैक्रो के कुछ उपयोगकर्ता दस्तावेज़ नहीं पढ़ेंगे. हमारा सुझाव है कि अगर हो सके, तो सिंबल मैक्रो का इस्तेमाल करें. इनमें एट्रिब्यूट टाइप की जांच करने की सुविधा पहले से मौजूद होती है.