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

7.3 · 7.2 · 7.1 · 7.0 · 6.5

หน้านี้จะถือว่าคุณคุ้นเคยกับ Bazel แล้ว โดยจะให้คำแนะนำและคำแนะนำเกี่ยวกับการกำหนดโครงสร้างโปรเจ็กต์เพื่อใช้ประโยชน์สูงสุดจากฟีเจอร์ของ Bazel

เป้าหมายโดยรวมมีดังนี้

  • วิธีใช้ทรัพยากร Dependency แบบละเอียดเพื่ออนุญาตการทำงานพร้อมกันและส่วนเพิ่ม
  • เพื่อให้ทรัพยากร Dependency มีการห่อหุ้มไว้อย่างดี
  • เพื่อทำให้โค้ดมีโครงสร้างที่ดีและทดสอบได้
  • วิธีสร้างการกำหนดค่าการสร้างที่เข้าใจและดูแลรักษาได้ง่าย

หลักเกณฑ์เหล่านี้ไม่ใช่ข้อกำหนด โครงการส่วนใหญ่จะปฏิบัติตามหลักเกณฑ์เหล่านี้ไม่ได้ทั้งหมด ดังที่หน้า man ของ lint บอกไว้ว่า "จะมีการมอบรางวัลพิเศษให้กับบุคคลแรกที่เขียนโปรแกรมจริงที่ไม่มีการผิดพลาดด้วยการตรวจสอบที่เข้มงวด" อย่างไรก็ตาม การนำหลักการเหล่านี้มาใช้ให้ได้มากที่สุดจะช่วยให้โปรเจ็กต์อ่านง่ายขึ้น เกิดข้อผิดพลาดน้อยลง และสร้างได้เร็วขึ้น

หน้านี้ใช้ระดับข้อกำหนดที่อธิบายไว้ในRFC นี้

การสร้างและการทดสอบที่ทำงานอยู่

โปรเจ็กต์ควรเรียกใช้ bazel build //... และ bazel test //... ได้สำเร็จใน Branch ที่เสถียรเสมอ เป้าหมายที่จำเป็นแต่ไม่สร้างภายใต้สถานการณ์บางอย่าง (เช่น ต้องใช้แฟล็กบิลด์ที่เจาะจง ไม่สร้างบนบางแพลตฟอร์ม ต้องมีข้อตกลงการอนุญาตให้ใช้สิทธิ) ควรติดแท็กให้เฉพาะเจาะจงที่สุด (เช่น "requires-osx") การติดแท็กนี้ช่วยให้กรองเป้าหมายได้ละเอียดกว่าแท็ก "ด้วยตนเอง" และช่วยให้ผู้ตรวจสอบไฟล์ BUILD เข้าใจได้ว่าข้อจำกัดของเป้าหมายคืออะไร

ทรัพยากร Dependency ของบุคคลที่สาม

คุณประกาศทรัพยากร Dependency ของบุคคลที่สามได้โดยทำดังนี้

  • หรือประกาศเป็นที่เก็บระยะไกลในไฟล์ WORKSPACE
  • หรือใส่ไว้ในไดเรกทอรีชื่อ third_party/ ใต้ไดเรกทอรีพื้นที่ทำงาน

ขึ้นอยู่กับไบนารี

คุณควรสร้างทุกอย่างจากซอร์สทุกครั้งที่เป็นไปได้ โดยทั่วไปแล้ว หมายความว่าแทนที่จะใช้ไลบรารี some-library.so คุณจะต้องสร้างไฟล์ BUILD และสร้าง some-library.so จากแหล่งที่มาของไฟล์นั้น แล้วใช้เป้าหมายนั้น

การสร้างจากซอร์สโค้ดเสมอช่วยให้มั่นใจได้ว่าบิลด์ไม่ได้ใช้ไลบรารีที่สร้างขึ้นด้วย Flag ที่เข้ากันไม่ได้หรือสถาปัตยกรรมอื่น นอกจากนี้ยังมีฟีเจอร์บางอย่าง เช่น ความครอบคลุม การวิเคราะห์แบบคงที่ หรือการวิเคราะห์แบบไดนามิกที่ทํางานในแหล่งที่มาเท่านั้น

การกำหนดเวอร์ชัน

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