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

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

• **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 = "/versions/8.4.0//other/package:image.png" या src = select(...) का इस्तेमाल किया जाता है, तो क्या होगा?

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