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

Nightly · 9.1 · 9.0 · 8.7 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

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

    แฟล็กนี้ไม่บังคับ แต่ก็ระบุได้หลายครั้งเช่นกัน

    /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'ed (หรืออ่านไม่ได้) แต่จะไม่แสดงข้อผิดพลาดสำหรับไฟล์ที่ try-import'ed

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

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

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

บรรทัดส่วนใหญ่ของ 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 (และมีความเฉพาะเจาะจงมากกว่า 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