หน้านี้จะถือว่าคุณคุ้นเคยกับ 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 แบบย้อนกลับจะต้องอัปเดต