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