तारीख सेव करें: BazelCon 2023, 24 से 25 अक्टूबर तक Google म्यूनिख में होगा! ज़्यादा जानें

डिप्लॉयमेंट के नियम

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

यह पेज उन नियम लेखकों के लिए है जो अपने नियम अन्य लोगों को उपलब्ध कराने की योजना बना रहे हैं.

होस्टिंग और नाम रखने के नियम

नए नियम, आपके संगठन में काम करने वाले GitHub के डेटा स्टोर करने की जगह में जाने चाहिए. अगर आपको लगता है कि आपके नियम bazelbuild संगठन में हैं, तो GitHub पर थ्रेड शुरू करें.

Bazel के नियमों के लिए रिपॉज़िटरी के नाम, इस फ़ॉर्मैट में तय किए गए हैं: $ORGANIZATION/rules_$NAME. GitHub पर उदाहरण देखें. लगातार अपडेट करने के लिए, आपको अपने Bazel के नियमों को पब्लिश करते समय इस फ़ॉर्मैट का पालन करना होगा.

पक्का करें कि ज़्यादा जानकारी वाला GitHub डेटा स्टोर करने की जगह का ब्यौरा और README.md टाइटल का इस्तेमाल किया गया हो, उदाहरण:

  • डेटा स्टोर करने की जगह का नाम: bazelbuild/rules_go
  • डेटा स्टोर करने की जगह का ब्यौरा: Bzel के लिए नियम बनाएं
  • रिपॉज़िटरी टैग: golang, bazel
  • README.md हेडर: Bazen के लिए नियमों पर जाएं (https://bazel.build के लिंक पर ध्यान दें, जो उन उपयोगकर्ताओं की सही जगह पर जाने में मदद करेगा जो बेज़ल के बारे में नहीं जानते)

नियमों को भाषा (जैसे, स्काला) या प्लैटफ़ॉर्म (जैसे कि Android) के हिसाब से ग्रुप में बांटा जा सकता है.

डेटा स्टोर करने की जगह

डेटा स्टोर करने की हर जगह का एक खास लेआउट होना चाहिए, ताकि उपयोगकर्ता तेज़ी से नए नियमों को समझ सकें.

उदाहरण के लिए, (मेक- बिलीव) mockascript भाषा के लिए नए नियम लिखते समय, डेटा स्टोर करने की जगह का स्ट्रक्चर इस तरह का होगा:

/
  LICENSE
  README
  WORKSPACE
  mockascript/
    constraints/
      BUILD
    runfiles/
      BUILD
      runfiles.mocs
    BUILD
    defs.bzl
  tests/
    BUILD
    some_test.sh
    another_test.py
  examples/
    BUILD
    bin.mocs
    lib.mocs
    test.mocs

Workspace

प्रोजेक्ट के WORKSPACE में, आपको वह नाम तय करना होगा जिसका इस्तेमाल करके उपयोगकर्ता आपके नियमों का रेफ़रंस देंगे. अगर आपके नियम bazelbuild संगठन से जुड़े हैं, तो आपको rules_<lang> (जैसे, rules_mockascript) का इस्तेमाल करना होगा. नहीं तो, आपको अपने डेटा स्टोर करने की जगह <org>_rules_<lang> (जैसे, build_stack_rules_proto) का नाम रखना चाहिए. अगर आपको लगता है कि आपके नियमों को bazelbuild वाले संगठन के नियमों के लिए कन्वेंशन का पालन करना चाहिए, तो कृपया GitHub पर थ्रेड शुरू करें.

नीचे दिए गए सेक्शन में, मान लें कि रिपॉज़िटरी bazelbuild संगठन से जुड़ा है.

workspace(name = "rules_mockascript")

README

सबसे ऊपर लेवल में, README होना चाहिए, जिसमें कम से कम यह हो कि उपयोगकर्ताओं को आपके नियम का इस्तेमाल करने के लिए, अपनी WORKSPACE फ़ाइल में कॉपी करके चिपकाना होगा. आम तौर पर, यह एक http_archive होगा, जो आपके GitHub रिलीज़ और एक मैक्रो कॉल की जानकारी देगा, जो आपके नियम के मुताबिक ज़रूरी टूल को डाउनलोड/कॉन्फ़िगर करता है. उदाहरण के लिए, Go नियमों के लिए यह ऐसा दिखता है:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_go",
    urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
    sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()

अगर आपके नियम किसी दूसरी रिपॉज़िटरी के नियमों पर निर्भर करते हैं, तो उसे नियमों के दस्तावेज़ में बताएं (उदाहरण के लिए, Skydoc के नियम देखें, जो Sass नियमों पर निर्भर करते हैं) और एक WORKSPACE मैक्रो दें, जो सभी डिपेंडेंसी डाउनलोड करेगा (ऊपर rules_go देखें).

नियम

आम तौर पर, डेटा स्टोर करने की जगह में कई नियम होते हैं. भाषा के नाम वाली डायरेक्ट्री बनाएं और एक एंट्री पॉइंट - defs.bzl फ़ाइल दें सभी नियमों को एक्सपोर्ट करें (इसमें BUILD फ़ाइल भी शामिल करें, ताकि डायरेक्ट्री एक पैकेज हो). rules_mockascript के लिए, इसका मतलब है कि mockascript नाम की एक डायरेक्ट्री होगी, उसमें BUILD फ़ाइल होगी, और defs.bzl फ़ाइल होगी:

/
  mockascript/
    BUILD
    defs.bzl

कंस्ट्रेंट

अगर आपका नियम टूलचेन नियमों को तय करता है, तो हो सकता है कि आपको कस्टम constraint_setting और/या constraint_value की जानकारी देनी पड़े. इन्हें //<LANG>/constraints पैकेज में डालें. आपकी डायरेक्ट्री का स्ट्रक्चर कुछ ऐसा दिखेगा:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

सबसे सही तरीकों के लिए, कृपया github.com/bazelbuild/platforms पढ़ें और देखें कि पहले से मौजूद कंस्ट्रेंट पहले से मौजूद हैं या नहीं. अगर आपकी कॉन्टेटिटी अलग-अलग भाषा के हैं, तो वहां अपने कंस्ट्रेंट का योगदान देने के बारे में सोचें. कस्टम कंस्ट्रेंट के बारे में ध्यान रखें, आपके नियमों के सभी उपयोगकर्ता, अपनी BUILD फ़ाइलों में प्लैटफ़ॉर्म के हिसाब से लॉजिक करने के लिए उनका इस्तेमाल करेंगे. उदाहरण के लिए, selects का इस्तेमाल करना. कस्टम कंस्ट्रेंट की मदद से, आप ऐसी भाषा तय करते हैं जो पूरे बैज़ल नेटवर्क की बात करती है.

रनफ़ाइल लाइब्रेरी

अगर आपका नियम, रनफ़ाइल को ऐक्सेस करने के लिए कोई स्टैंडर्ड लाइब्रेरी उपलब्ध कराता है, तो यह //<LANG>/runfiles (//<LANG>/runfiles:runfiles का छोटा नाम) पर मौजूद लाइब्रेरी टारगेट के रूप में होना चाहिए. ऐसे उपयोगकर्ता टारगेट जो अपनी डेटा डिपेंडेंसी को ऐक्सेस करना चाहते हैं, वे आम तौर पर इस टारगेट को अपनी deps एट्रिब्यूट में जोड़ देंगे.

डेटा स्टोर करने की जगह से जुड़े नियम

डिपेंडेंसी

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

<LANG>/repositories.bzl नाम की फ़ाइल बनाएं और rules_<LANG>_dependencies नाम का एक एंट्री पॉइंट मैक्रो दें. हमारी डायरेक्ट्री कैसी दिखेगी:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl
    repositories.bzl

टूलचेन रजिस्टर करना

आपके नियम, टूलटिप को भी रजिस्टर कर सकते हैं. कृपया एक अलग WORKSPACE मैक्रो दें, जो इन टूलचेन को रजिस्टर करता हो. इस तरह, उपयोगकर्ता पिछले मैक्रो को नज़रअंदाज़ कर सकते हैं और मैन्युअल तौर पर डिपेंडेंसी कंट्रोल कर सकते हैं. साथ ही, वे टूलचेन को रजिस्टर करने की अनुमति भी दे सकते हैं.

इसलिए, rules_<LANG>_toolchains नाम की WORKSPACE मैक्रो को <LANG>/repositories.bzl फ़ाइल में जोड़ें.

ध्यान दें कि विश्लेषण के चरण में बेचैन से जुड़ी समस्याएं हल करने के लिए, Bazel को, रजिस्टर किए गए सभी toolchainटारगेट का विश्लेषण करना होगा. बेज़ल को toolchain.toolchain एट्रिब्यूट से जुड़े सभी टारगेट का विश्लेषण करने की ज़रूरत नहीं है. अगर टूलटिप को रजिस्टर करने के लिए, आपको डेटा स्टोर करने की जगह में कॉम्प्लेक्स कंप्यूटेशन की प्रक्रिया पूरी करनी है, तो रिपॉज़िटरी से, <LANG>_toolchain के टारगेट के साथ toolchain टारगेट का डेटा स्टोर करने के बारे में सोचें. पहले वाला हमेशा फ़ेच किया जाएगा और बाद में ही मिलेगा, जब उपयोगकर्ता को वाकई <LANG> कोड बनाना होगा.

रिलीज़ स्निपेट

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

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_<LANG>",
    urls = ["<url_to_the_release.zip"],
    sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()

जांच

जांच से यह पुष्टि होगी कि नियम उम्मीद के मुताबिक काम कर रहे हैं या नहीं. यह नियम की भाषा के लिए मानक जगह पर हो सकती है या फिर टॉप लेवल पर tests/ डायरेक्ट्री हो सकती है.

उदाहरण (ज़रूरी नहीं)

उपयोगकर्ताओं के लिए इस examples/ डायरेक्ट्री को इस्तेमाल करना मददगार होता है. इससे उपयोगकर्ताओं को नियमों को इस्तेमाल करने के कुछ बुनियादी तरीकों का पता चलता है.

टेस्ट करना

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

dist: xenial  # Ubuntu 16.04

# On trusty (or later) images, the Bazel apt repository can be used.
addons:
  apt:
    sources:
    - sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
      key_url: 'https://bazel.build/bazel-release.pub.gpg'
    packages:
    - bazel

script:
  - bazel build //...
  - bazel test //...

अगर आपका डेटा स्टोर करने की जगह bazenbuild से जुड़े संगठन में है, तो उसे ci.bazel.build में जोड़ने के लिए कहें.

दस्तावेज़

अपने नियमों पर टिप्पणी करने के तरीके के बारे में निर्देश पाने के लिए स्टारडॉक दस्तावेज़ देखें, ताकि दस्तावेज़ अपने आप जनरेट हो सकें.

अक्सर पूछे जाने वाले सवाल

हम Bazel GitHub की मुख्य रिपॉज़िटरी (डेटा स्टोर करने की जगह) में, अपना नियम क्यों नहीं जोड़ सकते?

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

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

हम बैज़ल रिपॉज़िटरी (//tools/build_rules या //tools/build_defs से कम) में मौजूद सभी नियम लागू करते थे. हालांकि, हमने अब भी कुछ नियम बनाए हैं, लेकिन हम बाकी नियमों को लागू करने पर काम कर रहे हैं.