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

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

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

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

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

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

การเรียกใช้บิลด์และการทดสอบ

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

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

คุณอาจประกาศการอ้างอิงของบุคคลที่สามได้ดังนี้

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

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

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

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

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

ขอแนะนำให้สร้างโค้ดทั้งหมดจากส่วนหัวทุกครั้งที่เป็นไปได้ เมื่อต้องใช้เวอร์ชัน ให้หลีกเลี่ยงการใส่เวอร์ชันในชื่อเป้าหมาย (เช่น //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

Open Source bazelrc-preset.bzl {: .external} จะสร้างไฟล์ bazelrc ที่กำหนดเองซึ่งตรงกับเวอร์ชัน Bazel ของคุณและมี ค่าที่กำหนดไว้ล่วงหน้าของแฟล็กที่แนะนำ

แพ็กเกจ

ทุกไดเรกทอรีที่มีไฟล์ที่สร้างได้ควรเป็นแพ็กเกจ หากBUILD ไฟล์อ้างอิงถึงไฟล์ในไดเรกทอรีย่อย (เช่น srcs = ["a/b/C.java"]) แสดงว่าควรเพิ่มไฟล์ BUILD ลงในไดเรกทอรีย่อยนั้น ยิ่งโครงสร้างนี้มีอยู่นานเท่าใด ก็ยิ่งมีแนวโน้มที่จะสร้างการอ้างอิงแบบวงกลมโดยไม่ตั้งใจ ขอบเขตของเป้าหมายจะขยายออก และจะต้องอัปเดตการอ้างอิงย้อนกลับจำนวนมากขึ้น