.bzl শৈলী গাইড

এই পৃষ্ঠাটি Starlark-এর জন্য মৌলিক শৈলী নির্দেশিকা কভার করে এবং ম্যাক্রো এবং নিয়ম সম্পর্কে তথ্যও অন্তর্ভুক্ত করে।

স্টারলার্ক এমন একটি ভাষা যা সংজ্ঞায়িত করে যে কীভাবে সফ্টওয়্যার তৈরি করা হয়, এবং যেমন এটি একটি প্রোগ্রামিং এবং একটি কনফিগারেশন ভাষা উভয়ই।

আপনি BUILD ফাইল, ম্যাক্রো এবং বিল্ড নিয়ম লিখতে Starlark ব্যবহার করবেন। ম্যাক্রো এবং নিয়মগুলি মূলত মেটা-ভাষা - তারা সংজ্ঞায়িত করে কিভাবে BUILD লিখতে হয়৷ BUILD ফাইলগুলি সহজ এবং পুনরাবৃত্তিমূলক হওয়ার উদ্দেশ্যে করা হয়েছে৷

সমস্ত সফ্টওয়্যার লেখার চেয়ে বেশি বার পড়া হয়। এটি স্টারলার্কের জন্য বিশেষভাবে সত্য, কারণ প্রকৌশলীরা তাদের লক্ষ্যগুলির নির্ভরতা এবং তাদের বিল্ডগুলির বিশদ বুঝতে BUILD ফাইলগুলি পড়েন। এই পঠনটি প্রায়শই পাস করার সময়, তাড়াহুড়োতে বা অন্য কোনও কাজ সম্পাদনের সমান্তরালে ঘটবে। ফলস্বরূপ, সরলতা এবং পঠনযোগ্যতা অত্যন্ত গুরুত্বপূর্ণ যাতে ব্যবহারকারীরা দ্রুত BUILD ফাইলগুলিকে পার্স এবং বুঝতে পারে।

যখন একজন ব্যবহারকারী একটি BUILD ফাইল খোলে, তারা দ্রুত ফাইলের লক্ষ্যগুলির তালিকা জানতে চায়; অথবা সেই C++ লাইব্রেরির উৎসের তালিকা পর্যালোচনা করুন; অথবা সেই জাভা বাইনারি থেকে একটি নির্ভরতা সরান। প্রতিবার আপনি বিমূর্তকরণের একটি স্তর যোগ করলে, আপনি একজন ব্যবহারকারীর জন্য এই কাজগুলি করা কঠিন করে তুলবেন।

BUILD ফাইলগুলিও বিভিন্ন সরঞ্জাম দ্বারা বিশ্লেষণ এবং আপডেট করা হয়। টুলগুলি আপনার BUILD ফাইলটি সম্পাদনা করতে সক্ষম নাও হতে পারে যদি এটি বিমূর্ততা ব্যবহার করে। আপনার BUILD ফাইলগুলিকে সহজ রাখা আপনাকে আরও ভাল টুলিং পেতে অনুমতি দেবে। একটি কোড বেস বাড়ার সাথে সাথে একটি লাইব্রেরি আপডেট করতে বা পরিষ্কার করার জন্য অনেকগুলি BUILD ফাইল জুড়ে পরিবর্তনগুলি আরও ঘন ঘন হয়ে ওঠে।

সাধারণ উপদেশ

শৈলী

পাইথন শৈলী

সন্দেহ হলে, যেখানে সম্ভব PEP 8 শৈলী নির্দেশিকা অনুসরণ করুন। বিশেষত, পাইথন কনভেনশন অনুসরণ করতে ইন্ডেন্টেশনের জন্য দুটি স্থানের পরিবর্তে চারটি ব্যবহার করুন।

যেহেতু স্টারলার্ক পাইথন নয় , তাই পাইথন শৈলীর কিছু দিক প্রযোজ্য নয়। উদাহরণ স্বরূপ, PEP 8 পরামর্শ দেয় যে সিঙ্গেলটনের সাথে তুলনা করা হবে is , যা স্টারলার্কের অপারেটর নয়।

ডকস্ট্রিং

ডকস্ট্রিং ব্যবহার করে ডকুমেন্ট ফাইল এবং ফাংশন। প্রতিটি .bzl ফাইলের শীর্ষে একটি ডকস্ট্রিং এবং প্রতিটি পাবলিক ফাংশনের জন্য একটি ডকস্ট্রিং ব্যবহার করুন৷

নথির নিয়ম এবং দিক

নিয়ম এবং দিক, তাদের গুণাবলী, সেইসাথে প্রদানকারী এবং তাদের ক্ষেত্রগুলি, doc আর্গুমেন্ট ব্যবহার করে নথিভুক্ত করা উচিত।

