ภาพรวมของทรัพยากร Dependency ภายนอก

Nightly · 9.1 · 9.0 · 8.7 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

Bazel รองรับ การขึ้นต่อกันภายนอก ไฟล์ต้นฉบับ (ทั้งข้อความและไบนารี) ที่ใช้ ในการบิลด์ซึ่งไม่ได้มาจากพื้นที่ทำงาน เช่น อาจเป็นชุดกฎที่โฮสต์ในที่เก็บ GitHub, อาร์ติแฟกต์ Maven หรือไดเรกทอรีในเครื่องของคุณที่อยู่นอกพื้นที่ทำงานปัจจุบัน

ตั้งแต่ Bazel 6.0 เป็นต้นมา คุณสามารถจัดการทรัพยากร Dependency ภายนอกด้วย Bazel ได้ 2 วิธี ได้แก่ ระบบ WORKSPACE แบบดั้งเดิมที่เน้นที่เก็บข้อมูล และ ระบบ MODULE.bazel ใหม่ที่เน้นโมดูล (ชื่อรหัส Bzlmod, และเปิดใช้ด้วยแฟล็ก --enable_bzlmod) คุณสามารถใช้ระบบทั้งสองร่วมกันได้ แต่ Bzlmod จะมาแทนที่ระบบ WORKSPACE ใน Bazel เวอร์ชันต่อๆ ไป โปรดดูคำแนะนำในการย้ายข้อมูล Bzlmod เกี่ยวกับวิธีย้ายข้อมูล

เอกสารนี้จะอธิบายแนวคิดเกี่ยวกับการจัดการทรัพยากร Dependency ภายนอกใน Bazel ก่อนที่จะลงรายละเอียดเกี่ยวกับระบบทั้งสองตามลำดับ

แนวคิด

ที่เก็บ

แผนผังไดเรกทอรีที่มีไฟล์เครื่องหมายขอบเขตที่รูท ซึ่งมีไฟล์ต้นฉบับที่ใช้ได้ในบิลด์ Bazel มักเรียกสั้นๆ ว่า repo

ไฟล์เครื่องหมายขอบเขตของ repo อาจเป็น MODULE.bazel (บ่งบอกว่า repo นี้แสดงโมดูล Bazel), REPO.bazel (ดู ด้านล่าง) หรือในบริบทเดิม WORKSPACE หรือ WORKSPACE.bazel ไฟล์เครื่องหมายขอบเขตของ repo จะระบุขอบเขตของ repo โดยไฟล์ดังกล่าวจะอยู่ในไดเรกทอรีร่วมกันได้หลายไฟล์

ที่เก็บหลัก

ที่เก็บที่กำลังเรียกใช้คำสั่ง Bazel ปัจจุบัน

พื้นที่ทำงาน

สภาพแวดล้อมที่คำสั่ง Bazel ทั้งหมดใช้ร่วมกันจะทำงานจากที่เก็บหลักเดียวกัน

โปรดทราบว่าที่ผ่านมาแนวคิด "ที่เก็บข้อมูล" และ "พื้นที่ทำงาน" มักใช้รวมๆ กัน คำว่า "พื้นที่ทำงาน" มักใช้เพื่ออ้างอิงถึงที่เก็บข้อมูลหลัก และบางครั้งยังใช้เป็นคำพ้องความหมายของ "ที่เก็บข้อมูล" ด้วย

ชื่อที่เก็บ Canonical

ชื่อ Canonical ที่ใช้ระบุที่เก็บ ในบริบทของพื้นที่ทำงาน ที่เก็บแต่ละแห่งจะมีชื่อ Canonical เดียว คุณระบุเป้าหมายภายใน repo ที่มีชื่อ Canonical เป็น canonical_name ได้โดยใช้ป้ายกำกับ @@canonical_name//pac/kage:target (โปรดสังเกต @)

ที่เก็บหลักจะมีสตริงว่างเป็นชื่อ Canonical เสมอ

ชื่อที่เก็บที่ปรากฏ

