पहलू

इस पेज पर, आसपेक्ट के इस्तेमाल के बुनियादी सिद्धांतों और फ़ायदों के बारे में बताया गया है. साथ ही, आसान और बेहतर उदाहरण भी दिए गए हैं.

ऐस्पेक्ट की मदद से, अतिरिक्त जानकारी और कार्रवाइयों के साथ बिल्ड डिपेंडेंसी ग्राफ़ को बेहतर बनाया जा सकता है. कुछ सामान्य स्थितियां, जब पहलू उपयोगी हो सकते हैं:

• बेज़ल को इंटिग्रेट करने वाले आईडीई, प्रोजेक्ट के बारे में जानकारी इकट्ठा करने के लिए, पहलुओं का इस्तेमाल कर सकते हैं.
• कोड जनरेशन टूल, अपने इनपुट पर टारगेट के हिसाब से काम करने के लिए, अलग-अलग पहलुओं का फ़ायदा ले सकते हैं. उदाहरण के लिए, BUILD फ़ाइलें protobuf लाइब्रेरी की परिभाषाओं की हैरारकी तय कर सकती हैं. साथ ही, भाषा के हिसाब से बने नियम, किसी खास भाषा के लिए protobuf सहायता कोड जनरेट करने वाली कार्रवाइयों को अटैच करने के लिए, आसपेक्ट का इस्तेमाल कर सकते हैं.

आसपेक्ट से जुड़ी बुनियादी बातें

BUILD फ़ाइलें, किसी प्रोजेक्ट के सोर्स कोड के बारे में जानकारी देती हैं: प्रोजेक्ट में कौनसी सोर्स फ़ाइलें शामिल हैं, उन फ़ाइलों से कौनसे आर्टफ़ैक्ट (टारगेट) बनाए जाने चाहिए, उन फ़ाइलों के बीच कौनसी डिपेंडेंसी हैं वगैरह. Bazel, बिल्ड करने के लिए इस जानकारी का इस्तेमाल करता है. इसका मतलब है कि यह आर्टफ़ैक्ट बनाने के लिए ज़रूरी कार्रवाइयों (जैसे, कंपाइलर या लिंकर चलाना) का सेट तय करता है और उन कार्रवाइयों को पूरा करता है. Baज़ल, टारगेट के बीच एक डिपेंडेंसी ग्राफ़ बनाकर और उन कार्रवाइयों को इकट्ठा करने के लिए इस ग्राफ़ पर जाकर ऐसा करता है.

यह BUILD फ़ाइल देखें:

java_library(name = 'W', ...)
java_library(name = 'Y', deps = [':W'], ...)
java_library(name = 'Z', deps = [':W'], ...)
java_library(name = 'Q', ...)
java_library(name = 'T', deps = [':Q'], ...)
java_library(name = 'X', deps = [':Y',':Z'], runtime_deps = [':T'], ...)

यह BUILD फ़ाइल, डिपेंडेंसी वाले ग्राफ़ के बारे में बताती है. यह ग्राफ़ नीचे दी गई इमेज में दिखाया गया है:

पहला डायग्राम. BUILD फ़ाइल डिपेंडेंसी ग्राफ़.

Baज़ल, इस डिपेंडेंसी ग्राफ़ का विश्लेषण करने के लिए, ऊपर दिए गए उदाहरण में मौजूद हर टारगेट के लिए, इससे जुड़े नियम (इस मामले में "java_library") को लागू करने के फ़ंक्शन को कॉल करते हैं. नियम लागू करने वाले फ़ंक्शन, ऐसी कार्रवाइयां जनरेट करते हैं जो आर्टफ़ैक्ट बनाती हैं, जैसे कि .jar फ़ाइलें. साथ ही, इन फ़ंक्शन के ज़रिए वे जगहें और नाम जैसी जानकारी, मोबाइल और इंटरनेट सेवा देने वाली कंपनियों के टारगेट की डिपेंडेंसी के हिसाब से भेजी जाती है.

