แนวทางปฏิบัติแนะนำ

รายงานปัญหา ดูแหล่งที่มา ตอนกลางคืน · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

เป้าหมายโดยรวมมีดังนี้

  • วิธีใช้ทรัพยากร Dependency แบบละเอียดเพื่ออนุญาตการทำงานพร้อมกันและส่วนเพิ่ม
  • เพื่อให้ทรัพยากร Dependency มีการห่อหุ้มไว้อย่างดี
  • เพื่อทำให้โค้ดมีโครงสร้างที่ดีและทดสอบได้
  • เพื่อสร้างการกำหนดค่าบิลด์ที่เข้าใจง่ายและดูแลรักษา

หลักเกณฑ์เหล่านี้ไม่ใช่ข้อกำหนด มีเพียงไม่กี่โครงการเท่านั้นที่สามารถปฏิบัติตาม ทั้งหมดเลย ดังที่หน้าเว็บผู้ชายของ Lint บอกว่า "จะมีรางวัลพิเศษให้ แก่บุคคลแรกที่ผลิตโปรแกรมจริงที่ไม่พบข้อผิดพลาด การตรวจสอบอย่างเข้มงวด" อย่างไรก็ตาม ให้นำหลักการเหล่านี้มาใช้ให้มากที่สุด ควรทำให้โปรเจ็กต์อ่านได้ง่ายขึ้น มีโอกาสเกิดข้อผิดพลาดน้อยลง และสร้างเสร็จเร็วขึ้น

หน้านี้ใช้ระดับของข้อกำหนดที่อธิบายไว้ใน RFC นี้

การเรียกใช้บิลด์และการทดสอบ

โปรเจ็กต์ควรเรียกใช้ bazel build //... ได้อยู่เสมอและ bazel test //... ใน Branch ที่เสถียรเรียบร้อยแล้ว เป้าหมายที่จำเป็น แต่ไม่ได้สร้างภายใต้สถานการณ์บางอย่าง (เช่น กำหนดให้สร้าง ไม่สร้างบนแพลตฟอร์มเฉพาะ ต้องมีข้อตกลงการอนุญาตให้ใช้สิทธิ) ควรเป็น ติดแท็กให้เฉพาะเจาะจงมากที่สุด (เช่น "requires-osx") ช่วงเวลานี้ การติดแท็กจะทำให้มีการกรองเป้าหมายในระดับที่ละเอียดกว่า "ด้วยตนเอง" และอนุญาตให้ตรวจสอบไฟล์ BUILD เพื่อทำความเข้าใจ ข้อจำกัดของเป้าหมาย

ทรัพยากร Dependency ของบุคคลที่สาม

คุณประกาศทรัพยากร Dependency ของบุคคลที่สามได้โดยทำดังนี้

  • ประกาศเป็นที่เก็บระยะไกลในไฟล์ WORKSPACE
  • หรือใส่ไว้ในไดเรกทอรีชื่อ third_party/ ใต้ไดเรกทอรีพื้นที่ทำงาน

ขึ้นอยู่กับไบนารี

ทุกอย่างควรสร้างขึ้นจากแหล่งที่มาทุกครั้งที่เป็นไปได้ โดยทั่วไปหมายความว่า แทนที่จะใช้ไลบรารี some-library.so คุณจะสร้าง BUILD และสร้าง some-library.so จากแหล่งที่มาของไฟล์ แล้วจะขึ้นอยู่กับว่า เป้าหมาย

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

การกำหนดเวอร์ชัน

แนะนำให้สร้างโค้ดทั้งหมดจากส่วนหัวทุกครั้งที่เป็นไปได้ กรณีที่ต้องมีเวอร์ชัน เพื่อหลีกเลี่ยงการรวมเวอร์ชันไว้ในชื่อเป้าหมาย (เช่น //guava, ไม่ใช่ //guava-20.0) การตั้งชื่อเช่นนี้ทำให้การอัปเดตไลบรารีทำได้ง่ายขึ้น (มีเพียง ต้องมีการอัปเดตเป้าหมาย) ทั้งยังมีความยืดหยุ่นมากกว่าการขึ้นต่อกันของเพชร ปัญหา: หากไลบรารี 1 รายการใช้ guava-19.0 และอีกรายการขึ้นอยู่กับ guava-20.0 คุณอาจได้ไลบรารีที่พยายามใช้ 2 เวอร์ชันที่ต่างกัน หากคุณสร้างชื่อแทนที่ทำให้เข้าใจผิดเพื่อชี้เป้าหมายทั้ง 2 รายการไปยังไลบรารี guava เดียว ไฟล์ BUILD อาจทำให้เข้าใจผิด

กำลังใช้ไฟล์ .bazelrc

สำหรับตัวเลือกเฉพาะโปรเจ็กต์ ให้ใช้ไฟล์การกำหนดค่า workspace/.bazelrc (ดูรูปแบบ bazelrc)

หากต้องการรองรับตัวเลือกต่อผู้ใช้สําหรับโปรเจ็กต์ที่คุณไม่ ต้องการตรวจสอบการควบคุมแหล่งที่มา ให้ใส่บรรทัด:

try-import %workspace%/user.bazelrc

(หรือชื่อไฟล์อื่นๆ) ใน workspace/.bazelrc และเพิ่ม user.bazelrc ไปที่ .gitignore

แพ็กเกจ

ทุกไดเรกทอรีที่มีไฟล์ที่บิลด์ได้ควรเป็นแพ็กเกจ หากBUILD อ้างอิงไฟล์ในไดเรกทอรีย่อย (เช่น srcs = ["a/b/C.java"]) สัญญาณที่บอกว่าควรเพิ่มไฟล์ BUILD ลงในไดเรกทอรีย่อยนั้น ยิ่งยาว มีโครงสร้างนี้อยู่ ทรัพยากร Dependency แบบเวียนกลับจะมีมากขึ้น ขอบเขตของเป้าหมายจะค่อยๆ คืบคลาน และเพิ่มขึ้นเรื่อยๆ โดยไม่ได้ตั้งใจ ของทรัพยากร Dependency แบบย้อนกลับจะต้องอัปเดต