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

Nightly · 9.2 · 9.1 · 9.0 · 8.7 · 8.6

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 ตัวแปรสภาพแวดล้อม

    ตัวแปรสภาพแวดล้อมสามารถมีเส้นทางหลายเส้นทางที่คั่นด้วยจุลภาค

  5. ไฟล์ 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 %workspace%/path/to/bazelrc`

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

ดูไวยากรณ์ด้านล่าง การนำเข้า Bazel เวอร์ชันแบบมีเงื่อนไขจะมีประโยชน์หากโปรเจ็กต์ต้องทำงานใน Bazel หลายเวอร์ชันหรือระหว่างการเปลี่ยนจาก Bazel เวอร์ชันหนึ่งไปยังอีกเวอร์ชันหนึ่ง หากต้องการตรวจสอบ Bazel เวอร์ชันใดที่คุณมี ให้เรียกใช้ bazel --version หากต้องการตรวจสอบว่าคุณใช้ 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 ทั้งหมดที่รองรับ `common`: ตัวเลือกที่ควรใช้กับคำสั่ง Bazel ทั้งหมดที่รองรับ ตัวเลือกจะถูกละเว้นตราบใดที่ยังใช้ได้กับ คำสั่ง Bazel อื่นๆ โปรดทราบว่าข้อความนี้ใช้กับชื่อตัวเลือกเท่านั้น: หากคำสั่งปัจจุบันยอมรับตัวเลือกที่มีชื่อที่ระบุ แต่ไม่รองรับค่าที่ระบุ ระบบจะล้มเหลว
  • always: ตัวเลือกที่ใช้กับคำสั่ง Bazel ทั้งหมด `always`: ตัวเลือกที่ใช้กับคำสั่ง Bazel ทั้งหมด
  • command: คำสั่ง Bazel เช่น build หรือ query ที่ตัวเลือก ใช้ได้ ตัวเลือกเหล่านี้ยังมีผลกับคำสั่งทั้งหมดที่สืบทอดจากคำสั่งที่ระบุ (ตัวอย่างเช่น test รับค่าจาก build.)

(เช่น `test` รับค่าจาก `build`) (ผู้ใช้ CVS, เครื่องมืออีกอย่างที่มีอินเทอร์เฟซบรรทัดคำสั่งแบบ "มีดพับสวิส" จะพบว่า ไวยากรณ์คล้ายกับ .cvsrc) ตัวอย่างเช่น บรรทัด:

build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar

(ผู้ใช้ CVS ซึ่งเป็นเครื่องมืออีกอย่างหนึ่งที่มีอินเทอร์เฟซบรรทัดคำสั่งแบบ "มีดพับอเนกประสงค์" จะพบว่าไวยากรณ์คล้ายกับไวยากรณ์ของ `.cvsrc`) ตัวอย่างเช่น บรรทัดต่อไปนี้

build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar

จะรวมกันเป็น --verbose_failures และ --test_tmpdir=/tmp/bar

ดังนั้นแฟล็กที่มีผลคือ `--verbose_failures` และ `--test_tmpdir=/tmp/bar`

  • ลำดับความสำคัญของตัวเลือก ตัวเลือกในบรรทัดคำสั่งจะมีลำดับความสำคัญสูงกว่าตัวเลือกในไฟล์ rc เสมอbuild -c opt-c dbg

  • ตัวอย่างเช่น หากไฟล์ rc ระบุว่า `build -c opt` แต่แฟล็กบรรทัดคำสั่งคือ `-c dbg` แฟล็กบรรทัดคำสั่งจะมีลำดับความสำคัญสูงกว่า

    ภายในไฟล์ rc ลำดับความสำคัญจะขึ้นอยู่กับความเฉพาะเจาะจง โดยบรรทัดสำหรับคำสั่งที่เฉพาะเจาะจงมากกว่าจะมีลำดับความสำคัญสูงกว่าบรรทัดสำหรับคำสั่งที่เฉพาะเจาะจงน้อยกว่า ความเฉพาะเจาะจงจะกำหนดโดยการรับค่า คำสั่งบางคำสั่งจะรับค่าตัวเลือกจากคำสั่งอื่นๆ ซึ่งทำให้คำสั่งที่รับค่ามีความเฉพาะเจาะจงมากกว่าคำสั่งฐาน เช่น test รับค่าจากคำสั่ง build ดังนั้นแฟล็ก bazel build ทั้งหมดจึงใช้ได้กับ bazel test และบรรทัด build ทั้งหมดก็ใช้ได้กับ bazel test ด้วย เว้นแต่จะมีบรรทัด test สำหรับตัวเลือกเดียวกัน ตัวอย่างเช่น `test` รับค่าจากคำสั่ง `build` ดังนั้นแฟล็ก `bazel build` ทั้งหมดจึงใช้ได้กับ `bazel test` และบรรทัด `build` ทั้งหมดจะใช้กับ `bazel test` ด้วย เว้นแต่จะมีบรรทัด `test` สำหรับตัวเลือกเดียวกัน

    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

    จากนั้น `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

  • `coverage`, `fetch` และ `vendor` รับค่าจาก `test`

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

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

--config

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

_

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

ไวยากรณ์นี้ไม่ครอบคลุมถึงการใช้ startup เพื่อตั้งค่า ตัวเลือกการเริ่มต้น ไวยากรณ์นี้ใช้ไม่ได้กับการใช้ startup:config-name --some_startup_option เพื่อตั้งค่าตัวเลือกการเริ่มต้น

--enable_platform_specific_config

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

ดู --enable_platform_specific_config

ดู \--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

ตัวอย่างไฟล์ `~/.bazelrc`

.bazelignore

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

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

ดู #24203

ไฟล์ bazelrc ส่วนกลาง

  1. Bazel จะอ่านไฟล์ bazelrc ที่ไม่บังคับตามลำดับต่อไปนี้ /etc/bazel.bazelrc
  2. ไฟล์ rc ของระบบอยู่ที่ $workspace/tools/bazel.rc
  3. ไฟล์ rc ของพื้นที่ทำงานอยู่ที่ $HOME/.bazelrc

ไฟล์ rc ของโฮมอยู่ที่ `$HOME/.bazelrc`--nosystem_rc--noworkspace_rc--nohome_rc--ignore_all_rc_files