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

หน้านี้จะถือว่าคุณคุ้นเคยกับ 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 แบบย้อนกลับที่เพิ่มขึ้น