आसपेक्ट, नियमों से मिलते-जुलते होते हैं. इनमें लागू करने का एक फ़ंक्शन होता है, जो कार्रवाइयां जनरेट करता है और सेवा देता है. हालांकि, इनकी ताकत इस बात पर निर्भर करती है कि उनके लिए डिपेंडेंसी ग्राफ़ कैसे बनाया गया है. किसी पहलू को लागू करने का तरीका और उन सभी एट्रिब्यूट की सूची होती है जिन्हें वह प्रॉडक्ट के साथ दिखाता है. ऐसे पहलू A पर विचार करें जो "deps" नाम के एट्रिब्यूट के साथ लागू होता है. इस पहलू को ऐसे टारगेट X पर लागू किया जा सकता है जिससे आसपेक्ट ऐप्लिकेशन नोड A(X) मिलता है. लागू करने के दौरान, ऐस्पेक्ट A को उन सभी टारगेट पर बार-बार लागू किया जाता है जिनके बारे में X अपने "deps" एट्रिब्यूट (A की प्रॉपेगेशन सूची में मौजूद सभी एट्रिब्यूट) में बताता है.

इस तरह, किसी टारगेट X पर एस्पेक्ट A लागू करने से, टारगेट के मूल डिपेंडेंसी ग्राफ़ का "शैडो ग्राफ़" बन जाता है. यह ग्राफ़, नीचे दिए गए चित्र में दिखाया गया है:

दूसरी इमेज. अलग-अलग पहलुओं के साथ ग्राफ़ बनाएं.

सिर्फ़ प्रॉपेगेशन सेट में मौजूद एट्रिब्यूट के किनारों को ही शेडो किया जाता है. इसलिए, इस उदाहरण में runtime_deps एज को शेडो नहीं किया गया है. इसके बाद, शैडो ग्राफ़ के सभी नोड पर, ऐस्पेक्ट लागू करने वाला फ़ंक्शन लागू किया जाता है. यह उसी तरह होता है जिस तरह ओरिजनल ग्राफ़ के नोड पर नियम लागू किए जाते हैं.

आसान उदाहरण

इस उदाहरण में, एक नियम और इसकी deps एट्रिब्यूट वाली सभी डिपेंडेंसी के लिए सोर्स फ़ाइलों को बार-बार प्रिंट करने का तरीका बताया गया है. इसमें, ऐस्पेक्ट लागू करने का तरीका, ऐस्पेक्ट की परिभाषा, और Bazel कमांड लाइन से ऐस्पेक्ट को शुरू करने का तरीका दिखाया गया है.

def _print_aspect_impl(target, ctx):
    # Make sure the rule has a srcs attribute.
    if hasattr(ctx.rule.attr, 'srcs'):
        # Iterate through the files that make up the sources and
        # print their paths.
        for src in ctx.rule.attr.srcs:
            for f in src.files.to_list():
                print(f.path)
    return []

print_aspect = aspect(
    implementation = _print_aspect_impl,
    attr_aspects = ['deps'],
)

आइए, इस उदाहरण को अलग-अलग हिस्सों में बांटकर, हर हिस्से की अलग से जांच करते हैं.

आसपेक्ट की परिभाषा

print_aspect = aspect(
    implementation = _print_aspect_impl,
    attr_aspects = ['deps'],
)

आसपेक्ट की परिभाषाएं, नियम की परिभाषाओं से मेल खाती हैं और इन्हें aspect फ़ंक्शन का इस्तेमाल करके तय किया जाता है.

नियम की तरह ही, किसी पहलू को लागू करने का फ़ंक्शन भी होता है. इस मामले में, यह फ़ंक्शन _print_aspect_impl है.

attr_aspects, नियम के उन एट्रिब्यूट की सूची है जिनके साथ आसपेक्ट लागू होता है. इस मामले में, यह आसपेक्ट उन नियमों के deps एट्रिब्यूट के साथ प्रॉगेट होगा जिन पर इसे लागू किया गया है.

attr_aspects के लिए एक और सामान्य आर्ग्युमेंट ['*'] है, जो किसी नियम के सभी एट्रिब्यूट में एस्पेक्ट को प्रॉपैगेट करेगा.

आसपेक्ट को लागू करना

