Làm việc với các phần phụ thuộc bên ngoài

Bazel có thể phụ thuộc vào mục tiêu từ các dự án khác. Phần phụ thuộc của các dự án khác này được gọi là phần phụ thuộc bên ngoài.

Lưu ý: Bazel phiên bản 5.0 trở lên có một hệ thống phần phụ thuộc bên ngoài mới tên mã là "Bzlmod", hệ thống này khiến nhiều nội dung trên trang này đã lỗi thời. Vui lòng xem hướng dẫn sử dụng về Bzlmod để biết thêm thông tin.

Tệp WORKSPACE (hoặc tệp WORKSPACE.bazel) trong thư mục không gian làm việc cho Bazel biết cách lấy nguồn của các dự án khác. Các dự án khác này có thể chứa một hoặc nhiều tệp BUILD với các mục tiêu riêng. Các tệp BUILD trong dự án chính có thể phụ thuộc vào các mục tiêu bên ngoài này bằng cách sử dụng tên của các tệp đó trong tệp WORKSPACE.

Ví dụ: giả sử có hai dự án trên một hệ thống:

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

Nếu project1 muốn phụ thuộc vào một mục tiêu, :foo, được xác định trong /home/user/project2/BUILD, thì phần tử này có thể chỉ định rằng bạn có thể tìm thấy kho lưu trữ có tên project2 tại /home/user/project2. Sau đó, các mục tiêu trong /home/user/project1/BUILD có thể phụ thuộc vào @project2//:foo.

Tệp WORKSPACE cho phép người dùng phụ thuộc vào mục tiêu từ các phần khác của hệ thống tệp hoặc được tải xuống từ Internet. Tệp này sử dụng cú pháp giống như tệp BUILD, nhưng hỗ trợ một bộ quy tắc khác, được gọi là quy tắc lưu trữ (đôi khi còn gọi là quy tắc không gian làm việc). Bazel có một vài quy tắc tích hợp sẵn về kho lưu trữ và một tập hợp quy tắc kho lưu trữ Starlark được nhúng. Người dùng cũng có thể viết các quy tắc kho lưu trữ tuỳ chỉnh để có hành vi phức tạp hơn.

Các loại phần phụ thuộc bên ngoài được hỗ trợ

Bạn có thể sử dụng một số loại phần phụ thuộc bên ngoài cơ bản:

• Phần phụ thuộc trên các dự án Bazel khác
• Phần phụ thuộc vào các dự án không phải Bazel
• Phần phụ thuộc trên gói bên ngoài

Tuỳ thuộc vào các dự án khác của Bazel

Nếu muốn sử dụng các mục tiêu từ dự án Bazel thứ hai, bạn có thể sử dụng local_repository, git_repository hoặc http_archive để liên kết tượng trưng từ hệ thống tệp cục bộ, tham chiếu đến kho lưu trữ git hoặc tải kho lưu trữ xuống (tương ứng).

Ví dụ: giả sử bạn đang làm việc trên một dự án my-project/ và bạn muốn phụ thuộc vào các mục tiêu từ dự án coworkers-project/ của đồng nghiệp. Cả hai dự án đều sử dụng Bazel, vì vậy, bạn có thể thêm dự án của đồng nghiệp dưới dạng phần phụ thuộc bên ngoài, sau đó sử dụng bất kỳ mục tiêu nào mà đồng nghiệp của bạn đã xác định trong tệp BUILD của riêng bạn. Bạn sẽ thêm đoạn mã sau vào my_project/WORKSPACE:

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

Nếu đồng nghiệp của bạn có một mục tiêu là //foo:bar, thì dự án của bạn có thể gọi mục tiêu đó là @coworkers_project//foo:bar. Tên dự án bên ngoài phải là tên không gian làm việc hợp lệ.

Tuỳ thuộc vào các dự án không phải của Bazel

Các quy tắc có tiền tố new_, chẳng hạn như new_local_repository, cho phép bạn tạo mục tiêu từ các dự án không sử dụng Bazel.

Ví dụ: giả sử bạn đang làm việc trên một dự án my-project/ và bạn muốn phụ thuộc vào dự án coworkers-project/ của đồng nghiệp. Dự án của đồng nghiệp sử dụng make để tạo, nhưng bạn muốn phụ thuộc vào một trong các tệp .so mà dự án này tạo ra. Để thực hiện việc này, hãy thêm đoạn mã sau vào my_project/WORKSPACE:

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

build_file chỉ định một tệp BUILD để phủ lên dự án hiện có, ví dụ:

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

Sau đó, bạn có thể phụ thuộc vào @coworkers_project//:some-lib trong các tệp BUILD của dự án.

Tuỳ thuộc vào các gói bên ngoài

Kho lưu trữ và cấu phần phần mềm Maven

Sử dụng bộ quy tắc rules_jvm_external để tải cấu phần phần mềm xuống từ kho lưu trữ Maven và cung cấp dưới dạng phần phụ thuộc Java.

Đang tìm nạp phần phụ thuộc

