การลงทะเบียน BazelCon 2024 เปิดให้ลงทะเบียนแล้วในตอนนี้

หน้านี้ได้รับการแปลโดย Cloud Translation API

การทำงานกับทรัพยากร Dependency ภายนอก

รายงานปัญหา ดูแหล่งที่มา รุ่น Nightly · 7.4 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bazel สามารถใช้เป้าหมายจากโปรเจ็กต์อื่นๆ ได้ ทรัพยากร Dependency จากโปรเจ็กต์อื่นๆ เหล่านี้เรียกว่าทรัพยากร Dependency ภายนอก

ไฟล์ WORKSPACE (หรือไฟล์ WORKSPACE.bazel) ในไดเรกทอรีเวิร์กสเปซจะบอก Bazel ว่าจะรับแหล่งที่มาของโปรเจ็กต์อื่นๆ อย่างไร โปรเจ็กต์อื่นๆ เหล่านี้อาจมีไฟล์ BUILD อย่างน้อย 1 ไฟล์ที่มีเป้าหมายของตนเอง ไฟล์ BUILD ภายในโปรเจ็กต์หลักอาจขึ้นอยู่กับเป้าหมายภายนอกเหล่านี้โดยใช้ชื่อจากไฟล์ WORKSPACE

ตัวอย่างเช่น สมมติว่าระบบมีโปรเจ็กต์ 2 รายการดังนี้

/
  home/
    user/
      project1/
        WORKSPACE
        BUILD
        srcs/
          ...
      project2/
        WORKSPACE
        BUILD
        my-libs/

หาก project1 ต้องการใช้เป้าหมาย :foo ที่กําหนดไว้ใน /home/user/project2/BUILD ก็ระบุได้ว่าที่เก็บข้อมูลที่ชื่อ project2 จะอยู่ที่ /home/user/project2 จากนั้นเป้าหมายใน /home/user/project1/BUILD อาจขึ้นอยู่กับ @project2//:foo

ไฟล์ WORKSPACE ช่วยให้ผู้ใช้อ้างอิงเป้าหมายจากส่วนอื่นๆ ของระบบไฟล์หรือดาวน์โหลดจากอินเทอร์เน็ตได้ โดยจะใช้ไวยากรณ์เดียวกันกับไฟล์ BUILD แต่อนุญาตกฎต่างชุดกันซึ่งเรียกว่ากฎที่เก็บ (บางครั้งอาจเรียกว่ากฎพื้นที่ทำงาน) Bazel มาพร้อมกับกฎที่เก็บข้อมูลในตัว 2-3 รายการและชุดกฎที่เก็บข้อมูล Starlark ที่ฝังอยู่ นอกจากนี้ ผู้ใช้ยังเขียนกฎที่กำหนดเองของที่เก็บเพื่อให้ได้ลักษณะการทำงานที่ซับซ้อนมากขึ้นได้ด้วย

ประเภททรัพยากร Dependency ภายนอกที่รองรับ

คุณใช้ทรัพยากรภายนอกประเภทพื้นฐานได้ 2-3 ประเภท ดังนี้

การพึ่งพาโปรเจ็กต์อื่นๆ ของ Bazel
การพึ่งพาโปรเจ็กต์ที่ไม่ใช่ Bazel
การพึ่งพาแพ็กเกจภายนอก

ขึ้นอยู่กับโปรเจ็กต์ Bazel อื่นๆ

หากต้องการใช้เป้าหมายจากโปรเจ็กต์ Bazel ที่ 2 ให้ใช้ local_repository, git_repository หรือ http_archive เพื่อซิมจากระบบไฟล์ในเครื่อง อ้างอิงที่เก็บ Git หรือดาวน์โหลด (ตามลำดับ)

ตัวอย่างเช่น สมมติว่าคุณทํางานในโปรเจ็กต์ my-project/ และต้องการใช้เป้าหมายจากโปรเจ็กต์ coworkers-project/ ของเพื่อนร่วมงาน ทั้ง 2 โปรเจ็กต์ใช้ Bazel คุณจึงเพิ่มโปรเจ็กต์ของเพื่อนร่วมงานเป็นแบบพึ่งพาภายนอกได้ จากนั้นใช้เป้าหมายที่เพื่อนร่วมงานกำหนดไว้จากไฟล์ BUILD ของคุณเอง คุณจะต้องเพิ่มรายการต่อไปนี้ลงใน my_project/WORKSPACE

local_repository(
    name = "coworkers_project",
    path = "/path/to/coworkers-project",
)

หากเพื่อนร่วมงานมี //foo:bar เป้าหมาย โปรเจ็กต์จะเรียกว่า @coworkers_project//foo:bar ชื่อโปรเจ็กต์ภายนอกต้องเป็นชื่อพื้นที่ทำงานที่ถูกต้อง