নামকরণের রীতি

  • ভেরিয়েবল এবং ফাংশনের নাম আন্ডারস্কোর ( [az][a-z0-9_]* ), যেমন cc_library দ্বারা পৃথক করা শব্দের সাথে ছোট হাতের অক্ষর ব্যবহার করে।
  • শীর্ষ-স্তরের ব্যক্তিগত মানগুলি একটি আন্ডারস্কোর দিয়ে শুরু হয়। Bazel প্রয়োগ করে যে ব্যক্তিগত মান অন্য ফাইল থেকে ব্যবহার করা যাবে না। স্থানীয় ভেরিয়েবলের আন্ডারস্কোর উপসর্গ ব্যবহার করা উচিত নয়।

লাইন দৈর্ঘ্য

BUILD ফাইলগুলির মতো, লেবেলগুলি দীর্ঘ হতে পারে বলে কোনও কঠোর লাইন দৈর্ঘ্যের সীমা নেই৷ যখন সম্ভব, প্রতি লাইনে সর্বাধিক 79টি অক্ষর ব্যবহার করার চেষ্টা করুন (পাইথনের স্টাইল গাইড অনুসরণ করুন, পিইপি 8 )। এই নির্দেশিকা কঠোরভাবে প্রয়োগ করা উচিত নয়: সম্পাদকদের 80টির বেশি কলাম প্রদর্শন করা উচিত, স্বয়ংক্রিয় পরিবর্তনগুলি প্রায়শই দীর্ঘ লাইন প্রবর্তন করবে, এবং মানুষের ইতিমধ্যে পাঠযোগ্য লাইনগুলিকে বিভক্ত করতে সময় ব্যয় করা উচিত নয়।

মূলশব্দ আর্গুমেন্ট

কীওয়ার্ড আর্গুমেন্টে, সমান চিহ্নের চারপাশে স্পেস পছন্দ করা হয়:

def fct(name, srcs):
    filtered_srcs = my_filter(source = srcs)
    native.cc_library(
        name = name,
        srcs = filtered_srcs,
        testonly = True,
    )

বুলিয়ান মান

বুলিয়ান মানের জন্য (যেমন একটি নিয়মে বুলিয়ান অ্যাট্রিবিউট ব্যবহার করার সময়) True এবং False ( 1 এবং 0 এর পরিবর্তে) মান পছন্দ করুন।

উত্পাদন কোডে print() ফাংশন ব্যবহার করবেন না; এটি শুধুমাত্র ডিবাগ করার উদ্দেশ্যে করা হয়েছে, এবং আপনার .bzl ফাইলের সকল প্রত্যক্ষ এবং পরোক্ষ ব্যবহারকারীদের স্প্যাম করবে। একমাত্র ব্যতিক্রম হল যে আপনি print() ব্যবহার করে এমন কোড জমা দিতে পারেন যদি এটি ডিফল্টরূপে নিষ্ক্রিয় থাকে এবং শুধুমাত্র উৎস সম্পাদনা করেই সক্ষম করা যায় -- উদাহরণস্বরূপ, যদি print() এর সমস্ত ব্যবহার if DEBUG: যেখানে DEBUG হয় False থেকে হার্ডকোড করা হয়েছে। এই বিবৃতিগুলি পঠনযোগ্যতার উপর তাদের প্রভাবকে ন্যায্যতা দেওয়ার জন্য যথেষ্ট কার্যকর কিনা তা মনে রাখবেন।

ম্যাক্রো

একটি ম্যাক্রো হল একটি ফাংশন যা লোডিং পর্বের সময় এক বা একাধিক নিয়ম চালু করে। সাধারণভাবে, ম্যাক্রোর পরিবর্তে যখনই সম্ভব নিয়ম ব্যবহার করুন। ব্যবহারকারীর দ্বারা দেখা বিল্ড গ্রাফটি বিল্ডের সময় Bazel দ্বারা ব্যবহৃত গ্রাফের মতো নয় - Bazel কোনো বিল্ড গ্রাফ বিশ্লেষণ করার আগে ম্যাক্রোগুলিকে প্রসারিত করা হয়৷

এই কারণে, যখন কিছু ভুল হয়ে যায়, ব্যবহারকারীকে বিল্ড সমস্যা সমাধানের জন্য আপনার ম্যাক্রোর বাস্তবায়ন বুঝতে হবে। উপরন্তু, bazel query ফলাফল ব্যাখ্যা করা কঠিন হতে পারে কারণ ফলাফলে দেখানো লক্ষ্যগুলি ম্যাক্রো সম্প্রসারণ থেকে আসে। অবশেষে, দিকগুলি ম্যাক্রো সম্পর্কে সচেতন নয়, তাই দিকগুলির উপর নির্ভর করে টুলিং (আইডিই এবং অন্যান্য) ব্যর্থ হতে পারে।

