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

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

• अतिरिक्त आर्ग्युमेंट को, उसके नीचे मौजूद genrule पर फ़ॉरवर्ड करने के लिए, **kwargs का इस्तेमाल करें. यह Python में इस्तेमाल होने वाले **kwargs की तरह ही काम करता है. यह तब काम आता है, जब कोई उपयोगकर्ता 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 = "/versions/8.3.0//other/package:image.png" या src = select(...) का इस्तेमाल किया गया हो, तो क्या होगा?

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