ชื่อที่ใช้ระบุที่เก็บในบริบทของ repo อื่น คุณอาจคิดว่าชื่อนี้เป็น "ชื่อเล่น" ของ repo ก็ได้ เช่น repo ที่มีชื่อ Canonical เป็น michael อาจมีชื่อที่ปรากฏเป็น mike ในบริบทของ repo alice แต่มีชื่อที่ปรากฏเป็น mickey ในบริบทของ repo bob ในกรณีนี้ คุณระบุเป้าหมายภายใน michael ได้โดยใช้ป้ายกำกับ @mike//pac/kage:target ในบริบทของ alice (โปรดสังเกต @ ตัวเดียว)

ในทางกลับกัน คุณอาจเข้าใจได้ว่าชื่อนี้เป็นการแมปที่เก็บ โดย repo แต่ละแห่ง จะเก็บการแมปจาก "ชื่อที่เก็บที่ปรากฏ" ไปยัง "ชื่อที่เก็บ Canonical"

กฎของที่เก็บ

สคีมาสำหรับคำจำกัดความของที่เก็บข้อมูลที่บอก Bazel ว่าจะแสดงที่เก็บข้อมูลอย่างไร เช่น "ดาวน์โหลดไฟล์เก็บถาวร zip จาก URL ที่ระบุและแตกไฟล์" หรือ "ดึงข้อมูลอาร์ติแฟกต์ Maven ที่ระบุและทำให้พร้อมใช้งานเป็นเป้าหมาย java_import" หรือเพียง "สร้างลิงก์สัญลักษณ์ของไดเรกทอรีในเครื่อง" ทุก repo จะกำหนด โดยการเรียกใช้กฎของ repo ด้วยจำนวนอาร์กิวเมนต์ที่เหมาะสม

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีเขียน กฎของที่เก็บเองได้ที่กฎของที่เก็บ

กฎของ repo ที่ใช้กันมากที่สุดคือ http_archive ซึ่งดาวน์โหลดไฟล์เก็บถาวร จาก URL และแตกไฟล์ และ local_repository ซึ่งสร้างลิงก์สัญลักษณ์ของ ไดเรกทอรีในเครื่องที่เป็นที่เก็บ Bazel อยู่แล้ว

ดึงข้อมูลที่เก็บ

การดำเนินการทำให้ repo พร้อมใช้งานในดิสก์ในเครื่องโดยการเรียกใช้กฎของ repo ที่เชื่อมโยง repo ที่กำหนดไว้ในพื้นที่ทำงานจะไม่พร้อมใช้งานในดิสก์ในเครื่องจนกว่าจะมีการดึงข้อมูล

โดยปกติแล้ว Bazel จะดึงข้อมูล repo ก็ต่อเมื่อต้องการบางอย่างจาก repo และยังไม่ได้ดึงข้อมูล repo นั้น หากมีการดึงข้อมูล repo ไปแล้วก่อนหน้านี้ Bazel จะดึงข้อมูล repo อีกครั้งก็ต่อเมื่อคำจำกัดความของ repo มีการเปลี่ยนแปลง

คุณใช้คำสั่ง fetch เพื่อเริ่มการดึงข้อมูลล่วงหน้าสำหรับที่เก็บ เป้าหมาย หรือที่เก็บที่จำเป็นทั้งหมดเพื่อทำการบิลด์ได้ ความสามารถนี้ช่วยให้สามารถทำการบิลด์แบบออฟไลน์ได้โดยใช้ตัวเลือก --nofetch

ตัวเลือก --fetch มีไว้เพื่อจัดการการเข้าถึงเครือข่าย ค่าเริ่มต้นคือ True อย่างไรก็ตาม เมื่อตั้งค่าเป็น False (--nofetch) คำสั่งจะใช้เวอร์ชันที่แคชไว้ของทรัพยากร Dependency และหากไม่มี คำสั่งจะส่งผลให้เกิดข้อผิดพลาด

ดูข้อมูลเพิ่มเติมเกี่ยวกับการควบคุมการดึงข้อมูลได้ที่ ตัวเลือกการดึงข้อมูล

เลย์เอาต์ไดเรกทอรี

หลังจากดึงข้อมูลแล้ว คุณจะพบ repo ในไดเรกทอรีย่อย external ใน เอาต์พุตเบสภายใต้ชื่อ Canonical

คุณเรียกใช้คำสั่งต่อไปนี้เพื่อดูเนื้อหาของ repo ที่มีชื่อ Canonical เป็น canonical_name

