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

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

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

नए नियमों को आपके संगठन के GitHub खाते में मौजूद रिपॉज़िटरी में शामिल किया जाना चाहिए. अगर आपको लगता है कि आपके नियम bazelbuild संगठन में शामिल होने चाहिए, तो bazel-dev mailing list से संपर्क करें.

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) के हिसाब से ग्रुप किया जा सकता है.

डेटा संग्रह स्थान में मौजूद कॉन्टेंट

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

उदाहरण के लिए, (मेक-बिलीव) 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 संगठन के नियमों के लिए तय किए गए तरीके का पालन करना चाहिए, तो कृपया bazel-dev mailing list से संपर्क करें.

यहां दिए गए सेक्शन में, मान लें कि रिपॉज़िटरी 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 इकोसिस्टम करेगा.

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

अगर आपका नियम, रनफ़ाइल ऐक्सेस करने के लिए स्टैंडर्ड लाइब्रेरी उपलब्ध कराता है, तो यह //<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/ डायरेक्ट्री का होना फ़ायदेमंद होता है. इससे उपयोगकर्ताओं को नियमों को इस्तेमाल करने के कुछ बुनियादी तरीकों के बारे में पता चलता है.

टेस्ट करना

Travis को सेट अप करने के लिए, शुरू करने से जुड़े दस्तावेज़ पढ़ें. इसके बाद, अपनी रिपॉज़िटरी में .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 //...

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

दस्तावेज़

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

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

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

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

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

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