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

यह पेज नियम लिखने वाले उन लोगों के लिए है जो अपने नियम लागू करना चाहते हैं भी शेयर किया जा सकता है.

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

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

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

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

पक्का करें कि आपने GitHub रिपॉज़िटरी की पूरी जानकारी दी है. साथ ही, README.md का इस्तेमाल किया है शीर्षक, उदाहरण:

• डेटा स्टोर करने की जगह का नाम: bazelbuild/rules_go
• डेटा स्टोर करने की जगह की जानकारी: Basel के लिए Go के नियम
• डेटा स्टोर करने की जगह के टैग: golang, bazel
• README.md हेडर: Bazz के लिए नियमों को लागू करना (https://bazu.build का लिंक देखें, जो अनजान उपयोगकर्ताओं को आपकी मदद करेगा) साथ ही, डिज़ाइन किया गया है)

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

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

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

उदाहरण के लिए, (make-belyve) के लिए नए नियम लिखते समय 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 में, आपको वह नाम तय करना होगा जिसे उपयोगकर्ता इस्तेमाल करेंगे जोड़ें, ताकि आप अपने नियमों का संदर्भ दे सकें. अगर आपके नियम baZbuild संगठन के किसी भी हिस्से का इस्तेमाल कर सकते हैं, तो आपको rules_<lang> (जैसे कि rules_mockascript). या फिर, आपको अपने डेटा स्टोर करने की जगह <org>_rules_<lang> (जैसे कि build_stack_rules_proto). प्लीज़ GitHub पर थ्रेड शुरू करो अगर आपको लगता है कि आपके नियमों को baज़लbuild संगठन का नाम.

नीचे दिए गए सेक्शन में, मान लें कि डेटा स्टोर करने की जगह ba Profilebuild संगठन के तौर पर इस्तेमाल किया जा सकता है.

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()

अगर आपके नियम, डेटा स्टोर करने की किसी दूसरी जगह के नियमों पर निर्भर करते हैं, तो इसे नियमों का दस्तावेज़ (उदाहरण के लिए, स्काईडॉक के नियम, जो 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 फ़ाइलों में प्लैटफ़ॉर्म के हिसाब से लॉजिक परफ़ॉर्म करने के लिए करें. उदाहरण के लिए, चुनें का इस्तेमाल करके). पसंद के मुताबिक कंस्ट्रेंट की मदद से, ऐसी भाषा तय की जाती है जो पूरे Basel नेटवर्क पर दी गई है बातचीत करेगा.

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

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

ध्यान दें कि विश्लेषण के चरण में टूलचेन को हल करने के लिए, Baज़र को रजिस्टर किए गए सभी toolchain टारगेट का विश्लेषण करें. बेज़ल को यह करने की ज़रूरत नहीं होगी 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 की कार्रवाइयों का इस्तेमाल करते हैं. rules-template रेपो में इस्तेमाल किया गया कॉन्फ़िगरेशन देखें. इन नियम को "फिर से इस्तेमाल किए जा सकने वाले वर्कफ़्लो" का इस्तेमाल करके, आसान बनाया जाता है बेज़ल-कॉन्ट्रिब में होस्ट किया गया संगठन ci.yaml हर PR और main कॉमिट की जांच करता है और जब भी आप किसी टैग को डेटा स्टोर करने की जगह में पुश करते हैं, तो release.yaml चलता है. ज़्यादा जानकारी के लिए, नियम टेंप्लेट रेपो में टिप्पणियां देखें.

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

दस्तावेज़

इसके लिए Stardoc दस्तावेज़ देखें अपने नियमों पर टिप्पणी करने से जुड़े निर्देश, ताकि दस्तावेज़ जनरेट किए जा सकें स्वचालित रूप से.

नियम-टेंप्लेट दस्तावेज़/ फ़ोल्डर इससे यह पक्का करने में मदद मिलती है कि docs/ फ़ोल्डर में Markdown कॉन्टेंट हमेशा अप-टू-डेट रहता है जैसे ही Starlark फ़ाइलें अपडेट होती हैं.

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

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

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

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

हमारे पास Baज़ल का डेटा स्टोर करने की जगह में (नीचे) सभी नियम होते थे //tools/build_rules या //tools/build_defs). हमारे पास अब भी कुछ नियम हैं लेकिन हम शेष नियमों को लागू करने पर काम कर रहे हैं.