def _print_aspect_impl(target, ctx):
    # Make sure the rule has a srcs attribute.
    if hasattr(ctx.rule.attr, 'srcs'):
        # Iterate through the files that make up the sources and
        # print their paths.
        for src in ctx.rule.attr.srcs:
            for f in src.files.to_list():
                print(f.path)
    return []

आसपेक्ट लागू करने वाले फ़ंक्शन, नियम लागू करने वाले फ़ंक्शन से मिलते-जुलते हैं. ये प्रोवाइडर दिखाते हैं, कार्रवाइयां जनरेट कर सकते हैं, और दो आर्ग्युमेंट लेते हैं:

• target: वह टारगेट जिस पर आसपेक्ट लागू किया जा रहा है.
• ctx: ctx ऑब्जेक्ट, जिसका इस्तेमाल एट्रिब्यूट को ऐक्सेस करने के साथ-साथ, आउटपुट और कार्रवाइयां जनरेट करने के लिए किया जा सकता है.

लागू करने वाला फ़ंक्शन, ctx.rule.attr के ज़रिए टारगेट नियम के एट्रिब्यूट ऐक्सेस कर सकता है. यह उन प्रोवाइडर की जांच कर सकता है जिन्हें target आर्ग्युमेंट की मदद से, टारगेट से उपलब्ध कराया जाता है.

सेवा देने वालों की सूची दिखाने के लिए, आसपेक्ट की ज़रूरत होती है. इस उदाहरण में, आसपेक्ट रेशियो कुछ नहीं दिखाता है. इसलिए, यह खाली सूची दिखाता है.

कमांड लाइन का इस्तेमाल करके, ऐस्पेक्ट को चालू करना

किसी आसपेक्ट को लागू करने का सबसे आसान तरीका, कमांड लाइन से --aspects आर्ग्युमेंट का इस्तेमाल करना है. मान लें कि ऊपर दिया गया आसपेक्ट रेशियो, print.bzl नाम की फ़ाइल में तय किया गया था:

bazel build //MyExample:example --aspects print.bzl%print_aspect

print_aspect को टारगेट example और उन सभी टारगेट नियमों पर लागू करेगा जो deps एट्रिब्यूट के ज़रिए बार-बार ऐक्सेस किए जा सकते हैं.

--aspects फ़्लैग में एक आर्ग्युमेंट होता है, जो <extension file label>%<aspect top-level name> फ़ॉर्मैट में आसपेक्ट की जानकारी देता है.

बेहतर उदाहरण

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

file_count.bzl फ़ाइल:

FileCountInfo = provider(
    fields = {
        'count' : 'number of files'
    }
)

def _file_count_aspect_impl(target, ctx):
    count = 0
    # Make sure the rule has a srcs attribute.
    if hasattr(ctx.rule.attr, 'srcs'):
        # Iterate through the sources counting files
        for src in ctx.rule.attr.srcs:
            for f in src.files.to_list():
                if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
                    count = count + 1
    # Get the counts from our dependencies.
    for dep in ctx.rule.attr.deps:
        count = count + dep[FileCountInfo].count
    return [FileCountInfo(count = count)]

file_count_aspect = aspect(
    implementation = _file_count_aspect_impl,
    attr_aspects = ['deps'],
    attrs = {
        'extension' : attr.string(values = ['*', 'h', 'cc']),
    }
)

def _file_count_rule_impl(ctx):
    for dep in ctx.attr.deps:
        print(dep[FileCountInfo].count)

file_count_rule = rule(
    implementation = _file_count_rule_impl,
    attrs = {
        'deps' : attr.label_list(aspects = [file_count_aspect]),
        'extension' : attr.string(default = '*'),
    },
)

BUILD.bazel फ़ाइल:

load('//:file_count.bzl', 'file_count_rule')

cc_library(
    name = 'lib',
    srcs = [
        'lib.h',
        'lib.cc',
    ],
)

cc_binary(
    name = 'app',
    srcs = [
        'app.h',
        'app.cc',
        'main.cc',
    ],
    deps = ['lib'],
)

