बिल्ड इवेंट प्रोटोकॉल

7.3 · 7.2 · 7.1 · 7.0 · 6.5

बिल्ड इवेंट प्रोटोकॉल (बीईपी) की मदद से, तीसरे पक्ष के प्रोग्राम को Bazel को कॉल करने के बारे में अहम जानकारी मिलती है. उदाहरण के लिए, IDE प्लगिन या बिल्ड के नतीजे दिखाने वाले डैशबोर्ड के लिए जानकारी इकट्ठा करने के लिए, BEP का इस्तेमाल किया जा सकता है.

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

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

  • बिल्ड इवेंट आइडेंटिफ़ायर: बिल्ड इवेंट के टाइप के आधार पर, यह ओपेक स्ट्रिंग या स्ट्रक्चर्ड जानकारी हो सकती है. इससे, बिल्ड इवेंट के बारे में ज़्यादा जानकारी मिलती है. बिल्ड इवेंट आइडेंटिफ़ायर, बिल्ड के लिए यूनीक होता है.

  • चाइल्ड: कोई बिल्ड इवेंट, अपने चाइल्ड फ़ील्ड में बिल्ड इवेंट आइडेंटिफ़ायर शामिल करके, दूसरे बिल्ड इवेंट का एलान कर सकता है. उदाहरण के लिए, PatternExpanded बिल्ड इवेंट से यह पता चलता है कि वह बच्चों के लिए कौनसे टारगेट लेता है. प्रोटोकॉल इस बात की गारंटी देता है कि पहले इवेंट को छोड़कर, सभी इवेंट की घोषणा पिछले इवेंट के ज़रिए की जाएगी.

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

बिल्ड इवेंट ग्राफ़

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

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

  1. रूट इवेंट हमेशा BuildStarted इवेंट होता है. अन्य सभी इवेंट, इसके डिसेंडेंट हैं.
  2. BuildStarted इवेंट के तुरंत बाद के बच्चों में, कमांड के बारे में मेटाडेटा मौजूद होता है.
  3. निर्देश से तैयार किए गए डेटा वाले इवेंट, जैसे कि बनाई गई फ़ाइलें और जांच के नतीजे BuildFinished इवेंट से पहले दिखते हैं.
  4. BuildFinished इवेंट के बाद, ऐसे इवेंट हो सकते हैं जिनमें बिल्ड के बारे में खास जानकारी होती है (उदाहरण के लिए, मेट्रिक या प्रोफ़ाइलिंग डेटा).

Build Event Protocol का इस्तेमाल करना

बाइनरी फ़ॉर्मैट में इस्तेमाल करना

BEP को बाइनरी फ़ॉर्मैट में इस्तेमाल करने के लिए:

  1. --build_event_binary_file=/path/to/file विकल्प तय करके, Bazel को प्रोटोकॉल बफ़र मैसेज को फ़ाइल में सीरियलाइज़ करने के लिए कहें. इस फ़ाइल में क्रम से लगाए गए प्रोटोकॉल बफ़र मैसेज होंगे, जिनमें हर मैसेज की लंबाई को सीमा में रखा जाएगा. हर मैसेज के आगे, उसकी लंबाई होती है. इसे वैरिएबल लेंथ इंटरजर के तौर पर एन्कोड किया जाता है. इस फ़ॉर्मैट को प्रोटोकॉल बफ़र लाइब्रेरी के parseDelimitedFrom(InputStream) तरीके का इस्तेमाल करके पढ़ा जा सकता है.

  2. इसके बाद, एक ऐसा प्रोग्राम लिखें जो क्रम से लगाए गए प्रोटोकॉल बफ़र मैसेज से काम की जानकारी ले.

टेक्स्ट या JSON फ़ॉर्मैट में इस्तेमाल करें

Bazel कमांड-लाइन के इन फ़्लैग से, BEP को टेक्स्ट और JSON जैसे ऐसे फ़ॉर्मैट में आउटपुट किया जाएगा जिन्हें कोई भी पढ़ सकता है:

--build_event_text_file
--build_event_json_file

बिल्ड इवेंट सेवा

बिल्ड इवेंट सेवा प्रोटोकॉल, बिल्ड इवेंट पब्लिश करने के लिए एक सामान्य gRPC सेवा है. बिल्ड इवेंट सेवा प्रोटोकॉल, BEP से अलग होता है और BEP इवेंट को ओपेक बाइट के रूप में देखता है. Bazel, Build Event Service प्रोटोकॉल के gRPC क्लाइंट के साथ शिप होता है. यह प्रोटोकॉल, Build Event Protocol इवेंट पब्लिश करता है. --bes_backend=HOST:PORT फ़्लैग का इस्तेमाल करके, एंडपॉइंट तय किया जा सकता है, ताकि इवेंट भेजे जा सकें. अगर आपका बैकएंड gRPC का इस्तेमाल करता है, तो आपको पते के आगे सही स्कीम जोड़ना होगा: सादा टेक्स्ट gRPC के लिए grpc:// और TLS चालू होने पर gRPC के लिए grpcs://.

इवेंट सेवा के फ़्लैग बनाना

Basel के पास Build Event Service प्रोटोकॉल से जुड़े कई फ़्लैग हैं, जिनमें ये शामिल हैं:

  • --bes_backend
  • --[no]bes_best_effort
  • --[no]bes_lifecycle_events
  • --bes_results_url
  • --bes_timeout
  • --project_id

इनमें से हर फ़्लैग के बारे में जानने के लिए, कमांड-लाइन रेफ़रंस देखें.

पुष्टि करना और सुरक्षा

Basel का Build इवेंट सर्विस लागू करने की सुविधा, पुष्टि करने और TLS के साथ भी काम करती है. इन सेटिंग को नीचे दिए गए फ़्लैग का इस्तेमाल करके कंट्रोल किया जा सकता है. कृपया ध्यान दें कि इन फ़्लैग का इस्तेमाल, Bazel के रिमोट एक्सीक्यूशन के लिए भी किया जाता है. इसका मतलब है कि Build Event Service और रिमोट EXECUTION एंडपॉइंट को एक ही पुष्टि और TLS इन्फ़्रास्ट्रक्चर शेयर करना होगा.

  • --[no]google_default_credentials
  • --google_credentials
  • --google_auth_scopes
  • --tls_certificate
  • --[no]tls_enabled

इनमें से हर फ़्लैग के बारे में जानने के लिए, कमांड-लाइन रेफ़रंस देखें.

इवेंट सेवा बनाना और रिमोट कैश मेमोरी

आम तौर पर, BEP में उन लॉग फ़ाइलों के कई रेफ़रंस होते हैं (test.log, test.xml वगैरह) जिन्हें उस मशीन पर सेव किया जाता है जहां Bazel चल रहा है. आम तौर पर, रिमोट बीईएस सर्वर इन फ़ाइलों को ऐक्सेस नहीं कर सकता, क्योंकि ये अलग-अलग मशीनों पर मौजूद होती हैं. इस समस्या को हल करने के लिए, रिमोट कैश मेमोरी के साथ Bazel का इस्तेमाल करें. Bazel, सभी आउटपुट फ़ाइलों को रिमोट कैश मेमोरी में अपलोड करेगा. इनमें, BEP में रेफ़र की गई फ़ाइलें भी शामिल हैं. इसके बाद, BES सर्वर कैश मेमोरी से रेफ़र की गई फ़ाइलें फ़ेच कर सकता है.

ज़्यादा जानकारी के लिए, GitHub पर समस्या 3689 देखें.