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

หมายเหตุ: คุณกำหนดการกำหนดค่าในไฟล์ .bazelrc ได้ และทุกบรรทัดของ รูปแบบ command:name (สำหรับคำสั่งที่เกี่ยวข้อง) จะถูกขยายใน ที่แตกต่างกัน rc ไฟล์ เพื่อไม่ให้ชื่อขัดแย้งกัน เราขอแนะนำให้คุณกำหนดค่า ที่กำหนดไว้ในไฟล์ rc ส่วนบุคคล จะเริ่มต้นด้วยเครื่องหมายขีดล่าง (_) เพื่อหลีกเลี่ยง การแชร์ชื่อโดยไม่ได้ตั้งใจ

--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 ที่ไม่บังคับตามลำดับต่อไปนี้

1. ไฟล์ rc ของระบบอยู่ที่ etc/bazel.bazelrc
2. ไฟล์ rc ของ Workspace อยู่ที่ $workspace/tools/bazel.rc
3. ไฟล์ rc ของบ้านอยู่ที่ $HOME/.bazelrc

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