नियमों को डिप्लॉय करना

यह पेज उन नियम लेखकों के लिए है जो अपने नियमों को दूसरों के लिए उपलब्ध कराना चाहते हैं.

हमारा सुझाव है कि आप टेंप्लेट रिपॉज़िटरी से नया नियमों का सेट शुरू करें: https://github.com/bazel-contrib/rules-template यह टेंप्लेट, यहां दिए गए सुझावों का पालन करता है. इसमें एपीआई दस्तावेज़ जनरेशन शामिल है और सीआई/सीडी पाइपलाइन सेट अप की जाती है, ताकि आपके नियमों के सेट को आसानी से डिस्ट्रिब्यूट किया जा सके.

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

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

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

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

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

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

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

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

उदाहरण के लिए, (make-believe) 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 फ़ाइल में कॉपी-पेस्ट करना होगा. आम तौर पर, यह आपकी GitHub रिलीज़ पर ले जाने वाला http_archive और एक मैक्रो कॉल होगा, जो आपके नियम के लिए ज़रूरी टूल डाउनलोड/कॉन्फ़िगर करता है. उदाहरण के लिए, 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 का इस्तेमाल करना. कस्टम पाबंदियों की मदद से, एक ऐसी भाषा तय की जाती है जिसका इस्तेमाल, Bazel का पूरा नेटवर्क करेगा.

Runfiles लाइब्रेरी

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

रिपॉज़िटरी के नियम

डिपेंडेंसी

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

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

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

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

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

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

ध्यान दें कि विश्लेषण के चरण में टूलचेन को हल करने के लिए, Bazel को रजिस्टर किए गए सभी toolchain टारगेट का विश्लेषण करना होगा. Bazel को toolchain.toolchain एट्रिब्यूट के ज़रिए रेफ़र किए गए सभी टारगेट का विश्लेषण करने की ज़रूरत नहीं होगी. अगर टूलचेन रजिस्टर करने के लिए, आपको रिपॉज़िटरी में जटिल कैलकुलेशन करना है, तो toolchain टारगेट वाली रिपॉज़िटरी को <LANG>_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/ डायरेक्ट्री का होना फ़ायदेमंद होता है. इससे उन्हें नियमों का इस्तेमाल करने के कुछ बुनियादी तरीके पता चलते हैं.

सीआई/सीडी

कई नियमों के सेट में GitHub Actions का इस्तेमाल किया जाता है. rules-template repo में इस्तेमाल किए गए कॉन्फ़िगरेशन को देखें. इन कॉन्फ़िगरेशन को आसान बनाने के लिए, bazel-contrib.org में होस्ट किए गए "फिर से इस्तेमाल किए जा सकने वाले वर्कफ़्लो" का इस्तेमाल किया गया है. ci.yaml हर एक पीआर और main कमिट पर टेस्ट चलाता है. साथ ही, release.yaml किसी टैग को रिपॉज़िटरी में पुश करने पर भी चलता है. ज़्यादा जानकारी के लिए, rules-template repo में मौजूद टिप्पणियां देखें.

अगर आपकी रिपॉज़िटरी bazelbuild संगठन के तहत है, तो आपके पास ci.bazel.build में इसे जोड़ने का अनुरोध करने का विकल्प है.

दस्तावेज़

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

rules-template docs/ फ़ोल्डर में, यह पक्का करने का एक आसान तरीका बताया गया है कि Starlark फ़ाइलों के अपडेट होने पर, docs/ फ़ोल्डर में मौजूद मार्कडाउन कॉन्टेंट हमेशा अप-टू-डेट रहे.

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

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

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

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

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