ls $(bazel info output_base)/external/ canonical_name

ไฟล์ REPO.bazel

ไฟล์ REPO.bazel ใช้เพื่อทำเครื่องหมายขอบเขตบนสุดของแผนผังไดเรกทอรีที่เป็น repo ไฟล์นี้ไม่จำเป็นต้องมีเนื้อหาใดๆ เพื่อใช้เป็นไฟล์ขอบเขตของ repo แต่คุณยังใช้ไฟล์นี้เพื่อระบุแอตทริบิวต์ทั่วไปสำหรับเป้าหมายการบิลด์ทั้งหมดภายใน repo ได้ด้วย

ไวยากรณ์ของไฟล์ REPO.bazel จะคล้ายกับไฟล์ BUILD ยกเว้นว่าจะไม่รองรับคำสั่ง load และมีเพียงฟังก์ชันเดียวคือ repo() ที่พร้อมใช้งาน repo() จะใช้อาร์กิวเมนต์เดียวกับ package() ฟังก์ชัน ในไฟล์ BUILD โดยที่ package() จะระบุแอตทริบิวต์ทั่วไปสำหรับเป้าหมายการบิลด์ทั้งหมดภายในแพ็กเกจ ส่วน repo() จะทำเช่นเดียวกันสำหรับเป้าหมายการบิลด์ทั้งหมดภายใน repo

ตัวอย่างเช่น คุณระบุใบอนุญาตทั่วไปสำหรับเป้าหมายทั้งหมดใน repo ได้โดยใช้ไฟล์ REPO.bazel ต่อไปนี้

repo(
    default_package_metadata = ["//:my_license"],
)

จัดการการขึ้นต่อกันภายนอกด้วย Bzlmod

Bzlmod ซึ่งเป็นระบบย่อยใหม่สำหรับการขึ้นต่อกันภายนอกจะไม่ทำงานกับคำจำกัดความของ repo โดยตรง แต่จะสร้างกราฟการขึ้นต่อกันจาก โมดูล เรียกใช้ ส่วนขยาย ที่ด้านบนของกราฟ และกำหนด repo ตามนั้น

**โมดูล** Bazel คือโปรเจ็กต์ Bazel ที่มีได้หลาย เวอร์ชัน โดยแต่ละเวอร์ชันจะเผยแพร่ข้อมูลเมตาเกี่ยวกับโมดูลอื่นๆ ที่โมดูลนั้นขึ้นต่อกัน โมดูลต้องมีไฟล์ MODULE.bazel ที่รูท repo ข้างไฟล์ WORKSPACE ไฟล์นี้เป็นไฟล์ Manifest ของโมดูล ซึ่งประกาศชื่อ เวอร์ชัน รายการการขึ้นต่อกัน และข้อมูลอื่นๆ ตัวอย่างพื้นฐานมีดังนี้

module(name = "my-module", version = "1.0")

bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")

โมดูลต้องแสดงรายการเฉพาะการขึ้นต่อกันโดยตรง ซึ่ง Bzlmod จะค้นหาใน รีจิสทรี Bazel ซึ่งโดยค่าเริ่มต้นคือ รีจิสทรีกลาง ของ Bazel รีจิสทรีจะให้ไฟล์ MODULE.bazel ของทรัพยากร Dependency ซึ่งช่วยให้ Bazel ค้นพบกราฟทรัพยากร Dependency แบบทรานซิทีฟทั้งหมดก่อนที่จะทำการแก้ปัญหาเวอร์ชัน

หลังจากแก้ปัญหาเวอร์ชันแล้ว ซึ่งจะมีการเลือกเวอร์ชันเดียวสำหรับแต่ละโมดูล Bazel จะปรึกษาข้อมูลรีจิสทรีอีกครั้งเพื่อดูวิธีกำหนด repo สำหรับแต่ละโมดูล (ในกรณีส่วนใหญ่จะใช้ http_archive)

