كتابة ملفات إعداد Bazelrc

يقبل بازيل خيارات متعددة. تتنوع بعض الخيارات بشكل متكرر (على سبيل المثال، --subcommands)، بينما تظل خيارات أخرى كما هي على مستوى عدة إصدارات (مثل --package_path). لتجنُّب تحديد هذه الخيارات التي لم يتم تغييرها لكل إصدار (وأوامر أخرى)، يمكنك تحديد الخيارات في ملف إعداد يُسمى .bazelrc.

أين توجد ملفات .bazelrc؟

يبحث Basel عن ملفات الإعداد الاختيارية في المواقع التالية، بالترتيب الموضح أدناه. يتم تفسير الخيارات بهذا الترتيب، لذلك يمكن أن تلغي الخيارات في الملفات اللاحقة قيمة من ملف سابق في حال حدوث تعارض. جميع الخيارات التي تتحكم في أي من هذه الملفات يتم تحميلها هي خيارات بدء التشغيل، مما يعني أنه يجب أن تحدث بعد bazel وقبل الأمر (build، test، إلخ).

1. ملف RC من النظام، ما لم يكن --nosystem_rc متوفرًا.

   المسار:

   • نظاما التشغيل Linux/macOS/Unix: /etc/bazel.bazelrc
   • على نظام التشغيل Windows: %ProgramData%\bazel.bazelrc

   لا يعد هذا خطأً إذا لم يتم العثور على هذا الملف.

   في حال الحاجة إلى موقع جغرافي آخر محدّد من قبل النظام، عليك إنشاء ملف ثنائي بازل مخصّص، مع إلغاء قيمة BAZEL_SYSTEM_BAZELRC_PATH في //src/main/cpp:option_processor. قد يحتوي الموقع الذي يحدده النظام على مراجع متغيرة للبيئة، مثل ${VAR_NAME} على Unix أو %VAR_NAME% على Windows.

2. ملف RC، ما لم يكن --noworkspace_rc موجودًا

   المسار: .bazelrc في دليل مساحة العمل (بجانب الملف WORKSPACE الرئيسي).

   لا يعد هذا خطأً إذا لم يتم العثور على هذا الملف.

3. ملف RC المنزلي، ما لم يكن --nohome_rc متوفرًا.

   المسار:

   • نظاما التشغيل Linux/macOS/Unix: $HOME/.bazelrc
   • على نظام التشغيل Windows: %USERPROFILE%\.bazelrc إذا كان موجودًا أو %HOME%/.bazelrc

   لا يعد هذا خطأً إذا لم يتم العثور على هذا الملف.

4. ملف RC الذي حدّده المستخدم في حال تحديده باستخدام --bazelrc=file

   هذه العلامة اختيارية ولكن يمكن تحديدها عدة مرات أيضًا.

   تشير الخاصية /dev/null إلى أنه سيتم تجاهل جميع --bazelrc، ما يُعدّ مفيدًا لإيقاف البحث عن ملف RC لمستخدم، كما هو الحال في إصدارات الإصدارات.

   مثال:

   --bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
   

   • تمت قراءة x.rc وy.rc.
   • تم تجاهل z.rc بسبب /dev/null السابق.

بالإضافة إلى ملف الإعداد الاختياري هذا، يبحث Bazel عن ملف RC عام. لمزيد من التفاصيل، راجِع قسم البازار العالمي.

بنية .bazelrc ودلالاته

مثل كل ملفات UNIX "rc"، يكون الملف .bazelrc هو ملف نصي يتضمّن قاعدة نحوية مستندة إلى سطر. ويتم تجاهل الأسطر والأسطر الفارغة التي تبدأ بـ # (التعليقات). يحتوي كل سطر على تسلسل من الكلمات المميّزة وفقًا للقواعد نفسها المُستخدَمة في واجهة Bourne.

الاستيراد

الأسطر التي تبدأ بـ import أو try-import خاصة: يمكنك استخدامها لتحميل ملفات "rc" الأخرى. لتحديد مسار مرتبط بجذر مساحة العمل، اكتب import %workspace%/path/to/bazelrc.

الفرق بين import وtry-import هو أنّ Bazel يخفق إذا كان ملف import غير متوفّر (أو يتعذّر قراءته)، ولكن لا يحدث ذلك بالنسبة إلى try-import. الملف.

أولوية الاستيراد:

• وتُعطى الخيارات في الملف المُستورَد الأولوية على الخيارات المُحدّدة قبل بيان الاستيراد.
• وتُعطى الخيارات المحدّدة بعد بيان الاستيراد الأولوية على الخيارات الواردة في الملف المستورَد.
• وتُعطى الخيارات في الملفات التي تم استيرادها لاحقًا الأولوية على الملفات التي تم استيرادها في وقت سابق.

الإعدادات التلقائية للخيارات

تحدّد معظم سطور البازيلك قيم الخيارات التلقائية. وتحدّد الكلمة الأولى في كل سطر عند تطبيق هذه الإعدادات التلقائية:

• startup: خيارات بدء التشغيل، التي يتم تنفيذها قبل الأمر، والموضّحة في bazel help startup_options.
• common: الخيارات التي تنطبق على جميع أوامر Bazel.
• command: الأمر Bazel، مثل build أو query الذي تنطبق عليه الخيارات. وتسري هذه الخيارات أيضًا على جميع الأوامر التي تكتسب من الأمر المحدّد. (على سبيل المثال، test من build.)

