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

ไวยากรณ์และอรรถศาสตร์ .bazelrc

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

การนำเข้า

บรรทัดที่เริ่มต้นด้วย import หรือ try-import จะมีความพิเศษ นั่นคือใช้บรรทัดเหล่านี้เพื่อโหลดไฟล์ "rc" อื่นๆ หากต้องการระบุเส้นทางที่สัมพัทธ์กับรูทของพื้นที่ทำงาน ให้เขียน import %workspace%/path/to/bazelrc

ความแตกต่างระหว่าง import และ try-import คือ Bazel จะล้มเหลวหากไฟล์ของ import หายไป (หรืออ่านไม่ได้) แต่ไฟล์ของ try-import จะไม่สำเร็จ

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

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

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

บรรทัดส่วนใหญ่ของ bazelrc กำหนดค่าตัวเลือกเริ่มต้น คำแรกในแต่ละบรรทัด จะระบุว่าระบบจะใช้ค่าเริ่มต้นเหล่านี้เมื่อใด

• startup: ตัวเลือกการเริ่มต้นใช้งาน ซึ่งจะอยู่ก่อนคำสั่ง และอธิบายไว้ใน bazel help startup_options
• common: ตัวเลือกที่ใช้กับคำสั่ง Bazel ทั้งหมด
• command: คำสั่ง Bazel เช่น build หรือ query ที่จะใช้ตัวเลือก ตัวเลือกเหล่านี้จะมีผลกับคำสั่งทั้งหมดที่รับค่าจากคำสั่งที่ระบุด้วย (เช่น test รับค่ามาจาก build)

อาจมีการใช้แต่ละบรรทัดมากกว่า 1 ครั้ง และอาร์กิวเมนต์ที่อยู่หลังคำแรกจะถูกรวมเข้าด้วยกันราวกับว่าปรากฏในบรรทัดเดียว (ผู้ใช้ CVS ซึ่งเป็นเครื่องมืออีกอย่างหนึ่งที่มีอินเทอร์เฟซบรรทัดคำสั่ง "Swiss Army knife" จะพบไวยากรณ์ที่คล้ายกับของ .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

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

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

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

--config

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

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

--config=foo จะขยายไปยังตัวเลือกที่กำหนดไว้ในไฟล์ rc เป็นแบบ "in-place" เพื่อให้ตัวเลือกที่ระบุสำหรับการกำหนดค่ามีลำดับความสำคัญเท่ากับตัวเลือก --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 ละเว้น บรรทัดละ 1 รายการ รายการต่างๆ จะสัมพัทธ์กับรูทของพื้นที่ทำงาน

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

Bazel อ่านไฟล์ bazelrc ที่ไม่บังคับตามลำดับดังนี้ - ไฟล์ rc-ระบบที่ etc/bazel.bazelrc - ไฟล์ rc-ของ Workspace อยู่ที่ $workspace/tools/bazel.rc - ไฟล์ rc-Home เริ่มแปลที่ $HOME/.bazelrc

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