ম্যাক্রোগুলির জন্য একটি নিরাপদ ব্যবহার হল বাজেল সিএলআই বা বিল্ড ফাইলগুলিতে সরাসরি উল্লেখ করার উদ্দেশ্যে অতিরিক্ত লক্ষ্যগুলি সংজ্ঞায়িত করার জন্য: সেক্ষেত্রে, কেবলমাত্র সেই লক্ষ্যগুলির শেষ ব্যবহারকারীদের সেগুলি সম্পর্কে জানতে হবে এবং ম্যাক্রো দ্বারা প্রবর্তিত কোনও বিল্ড সমস্যা কখনই নয় তাদের ব্যবহার থেকে অনেক দূরে।

যে ম্যাক্রোগুলি তৈরি করা লক্ষ্যগুলিকে সংজ্ঞায়িত করে (ম্যাক্রোর বাস্তবায়নের বিবরণ যা CLI-তে উল্লেখ করা উচিত নয় বা সেই ম্যাক্রো দ্বারা তাত্ক্ষণিক নয় এমন লক্ষ্যগুলির উপর নির্ভর করে), এই সর্বোত্তম অনুশীলনগুলি অনুসরণ করুন:

  • একটি ম্যাক্রো একটি name যুক্তি গ্রহণ করা উচিত এবং সেই নামের সাথে একটি লক্ষ্য সংজ্ঞায়িত করা উচিত। সেই টার্গেটই হয়ে ওঠে ম্যাক্রোর প্রধান টার্গেট ।
  • জেনারেটেড টার্গেট, যা ম্যাক্রো দ্বারা সংজ্ঞায়িত অন্য সব লক্ষ্য, উচিত:
    • তাদের নামের পূর্বে <name> অথবা _<name> দিয়ে লিখুন। উদাহরণস্বরূপ, name = '%s_bar' % (name) ব্যবহার করে।
    • সীমিত দৃশ্যমানতা আছে ( //visibility:private ), এবং
    • ওয়াইল্ডকার্ড লক্ষ্যে ( :all , ... , :* , etc) সম্প্রসারণ এড়াতে একটি manual ট্যাগ রাখুন।
  • name শুধুমাত্র ম্যাক্রো দ্বারা সংজ্ঞায়িত লক্ষ্যগুলির নাম প্রাপ্ত করার জন্য ব্যবহার করা উচিত, অন্য কিছুর জন্য নয়। উদাহরণস্বরূপ, একটি নির্ভরতা বা ইনপুট ফাইল তৈরি করতে নামটি ব্যবহার করবেন না যা ম্যাক্রো নিজেই তৈরি করে না।
  • ম্যাক্রোতে তৈরি সমস্ত লক্ষ্যগুলিকে মূল লক্ষ্যের সাথে কিছু উপায়ে সংযুক্ত করা উচিত।
  • ম্যাক্রোতে প্যারামিটারের নামগুলি সামঞ্জস্যপূর্ণ রাখুন। যদি একটি প্যারামিটার প্রধান লক্ষ্যে একটি বৈশিষ্ট্য মান হিসাবে পাস করা হয়, তার নাম একই রাখুন। যদি একটি ম্যাক্রো প্যারামিটার একটি সাধারণ নিয়ম অ্যাট্রিবিউটের মতো একই উদ্দেশ্যে কাজ করে, যেমন deps , আপনি অ্যাট্রিবিউটের মতো নাম (নীচে দেখুন)।
  • একটি ম্যাক্রো কল করার সময়, শুধুমাত্র কীওয়ার্ড আর্গুমেন্ট ব্যবহার করুন। এটি নিয়মের সাথে সামঞ্জস্যপূর্ণ, এবং ব্যাপকভাবে পাঠযোগ্যতা উন্নত করে।

প্রকৌশলীরা প্রায়শই ম্যাক্রো লেখেন যখন প্রাসঙ্গিক নিয়মের Starlark API তাদের নির্দিষ্ট ব্যবহারের ক্ষেত্রে অপর্যাপ্ত হয়, নিয়মটি স্থানীয় কোডে বা স্টারলার্কের মধ্যে বেজেলের মধ্যে সংজ্ঞায়িত করা হোক না কেন। আপনি যদি এই সমস্যার সম্মুখীন হন, তাহলে নিয়ম লেখককে জিজ্ঞাসা করুন যে তারা আপনার লক্ষ্যগুলি পূরণ করতে API প্রসারিত করতে পারে কিনা।

একটি অঙ্গুষ্ঠের নিয়ম হিসাবে, যত বেশি ম্যাক্রো নিয়মের সাথে সাদৃশ্যপূর্ণ, তত ভাল।

ম্যাক্রোগুলিও দেখুন।

নিয়ম

  • নিয়ম, দিক এবং তাদের গুণাবলীতে ছোট হাতের নাম ব্যবহার করা উচিত ("সাপের কেস")।
  • নিয়মের নামগুলি এমন বিশেষ্য যা নিয়ম দ্বারা উত্পাদিত প্রধান ধরণের শিল্পকর্মকে বর্ণনা করে, এর নির্ভরতার দৃষ্টিকোণ থেকে (বা পাতার নিয়মের জন্য, ব্যবহারকারী)। এটি অগত্যা একটি ফাইল প্রত্যয় নয়. উদাহরণ স্বরূপ, পাইথন এক্সটেনশন হিসাবে ব্যবহার করার জন্য C++ আর্টিফ্যাক্ট তৈরি করে এমন একটি নিয়মকে py_extension বলা যেতে পারে। বেশিরভাগ ভাষার জন্য, সাধারণ নিয়মগুলির মধ্যে রয়েছে:
    • *_library - একটি সংকলন ইউনিট বা "মডিউল"।
    • *_binary - একটি টার্গেট যা একটি এক্সিকিউটেবল বা ডিপ্লয়মেন্ট ইউনিট তৈরি করে।
    • *_test - একটি পরীক্ষার লক্ষ্য। এটি একাধিক পরীক্ষা অন্তর্ভুক্ত করতে পারে। একটি *_test টার্গেটের সমস্ত পরীক্ষা একই থিমের বৈচিত্র্যের আশা করুন, উদাহরণস্বরূপ, একটি একক লাইব্রেরি পরীক্ষা করা।
    • *_import : একটি লক্ষ্য যা একটি পূর্ব-সংকলিত শিল্পবস্তুকে অন্তর্ভুক্ত করে, যেমন একটি .jar বা একটি .dll যা সংকলনের সময় ব্যবহৃত হয়।
  • বৈশিষ্ট্যগুলির জন্য সামঞ্জস্যপূর্ণ নাম এবং প্রকারগুলি ব্যবহার করুন। কিছু সাধারণভাবে প্রযোজ্য বৈশিষ্ট্য অন্তর্ভুক্ত:
    • srcs : label_list , ফাইলগুলিকে অনুমতি দেয়: উত্স ফাইলগুলি, সাধারণত মানব-লেখক৷
    • deps : label_list , সাধারণত ফাইলগুলিকে অনুমতি দেয় না : সংকলন নির্ভরতা।
    • data : label_list , ফাইলগুলিকে অনুমতি দেয়: ডেটা ফাইল, যেমন টেস্ট ডেটা ইত্যাদি।
    • runtime_deps : label_list : রানটাইম নির্ভরতা যা সংকলনের জন্য প্রয়োজন হয় না।
  • অ-স্পষ্ট আচরণ সহ যেকোন বৈশিষ্ট্যের জন্য (উদাহরণস্বরূপ, বিশেষ প্রতিস্থাপন সহ স্ট্রিং টেমপ্লেট, বা নির্দিষ্ট প্রয়োজনীয়তার সাথে আহ্বান করা সরঞ্জামগুলি), বৈশিষ্ট্যের ঘোষণার ( attr.label_list() বা অনুরূপ) doc কীওয়ার্ড আর্গুমেন্ট ব্যবহার করে ডকুমেন্টেশন সরবরাহ করুন।
  • নিয়ম বাস্তবায়ন ফাংশন প্রায় সবসময় ব্যক্তিগত ফাংশন হওয়া উচিত (একটি নেতৃস্থানীয় আন্ডারস্কোর সহ নামকরণ করা হয়েছে)। একটি সাধারণ শৈলী হল myrule-এর বাস্তবায়ন ফাংশনকে myrule নাম _myrule_impl ।
  • একটি সু-সংজ্ঞায়িত প্রদানকারী ইন্টারফেস ব্যবহার করে আপনার নিয়মগুলির মধ্যে তথ্য পাস করুন। ঘোষণা এবং নথি প্রদানকারী ক্ষেত্র.
  • এক্সটেনসিবিলিটি মাথায় রেখে আপনার নিয়ম ডিজাইন করুন। বিবেচনা করুন যে অন্যান্য নিয়মগুলি আপনার নিয়মের সাথে ইন্টারঅ্যাক্ট করতে, আপনার প্রদানকারীদের অ্যাক্সেস করতে এবং আপনার তৈরি করা ক্রিয়াগুলি পুনরায় ব্যবহার করতে চাইতে পারে।
  • আপনার নিয়মে কর্মক্ষমতা নির্দেশিকা অনুসরণ করুন।