قد يتم استخدام كل سطر من هذه الأسطر أكثر من مرة ويتم دمج الوسيطات التي تتبع الكلمة الأولى كما لو كانت تظهر في سطر واحد. (بالنسبة إلى مستخدمي CVS، أداة أخرى تستخدم واجهة سطر الأوامر "سكين الجيش السويسري"، ستعثر على البنية المشابهة للغة .cvsrc.) على سبيل المثال، الأسطر:

build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar

تم دمجها معًا:

build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar

لذا، فالعلامتان الفعّالتان هما --verbose_failures و--test_tmpdir=/tmp/bar.

أولوية الخيار:

• دائمًا ما يكون للخيارات في سطر الأوامر الأولوية على الخيارات المتوفرة في ملفات RC. على سبيل المثال، إذا كان ملف RC يعرض build -c opt ولكن علامة سطر الأوامر هي -c dbg، تكون الأولوية لعلامة سطر الأوامر.

• في ملف RC، يكون الأولوية مُحدَّدة حسب الأولوية: تُعطى الأولوية لأمر أكثر تحديدًا على الأسطر للأمر الأقل تحديدًا.

  ويتم تحديد الدقة من خلال الاكتساب. تكتسب بعض الأوامر خيارات من الأوامر الأخرى، ما يجعل الأمر الموروث أكثر تحديدًا من الأمر الأساسي. على سبيل المثال:test منbuild الأمر كلهbazel build العلامات صالحة لـbazel test ، وجميعbuild تنطبق أيضًا الخطوط علىbazel test ما لم يكن هناكtest سطر للخيار نفسه. إذا كان ملف rc يقول:

  test -c dbg --test_env=PATH
  build -c opt --verbose_failures
  

  ثم سيستخدم bazel build //foo -c opt --verbose_failures وbazel test //foo سيستخدم --verbose_failures -c dbg --test_env=PATH.

  الرسم البياني (للتخصيص) هو:

  • يكتسب كل أمر من common
  • تكتسب الأوامر التالية من (وتكون أكثر تحديدًا من) build: test ،run ،clean ،mobile-install ،info ، print_action ،config ،cquery ، وِaquery
  • coverage يكتسب من test

• يتم تحليل سطرين يحددان خيارات الأمر نفسه بدقة محددة بالترتيب الذي تظهر به داخل الملف.

• بما أنّ قاعدة الأولوية هذه لا تتطابق مع ترتيب الملف، سيساعدك ذلك على اتّباع ترتيب الأولوية داخل ملفات RC: البدء بخيارات common في أعلى الصفحة، وإنهاء الأوامر الأكثر تحديدًا في أسفل الملف. وبهذه الطريقة، الترتيب الذي تتم به قراءة الخيارات مماثل للترتيب الذي يتم تطبيقها به، وهو أكثر بساطة.

قد تتضمن الوسيطات المُحدَّدة في سطر من ملف RC وسيطات ليست خيارات، مثل أسماء أهداف الإصدار، وما إلى ذلك. وتكون الأولوية لهذه الخيارات، مثل الخيارات المحدّدة في الملفات نفسها، مقارنةً بأشقائها في سطر الأوامر، وتُضاف دائمًا إلى القائمة الصريحة للوسيطات غير الاختيارية.

--config

بالإضافة إلى إعداد الخيارات التلقائية، يمكن استخدام ملف RC لتجميع الخيارات وتوفير اختصار للتجميعات الشائعة. ويتم ذلك عن طريق إضافة لاحقة :name إلى الأمر. يتم تجاهل هذه الخيارات تلقائيًا، ولكن سيتم تضمينها عند تضمين الخيار --config=name، إما في سطر الأوامر أو في ملف .bazelrc، بشكل متكرّر، حتى داخل ملف آخر. تهيئة تلقائية. لن يتم توسيع الخيارات المحددة من قِبل command:name إلا للأوامر السارية، بترتيب الأولوية الموضح أعلاه.

يتم توسيع --config=foo إلى الخيارات المحدّدة في ملفات RC "في مكانها" بحيث يكون للخيارات المحدّدة للإعداد الإعدادات نفسها في الخيار --config=foo.

لا تمتد هذه البنية إلى استخدام startup لضبط خيارات بدء التشغيل. سيتم تجاهل الإعدادات startup:config-name --some_startup_option في .bazelrc.

مثال

إليك مثال على ملف ~/.bazelrc:

# Bob's Bazel option defaults

startup --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --show_timestamps --keep_going --jobs 600
build --color=yes
query --keep_going

# Definition of --config=memcheck
build:memcheck --strip=never --test_timeout=3600

ملفات أخرى تحكم سلوك Bazel

.bazelignore

يمكنك تحديد الأدلة داخل مساحة العمل التي تريد أن يتجاهلها Bazel، مثل المشاريع ذات الصلة التي تستخدم أنظمة إصدار أخرى. ضَع ملفًا باسم .bazelignore في جذر مساحة العمل وأضِف الأدلة التي تريد أن يتجاهلها Bazel، واحدًا في كل سطر. ترتبط الإدخالات بجذر مساحة العمل.

ملف البازيلش العالمي

تقرأ Bazel ملفات بازيليك اختيارية بالترتيب التالي: - ملف RC النظام الموجود في etc/bazel.bazelrc. - ملف RC-rc موجود في $workspace/tools/bazel.rc. - ملف RC-المنزل محليًا في $HOME/.bazelrc

لكل ملف بازيلك مدرج هنا علامة مطابقة يمكن استخدامها لإيقافها (مثل --nosystem_rc و--noworkspace_rc و--nohome_rc). يمكنك أيضًا جعل بازيل يتجاهل جميع بازيليك بتمرير خيار بدء التشغيل --ignore_all_rc_files.