BazelCon 2024 đăng ký và CFP hiện đã mở!
Để xem tài liệu về bản phát hành ổn định, vui lòng sử dụng trình đơn thả xuống "Tài liệu đã tạo phiên bản". Chế độ xem mặc định phản ánh phiên bản mới nhất ở HEAD.

Trang này được dịch bởi Cloud Translation API.

Quy tắc kho lưu trữ

Báo cáo vấn đề Xem nguồn Nightly .

Trang này trình bày cách xác định các quy tắc về kho lưu trữ và cung cấp ví dụ để bạn biết thêm thông tin chi tiết.

Kho lưu trữ bên ngoài là một cây thư mục, chứa các tệp nguồn có thể dùng trong bản dựng Bazel, được tạo theo yêu cầu bằng cách chạy quy tắc kho lưu trữ tương ứng. Repos có thể được xác định theo nhiều cách, nhưng cuối cùng, mỗi kho lưu trữ được xác định bằng cách gọi quy tắc kho lưu trữ, giống như mục tiêu bản dựng được xác định bằng cách gọi quy tắc bản dựng. Các thư viện này có thể được dùng để phụ thuộc vào thư viện của bên thứ ba (chẳng hạn như thư viện đóng gói Maven), nhưng cũng để tạo các tệp BUILD dành riêng cho máy chủ lưu trữ Bazel đang chạy.

Định nghĩa quy tắc kho lưu trữ

Trong tệp .bzl, hãy sử dụng hàm repository_rule để xác định một quy tắc kho lưu trữ mới và lưu trữ quy tắc đó trong biến toàn cục. Sau khi xác định quy tắc kho lưu trữ, hệ thống có thể gọi quy tắc này dưới dạng một hàm để xác định kho lưu trữ. Lệnh gọi này thường được thực hiện từ bên trong hàm triển khai tiện ích mô-đun.

Hai thành phần chính trong định nghĩa quy tắc repo là giản đồ thuộc tính và hàm triển khai. Giản đồ thuộc tính xác định tên và loại thuộc tính được truyền đến lệnh gọi quy tắc repo, đồng thời hàm triển khai được chạy khi cần tìm nạp repo đó.

Thuộc tính

Thuộc tính là các đối số được truyền đến lệnh gọi quy tắc repo. Giản đồ của các thuộc tính mà quy tắc repo chấp nhận được chỉ định bằng đối số attrs khi quy tắc repo được xác định bằng lệnh gọi đến repository_rule. Ví dụ về cách xác định các thuộc tính url và sha256 dưới dạng chuỗi:

http_archive = repository_rule(
    implementation=_impl,
    attrs={
        "url": attr.string(mandatory=True)
        "sha256": attr.string(mandatory=True)
    }
)

Để truy cập vào một thuộc tính trong hàm triển khai, hãy sử dụng repository_ctx.attr.<attribute_name>:

def _impl(repository_ctx):
    url = repository_ctx.attr.url
    checksum = repository_ctx.attr.sha256

Tất cả repository_rule đều có thuộc tính name được xác định ngầm. Đây là một thuộc tính chuỗi hoạt động khá kỳ diệu: khi được chỉ định làm dữ liệu đầu vào cho lệnh gọi quy tắc repo, nó sẽ có một tên repo rõ ràng; nhưng khi đọc từ hàm triển khai của quy tắc kho lưu trữ bằng cách sử dụng repository_ctx.attr.name, giá trị này sẽ trả về tên kho lưu trữ chuẩn.

Chức năng triển khai

Mọi quy tắc repo đều yêu cầu một hàm implementation. Giao diện này chứa logic thực tế của quy tắc và được thực thi nghiêm ngặt trong Giai đoạn tải.

Hàm này có đúng một tham số đầu vào là repository_ctx. Hàm này trả về None để biểu thị rằng quy tắc có thể tái tạo dựa trên các tham số được chỉ định, hoặc một lệnh với một tập hợp các tham số cho quy tắc đó để biến quy tắc đó thành một quy tắc có thể tái tạo tạo ra cùng một repo. Ví dụ: đối với một quy tắc theo dõi kho lưu trữ git, tức là trả về một giá trị nhận dạng cam kết cụ thể thay vì một nhánh nổi được chỉ định ban đầu.

Bạn có thể sử dụng tham số đầu vào repository_ctx để truy cập vào các giá trị thuộc tính và các hàm không gián đoạn (tìm tệp nhị phân, thực thi tệp nhị phân, tạo tệp trong kho lưu trữ hoặc tải tệp xuống từ Internet). Hãy xem tài liệu về API để biết thêm ngữ cảnh. Ví dụ:

def _impl(repository_ctx):
  repository_ctx.symlink(repository_ctx.attr.path, "")

local_repository = repository_rule(
    implementation=_impl,
    ...)

Khi nào hàm triển khai được thực thi?

