เขียนไฟล์การกำหนดค่า bazelrc

Bazel ยอมรับตัวเลือกมากมาย ตัวเลือกบางอย่างจะเปลี่ยนแปลงบ่อย (เช่น --subcommands) ในขณะที่ตัวเลือกอื่นๆ จะคงที่ในหลายๆ บิลด์ (เช่น --package_path) หากต้องการหลีกเลี่ยงการระบุตัวเลือกที่ไม่มีการเปลี่ยนแปลงเหล่านี้สำหรับทุกบิลด์ (และคำสั่งอื่นๆ) คุณสามารถระบุตัวเลือกในไฟล์การกำหนดค่าที่ชื่อ .bazelrc ได้

.bazelrc ไฟล์อยู่ที่ไหน

Bazel จะค้นหาไฟล์การกำหนดค่าที่ไม่บังคับในตำแหน่งต่อไปนี้ ตามลำดับที่แสดงด้านล่าง ระบบจะตีความตัวเลือกตามลำดับนี้ ดังนั้นตัวเลือกในไฟล์ที่อยู่ภายหลังจะลบล้างค่าจากไฟล์ก่อนหน้าได้หากเกิดความขัดแย้ง ตัวเลือกทั้งหมดที่ควบคุมการโหลดไฟล์เหล่านี้คือตัวเลือกการเริ่มต้น ซึ่งหมายความว่าตัวเลือกเหล่านี้ต้องอยู่หลัง bazel และก่อนคำสั่ง (build, test ฯลฯ)

1. ไฟล์ RC ของระบบ เว้นแต่จะมี --nosystem_rc

   เส้นทาง:

   • ใน Linux/macOS/Unixes ให้ทำดังนี้ /etc/bazel.bazelrc
   • ใน Windows %ProgramData%\bazel.bazelrc

   หากไม่มีไฟล์นี้ ก็ไม่ใช่ข้อผิดพลาด

   หากต้องการตำแหน่งอื่นที่ระบบระบุ คุณต้องสร้างไบนารี Bazel ที่กำหนดเอง โดยลบล้างค่า BAZEL_SYSTEM_BAZELRC_PATH ใน //src/main/cpp:option_processor ตำแหน่งที่ระบบระบุอาจมีการอ้างอิงตัวแปรสภาพแวดล้อม เช่น ${VAR_NAME} ใน Unix หรือ %VAR_NAME% ใน Windows

2. ไฟล์ RC ของพื้นที่ทำงาน เว้นแต่จะมี --noworkspace_rc

   เส้นทาง: .bazelrc ในไดเรกทอรีพื้นที่ทำงาน (ข้างไฟล์ main MODULE.bazel)

   หากไม่มีไฟล์นี้ ก็ไม่ใช่ข้อผิดพลาด

3. ไฟล์ RC ของบ้าน เว้นแต่จะมี --nohome_rc

   เส้นทาง:

   • ใน Linux/macOS/Unixes ให้ทำดังนี้ $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 ทั่วโลก

.bazelrc ไวยากรณ์และความหมาย

เช่นเดียวกับไฟล์ "rc" ทั้งหมดของ UNIX ไฟล์ .bazelrc เป็นไฟล์ข้อความที่มีไวยากรณ์แบบบรรทัด ระบบจะละเว้นบรรทัดว่างและบรรทัดที่ขึ้นต้นด้วย # (ความคิดเห็น) แต่ละ บรรทัดมีลำดับของคำ ซึ่งจะมีการโทเค็นตาม กฎเดียวกันกับ Bourne Shell

การนำเข้า

บรรทัดที่ขึ้นต้นด้วย import, try-import หรือ try-import-if-bazel-version เป็นบรรทัดพิเศษ: ใช้บรรทัดเหล่านี้เพื่อโหลดไฟล์ "rc" อื่นๆ หากต้องการระบุเส้นทางที่ เกี่ยวข้องกับรูทของพื้นที่ทำงาน ให้เขียน import %workspace%/path/to/bazelrc

ความแตกต่างระหว่างคำสั่งนำเข้าต่างๆ มีดังนี้

• import - Bazel จะล้มเหลวหากไม่มีไฟล์ที่ imported (หรืออ่านไม่ได้)
• try-import - ระบบจะพยายามนำเข้าไฟล์ แต่จะไม่เหมือนกับ import ซึ่ง Bazel จะไม่ล้มเหลวหากไม่มีไฟล์ (หรืออ่านไม่ได้)
• try-import-if-bazel-version - คล้ายกับ try-import แต่จะมีการตรวจสอบเงื่อนไขเพิ่มเติมใน Bazel เวอร์ชันปัจจุบันก่อนที่จะพยายามนำเข้า ดูไวยากรณ์ได้ที่ด้านล่าง