ขึ้นอยู่กับโปรเจ็กต์ที่ไม่ใช่ Bazel

กฎที่มี new_ นำหน้า เช่น new_local_repository ช่วยให้คุณสร้างเป้าหมายจากโปรเจ็กต์ที่ไม่ได้ใช้ Bazel ได้

ตัวอย่างเช่น สมมติว่าคุณกำลังทําโปรเจ็กต์ my-project/ และต้องการใช้โปรเจ็กต์ coworkers-project/ ของเพื่อนร่วมงาน โปรเจ็กต์ของเพื่อนร่วมงานใช้ make ในการสร้าง แต่คุณต้องการใช้ไฟล์ .so ที่โปรเจ็กต์สร้างขึ้น โดยเพิ่มข้อมูลต่อไปนี้ลงใน my_project/WORKSPACE

new_local_repository(
    name = "coworkers_project",
    path = "/path/to/coworkers-project",
    build_file = "coworker.BUILD",
)

build_file ระบุไฟล์ BUILD เพื่อวางซ้อนในโปรเจ็กต์ที่มีอยู่ เช่น

cc_library(
    name = "some-lib",
    srcs = glob(["**"]),
    visibility = ["//visibility:public"],
)

จากนั้นคุณสามารถใช้ @coworkers_project//:some-lib จากไฟล์ BUILD ของโปรเจ็กต์

ขึ้นอยู่กับแพ็กเกจภายนอก

อาร์ติแฟกต์และที่เก็บ Maven

ใช้ชุดกฎ rules_jvm_external เพื่อดาวน์โหลดอาร์ติแฟกต์จากที่เก็บ Maven และทำให้อาร์ติแฟกต์ดังกล่าวพร้อมใช้งานเป็น Dependency ของ Java

กำลังดึงข้อมูลทรัพยากร Dependency

โดยค่าเริ่มต้น ระบบจะดึงข้อมูลทรัพยากรภายนอกตามที่จำเป็นในระหว่าง bazel build หากต้องการโหลดข้อมูลพึ่งพาที่จำเป็นสำหรับชุดเป้าหมายที่เฉพาะเจาะจงไว้ล่วงหน้า ให้ใช้ bazel fetch หากต้องการดึงข้อมูลทรัพยากรภายนอกทั้งหมดโดยไม่มีเงื่อนไข ให้ใช้ bazel sync เนื่องจากระบบจะจัดเก็บที่เก็บข้อมูลที่ดึงข้อมูลไว้ในฐานเอาต์พุต การดึงข้อมูลจึงเกิดขึ้นต่อพื้นที่ทํางาน

ทรัพยากร Dependency ที่ซ้อนทับ

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

myproject/WORKSPACE

workspace(name = "myproject")

local_repository(
    name = "A",
    path = "../A",
)
local_repository(
    name = "B",
    path = "../B",
)

A/WORKSPACE

workspace(name = "A")

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

B/WORKSPACE

workspace(name = "B")

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

ทั้งทรัพยากร Dependency A และ B ขึ้นอยู่กับ testrunner แต่จะขึ้นอยู่กับ testrunner เวอร์ชันที่แตกต่างกัน เหตุผลที่เครื่องมือรันทดสอบเหล่านี้อยู่ร่วมกันอย่างสันติภายใน myproject นั้นไม่มีอยู่ แต่เครื่องมือรันทดสอบจะขัดแย้งกันเนื่องจากมีชื่อเดียวกัน หากต้องการประกาศทั้ง 2 รายการ ให้อัปเดต myproject/WORKSPACE ดังนี้

workspace(name = "myproject")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "testrunner-v1",
    urls = ["https://github.com/testrunner/v1.zip"],
    sha256 = "..."
)
http_archive(
    name = "testrunner-v2",
    urls = ["https://github.com/testrunner/v2.zip"],
    sha256 = "..."
)
local_repository(
    name = "A",
    path = "../A",
    repo_mapping = {"@testrunner" : "@testrunner-v1"}
)
local_repository(
    name = "B",
    path = "../B",
    repo_mapping = {"@testrunner" : "@testrunner-v2"}
)

กลไกนี้ยังใช้เพื่อต่อเพชรเข้าด้วยกันได้ด้วย เช่น หาก A และ B มีทรัพยากร Dependency เดียวกันแต่เรียกใช้ด้วยชื่ออื่น คุณจะผนวกทรัพยากร Dependency เหล่านั้นใน myproject/WORKSPACE ได้

การลบล้างที่เก็บจากบรรทัดคำสั่ง

