प्रोटोकॉल बफ़र के नियम

किसी समस्या की शिकायत करें सोर्स देखें

नियम

proto_lang_toolchain

नियम का सोर्स देखें 
proto_lang_toolchain(name, blacklisted_protos, command_line, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, mnemonic, output_files, plugin, plugin_format_flag, progress_message, proto_compiler, restricted_to, runtime, tags, target_compatible_with, testonly, visibility)

अगर Bazel का इस्तेमाल किया जा रहा है, तो कृपया https://github.com/bazelbuild/rules_proto से नियम लोड करें.

यह बताता है कि lang_proto_library नियम (उदाहरण के लिए, java_proto_library) प्रोटो-कंपाइलर को शुरू करना चाहिए. कुछ lang_proto_library नियम यह तय करने की अनुमति देते हैं कि कमांड-लाइन फ़्लैग का इस्तेमाल करके, किस टूलचेन का इस्तेमाल करना है; उनके दस्तावेज़ देखें.

आम तौर पर, आपको इस तरह के नियम तब तक नहीं लिखने चाहिए, जब तक कि आप अपने Java कंपाइलर को ट्यून न करना चाहें.

कोई कंपाइलर नहीं है. प्रोटो-कंपाइलर को उस Proto_library नियम से लिया जाता है जिससे हम जुड़े होते हैं. इसे Blaze को कमांड-लाइन फ़्लैग के रूप में पास किया गया है. कुछ सुविधाओं के लिए, Proto_library नियम पर ही प्रोटो-कंपाइलर शुरू करना ज़रूरी होता है. lang_proto_library जिस कंपाइलर का इस्तेमाल करता है, बेहतर वही होता है proto_library.

उदाहरण

इसका एक आसान उदाहरण यह होगा: 

proto_lang_toolchain(
    name = "javalite_toolchain",
    command_line = "--javalite_out=shared,immutable:$(OUT)",
    plugin = ":javalite_plugin",
    runtime = ":protobuf_lite",
)

तर्क

एट्रिब्यूट
name

नाम; ज़रूरी है

इस टारगेट के लिए एक खास नाम.
blacklisted_protos

लेबल की सूची; [] डिफ़ॉल्ट है

blacklisted_protos के srcs एट्रिब्यूट में मौजूद फ़ाइलों के लिए, कोई कोड जनरेट नहीं किया जाएगा. इसका इस्तेमाल .proto फ़ाइलों के लिए किया जाता है, जो पहले से ही प्रोटो रनटाइम से लिंक हैं, जैसे कि any.proto.
command_line

स्ट्रिंग; ज़रूरी है

कोड जनरेट करने के लिए, यह वैल्यू प्रोटो-कंपिलर को भेजी जाएगी. सिर्फ़ इस कोड-जनरेटर/प्लगिन के लिए खास तौर पर बने हिस्सों को शामिल करें (उदाहरण के लिए, -I पैरामीटर शामिल न करें)
  • $(OUT) की वैल्यू, lang_proto_library के हिसाब से तय होती है. नियमों से यह तय किया जाना चाहिए कि वे इस वैरिएबल को किस तरह समझते हैं. उदाहरण के लिए, Java के लिए, $(OUT) को बनाने के लिए src-jar फ़ाइल नाम से बदल दिया जाएगा.
mnemonic

स्ट्रिंग; "GenProto" डिफ़ॉल्ट है

यह वैल्यू, प्रोटोक ऐक्शन पर निमोनिक के तौर पर सेट की जाएगी.
output_files

स्ट्रिंग; "legacy" डिफ़ॉल्ट है

यह प्रॉपर्टी तय करती है कि command_line में $(OUT) को कैसे फ़ॉर्मैट किया जाए. इसके लिए, एक फ़ाइल के पाथ या कई फ़ाइलें होने पर आउटपुट डायरेक्ट्री इस्तेमाल की जा सकती है. संभावित वैल्यू ये हैं: "एक", "एक से ज़्यादा".
plugin

लेबल; None डिफ़ॉल्ट है

अगर यह पैरामीटर उपलब्ध कराया जाता है, तो इसे प्रोटो-कंपालर को कॉल करने वाली कार्रवाई के लिए उपलब्ध कराया जाएगा. साथ ही, इसे प्रोटो-कंपाइलर को भेज दिया जाएगा: --plugin=protoc-gen-PLUGIN=<executable>.
plugin_format_flag

स्ट्रिंग; "" डिफ़ॉल्ट है

अगर यह वैल्यू दी जाती है, तो इसे प्रोटो-कंपाइलर को भेज दिया जाएगा, ताकि प्लगिन का इस्तेमाल किया जा सके. मान में एक %s होना चाहिए, जिसे एक्ज़ीक्यूटेबल प्लगिन से बदला गया हो. --plugin=protoc-gen-PLUGIN=<executable>.
progress_message

स्ट्रिंग; "Generating proto_library %{label}" डिफ़ॉल्ट है

प्रोटॉक कार्रवाई में यह वैल्यू, प्रोग्रेस मैसेज के तौर पर सेट की जाएगी.
proto_compiler

लेबल; None डिफ़ॉल्ट है

प्रोटो कंपाइलर एक्ज़ीक्यूट किया जा सकता है. अगर यह टारगेट दिया जाता है, तो कोड जनरेट करने के लिए प्रोटो-कंपाइलर के तौर पर इसका इस्तेमाल किया जाएगा.
runtime

लेबल; None डिफ़ॉल्ट है

