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