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

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

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

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

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

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

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

/
  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 में, आपको वह नाम तय करना होगा जिसका इस्तेमाल करके उपयोगकर्ता आपके नियमों का रेफ़रंस लेंगे. अगर आपके नियम, bazelbuild संगठन के तहत हैं, तो आपको rules_<lang> (जैसे, rules_mockascript) का इस्तेमाल करना होगा. इसके अलावा, आपको अपनी रिपॉज़िटरी का नाम <org>_rules_<lang> (जैसे, build_stack_rules_proto) रखना होगा. अगर आपको लगता है कि आपके नियमों को bazelbuild संगठन के नियमों के कन्वेंशन के मुताबिक होना चाहिए, तो कृपया bazel-dev मेलिंग सूची से संपर्क करें.

यहां दिए गए सेक्शन में, मान लें कि रिपॉज़िटरी, 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 फ़ाइलों में प्लैटफ़ॉर्म के हिसाब से लॉजिक लागू करने के लिए इनका इस्तेमाल करेंगे. उदाहरण के लिए, सेलेक्ट का इस्तेमाल करना. कस्टम कंस्ट्रेंट की मदद से, ऐसी भाषा तय की जाती है जिसका इस्तेमाल Bazel का पूरा इकोसिस्टम करेगा.

Runfiles की लाइब्रेरी

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

टेस्ट करना

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 में ci.bazel.build.

दस्तावेज़

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

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

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

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

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

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