หน้านี้จะถือว่าคุณคุ้นเคยกับ Bazel รวมถึงให้หลักเกณฑ์และคำแนะนำเกี่ยวกับโครงสร้างโปรเจ็กต์เพื่อใช้ประโยชน์สูงสุดจากฟีเจอร์ของ Bazel
เป้าหมายโดยรวมได้แก่
- เพื่อใช้ทรัพยากร Dependency แบบละเอียดเพื่อให้ดำเนินการพร้อมกันกับส่วนเพิ่มได้
- เพื่อให้ครอบคลุมทรัพยากร Dependency เป็นอย่างดี
- ทำให้โค้ดมีโครงสร้างที่ดีและทดสอบได้
- เพื่อสร้างการกำหนดค่าบิวด์ที่เข้าใจง่ายและดูแลรักษาได้ง่าย
หลักเกณฑ์เหล่านี้ไม่ใช่ข้อกำหนด มีโปรเจ็กต์ไม่กี่โปรเจ็กต์ที่ทำตามหลักเกณฑ์ทั้งหมดได้ ดังที่หน้าคนของ Lint กล่าวว่า "จะมีรางวัลพิเศษมอบให้กับบุคคลแรกที่ผลิตรายการจริงที่ไม่พบข้อผิดพลาดที่มีการตรวจสอบอย่างเข้มงวด" อย่างไรก็ตาม การใช้หลักการเหล่านี้ให้มากที่สุดจะช่วยให้โปรเจ็กต์อ่านได้ง่ายขึ้น เกิดข้อผิดพลาดน้อยลง และสร้างได้เร็วขึ้น
หน้านี้ใช้ระดับข้อกำหนดที่อธิบายไว้ใน RFC นี้
การเรียกใช้บิลด์และการทดสอบ
โปรเจ็กต์ควรเรียกใช้ bazel build //...
และ bazel test //...
ได้สำเร็จใน Branch ที่เสถียรเสมอ เป้าหมายที่จำเป็นแต่อย่าสร้างภายใต้สถานการณ์บางอย่าง (เช่น ต้องมีแฟล็กเวอร์ชันที่เจาะจง ไม่สร้างในแพลตฟอร์มที่เจาะจง ต้องมีข้อตกลงการอนุญาตให้ใช้สิทธิ) ควรติดแท็กให้เฉพาะเจาะจงที่สุด (เช่น "requires-osx
") การติดแท็กนี้ช่วยให้กรองเป้าหมายได้ในระดับที่ละเอียดกว่าแท็ก "ด้วยตนเอง" และอนุญาตให้มีผู้ตรวจสอบไฟล์ BUILD
เพื่อทำความเข้าใจข้อจำกัดของเป้าหมาย
ทรัพยากร Dependency ของบุคคลที่สาม
คุณสามารถประกาศทรัพยากร Dependency ของบุคคลที่สามได้โดยทำดังนี้
- โปรดประกาศเป็นที่เก็บระยะไกลในไฟล์
WORKSPACE
- หรือใส่ไว้ในไดเรกทอรีชื่อ
third_party/
ภายในไดเรกทอรีพื้นที่ทํางาน
ขึ้นอยู่กับไบนารี
ทุกอย่างควรสร้างขึ้นจากแหล่งที่มาทุกครั้งที่เป็นไปได้ โดยทั่วไปหมายความว่าคุณจะสร้างไฟล์ BUILD
และสร้าง some-library.so
จากแหล่งที่มาของไฟล์แทนที่จะขึ้นอยู่กับไลบรารี some-library.so
จากนั้นจะขึ้นอยู่กับเป้าหมายนั้น
การสร้างจากต้นทางเสมอทำให้มั่นใจได้ว่าบิลด์ไม่ได้ใช้ไลบรารีที่สร้างด้วยแฟล็กที่เข้ากันไม่ได้หรือสถาปัตยกรรมอื่น นอกจากนี้ยังมีฟีเจอร์บางอย่าง เช่น การครอบคลุม การวิเคราะห์แบบคงที่ หรือการวิเคราะห์แบบไดนามิกที่ทำงานได้ในแหล่งที่มาเท่านั้น
การกำหนดเวอร์ชัน
ขอแนะนำให้สร้างโค้ดทั้งหมดจากส่วนหัวหากเป็นไปได้ เมื่อต้องใช้เวอร์ชัน ให้หลีกเลี่ยงการรวมเวอร์ชันไว้ในชื่อเป้าหมาย (เช่น //guava
ไม่ใช่ //guava-20.0
) การตั้งชื่อนี้จะทำให้อัปเดตไลบรารีได้ง่ายขึ้น (ต้องอัปเดตเป้าหมายเพียง 1 รายการเท่านั้น) และยังมีความยืดหยุ่นต่อปัญหาการพึ่งพาไดมอนด์มากกว่า หากไลบรารีหนึ่งอิงตาม guava-19.0
และอีกไลบรารีหนึ่งใช้ guava-20.0
ท้ายที่สุดแล้วไลบรารีที่พยายามใช้ 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 แบบย้อนกลับที่เพิ่มขึ้น