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

ไฟล์ .bazelignore ไม่อนุญาตให้ใช้ความหมายของ Glob Bazel 8 เปิดตัวไฟล์ REPO.bazel ซึ่งอนุญาตให้ใช้คำสั่งอื่น ignore_directories() โดยจะใช้รายการไดเรกทอรีที่จะละเว้นเช่นเดียวกับ .bazelignore แต่ใช้ความหมายของ Glob ดู #24203

ไฟล์ .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