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

วันที่ รายงานปัญหา ดูแหล่งที่มา ตอนกลางคืน · 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/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 ในไดเรกทอรีพื้นที่ทำงาน (ถัดจากหลัก WORKSPACE)

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

  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 มองหา Global rc ดูรายละเอียดเพิ่มเติมได้ที่ส่วน bazelrc ทั่วโลก

ไวยากรณ์และความหมายภาษา.bazelrc

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

การนำเข้า

บรรทัดที่ขึ้นต้นด้วย 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 รับค่ามาจาก test

  • สองบรรทัดที่ระบุตัวเลือกสำหรับคำสั่งเดียวกันที่มีความจำเพาะเท่ากันคือ ได้รับการแยกวิเคราะห์ตามลำดับที่ปรากฏในไฟล์

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

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

--config

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

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

ไวยากรณ์นี้ไม่ได้ครอบคลุมการใช้ startup เพื่อตั้งค่า ตัวเลือกการเริ่มต้นใช้งาน การเกริ่นนำ ระบบจะไม่สนใจ startup:config-name --some_startup_option ในไฟล์ .bazelrc

ตัวอย่าง

ต่อไปนี้คือตัวอย่างไฟล์ ~/.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 ที่ไม่บังคับตามลำดับต่อไปนี้ - ไฟล์ rc ของระบบอยู่ที่ etc/bazel.bazelrc - ไฟล์ rc ของ Workspace อยู่ที่ $workspace/tools/bazel.rc - ไฟล์ rc ของบ้านในภาษาท้องถิ่นที่ $HOME/.bazelrc

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