หากต้องการลบล้างที่เก็บข้อมูลที่ประกาศไว้ด้วยที่เก็บข้อมูลในเครื่องจากบรรทัดคำสั่ง ให้ใช้ Flag --override_repository การใช้ Flag นี้จะเปลี่ยนเนื้อหาของที่เก็บข้อมูลภายนอกโดยไม่ต้องเปลี่ยนซอร์สโค้ด

เช่น หากต้องการลบล้าง @foo ไปยังไดเรกทอรีในเครื่อง /path/to/local/foo ให้ส่งผ่าน Flag --override_repository=foo=/path/to/local/foo

กรณีการใช้งานบางส่วนมีดังนี้

ปัญหาการแก้ไขข้อบกพร่อง เช่น คุณสามารถลบล้างที่เก็บข้อมูล http_archive ไปยังไดเรกทอรีในเครื่องเพื่อให้ทำการเปลี่ยนแปลงได้ง่ายขึ้น
ตัวแทนจำหน่ายรายย่อย หากคุณอยู่ในสภาพแวดล้อมที่ไม่สามารถเรียกใช้เครือข่าย ให้ลบล้างกฎที่เก็บข้อมูลที่อิงตามเครือข่ายเพื่อชี้ไปยังไดเรกทอรีในเครื่องแทน

การใช้พร็อกซี

Bazel จะรับที่อยู่พร็อกซีจากตัวแปรสภาพแวดล้อม HTTPS_PROXY และ HTTP_PROXY แล้วใช้เพื่อดาวน์โหลดไฟล์ HTTP/HTTPS (หากระบุไว้)

การรองรับ IPv6

บนเครื่องที่ใช้ IPv6 เท่านั้น Bazel จะดาวน์โหลดทรัพยากร Dependency ได้โดยไม่มีการเปลี่ยนแปลง อย่างไรก็ตาม ในเครื่องแบบ 2 สแต็ก IPv4/IPv6 นั้น Bazel จะเป็นไปตามแบบแผนเดียวกับ Java กล่าวคือ หากเปิดใช้ IPv4 ระบบจะเลือกใช้ IPv4 ในบางสถานการณ์ ตัวอย่างเช่น เมื่อเครือข่าย IPv4 แก้ไข/เข้าถึงที่อยู่ภายนอกไม่ได้ อาจทำให้เกิดข้อยกเว้น Network unreachable รายการและบิลด์ล้มเหลว ในกรณีเหล่านี้ คุณลบล้างลักษณะการทำงานของ Bazel เพื่อต้องการใช้ IPv6 ได้โดยใช้พร็อพเพอร์ตี้ระบบ java.net.preferIPv6Addresses=true กล่าวอย่างเจาะจงคือ

ใช้ --host_jvm_args=-Djava.net.preferIPv6Addresses=true startup option โดยเพิ่มบรรทัดต่อไปนี้ในไฟล์ .bazelrc

startup --host_jvm_args=-Djava.net.preferIPv6Addresses=true
หากคุณเรียกใช้เป้าหมายการสร้าง Java ที่ต้องเชื่อมต่ออินเทอร์เน็ตด้วย (บางครั้งการทดสอบการผสานรวมจำเป็นต้องใช้) ให้ใช้--jvmopt=-Djava.net.preferIPv6Addresses=true Flag เครื่องมือด้วย เช่น ใส่บรรทัดต่อไปนี้ในไฟล์ .bazelrc

build --jvmopt=-Djava.net.preferIPv6Addresses
หากคุณใช้ rules_jvm_external เช่น สำหรับการแก้ไขเวอร์ชันของข้อกำหนด ให้เพิ่ม -Djava.net.preferIPv6Addresses=true ลงในตัวแปรสภาพแวดล้อม COURSIER_OPTS เพื่อระบุตัวเลือก JVM สำหรับ Coursier ด้วย

Dependency แบบทรานซิทีฟ

Bazel จะอ่านเฉพาะ Dependency ที่แสดงในไฟล์ WORKSPACE เท่านั้น หากโปรเจ็กต์ของคุณ (A) อิงตามโปรเจ็กต์อื่น (B) ซึ่งแสดงรายการทรัพยากร Dependency ในโปรเจ็กต์ที่ 3 (C) ในไฟล์ WORKSPACE คุณจะต้องเพิ่มทั้ง B และ C ลงในไฟล์ WORKSPACE ของโปรเจ็กต์ ข้อกำหนดนี้อาจทำให้ไฟล์ WORKSPACE มีขนาดใหญ่ขึ้น แต่ช่วยลดโอกาสที่จะมีไลบรารีหนึ่งรวม C เวอร์ชัน 1.0 และอีกไลบรารีรวม C เวอร์ชัน 2.0

