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

รายงานปัญหา ดูแหล่งที่มา รุ่น Nightly · 8.0 7.4 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

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

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

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

   เส้นทาง:

   • ใน Linux/macOS/Unix: /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 ในไดเรกทอรีพื้นที่ทํางาน (ข้างไฟล์ MODULE.bazel หลัก)

   หากไม่มีไฟล์นี้ ก็ไม่ถือว่าเป็นข้อผิดพลาด

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

   เส้นทาง:

   • ใน Linux/macOS/Unix: $HOME/.bazelrc
   • ใน Windows: %USERPROFILE%\.bazelrc หากมี หรือ %HOME%/.bazelrc

   หากไม่มีไฟล์นี้ ก็ไม่ถือว่าเป็นข้อผิดพลาด

4. ไฟล์ RC ที่ผู้ใช้ระบุ หากระบุด้วย --bazelrc=file

   คุณจะใช้ Flag นี้หรือไม่ก็ได้ แต่ระบุได้หลายครั้ง

   /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 ไวยากรณ์และความหมาย

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

การนำเข้า

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

ความแตกต่างระหว่าง import กับ try-import คือ Bazel จะทำงานไม่สำเร็จหากไม่มีไฟล์ import (หรืออ่านไม่ได้) แต่จะไม่มีปัญหากับไฟล์ try-import

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

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

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

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

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

บรรทัดเหล่านี้แต่ละบรรทัดอาจใช้มากกว่า 1 ครั้ง และระบบจะรวมอาร์กิวเมนต์ที่อยู่หลังคำแรกเข้าด้วยกันราวกับว่าปรากฏในบรรทัดเดียว (ผู้ใช้ CVS ซึ่งเป็นเครื่องมืออีกอย่างที่มีอินเทอร์เฟซบรรทัดคำสั่ง "Swiss Army Knife" จะพบว่าไวยากรณ์คล้ายกับของ .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 แต่ Flag บรรทัดคำสั่งคือ -c dbg Flag บรรทัดคำสั่งจะมีลำดับความสำคัญเหนือกว่า

• ภายในไฟล์ rc ลําดับความสําคัญจะขึ้นอยู่กับความเฉพาะเจาะจง โดยบรรทัดสําหรับคําสั่งที่เฉพาะเจาะจงมากกว่าจะมีลําดับความสําคัญเหนือบรรทัดสําหรับคําสั่งที่เฉพาะเจาะจงน้อยกว่า

  ความเฉพาะเจาะจงจะกำหนดโดยการรับช่วง คำสั่งบางรายการรับค่าตัวเลือกมาจากคำสั่งอื่นๆ ซึ่งทำให้คำสั่งที่รับค่านั้นเจาะจงกว่าคำสั่งพื้นฐาน เช่น test รับค่ามาจากคําสั่ง build ดังนั้น Flag 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 เฉพาะสำหรับคำสั่งที่เกี่ยวข้องตามลําดับลําดับความสําคัญที่อธิบายไว้ข้างต้น

หมายเหตุ: คุณสามารถกำหนดค่าในไฟล์ .bazelrc ไฟล์ใดก็ได้ และระบบจะขยายบรรทัดทั้งหมดของรูปแบบ command:name (สำหรับคำสั่งที่เกี่ยวข้อง) ในไฟล์ rc ต่างๆ เราขอแนะนำให้การกำหนดค่าที่ระบุไว้ในไฟล์ rc ส่วนบุคคลขึ้นต้นด้วยขีดล่าง (_) เพื่อหลีกเลี่ยงการแชร์ชื่อโดยไม่ตั้งใจ

เพื่อหลีกเลี่ยงข้อขัดแย้งของชื่อ

--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 การเปิดใช้ Flag นี้เทียบเท่ากับการใช้ --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 ละเว้น โดยเพิ่มทีละไดเรกทอรีต่อบรรทัด รายการจะสัมพันธ์กับรูทของพื้นที่ทำงาน

ไฟล์ bazelrc ระดับระบบ

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

1. ไฟล์ rc ของระบบอยู่ที่ etc/bazel.bazelrc
2. ไฟล์ rc ของ Workspace อยู่ที่ $workspace/tools/bazel.rc
3. ไฟล์ rc ของบ้านอยู่ที่ $HOME/.bazelrc

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