เขียนไฟล์การกำหนดค่า 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 ในไดเรกทอรีพื้นที่ทำงาน (ข้างไฟล์ 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 เป็นบรรทัดพิเศษ ใช้บรรทัดเหล่านี้เพื่อโหลด ไฟล์ "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 ซึ่งเป็นเครื่องมืออีกอย่างที่มีอินเทอร์เฟซบรรทัดคำสั่งแบบ "มีดพับสวิส" จะเห็นว่าไวยากรณ์คล้ายกับของ .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