file_count_rule(
    name = 'file_count',
    deps = ['app'],
    extension = 'h',
)

आसपेक्ट की परिभाषा

file_count_aspect = aspect(
    implementation = _file_count_aspect_impl,
    attr_aspects = ['deps'],
    attrs = {
        'extension' : attr.string(values = ['*', 'h', 'cc']),
    }
)

इस उदाहरण में दिखाया गया है कि deps एट्रिब्यूट की मदद से, आसपेक्ट रेशियो कैसे लागू होता है.

attrs किसी आसपेक्ट के लिए एट्रिब्यूट के सेट के बारे में बताता है. सार्वजनिक आसपेक्ट एट्रिब्यूट, string टाइप के होते हैं और इन्हें पैरामीटर कहा जाता है. पैरामीटर में values एट्रिब्यूट की वैल्यू मौजूद होनी चाहिए. इस उदाहरण में extension नाम का एक पैरामीटर है, जिसकी वैल्यू '*', 'h' या 'cc' हो सकती है.

आसपेक्ट के लिए पैरामीटर वैल्यू, स्ट्रिंग एट्रिब्यूट से ली जाती हैं. इस एट्रिब्यूट का नाम वही होता है जो आसपेक्ट रेशियो का अनुरोध करता है. (file_count_rule की परिभाषा देखें). पैरामीटर वाले आसपेक्टों को कमांड लाइन के ज़रिए इस्तेमाल नहीं किया जा सकता, क्योंकि पैरामीटर को तय करने के लिए कोई सिंटैक्स नहीं होता.

ऐसेट में label या label_list टाइप के निजी एट्रिब्यूट भी हो सकते हैं. निजी लेबल एट्रिब्यूट का इस्तेमाल, उन टूल या लाइब्रेरी पर निर्भरता बताने के लिए किया जा सकता है जो ऐसेट से जनरेट की गई कार्रवाइयों के लिए ज़रूरी हैं. इस उदाहरण में कोई निजी एट्रिब्यूट तय नहीं किया गया है. हालांकि, नीचे दिए गए कोड स्निपेट से पता चलता है कि किसी टूल को किसी पहलू में कैसे पास किया जा सकता है:

...
    attrs = {
        '_protoc' : attr.label(
            default = Label('//tools:protoc'),
            executable = True,
            cfg = "exec"
        )
    }
...

आसपेक्ट को लागू करना

FileCountInfo = provider(
    fields = {
        'count' : 'number of files'
    }
)

def _file_count_aspect_impl(target, ctx):
    count = 0
    # Make sure the rule has a srcs attribute.
    if hasattr(ctx.rule.attr, 'srcs'):
        # Iterate through the sources counting files
        for src in ctx.rule.attr.srcs:
            for f in src.files.to_list():
                if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
                    count = count + 1
    # Get the counts from our dependencies.
    for dep in ctx.rule.attr.deps:
        count = count + dep[FileCountInfo].count
    return [FileCountInfo(count = count)]

नियम लागू करने वाले फ़ंक्शन की तरह ही, किसी एस्पेक्ट को लागू करने वाला फ़ंक्शन, उन प्रोवाइडर का स्ट्रक्चर दिखाता है जिन्हें उसकी डिपेंडेंसी ऐक्सेस कर सकती हैं.

इस उदाहरण में, FileCountInfo को सेवा देने वाली ऐसी कंपनी के तौर पर दिखाया गया है जिसके पास एक फ़ील्ड count है. fields एट्रिब्यूट का इस्तेमाल करके, सेवा देने वाली कंपनी के फ़ील्ड के बारे में साफ़ तौर पर बताना सबसे सही तरीका है.

