प्लैटफ़ॉर्म और टूलचेन के नियम

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

नियम

• constraint_setting
• constraint_value
• platform
• टूलचेन
• toolchain_type

constraint_setting

constraint_setting(name, default_constraint_value, deprecation, distribs, features, licenses, tags, testonly, visibility)

इस नियम का इस्तेमाल, नए तरह की पाबंदी के लिए किया जाता है. इसके लिए, प्लैटफ़ॉर्म कोई वैल्यू तय कर सकता है. उदाहरण के लिए, "glibc_version" नाम का constraint_setting तय किया जा सकता है. इससे यह पता चलेगा कि प्लैटफ़ॉर्म पर glibc लाइब्रेरी के अलग-अलग वर्शन इंस्टॉल किए जा सकते हैं. ज़्यादा जानकारी के लिए, प्लैटफ़ॉर्म पेज देखें.

हर constraint_setting में, उससे जुड़े constraint_value का एक बड़ा सेट होता है. आम तौर पर, इन्हें एक ही पैकेज में तय किया जाता है. हालांकि, कभी-कभी कोई दूसरा पैकेज, किसी मौजूदा सेटिंग के लिए नई वैल्यू पेश करता है. उदाहरण के लिए, पहले से तय की गई सेटिंग @platforms//cpu:cpu को कस्टम वैल्यू के साथ बढ़ाया जा सकता है, ताकि सीपीयू के ऐसे आर्किटेक्चर को टारगेट करने वाले प्लैटफ़ॉर्म को तय किया जा सके जिसके बारे में कम जानकारी उपलब्ध है.

तर्क

constraint_value

constraint_value(name, constraint_setting, deprecation, distribs, features, licenses, tags, testonly, visibility)

उदाहरण

नीचे दिए गए उदाहरण में, सीपीयू आर्किटेक्चर के लिए पहले से तय की गई constraint_value की नई संभावित वैल्यू बनाई गई है.

constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)

तर्क

प्लैटफ़ॉर्म

platform(name, constraint_values, deprecation, distribs, exec_properties, features, flags, licenses, missing_toolchain_error, parents, remote_execution_properties, required_settings, tags, testonly, visibility)

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

उदाहरण

इससे ऐसे प्लैटफ़ॉर्म के बारे में पता चलता है जो ARM पर Linux चलाने वाले किसी भी एनवायरमेंट के बारे में बताता है.