Theo mặc định, các phần phụ thuộc bên ngoài sẽ được tìm nạp khi cần trong bazel build. Nếu bạn muốn tìm nạp trước các phần phụ thuộc cần thiết cho một nhóm mục tiêu cụ thể, hãy sử dụng bazel fetch. Để tìm nạp vô điều kiện tất cả các phần phụ thuộc bên ngoài, hãy sử dụng bazel sync. Khi kho lưu trữ đã tìm nạp được lưu trữ trong cơ sở đầu ra, quá trình tìm nạp sẽ diễn ra theo mỗi không gian làm việc.

Ẩn phần phụ thuộc

Bất cứ khi nào có thể, bạn nên có một chính sách phiên bản duy nhất trong dự án. Đây là yêu cầu bắt buộc đối với các phần phụ thuộc mà bạn biên dịch và xuất hiện trong tệp nhị phân cuối cùng. Tuy nhiên, trong trường hợp điều này không đúng, bạn có thể đổ bóng các phần phụ thuộc. Hãy xem xét trường hợp sau:

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/NƠI LÀM VIỆC

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 = "..."
)

Cả hai phần phụ thuộc A và B đều phụ thuộc vào testrunner, nhưng lại phụ thuộc vào các phiên bản khác nhau của testrunner. Không có lý do nào để những trình chạy kiểm thử này không cùng tồn tại một cách yên bình trong myproject. Tuy nhiên, chúng sẽ xung đột với nhau vì chúng có cùng tên. Để khai báo cả hai phần phụ thuộc, hãy cập nhật 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"}
)

Cơ chế này cũng có thể được sử dụng để kết nối kim cương. Ví dụ: nếu A và B có cùng phần phụ thuộc nhưng gọi bằng tên khác, thì các phần phụ thuộc đó có thể được liên kết trong myproject/WORKSPACE.

Ghi đè kho lưu trữ qua dòng lệnh

Để ghi đè một kho lưu trữ đã khai báo bằng một kho lưu trữ cục bộ từ dòng lệnh, hãy sử dụng cờ --override_repository. Việc sử dụng cờ này sẽ thay đổi nội dung của các kho lưu trữ bên ngoài mà không cần thay đổi mã nguồn của bạn.

Ví dụ: để ghi đè @foo vào thư mục cục bộ /path/to/local/foo, hãy truyền cờ --override_repository=foo=/path/to/local/foo.

Một số trường hợp sử dụng bao gồm:

• Gỡ lỗi. Ví dụ: bạn có thể ghi đè kho lưu trữ http_archive vào thư mục cục bộ nơi bạn có thể thực hiện các thay đổi dễ dàng hơn.
• Nhà cung cấp. Nếu bạn đang ở trong môi trường không thể thực hiện lệnh gọi mạng, hãy ghi đè các quy tắc lưu trữ dựa trên mạng để trỏ đến các thư mục cục bộ.

Sử dụng proxy

Bazel sẽ chọn các địa chỉ proxy từ các biến môi trường HTTPS_PROXY và HTTP_PROXY, rồi sử dụng các địa chỉ này để tải các tệp HTTP/HTTPS xuống (nếu được chỉ định).

Hỗ trợ IPv6

Trên các máy chỉ có IPv6, Bazel có thể tải các phần phụ thuộc xuống mà không cần thay đổi. Tuy nhiên, trên các máy IPv4/IPv6 xếp chồng kép, Bazel tuân theo quy ước giống như Java: nếu IPv4 được bật, IPv4 sẽ được ưu tiên. Trong một số trường hợp, chẳng hạn như khi mạng IPv4 không thể phân giải/truy cập các địa chỉ bên ngoài, điều này có thể gây ra ngoại lệ Network unreachable và lỗi bản dựng. Trong những trường hợp này, bạn có thể ghi đè hành vi của Bazel để ưu tiên IPv6 bằng cách sử dụng thuộc tính hệ thống java.net.preferIPv6Addresses=true. Cụ thể:

• Sử dụng tuỳ chọn khởi động của --host_jvm_args=-Djava.net.preferIPv6Addresses=true, chẳng hạn như bằng cách thêm dòng sau vào tệp .bazelrc:

  startup --host_jvm_args=-Djava.net.preferIPv6Addresses=true

• Nếu bạn đang chạy các mục tiêu bản dựng Java cũng cần kết nối với Internet (đôi khi cần phải kiểm thử tích hợp), hãy sử dụng cờ công cụ --jvmopt=-Djava.net.preferIPv6Addresses=true, chẳng hạn như bằng cách đưa dòng sau vào tệp .bazelrc:

  build --jvmopt=-Djava.net.preferIPv6Addresses

• Nếu bạn đang sử dụng rules_jvm_external, chẳng hạn như để phân giải phiên bản phần phụ thuộc, hãy thêm -Djava.net.preferIPv6Addresses=true vào biến môi trường COURSIER_OPTS để cung cấp các tuỳ chọn máy ảo Java cho Bộ mã hoá

Phần phụ thuộc bắc cầu

