โมดูล Bazel คือโปรเจ็กต์ Bazel ที่มีได้หลายเวอร์ชัน โดยแต่ละเวอร์ชันจะเผยแพร่ข้อมูลเมตาเกี่ยวกับโมดูลอื่นๆ ที่ใช้ร่วมกัน ซึ่งคล้ายกับแนวคิดที่คุ้นเคยในระบบการจัดการทรัพยากร Dependency อื่นๆ เช่น อาร์ติแฟกต์ของ Maven, แพ็กเกจ npm, โมดูล Go หรือลัง Cargo
โมดูลต้องมีไฟล์ MODULE.bazel ที่รูทของรีโป (ข้างไฟล์ WORKSPACE) ไฟล์นี้เป็นไฟล์ Manifest ของโมดูล ซึ่งจะประกาศชื่อ เวอร์ชัน รายการของ Dependency โดยตรง และข้อมูลอื่นๆ ของโมดูล ตัวอย่างเบื้องต้นมีดังนี้
module(name = "my-module", version = "1.0")
bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")
ดูรายการทั้งหมดของคําสั่งที่มีอยู่ในไฟล์ MODULE.bazel
ในการแก้ไขข้อขัดข้องของโมดูล Bazel จะเริ่มด้วยการอ่านไฟล์ MODULE.bazel ของโมดูลรูท จากนั้นจะขอไฟล์ MODULE.bazel ของข้อกำหนดต่างๆ จากรีจิสทรี Bazel ซ้ำๆ จนกว่าจะพบกราฟข้อกำหนดทั้งหมด
จากนั้น Bazel จะเลือก 1 เวอร์ชันของแต่ละโมดูลที่จะใช้โดยค่าเริ่มต้น Bazel แสดงแต่ละโมดูลด้วยที่เก็บ และปรึกษาสำนักทะเบียนอีกครั้งเพื่อดูวิธีกำหนดที่เก็บแต่ละห้อง
รูปแบบเวอร์ชัน
Bazel มีระบบนิเวศที่หลากหลาย และโปรเจ็กต์ต่างๆ ก็ใช้รูปแบบการกำหนดเวอร์ชันที่หลากหลาย ความนิยมมากที่สุดในปัจจุบันคือ SemVer แต่ก็ยังมีโปรเจ็กต์ที่โดดเด่นซึ่งใช้รูปแบบที่แตกต่างออกไป เช่น Abseil ซึ่งเวอร์ชันอิงตามวันที่ เช่น 20210324.2)
ด้วยเหตุนี้ Bzlmod จึงใช้ข้อกำหนด SemVer เวอร์ชันที่ผ่อนปรนมากขึ้น โดยความแตกต่างมีดังนี้
- SemVer กำหนดให้ส่วน "release" ของเวอร์ชันประกอบด้วยกลุ่มย่อย 3 กลุ่ม ดังนี้
MAJOR.MINOR.PATCHใน Bazel ข้อกำหนดนี้จะถูกผ่อนปรน เพื่อให้สามารถใช้กลุ่มได้ไม่จำกัดจำนวน - ใน SemVer แต่ละส่วนในส่วน "release" ต้องเป็นตัวเลขเท่านั้น ใน Bazel กฎนี้มีความยืดหยุ่นมากขึ้นเพื่ออนุญาตให้ใช้ตัวอักษรได้ด้วย และความหมายของการเปรียบเทียบจะตรงกับ "ตัวระบุ" ในส่วน "รุ่นก่อนเผยแพร่"
- นอกจากนี้ จะไม่มีการบังคับใช้ความหมายของการเพิ่มเวอร์ชันหลัก ย่อย และเวอร์ชันแพตช์ แต่ดูรายละเอียดเกี่ยวกับวิธีที่เราแสดงความเข้ากันได้แบบย้อนหลังได้ที่ระดับความเข้ากันได้
เวอร์ชัน SemVer ที่ถูกต้องคือเวอร์ชันโมดูล Bazel ที่ถูกต้อง นอกจากนี้จะมี Sever 2 เวอร์ชัน a และ b เปรียบเทียบ a < b ก็ต่อเมื่อมีการคงไว้ชั่วคราวเดียวกันเมื่อเปรียบเทียบเวอร์ชันโมดูล Bazel
การเลือกเวอร์ชัน
ลองพิจารณาปัญหาเกี่ยวกับ Diamond Dependency ซึ่งเป็นปัญหาหลักในพื้นที่การจัดการ Dependency ที่มีเวอร์ชัน สมมติว่าคุณมีกราฟทรัพยากร Dependency ไว้
A 1.0
/ \
B 1.0 C 1.1
| |
D 1.0 D 1.1
ฉันควรใช้ D เวอร์ชันใด Bzlmod ใช้อัลกอริทึมการเลือกเวอร์ชันขั้นต่ำ (MVS) ที่เปิดตัวในระบบโมดูล Go เพื่อแก้ปัญหานี้ MVS จะถือว่าเวอร์ชันใหม่ทั้งหมดของโมดูลเข้ากันได้แบบย้อนหลัง ดังนั้นให้เลือกเวอร์ชันสูงสุดที่ระบุโดยเวอร์ชันที่เกี่ยวข้อง (D 1.1 ในตัวอย่างของเรา) สาเหตุที่เราเรียกว่า "ขั้นต่ำ" ก็คือ D 1.1 เป็นเวอร์ชันแรกสุดที่เป็นไปตามข้อกำหนดของเรา แม้ว่าจะมี D 1.2 ขึ้นไปก็ตาม แต่เราจะไม่เลือกเวอร์ชันเหล่านั้น การใช้ MVS จะสร้างกระบวนการเลือกเวอร์ชันที่มีความแม่นยำสูงและทำซ้ำได้
เวอร์ชันแย้ง
รีจิสทรีสามารถประกาศบางเวอร์ชันเป็น yanked ได้หากควรหลีกเลี่ยง (เช่น สำหรับช่องโหว่ด้านความปลอดภัย) Bazel จะแสดงข้อผิดพลาดเมื่อเลือกเวอร์ชันที่ยกเลิกของโมดูล หากต้องการแก้ไขข้อผิดพลาดนี้ ให้อัปเกรดเป็นเวอร์ชันใหม่ที่ไม่ใช่เวอร์ชันที่ถูกคัดออก หรือใช้แฟล็ก --allow_yanked_versions เพื่ออนุญาตเวอร์ชันที่ไม่ดีอย่างชัดเจน
ระดับความเข้ากันได้
ใน Go สมมติฐานของ MVS เกี่ยวกับการทำงานร่วมกันแบบย้อนหลังจะใช้งานได้เนื่องจากระบบจะถือว่าโมดูลเวอร์ชันที่เข้ากันไม่ได้แบบย้อนหลังเป็นโมดูลแยกต่างหาก ในแง่ของ SemVer หมายความว่า A 1.x และ A 2.x จะถือว่าเป็นโมดูลที่แตกต่างกัน และอยู่ร่วมกันได้ในกราฟการพึ่งพาที่แก้ไขแล้ว ซึ่งก็เป็นไปได้ด้วยการเข้ารหัสเวอร์ชันหลักในเส้นทางแพ็กเกจใน Go เพื่อไม่ให้เวลาคอมไพล์หรือเวลาลิงก์ขัดแย้งกัน
อย่างไรก็ตาม Bazel ให้การรับประกันดังกล่าวไม่ได้ จึงต้องใช้หมายเลข "เวอร์ชันหลัก" เพื่อตรวจหาเวอร์ชันที่ใช้ร่วมกันไม่ได้ย้อนหลัง ตัวเลขนี้เรียกว่าระดับความเข้ากันได้ และระบุโดยเวอร์ชันโมดูลแต่ละเวอร์ชันในคำสั่ง module() ซึ่งข้อมูลนี้ช่วยให้ Bazel แสดงข้อผิดพลาดเมื่อตรวจพบว่ามีโมดูลเดียวกันเวอร์ชันต่างๆ ที่มีระดับความเข้ากันได้แตกต่างกันในกราฟทรัพยากร Dependency ที่แก้ไขแล้ว
ลบล้าง
ระบุการลบล้างในไฟล์ MODULE.bazel เพื่อเปลี่ยนลักษณะการแก้ไขโมดูลของ Bazel มีเพียงการลบล้างของโมดูลรูทเท่านั้นที่จะมีผล หากใช้โมดูลทรัพยากร Dependency ระบบจะไม่สนใจการลบล้าง
การลบล้างแต่ละรายการจะระบุสำหรับชื่อโมดูลหนึ่งๆ ซึ่งส่งผลต่อเวอร์ชันทั้งหมดของโมดูลนั้นในกราฟความเกี่ยวข้อง แม้ว่าการลบล้างของโมดูลรูทเท่านั้นที่จะมีผล แต่ก็อาจใช้สำหรับการอ้างอิงแบบสับเปลี่ยนที่โมดูลรูทไม่ได้พึ่งโดยตรงได้
การลบล้างเวอร์ชันเดียว
single_version_override ใช้เพื่อวัตถุประสงค์หลายอย่าง ดังนี้
- แอตทริบิวต์
versionช่วยให้คุณปักหมุดทรัพยากร Dependency กับเวอร์ชันที่เจาะจงได้ ไม่ว่าจะมีการขอทรัพยากร Dependency เวอร์ชันใดในกราฟทรัพยากร Dependency ก็ตาม - เมื่อใช้แอตทริบิวต์
registryคุณสามารถบังคับให้ทรัพยากรนี้มาจากรีจิสทรีที่เฉพาะเจาะจงแทนที่จะทำตามกระบวนการการเลือกรีจิสทรีตามปกติ - เมื่อใช้แอตทริบิวต์
patch*คุณจะระบุชุดแพตช์ที่จะใช้กับโมดูลที่ดาวน์โหลดได้
แอตทริบิวต์เหล่านี้เป็นตัวเลือกทั้งหมด และสามารถนำไปผสมและจับคู่ได้
การลบล้างแบบหลายเวอร์ชัน
คุณสามารถระบุ multiple_version_override เพื่ออนุญาตให้โมดูลเดียวกันหลายเวอร์ชันอยู่ร่วมกันได้ในกราฟความสัมพันธ์ที่แก้ไขแล้ว
คุณระบุรายการเวอร์ชันที่อนุญาตสำหรับโมดูลอย่างชัดแจ้งได้ โดยต้องแสดงทั้งหมดในกราฟทรัพยากร Dependency ก่อนแก้ปัญหา โดยต้องมีการอ้างอิงแบบสับเปลี่ยนบางอย่างโดยขึ้นอยู่กับแต่ละเวอร์ชันที่อนุญาต หลังจากการแก้ไขแล้ว จะมีเฉพาะโมดูลเวอร์ชันที่อนุญาตเท่านั้นที่ยังคงอยู่ ขณะที่ Bazel จะอัปเกรดโมดูลเวอร์ชันอื่นๆ เป็นเวอร์ชันที่อนุญาตที่สูงกว่าซึ่งใกล้เคียงที่สุดในระดับความเข้ากันได้เดียวกัน หากไม่มีเวอร์ชันที่ได้รับอนุญาตสูงกว่าซึ่งมีระดับความเข้ากันได้ เดียวกันอยู่ Bazel จะแสดงข้อผิดพลาด
ตัวอย่างเช่น หากมีเวอร์ชัน 1.1, 1.3, 1.5, 1.7 และ 2.0 อยู่ในกราฟขึ้นต่อกันก่อนมีความละเอียด เวอร์ชันหลักคือระดับความเข้ากันได้ ดังนี้
- การลบล้างหลายเวอร์ชันที่อนุญาต
1.3,1.7และ2.0จะส่งผลให้1.1ได้รับการอัปเกรดเป็น1.3,1.5ได้รับการอัปเกรดเป็น1.7และเวอร์ชันอื่นๆ ยังคงเหมือนเดิม - การลบล้างหลายเวอร์ชันที่อนุญาต
1.5และ2.0ทําให้เกิดข้อผิดพลาด เนื่องจาก1.7ไม่มีเวอร์ชันที่สูงกว่าซึ่งมีระดับความเข้ากันได้เดียวกันให้อัปเกรด - การลบล้างหลายเวอร์ชันที่อนุญาต
1.9และ2.0จะทำให้เกิดข้อผิดพลาด เนื่องจาก1.9ไม่อยู่ในกราฟความเกี่ยวข้องก่อนการแก้ไข
นอกจากนี้ ผู้ใช้ยังลบล้างรีจิสทรีโดยใช้แอตทริบิวต์ registry ได้ ซึ่งคล้ายกับการลบล้างเวอร์ชันเดียว
การลบล้างที่ไม่ใช่รีจิสทรี
การลบล้างที่ไม่ใช่รีจิสทรีจะนำโมดูลออกจากการแปลงเวอร์ชันโดยสมบูรณ์ Bazel จะไม่ขอไฟล์ MODULE.bazel เหล่านี้จากรีจิสทรี แต่จะขอจากรีโปโดยตรง
Bazel รองรับการลบล้างที่ไม่ใช่รีจิสทรีต่อไปนี้
ชื่อที่เก็บและหน่วยงานที่เข้มงวด
ชื่อ Canonical ของที่เก็บที่รองรับโมดูลคือ module_name~version (เช่น bazel_skylib~1.0.3) สำหรับโมดูลที่มีการลบล้างที่ไม่ใช่รีจิสทรี ให้แทนที่ส่วน version ด้วยสตริง override โปรดทราบว่ารูปแบบชื่อ Canonical ไม่ใช่ API ที่คุณควรพึ่งพาและอาจมีการเปลี่ยนแปลงได้ทุกเมื่อ
ชื่อที่ปรากฏของรีโปที่สำรองข้อมูลโมดูลให้กับโมดูลที่ขึ้นต่อกันโดยตรงจะเป็นชื่อโมดูลโดยค่าเริ่มต้น เว้นแต่แอตทริบิวต์ repo_name ของคำสั่ง bazel_dep จะระบุไว้เป็นอย่างอื่น โปรดทราบว่าวิธีนี้หมายความว่าโมดูลจะดูได้เฉพาะการขึ้นต่อกันโดยตรงเท่านั้น ซึ่งจะช่วยป้องกันความเสียหายโดยไม่ตั้งใจที่เกิดจากการเปลี่ยนแปลงในข้อกำหนดเบื้องต้นแบบทรานซิทีฟ
ส่วนขยายของโมดูลยังนํารีพอสิทเพิ่มเติมมาไว้ในขอบเขตที่มองเห็นได้ของโมดูลได้ด้วย