หน้านี้จะถือว่าคุณคุ้นเคยกับ Bazel แล้ว โดยจะให้คำแนะนำและคำแนะนำเกี่ยวกับการกำหนดโครงสร้างโปรเจ็กต์เพื่อใช้ประโยชน์สูงสุดจากฟีเจอร์ของ Bazel
เป้าหมายโดยรวมมีดังนี้
- วิธีใช้ทรัพยากร Dependency แบบละเอียดเพื่ออนุญาตการทำงานพร้อมกันและส่วนเพิ่ม
- เพื่อให้ทรัพยากร Dependency มีการห่อหุ้มไว้อย่างดี
- เพื่อทำให้โค้ดมีโครงสร้างที่ดีและทดสอบได้
- เพื่อสร้างการกำหนดค่าบิลด์ที่เข้าใจง่ายและดูแลรักษา
หลักเกณฑ์เหล่านี้ไม่ใช่ข้อกำหนด มีเพียงไม่กี่โปรเจ็กต์เท่านั้นที่จะปฏิบัติตามหลักเกณฑ์ทั้งหมดได้ ดังที่หน้าเว็บสำหรับ lint ของ 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) การตั้งชื่อเช่นนี้ทำให้อัปเดตไลบรารีได้ง่ายขึ้น (เฉพาะเป้าหมายเดียวที่ต้องอัปเดตเท่านั้น) นอกจากนี้ยังมีความยืดหยุ่นมากขึ้นสำหรับปัญหาเกี่ยวกับการขึ้นต่อกันของเพชรด้วย เช่น หากไลบรารีหนึ่งใช้ guava-19.0 และอีกไลบรารีหนึ่งใช้ guava-20.0 คุณอาจได้รับไลบรารีที่พยายามใช้ 2 เวอร์ชันที่ต่างกัน
หากคุณสร้างชื่อแทนที่ทำให้เข้าใจผิดเพื่อชี้เป้าหมายทั้ง 2 รายการไปยังไลบรารี guava 1 รายการ แสดงว่าไฟล์ BUILD ทำให้เข้าใจผิด
กำลังใช้ไฟล์ .bazelrc
สำหรับตัวเลือกเฉพาะโปรเจ็กต์ ให้ใช้ไฟล์การกำหนดค่า workspace/.bazelrc ของคุณ (ดูรูปแบบ bazelrc)
ถ้าต้องการรองรับตัวเลือกต่อผู้ใช้สำหรับโปรเจ็กต์ที่คุณไม่ต้องการตรวจสอบการควบคุมแหล่งที่มา ให้ใส่บรรทัดต่อไปนี้
try-import %workspace%/user.bazelrc
(หรือชื่อไฟล์อื่นๆ) ใน workspace/.bazelrc
และเพิ่ม user.bazelrc ใน .gitignore
กล่องพัสดุ
ทุกไดเรกทอรีที่มีไฟล์ที่บิลด์ได้ควรเป็นแพ็กเกจ หากไฟล์ BUILD อ้างอิงไฟล์ในไดเรกทอรีย่อย (เช่น srcs = ["a/b/C.java"]) นั่นเป็นสัญญาณว่าควรเพิ่มไฟล์ BUILD ลงในไดเรกทอรีย่อยนั้น ยิ่งโครงสร้างนี้ยาวขึ้น ทรัพยากร Dependency แบบหมุนเวียนจะยิ่งมีแนวโน้มที่จะสร้างขึ้นโดยไม่ตั้งใจมากขึ้น ขอบเขตของเป้าหมายจะค่อยๆ เพิ่มขึ้น และจะต้องอัปเดตทรัพยากร Dependency แบบย้อนกลับจำนวนมากขึ้น