भाषा की खास लाइब्रेरी, जिससे जनरेट किया गया कोड इकट्ठा किया जाता है. सटीक व्यवहार lang_proto_library है. उदाहरण के लिए, Java को रनटाइम के हिसाब से कंपाइल करना चाहिए.

proto_library

नियम का सोर्स देखें 
proto_library(name, deps, srcs, data, allow_exports, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exports, features, import_prefix, licenses, restricted_to, strip_import_prefix, tags, target_compatible_with, testonly, visibility)

समर्थन नहीं होना या रुकना. इसके बजाय, कृपया https://github.com/bazelbuild/rules_proto का इस्तेमाल करें.

proto_library का इस्तेमाल करके, प्रोटोकॉल बफ़र की लाइब्रेरी तय करें, जिन्हें कई भाषाओं में इस्तेमाल किया जा सकता है. proto_library को इस्तेमाल किए जा सकने वाले नियमों के deps क्लॉज़ में शामिल किया जा सकता है, जैसे कि java_proto_library.

कमांड लाइन से इकट्ठा किए जाने पर proto_library, foo-descriptor-set.proto.bin नाम की फ़ाइल बनाता है. यह फ़ाइल उन मैसेज के लिए डिस्क्रिप्टर सेट होती है जो नियम srcs से भेजे जाते हैं. फ़ाइल क्रम से दी गई FileDescriptorSet है, जिसकी जानकारी https://developers.google.com/protocol-buffers/docs/techniques#self-description में दी गई है.

इस फ़ाइल में सिर्फ़ उन .proto फ़ाइलों के बारे में जानकारी है जिनके बारे में proto_library नियम के तहत सीधे तौर पर बताया गया है. ट्रांज़िटिव डिस्क्रिप्टर के सेट, [ProtoInfo].transitive_descriptor_sets Starlark की सेवा देने वाली कंपनी की मदद से उपलब्ध होती है. ProtoInfo.java में दस्तावेज़ देखें.

सुझाया गया कोड संगठन:

  • हर .proto फ़ाइल के लिए एक proto_library नियम.
  • foo.proto नाम की फ़ाइल foo_proto नाम के नियम में होगी और उसी पैकेज में मौजूद होगी.
  • foo_proto नाम के proto_library को रैप करने वाला [language]_proto_library, foo_[language]_proto नाम का होना चाहिए. साथ ही, यह उसी पैकेज में मौजूद होना चाहिए.

तर्क

एट्रिब्यूट
name

नाम; ज़रूरी है

इस टारगेट के लिए एक खास नाम.
deps

लेबल की सूची; [] डिफ़ॉल्ट है

अन्य proto_library नियमों की सूची, जिस पर टारगेट निर्भर करता है. proto_library सिर्फ़ अन्य proto_library टारगेट पर निर्भर हो सकता है. यह मुमकिन है कि यह किसी भाषा की लाइब्रेरी पर निर्भर न हो.
srcs

लेबल की सूची; [] डिफ़ॉल्ट है

.proto और .protodevel फ़ाइलों की सूची, जिन्हें टारगेट बनाने के लिए प्रोसेस किया गया है. आम तौर पर, यह एक खाली सूची होती है. alias-लाइब्रेरी, एक ऐसे मामले में इस्तेमाल का एक उदाहरण है जिसमें srcs खाली हो सकता है. यह एक Proto_library नियम है, जिसमें deps में एक या एक से ज़्यादा अन्य proto_library होने चाहिए. इस पैटर्न का इस्तेमाल, किसी स्थायी नाम के तहत सार्वजनिक एपीआई एक्सपोर्ट करने के लिए किया जा सकता है.
allow_exports

लेबल; None डिफ़ॉल्ट है

अनुमति वाली एक वैकल्पिक अनुमति, जो प्रोटो लाइब्रेरी को फिर से एक्सपोर्ट करने या lang_proto_library में इस्तेमाल करने से रोकती है. यह सूची, दिए गए पैकेज में शामिल नहीं है.
exports

लेबल की सूची; [] डिफ़ॉल्ट है

Proto_library ऐसे टारगेट की सूची जिनका रेफ़रंस प्रोटो सोर्स में "सार्वजनिक इंपोर्ट करें" की मदद से किया जा सकता है.
import_prefix

स्ट्रिंग; "" डिफ़ॉल्ट है

इस नियम में .proto फ़ाइलों के पाथ में जोड़ा जाने वाला प्रीफ़िक्स.

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

इस प्रीफ़िक्स को जोड़ने से पहले, strip_import_prefix एट्रिब्यूट में मौजूद प्रीफ़िक्स को हटा दिया जाता है.

strip_import_prefix

स्ट्रिंग; "" डिफ़ॉल्ट है

इस नियम में मौजूद .proto फ़ाइलों के पाथ से हटाया जाने वाला प्रीफ़िक्स.

सेट किए जाने पर, इस नियम के srcs एट्रिब्यूट में शामिल .proto सोर्स फ़ाइलों को उनके पाथ से ऐक्सेस किया जा सकता है. ऐसा करने के लिए, प्रीफ़िक्स का इस्तेमाल करना ज़रूरी होगा.

अगर यह रिलेटिव पाथ है (स्लैश से शुरू नहीं होता), तो इसे पैकेज-रिलेटिव के तौर पर लिया जाता है. अगर यह पूरा है, तो इसे रिपॉज़िटरी-रिलेटिव पाथ के तौर पर माना जाता है.

इस प्रीफ़िक्स को हटाने के बाद, import_prefix एट्रिब्यूट में प्रीफ़िक्स जोड़ा जाता है.