platform(
    name = "linux_arm",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

प्लैटफ़ॉर्म फ़्लैग

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

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

उदाहरण

platform(
    name = "foo",
    flags = [
        "--dynamic_mode=fully",
        "--//bool_flag",
        "--no//package:other_bool_flag",
    ],
)

इससे foo नाम का प्लैटफ़ॉर्म तय होता है. अगर यह टारगेट प्लैटफ़ॉर्म है (ऐसा इसलिए है, क्योंकि उपयोगकर्ता ने --platforms//:foo को चुना है, ट्रांज़िशन ने //command_line_option:platforms फ़्लैग को ["//:foo"] पर सेट किया है या //:foo को एक्ज़ीक्यूशन प्लैटफ़ॉर्म के तौर पर इस्तेमाल किया गया है), तो दिए गए फ़्लैग कॉन्फ़िगरेशन में सेट किए जाएंगे.

प्लैटफ़ॉर्म और बार-बार इस्तेमाल किए जा सकने वाले फ़्लैग

कुछ फ़्लैग को दोहराए जाने पर, उनकी वैल्यू बढ़ जाती हैं. जैसे, --features, --copt, और config.string(repeatable = True) के तौर पर बनाया गया कोई भी Starlark फ़्लैग. ये फ़्लैग, प्लैटफ़ॉर्म से फ़्लैग सेट करने की सुविधा के साथ काम नहीं करते. इसके बजाय, पिछली सभी वैल्यू हटा दी जाएंगी और उनकी जगह प्लैटफ़ॉर्म से मिली वैल्यू डाल दी जाएंगी.

उदाहरण के लिए, अगर नीचे दिया गया प्लैटफ़ॉर्म है, तो build --platforms=//:repeat_demo --features feature_a --features feature_b को लागू करने पर, --feature फ़्लैग की वैल्यू ["feature_c", "feature_d"] हो जाएगी. इससे, कमांड लाइन पर सेट की गई सुविधाएं हट जाएंगी.

platform(
    name = "repeat_demo",
    flags = [
        "--features=feature_c",
        "--features=feature_d",
    ],
)

इस वजह से, हमारा सुझाव है कि flags एट्रिब्यूट में दोहराए जा सकने वाले फ़्लैग का इस्तेमाल न करें.

प्लैटफ़ॉर्म इनहेरिटेंस

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

किसी प्लैटफ़ॉर्म में कंस्ट्रेंट सेटिंग की वैल्यू की जांच करते समय, सबसे पहले सीधे तौर पर सेट की गई वैल्यू (constraint_values एट्रिब्यूट के ज़रिए) की जांच की जाती है. इसके बाद, पैरंट पर कंस्ट्रेंट की वैल्यू की जांच की जाती है. यह प्रोसेस, पैरंट प्लैटफ़ॉर्म की चेन में बार-बार चलती रहती है. इस तरह, किसी प्लैटफ़ॉर्म पर सीधे तौर पर सेट की गई वैल्यू, पैरंट पर सेट की गई वैल्यू को बदल देंगी.

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

प्लैटफ़ॉर्म, पैरंट प्लैटफ़ॉर्म से (बंद किया गया) remote_execution_properties एट्रिब्यूट भी इनहेरिट कर सकते हैं. ध्यान दें: नए कोड में, इसके बजाय exec_properties का इस्तेमाल किया जाना चाहिए. नीचे दिए गए लॉजिक को लेगसी वर्शन के साथ काम करने के लिए बनाए रखा गया है. हालांकि, इसे आने वाले समय में हटा दिया जाएगा. पेरेंट प्लैटफ़ॉर्म मौजूद होने पर, remote_execution_platform को सेट करने का लॉजिक इस तरह होता है:

1. अगर चाइल्ड प्लैटफ़ॉर्म पर remote_execution_property सेट नहीं है, तो पेरेंट के remote_execution_properties का इस्तेमाल किया जाएगा.
2. अगर चाइल्ड प्लैटफ़ॉर्म पर remote_execution_property सेट है और उसमें लिटरल स्ट्रिंग {PARENT_REMOTE_EXECUTION_PROPERTIES} शामिल है, तो उस मैक्रो को पैरंट प्लैटफ़ॉर्म के remote_execution_property एट्रिब्यूट के कॉन्टेंट से बदल दिया जाएगा.
3. अगर चाइल्ड प्लैटफ़ॉर्म पर remote_execution_property सेट है और उसमें मैक्रो शामिल नहीं है, तो चाइल्ड के remote_execution_property का इस्तेमाल बिना किसी बदलाव के किया जाएगा.

remote_execution_properties को बंद कर दिया गया है और इसे चरणबद्ध तरीके से बंद किया जाएगा. इसलिए, एक ही इनहेरिटेंस चेन में remote_execution_properties और exec_properties को एक साथ इस्तेमाल नहीं किया जा सकता. बंद किए गए remote_execution_properties के बजाय, exec_properties का इस्तेमाल करना बेहतर है.

उदाहरण: कंस्ट्रेंट वैल्यू

platform(
    name = "parent",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)
platform(
    name = "child_a",
    parents = [":parent"],
    constraint_values = [
        "@platforms//cpu:x86_64",
    ],
)
platform(
    name = "child_b",
    parents = [":parent"],
)

इस उदाहरण में, चाइल्ड प्लैटफ़ॉर्म की ये प्रॉपर्टी हैं:

• child_a में कंस्ट्रेंट वैल्यू @platforms//os:linux (पैरंट से इनहेरिट की गई) और @platforms//cpu:x86_64 (सीधे तौर पर प्लैटफ़ॉर्म पर सेट की गई) हैं.
• child_b, पैरंट से सभी कंस्ट्रेंट वैल्यू इनहेरिट करता है और अपनी कोई भी वैल्यू सेट नहीं करता.

उदाहरण: एक्ज़ीक्यूशन प्रॉपर्टी

platform(
    name = "parent",
    exec_properties = {
      "k1": "v1",
      "k2": "v2",
    },
)
platform(
    name = "child_a",
    parents = [":parent"],
)
platform(
    name = "child_b",
    parents = [":parent"],
    exec_properties = {
      "k1": "child"
    }
)
platform(
    name = "child_c",
    parents = [":parent"],
    exec_properties = {
      "k1": ""
    }
)
platform(
    name = "child_d",
    parents = [":parent"],
    exec_properties = {
      "k3": "v3"
    }
)

इस उदाहरण में, चाइल्ड प्लैटफ़ॉर्म की ये प्रॉपर्टी हैं:

• child_a, पैरंट की "exec_properties" को इनहेरिट करता है और अपनी प्रॉपर्टी सेट नहीं करता.
• child_b, पैरंट के exec_properties को इनहेरिट करता है और k1 की वैल्यू को बदलता है. इसका exec_properties यह होगा: { "k1": "child", "k2": "v2" }.
• child_c, पैरंट के exec_properties को इनहेरिट करता है और k1 को अनसेट करता है. इसका exec_properties यह होगा: { "k2": "v2" }.
• child_d को पैरंट प्रॉपर्टी का exec_properties मिलता है. साथ ही, इसमें एक नई प्रॉपर्टी जुड़ जाती है. इसका exec_properties यह होगा: { "k1": "v1", "k2": "v2", "k3": "v3" }.

तर्क

टूल चेन

toolchain(name, deprecation, distribs, exec_compatible_with, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, use_target_platform_constraints, visibility)

यह नियम, किसी टूलचेन के टाइप और उसकी सीमाओं के बारे में बताता है, ताकि टूलचेन रिज़ॉल्यूशन के दौरान उसे चुना जा सके. ज़्यादा जानकारी के लिए, टूलचेन पेज देखें.

तर्क

toolchain_type

toolchain_type(name, compatible_with, deprecation, features, no_match_error, restricted_to, tags, target_compatible_with, testonly, visibility)

इस नियम में, एक नई तरह की टूलचेन के बारे में बताया गया है. यह एक ऐसा सामान्य टारगेट है जो टूल के एक ऐसे क्लास को दिखाता है जो अलग-अलग प्लैटफ़ॉर्म के लिए एक ही भूमिका निभाता है.

ज़्यादा जानकारी के लिए, टूलचेन पेज देखें.

उदाहरण

इससे कस्टम नियम के लिए टूलचेन टाइप तय किया जाता है.

toolchain_type(
    name = "bar_toolchain_type",
)

इसका इस्तेमाल bzl फ़ाइल में किया जा सकता है.

bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        # No `_compiler` attribute anymore.
    },
    toolchains = ["//bar_tools:toolchain_type"]
)

तर्क