การนำเข้า Bazel เวอร์ชันแบบมีเงื่อนไขอาจมีประโยชน์หากโปรเจ็กต์ต้องทำงานภายใต้ Bazel หลายเวอร์ชัน หรือในระหว่างการเปลี่ยนจาก Bazel เวอร์ชันหนึ่งไปยังอีกเวอร์ชันหนึ่ง คุณอาจต้องใช้แฟล็กที่แตกต่างกันสำหรับ Bazel เวอร์ชันต่างๆ เนื่องจากแฟล็กอาจเลิกใช้งาน นำออก หรือเปิดตัวในแต่ละรุ่น หากต้องการตรวจสอบเวอร์ชัน Bazel ที่คุณใช้ ให้เรียกใช้ bazel --version ระบบรองรับการตรวจสอบแบบมีเงื่อนไขต่อไปนี้ และต้องใช้เวอร์ชันเชิงความหมายที่ถูกต้อง

# Strictly greater than: used for post-release targeting
try-import-if-bazel-version >7.0.0 %workspace%/configs/post_v7.rc

# Greater than or equal to: commonly used for feature introduction
try-import-if-bazel-version >=6.0.0 %workspace%/configs/features.rc

# Strictly less than: used for deprecated flags removed in newer versions
try-import-if-bazel-version <7.0.0 %workspace%/configs/legacy.rc

# Less than or equal to: caps configuration to a specific version
try-import-if-bazel-version <=5.4.0 %workspace%/configs/v5_fixes.rc

# Exact match: hotfix for a specific broken release
try-import-if-bazel-version ==6.3.2 %workspace%/configs/hotfix_6.3.2.rc

# Not equal to: excludes broken version from standard config
try-import-if-bazel-version !=7.0.1 %workspace%/configs/standard.rc

ตัวดำเนินการเครื่องหมายตัวหนอนเพิ่มเติมจะระบุช่วงสำหรับการเปลี่ยนแปลงเวอร์ชันแพตช์ เวอร์ชันย่อย และเวอร์ชันหลัก

# Equivalent to >=1.2.3 <1.3.0
try-import-if-bazel-version ~1.2.3 %workspace%/configs/1.2.3_flags.rc

# Equivalent to >=1.2.0 <1.3.0 (Same as 1.2.x)
try-import-if-bazel-version ~1.2 %workspace%/configs/1.2_flags.rc

# Equivalent to >=1.0.0 <2.0.0 (Same as 1.x)
try-import-if-bazel-version ~1 %workspace%/configs/v1_flags.rc

ลำดับความสำคัญของการนำเข้า

• ตัวเลือกในไฟล์ที่นำเข้าจะมีลำดับความสำคัญเหนือกว่าตัวเลือกที่ระบุก่อน คำสั่งนำเข้า
• ตัวเลือกที่ระบุหลังคำสั่งนำเข้าจะมีลำดับความสำคัญสูงกว่าตัวเลือกในไฟล์ที่นำเข้า
• ตัวเลือกในไฟล์ที่นำเข้าในภายหลังจะมีลำดับความสำคัญเหนือกว่าไฟล์ที่นำเข้าก่อนหน้านี้

ค่าเริ่มต้นของตัวเลือก

บรรทัดส่วนใหญ่ของ bazelrc จะกำหนดค่าตัวเลือกเริ่มต้น คำแรกในแต่ละบรรทัดจะระบุเวลาที่ใช้ค่าเริ่มต้นเหล่านี้

• startup: ตัวเลือกการเริ่มต้น ซึ่งอยู่ก่อนคำสั่ง และอธิบายไว้ ใน bazel help startup_options
• common: ตัวเลือกที่ควรใช้กับคำสั่ง Bazel ทั้งหมดที่รองรับ ตัวเลือกเหล่านั้น หากคำสั่งไม่รองรับตัวเลือกที่ระบุในลักษณะนี้ ระบบจะละเว้นตัวเลือกดังกล่าวตราบใดที่ตัวเลือกนั้นใช้ได้กับคำสั่ง Bazel อื่นบางคำสั่ง โปรดทราบว่าการดำเนินการนี้ใช้กับชื่อตัวเลือกเท่านั้น หากคำสั่งปัจจุบันยอมรับ ตัวเลือกที่มีชื่อที่ระบุ แต่ไม่รองรับค่าที่ระบุ การดำเนินการจะล้มเหลว
• always: ตัวเลือกที่ใช้กับคำสั่ง Bazel ทั้งหมด หากคำสั่งไม่ รองรับตัวเลือกที่ระบุในลักษณะนี้ คำสั่งจะล้มเหลว
• command: คำสั่ง Bazel เช่น build หรือ query ซึ่งใช้ตัวเลือก ตัวเลือกเหล่านี้ยังมีผลกับคำสั่งทั้งหมดที่รับค่ามาจากคำสั่งที่ระบุด้วย (เช่น test รับค่าจาก build)

