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

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

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

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

नए नियम आपके संगठन के तहत, उनकी अपनी GitHub रिपॉज़िटरी में जाने चाहिए. अगर आपको लगता है कि आपके नियम baazbuild संगठन से जुड़े हैं, तो baज़ेन-डेवलपर ईमेल पाने वाले लोगों की सूची से संपर्क करें.

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

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

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

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

नीचे दिए गए सेक्शन में, मान लें कि डेटा स्टोर करने की जगह baazbuild संगठन की है.

workspace(name = "rules_mockascript")

README

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

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

कंस्ट्रेंट

अगर आपके नियम में toolchain से जुड़े नियम तय हैं, तो हो सकता है कि आपको कस्टम 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 मैक्रो दें. इस तरह उपयोगकर्ता टूलचेन को रजिस्टर करते हुए भी पिछले मैक्रो को छोड़ने और डिपेंडेंसी को मैन्युअल तौर पर कंट्रोल करने का फ़ैसला ले सकते हैं.

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

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

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

दस्तावेज़

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

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

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

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

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

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