Bazel chỉ đọc các phần phụ thuộc được liệt kê trong tệp WORKSPACE. Nếu dự án của bạn (A) phụ thuộc vào một dự án khác (B) có liệt kê một phần phụ thuộc trên dự án thứ ba (C) trong tệp WORKSPACE, thì bạn sẽ phải thêm cả B và C vào tệp WORKSPACE của dự án. Yêu cầu này có thể tăng kích thước tệp WORKSPACE, nhưng hạn chế khả năng có một thư viện bao gồm C ở phiên bản 1.0 và một thư viện khác bao gồm C ở phiên bản 2.0.

Lưu các phần phụ thuộc bên ngoài vào bộ nhớ đệm

Theo mặc định, Bazel sẽ chỉ tải lại các phần phụ thuộc bên ngoài xuống nếu định nghĩa của các phần phụ thuộc đó thay đổi. Các thay đổi đối với các tệp được tham chiếu trong định nghĩa (chẳng hạn như bản vá hoặc tệp BUILD) cũng được bazel tính đến.

Để buộc tải xuống lại, hãy dùng bazel sync.

Bố cục

Tất cả các phần phụ thuộc bên ngoài đều được tải xuống một thư mục thuộc thư mục con external ở cơ sở đầu ra. Trong trường hợp có một kho lưu trữ cục bộ, một đường liên kết tượng trưng sẽ được tạo ở đó thay vì tạo một thư mục mới. Bạn có thể thấy thư mục external bằng cách chạy:

ls $(bazel info output_base)/external

Xin lưu ý rằng việc chạy bazel clean sẽ không thực sự xoá thư mục bên ngoài. Để xoá tất cả cấu phần phần mềm bên ngoài, hãy sử dụng bazel clean --expunge.

Bản dựng ngoại tuyến

Đôi khi, việc chạy bản dựng trong môi trường ngoại tuyến là điều cần thiết hoặc mong muốn. Đối với các trường hợp sử dụng đơn giản, chẳng hạn như khi đi máy bay, tìm nạp trước các kho lưu trữ cần thiết có bazel fetch hoặc bazel sync là đủ; hơn nữa, việc sử dụng tuỳ chọn --nofetch có thể tắt tính năng tìm nạp thêm các kho lưu trữ trong bản dựng.

Đối với các bản dựng ngoại tuyến thực sự, trong đó một thực thể khác với bazel sẽ cung cấp các tệp cần thiết, đó là bazel hỗ trợ tuỳ chọn --distdir. Bất cứ khi nào quy tắc lưu trữ yêu cầu bazel tìm nạp một tệp qua ctx.download hoặc ctx.download_and_extract và cung cấp tổng giá trị băm của tệp cần thiết, trước tiên, bazel sẽ xem xét các thư mục do tuỳ chọn đó chỉ định để tìm một tệp khớp với tên cơ sở của URL đầu tiên được cung cấp và sử dụng bản sao cục bộ đó nếu hàm băm khớp.

Chính Bazel sử dụng kỹ thuật này để tự khởi động ngoại tuyến từ cấu phần phần mềm phân phối. API này thực hiện bằng cách thu thập tất cả các phần phụ thuộc bên ngoài cần thiết trong một distdir_tar nội bộ.

Tuy nhiên, bazel cho phép thực thi các lệnh tuỳ ý trong các quy tắc kho lưu trữ mà không cần biết các lệnh này có gọi mạng hay không. Do đó, bazel không có tuỳ chọn để thực thi các bản dựng hoàn toàn ngoại tuyến. Vì vậy, việc kiểm thử xem một bản dựng có hoạt động ngoại tuyến đúng cách hay không sẽ yêu cầu chặn mạng bên ngoài, như bazel đã thực hiện trong kiểm thử khởi động.

Các phương pháp hay nhất

Quy tắc kho lưu trữ

Quy tắc lưu trữ thường phải chịu trách nhiệm về:

• Phát hiện chế độ cài đặt hệ thống và ghi vào tệp.
• Tìm tài nguyên ở đâu đó trên hệ thống.
• Đang tải tài nguyên xuống từ các URL.
• Tạo hoặc liên kết tượng trưng các tệp BUILD vào thư mục lưu trữ bên ngoài.

Tránh sử dụng repository_ctx.execute khi có thể. Ví dụ: khi sử dụng thư viện C++ không phải của Bazel có bản dựng bằng Make, bạn nên sử dụng repository_ctx.download() rồi viết tệp BUILD để tạo bản dựng đó thay vì chạy ctx.execute(["make"]).

Ưu tiên http_archive hơn git_repository và new_git_repository. Lý do là:

• Các quy tắc lưu trữ Git phụ thuộc vào hệ thống git(1), trong khi trình tải xuống HTTP được tích hợp vào Bazel và không có phần phụ thuộc hệ thống.
• http_archive hỗ trợ danh sách urls dưới dạng bản sao, còn git_repository chỉ hỗ trợ một remote duy nhất.
• http_archive hoạt động với bộ nhớ đệm của kho lưu trữ, nhưng không hoạt động với git_repository. Xem #5116 để biết thêm thông tin.

Đừng sử dụng bind(). Hãy xem phần "Cân nhắc việc xoá liên kết" để biết nội dung thảo luận chi tiết về các vấn đề và các phương án thay thế.