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

หน้านี้ถือว่าคุณคุ้นเคยกับ 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 ลงในไดเรกทอรีย่อยนั้น ยิ่งโครงสร้างนี้อยู่นานเท่าใด ก็ยิ่งมีโอกาสที่จะเกิดความสัมพันธ์แบบวนโดยไม่ได้ตั้งใจ ขอบเขตของเป้าหมายจะขยายออกไป และจะต้องอัปเดตความสัมพันธ์แบบย้อนกลับจํานวนมากขึ้น