โมดูลยังระบุข้อมูลที่กำหนดเองที่เรียกว่า แท็ก ได้ด้วย ซึ่ง **ส่วนขยายโมดูล** จะใช้แท็กเหล่านี้หลังจากการแก้ปัญหาโมดูล เพื่อกำหนด repo เพิ่มเติม ส่วนขยายเหล่านี้มีความสามารถคล้ายกับกฎของ repo ซึ่งช่วยให้ดำเนินการต่างๆ เช่น I/O ของไฟล์และการส่งคำขอเครือข่ายได้ นอกจากนี้ ส่วนขยายยังช่วยให้ Bazel โต้ตอบกับระบบการจัดการแพ็กเกจอื่นๆ ได้โดยยังคงพิจารณากราฟการขึ้นต่อกันที่สร้างจากโมดูล Bazel

กำหนด repo ด้วย WORKSPACE

ในอดีต คุณสามารถจัดการการขึ้นต่อกันภายนอกได้โดยการกำหนด repo ในไฟล์ WORKSPACE (หรือ WORKSPACE.bazel) ไฟล์นี้มีไวยากรณ์คล้ายกับไฟล์ BUILD โดยใช้กฎของ repo แทนกฎการบิลด์

ข้อมูลโค้ดต่อไปนี้เป็นตัวอย่างการใช้กฎของ repo http_archive ในไฟล์ WORKSPACE

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "foo",
    urls = ["https://example.com/foo.zip"],
    sha256 = "c9526390a7cd420fdcec2988b4f3626fe9c5b51e2959f685e8f4d170d1a9bd96",
)

ข้อมูลโค้ดจะกำหนด repo ที่มีชื่อ Canonical เป็น foo ในระบบ WORKSPACE โดยค่าเริ่มต้น ชื่อ Canonical ของ repo จะเป็นชื่อที่ปรากฏสำหรับ repo อื่นๆ ทั้งหมดด้วย

ดูรายการฟังก์ชันทั้งหมดที่พร้อมใช้งานใน WORKSPACEไฟล์

ข้อบกพร่องของระบบ WORKSPACE

ในช่วงหลายปีที่ผ่านมานับตั้งแต่มีการเปิดตัวระบบ WORKSPACE ผู้ใช้ได้รายงานปัญหาต่างๆ มากมาย ซึ่งรวมถึง

  • Bazel ไม่ได้ประเมินไฟล์ WORKSPACE ของการขึ้นต่อกัน ดังนั้นการขึ้นต่อกันแบบทรานซิทีฟทั้งหมดจึงต้องกำหนดไว้ในไฟล์ WORKSPACE ของ repo หลัก นอกเหนือจากการขึ้นต่อกันโดยตรง
  • โปรเจ็กต์ต่างๆ ได้นำรูปแบบ "deps.bzl" มาใช้เพื่อหลีกเลี่ยงปัญหานี้ โดยกำหนดมาโครซึ่งจะกำหนด repo หลายรายการ และขอให้ผู้ใช้เรียกใช้มาโครนี้ในไฟล์ WORKSPACE
    • ซึ่งก่อให้เกิดปัญหาของตัวเอง เนื่องจากมาโครไม่สามารถ load ไฟล์ .bzl อื่นๆ ได้ โปรเจ็กต์เหล่านี้จึงต้องกำหนดการขึ้นต่อกันแบบทรานซิทีฟในมาโคร "deps" นี้ หรือหลีกเลี่ยงปัญหานี้โดยให้ผู้ใช้เรียกใช้มาโคร "deps" แบบหลายเลเยอร์
    • Bazel จะประเมินไฟล์ WORKSPACE ตามลำดับ นอกจากนี้ การขึ้นต่อกันจะระบุโดยใช้ http_archive กับ URL โดยไม่มีข้อมูลเวอร์ชัน ซึ่งหมายความว่าไม่มีวิธีที่เชื่อถือได้ในการแก้ปัญหาเวอร์ชันในกรณีของการขึ้นต่อกันแบบไดมอนด์ (A ขึ้นต่อกันกับ B และ C โดย B และ C ขึ้นต่อกันกับ D เวอร์ชันต่างๆ)

เนื่องจากข้อบกพร่องของ WORKSPACE Bzlmod จะมาแทนที่ระบบ WORKSPACE เดิมใน Bazel เวอร์ชันต่อๆ ไป โปรดอ่านคู่มือการย้ายข้อมูล Bzlmodเกี่ยวกับวิธีย้ายข้อมูลไปยัง Bzlmod