Chức năng triển khai của một quy tắc kho lưu trữ được thực thi khi Bazel cần một mục tiêu từ kho lưu trữ đó, chẳng hạn như khi một mục tiêu khác (trong một kho lưu trữ khác) phụ thuộc vào mục tiêu đó hoặc nếu được đề cập trên dòng lệnh. Sau đó, hàm triển khai dự kiến sẽ tạo kho lưu trữ trong hệ thống tệp. Quá trình này được gọi là "tìm nạp" kho lưu trữ.

Trái ngược với các mục tiêu thông thường, kho lưu trữ không nhất thiết phải được tìm nạp lại khi có gì đó thay đổi khiến kho lưu trữ đó khác đi. Lý do là có những thứ mà Bazel không thể phát hiện các thay đổi hoặc sẽ gây ra quá nhiều chi phí trên mỗi bản dựng (ví dụ: những thứ được tìm nạp từ mạng). Do đó, các kho lưu trữ chỉ được tìm nạp lại nếu một trong những điều sau thay đổi:

Các thuộc tính được truyền đến lệnh gọi quy tắc kho lưu trữ.
Mã Starlark bao gồm việc triển khai quy tắc repo.
Giá trị của bất kỳ biến môi trường nào được truyền đến phương thức getenv() của repository_ctx hoặc được khai báo bằng thuộc tính environ của repository_rule. Bạn có thể cố định giá trị của các biến môi trường này trên dòng lệnh bằng cờ --repo_env.
Nội dung của mọi tệp được truyền đến read(), execute() và các phương thức tương tự của repository_ctx được tham chiếu bằng một nhãn (ví dụ: //mypkg:label.txt nhưng không phải mypkg/label.txt)
Khi bazel fetch --force được thực thi.

Có hai tham số của repository_rule kiểm soát thời điểm tìm nạp lại các kho lưu trữ:

Nếu bạn đặt cờ configure, kho lưu trữ chỉ được tìm nạp lại trên bazel fetch khi tham số --configure được truyền vào kho lưu trữ đó (nếu bạn không đặt thuộc tính này, lệnh này sẽ không dẫn đến quá trình tìm nạp lại)
Nếu bạn đặt cờ local thì ngoài các trường hợp trên, kho lưu trữ cũng sẽ được tìm nạp lại khi máy chủ Bazel khởi động lại.

Khởi động lại hàm triển khai

Bạn có thể bắt đầu lại hàm triển khai trong khi tìm nạp một kho lưu trữ nếu một phần phụ thuộc mà nó yêu cầu bị thiếu. Trong trường hợp đó, việc thực thi hàm triển khai sẽ dừng, phần phụ thuộc bị thiếu sẽ được giải quyết và hàm sẽ được thực thi lại sau khi phần phụ thuộc đã được phân giải. Để tránh việc khởi động lại không cần thiết (tốn kém, vì việc truy cập mạng có thể phải lặp lại), các đối số nhãn được tìm nạp trước, miễn là tất cả các đối số nhãn đều có thể được phân giải vào một tệp hiện có. Xin lưu ý rằng việc phân giải đường dẫn từ một chuỗi hoặc nhãn chỉ được tạo trong quá trình thực thi hàm vẫn có thể gây ra quá trình khởi động lại.

Buộc tìm nạp lại kho lưu trữ bên ngoài

Đôi khi, một kho lưu trữ bên ngoài có thể trở nên lỗi thời mà không có thay đổi nào đối với định nghĩa hoặc phần phụ thuộc của kho lưu trữ đó. Ví dụ: một kho lưu trữ có thể tìm nạp các nguồn lưu trữ theo một nhánh cụ thể của kho lưu trữ bên thứ ba và các thay đổi mới có sẵn trên nhánh đó. Trong trường hợp này, bạn có thể yêu cầu bazel tìm nạp lại vô điều kiện tất cả các kho lưu trữ bên ngoài bằng cách gọi bazel fetch --force --all.

Hơn nữa, một số quy tắc repo kiểm tra máy cục bộ và có thể trở nên lỗi thời nếu máy cục bộ được nâng cấp. Tại đây, bạn có thể yêu cầu Bazel chỉ tìm nạp lại các kho lưu trữ bên ngoài đó, trong đó định nghĩa repository_rule có tập hợp thuộc tính configure, sử dụng bazel fetch --all --configure.

Ví dụ

Chuỗi công cụ được tự động định cấu hình C++: hệ thống này sử dụng quy tắc kho lưu trữ để tự động tạo các tệp cấu hình C++ cho Bazel bằng cách tìm trình biên dịch C++ cục bộ, môi trường và cờ mà trình biên dịch C++ hỗ trợ.
Kho lưu trữ Go sử dụng một số repository_rule để xác định danh sách các phần phụ thuộc cần thiết cho việc sử dụng quy tắc Go.
rules_jvm_external tạo kho lưu trữ bên ngoài có tên là @maven theo mặc định. Kho lưu trữ này tạo các mục tiêu bản dựng cho mọi cấu phần phần mềm Maven trong cây phụ thuộc bắc cầu.