แต่ละบรรทัดเหล่านี้อาจใช้มากกว่า 1 ครั้ง และอาร์กิวเมนต์ที่ตามหลังคำแรกจะรวมกันราวกับว่าปรากฏในบรรทัดเดียว (ผู้ใช้ 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, fetch และ vendor สืบทอดมาจาก test

• ระบบจะแยกวิเคราะห์ 2 บรรทัดที่ระบุตัวเลือกสำหรับคำสั่งเดียวกันที่ความจำเพาะเท่ากัน ตามลำดับที่ปรากฏในไฟล์

• เนื่องจากกฎลำดับความสำคัญนี้ไม่ตรงกับลำดับไฟล์ จึงช่วยให้ อ่านง่ายหากคุณทำตามลำดับความสำคัญภายในไฟล์ rc โดยเริ่มจาก ตัวเลือก common ที่ด้านบน และจบด้วยคำสั่งที่เฉพาะเจาะจงที่สุดที่ ด้านล่างของไฟล์ ด้วยวิธีนี้ ลำดับการอ่านตัวเลือกจะเหมือนกับลำดับการใช้ตัวเลือก ซึ่งเป็นวิธีที่ใช้งานง่ายกว่า

อาร์กิวเมนต์ที่ระบุในบรรทัดของไฟล์ rc อาจรวมถึงอาร์กิวเมนต์ที่ไม่ได้เป็นตัวเลือก เช่น ชื่อของเป้าหมายการสร้าง เป็นต้น ตัวเลือกเหล่านี้เช่นเดียวกับตัวเลือกที่ระบุในไฟล์เดียวกัน จะมีความสำคัญต่ำกว่าตัวเลือกที่คล้ายกันในบรรทัดคำสั่ง และจะนำหน้ารายการอาร์กิวเมนต์ที่ไม่ใช่ตัวเลือกเสมอ

--config

นอกจากจะใช้ตั้งค่าเริ่มต้นของตัวเลือกแล้ว ไฟล์ rc ยังใช้จัดกลุ่มตัวเลือก และระบุรูปแบบย่อสำหรับการจัดกลุ่มทั่วไปได้ด้วย โดยการเพิ่ม:name คำต่อท้ายลงในคำสั่ง ระบบจะไม่สนใจตัวเลือกเหล่านี้โดยค่าเริ่มต้น แต่จะรวมตัวเลือกเหล่านี้ไว้เมื่อมีตัวเลือก --config=name ไม่ว่าจะในบรรทัดคำสั่งหรือในไฟล์ .bazelrc แบบเรียกซ้ำ แม้จะอยู่ภายใน คำจำกัดความการกำหนดค่าอื่นก็ตาม ตัวเลือกที่ระบุโดย command:name จะขยายเฉพาะคำสั่งที่เกี่ยวข้องตามลำดับความสำคัญที่อธิบายไว้ข้างต้น

--config=foo จะขยายเป็นตัวเลือกที่กำหนดไว้ใน ไฟล์ rc "ในตำแหน่ง" เพื่อให้ตัวเลือก ที่ระบุสำหรับการกำหนดค่ามีลำดับความสำคัญเดียวกันกับที่ตัวเลือก --config=foo มี

ไวยากรณ์นี้ไม่มีผลกับการใช้ startup เพื่อตั้งค่าตัวเลือกการเริ่มต้น ระบบจะไม่สนใจการตั้งค่า startup:config-name --some_startup_option ใน .bazelrc

--enable_platform_specific_config

คุณเปิดใช้การกำหนดค่าเฉพาะแพลตฟอร์มใน .bazelrc ได้โดยอัตโนมัติโดยใช้ --enable_platform_specific_config ตัวอย่างเช่น หากระบบปฏิบัติการโฮสต์เป็น Linux และเรียกใช้คำสั่ง build ระบบจะเปิดใช้การกำหนดค่า build:linux โดยอัตโนมัติ ตัวระบุระบบปฏิบัติการที่รองรับคือ linux, macos, windows, freebsd และ openbsd การเปิดใช้ฟีเจอร์นี้จะเทียบเท่ากับการใช้ --config=linux ใน Linux, --config=windows ใน Windows และอื่นๆ

ดู --enable_platform_specific_config

ตัวอย่าง

ตัวอย่างไฟล์ ~/.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 ละเว้น (1 รายการต่อบรรทัด) รายการจะสัมพันธ์กับรูทของพื้นที่ทำงาน

ไฟล์ .bazelrc ทั่วโลก

Bazel จะอ่านไฟล์ bazelrc ที่ไม่บังคับตามลำดับต่อไปนี้

1. ไฟล์ rc ของระบบอยู่ที่ etc/bazel.bazelrc
2. ไฟล์ rc ของพื้นที่ทำงานอยู่ที่ $workspace/tools/bazel.rc
3. ไฟล์ rc ในหน้าแรกอยู่ที่ $HOME/.bazelrc

ไฟล์ bazelrc แต่ละไฟล์ที่แสดงที่นี่มีแฟล็กที่สอดคล้องกันซึ่งใช้เพื่อปิดใช้ได้ (เช่น --nosystem_rc, --noworkspace_rc, --nohome_rc) คุณยังทำให้ Bazel ไม่สนใจ bazelrc ทั้งหมดได้โดยส่งตัวเลือกการเริ่มต้น --ignore_all_rc_files