किसी ऐस्पेक्ट ऐप्लिकेशन A(X) के लिए, सेवा देने वाली कंपनियों का सेट, उन कंपनियों का यूनियन होता है जो टारगेट X के लिए नियम लागू करने और ऐस्पेक्ट A को लागू करने से मिलती हैं. नियम लागू करने पर, प्रोवाइडर को बनाया और फ़्रीज़ किया जाता है. ऐसा, ऐस्पेक्ट लागू होने से पहले किया जाता है. साथ ही, ऐस्पेक्ट से इनमें बदलाव नहीं किया जा सकता. अगर किसी टारगेट और उस पर लागू किए गए किसी एस्पेक्ट में, एक ही तरह के प्रोवाइडर का इस्तेमाल किया जाता है, तो गड़बड़ी होती है. हालांकि, OutputGroupInfo (जब तक नियम और एस्पेक्ट में अलग-अलग आउटपुट ग्रुप तय किए जाते हैं, तब तक मर्ज किया जाता है) और InstrumentedFilesInfo (जो एस्पेक्ट से लिया जाता है) के मामले में ऐसा नहीं होता. इसका मतलब है कि हो सकता है कि आसपेक्ट लागू करने पर, DefaultInfo कभी न दिखे.

पैरामीटर और निजी एट्रिब्यूट, ctx के एट्रिब्यूट में पास किए जाते हैं. इस उदाहरण में extension पैरामीटर का रेफ़रंस दिया गया है. साथ ही, यह तय किया गया है कि किन फ़ाइलों की गिनती की जाए.

सेवा देने वाली वापस कंपनियों के लिए, पहलू को लागू करने वाले एट्रिब्यूट की वैल्यू (attr_aspects सूची से) को, पहलू को लागू करने के नतीजों से बदल दिया जाता है. उदाहरण के लिए, अगर target X के डिपेंडेंसी में Y और Z हैं, तो A(X) के लिए ctx.rule.attr.deps [A(Y), A(Z)] होगा. इस उदाहरण में, ctx.rule.attr.deps ऐसे टारगेट ऑब्जेक्ट हैं जो उस ओरिजनल टारगेट के 'डिपेंडेंसी' पर ऐस्पेक्ट लागू करने के नतीजे हैं जिस पर ऐस्पेक्ट लागू किया गया है.

उदाहरण में, एस्पेक्ट, टारगेट की डिपेंडेंसी से FileCountInfo प्रोवाइडर को ऐक्सेस करता है, ताकि फ़ाइलों की कुल ट्रांज़िशन संख्या इकट्ठा की जा सके.

किसी नियम से एस्पेक्ट को लागू करना

def _file_count_rule_impl(ctx):
    for dep in ctx.attr.deps:
        print(dep[FileCountInfo].count)

file_count_rule = rule(
    implementation = _file_count_rule_impl,
    attrs = {
        'deps' : attr.label_list(aspects = [file_count_aspect]),
        'extension' : attr.string(default = '*'),
    },
)

नियम लागू करने से पता चलता है कि ctx.attr.deps के ज़रिए FileCountInfo को कैसे ऐक्सेस किया जा सकता है.

नियम की परिभाषा से पता चलता है कि किसी पैरामीटर (extension) को कैसे तय किया जाता है और उसे डिफ़ॉल्ट वैल्यू (*) कैसे दी जाती है. ध्यान दें कि आसपेक्ट रेशियो की परिभाषा में पैरामीटर पर लगाई गई पाबंदियों की वजह से, 'cc', 'h' या '*' में से किसी एक के अलावा कोई दूसरी डिफ़ॉल्ट वैल्यू देने पर गड़बड़ी होगी.

टारगेट नियम की मदद से किसी पहलू को लागू करना

load('//:file_count.bzl', 'file_count_rule')

cc_binary(
    name = 'app',
...
)

file_count_rule(
    name = 'file_count',
    deps = ['app'],
    extension = 'h',
)

इस उदाहरण में, नियम की मदद से extension पैरामीटर को ऐस्पेक्ट में पास करने का तरीका बताया गया है. नियम लागू करने में, extension पैरामीटर की डिफ़ॉल्ट वैल्यू होती है. इसलिए, extension को वैकल्पिक पैरामीटर माना जाएगा.

file_count टारगेट बनने के बाद, हमारे ऐस्पेक्ट का आकलन खुद के लिए किया जाएगा. साथ ही, deps के ज़रिए बार-बार ऐक्सेस किए जा सकने वाले सभी टारगेट का आकलन भी किया जाएगा.