การแคชทรัพยากร Dependency ภายนอก

โดยค่าเริ่มต้น Bazel จะดาวน์โหลดทรัพยากรภายนอกอีกครั้งก็ต่อเมื่อคำจำกัดความของทรัพยากรนั้นเปลี่ยนแปลงเท่านั้น Bazel จะพิจารณาการเปลี่ยนแปลงไฟล์ที่อ้างอิงในคําจํากัดความ (เช่น ไฟล์แพตช์หรือ BUILD) ด้วย

หากต้องการบังคับให้ดาวน์โหลดอีกครั้ง ให้ใช้ bazel sync

เลย์เอาต์

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

ls $(bazel info output_base)/external

โปรดทราบว่าการเรียกใช้ bazel clean จะไม่ลบไดเรกทอรีภายนอกจริงๆ หากต้องการนํารายการภายนอกทั้งหมดออก ให้ใช้ bazel clean --expunge

บิลด์แบบออฟไลน์

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

สำหรับการสร้างแบบออฟไลน์อย่างแท้จริง ซึ่งต้องให้ไฟล์ที่จำเป็นโดยเอนทิตีอื่นที่ไม่ใช่ bazel นั้น bazel รองรับตัวเลือก --distdir เมื่อใดก็ตามที่กฎของที่เก็บขอให้ Bazel ดึงข้อมูลไฟล์ผ่าน ctx.download หรือ ctx.download_and_extract และระบุผลรวมแฮชของไฟล์ที่ต้องการ Bazel จะตรวจสอบไดเรกทอรีที่ระบุโดยตัวเลือกนั้นเพื่อหาไฟล์ที่ตรงกับชื่อฐานของ URL แรกที่ระบุ และจะใช้สำเนาในเครื่องนั้นหากแฮชตรงกัน

Bazel เองก็ใช้เทคนิคนี้ในการเริ่มต้นระบบแบบออฟไลน์จาก distribution artifact ซึ่งทําโดยรวบรวมทรัพยากร Dependency ภายนอกทั้งหมดที่จําเป็นใน distdir_tar ภายใน

อย่างไรก็ตาม Bazel อนุญาตให้เรียกใช้คําสั่งแบบใดก็ได้ในกฎของที่เก็บ โดยไม่ทราบว่ามีการใช้คําสั่งเรียกใช้เครือข่ายหรือไม่ ดังนั้น Bazel จึงไม่มีตัวเลือกในการบังคับใช้การสร้างแบบออฟไลน์ทั้งหมด ดังนั้นการทดสอบว่าบิลด์ทํางานอย่างถูกต้องหรือไม่แบบออฟไลน์จึงต้องมีการบล็อกเครือข่ายจากภายนอก เช่นเดียวกับที่ bazel ทําในการทดสอบการเริ่มต้นระบบ

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

กฎที่เก็บ

โดยทั่วไปแล้ว กฎของที่เก็บควรรับผิดชอบในเรื่องต่อไปนี้

ตรวจหาการตั้งค่าระบบและเขียนลงในไฟล์
กำลังค้นหาแหล่งข้อมูลในส่วนอื่นๆ ของระบบ
การดาวน์โหลดทรัพยากรจาก URL
กำลังสร้างหรือ Symlink ไฟล์ BUILD ลงในไดเรกทอรีที่เก็บภายนอก

หลีกเลี่ยงการใช้ repository_ctx.execute เมื่อเป็นไปได้ เช่น เมื่อคุณใช้ไลบรารี C++ ที่ไม่ใช่ Bazel ซึ่งมีบิลด์ที่ใช้ Make มากกว่า ก็ควรใช้ repository_ctx.download() แล้วเขียนไฟล์ BUILD ที่สร้างดังกล่าว แทนการเรียกใช้ ctx.execute(["make"])

แนะนำให้ใช้ http_archive แทน git_repository และ new_git_repository เหตุผลมีดังนี้

กฎที่เก็บ Git ขึ้นอยู่กับ git(1) ของระบบ ในขณะที่โปรแกรมดาวน์โหลด HTTP สร้างขึ้นใน Bazel และไม่มีทรัพยากร Dependency ของระบบ
http_archive รองรับรายการ urls เป็นมิเรอร์ และ git_repository รองรับ remote เพียงรายการเดียว
http_archive ใช้ได้กับแคชที่เก็บ แต่ไม่ใช้ได้กับ git_repository ดูข้อมูลเพิ่มเติมที่ #5116

อย่าใช้ bind() ดู "พิจารณายกเลิกการผูก" สำหรับการพูดคุยถึงปัญหาและทางเลือกต่างๆ ที่ยาวนาน