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