Quy tắc kho lưu trữ

Báo cáo vấn đề Xem nguồn Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Trang này trình bày cách xác định các quy tắc kho lưu trữ và cung cấp ví dụ để 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. Bạn có thể xác định kho lưu trữ 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 một quy tắc kho lưu trữ, giống như các mục tiêu xây dựng được xác định bằng cách gọi các quy tắc xây dựng. Bạn có thể dùng các tệp này để phụ thuộc vào thư viện bên thứ ba (chẳng hạn như thư viện được đóng gói Maven) nhưng cũng có thể dùng để tạo các tệp BUILD dành riêng cho máy chủ mà Bazel đang chạy.

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

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

Hai thành phần chính của định nghĩa quy tắc kho lưu trữ 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 một lệnh gọi quy tắc kho lưu trữ, đồng thời hàm triển khai sẽ chạy khi cần tìm nạp kho lưu trữ.

Thuộc tính

Thuộc tính là các đối số được truyền đến lệnh gọi quy tắc kho lưu trữ. Lược đồ của các thuộc tính mà một quy tắc kho lưu trữ chấp nhận được chỉ định bằng đối số attrs khi quy tắc kho lưu trữ được xác định bằng một lệnh gọi đến repository_rule. Ví dụ về việc 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 theo cách hơi đặc biệt: khi được chỉ định làm đầu vào cho một lệnh gọi quy tắc kho lưu trữ, thuộc tính này sẽ lấy một tên kho lưu trữ rõ ràng; nhưng khi được đọ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, thuộc tính này sẽ trả về tên kho lưu trữ chuẩn.

Hàm triển khai

Mỗi quy tắc về kho lưu trữ đều yêu cầu một hàm implementation. Nội dung 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, repository_ctx. Hàm này trả về None để biểu thị rằng quy tắc có thể tái tạo với các tham số đã chỉ định, hoặc một từ điển có một tập hợp các tham số cho quy tắc đó sẽ biến quy tắc đó thành một quy tắc có thể tái tạo để tạo cùng một kho lưu trữ. Ví dụ: đối với một quy tắc theo dõi kho lưu trữ git, điều đó có nghĩa là trả về một mã 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ể 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 khép kí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 thông tin. 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?

Hàm triển khai của một quy tắc kho lưu trữ sẽ đượ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 mục tiê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. Đây được gọi là "tìm nạp" kho lưu trữ.

Không giống như các mục tiêu thông thường, các kho lưu trữ không nhất thiết phải được tìm nạp lại khi có thay đổi khiến kho lưu trữ khác đi. Lý do là Bazel không thể phát hiện các thay đổi hoặc sẽ gây ra quá nhiều chi phí cho 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 đây 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 kho lưu trữ.
Giá trị của mọi biến môi trường đượ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ể kết nối cứng các giá trị của những biến môi trường này trên dòng lệnh bằng cờ --repo_env.
Sự tồn tại, nội dung và loại của mọi đường dẫn đang được watch trong hàm triển khai của quy tắc kho lưu trữ.
- Một số phương thức khác của repository_ctx có tham số watch, chẳng hạn như read(), execute() và extract(), cũng có thể khiến các đường dẫn được theo dõi.
- Tương tự, repository_ctx.watch_tree và path.readdir có thể khiến các đường dẫn được theo dõi theo những cách khác.
Khi bazel fetch --force được thực thi.

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

Nếu cờ configure được đặt, thì kho lưu trữ sẽ được tìm nạp lại trên bazel fetch --force --configure (các kho lưu trữ không phải configure sẽ không được tìm nạp lại).
Nếu cờ local được đặt, ngoài các trường hợp trên, kho lưu trữ cũng được tìm nạp lại khi máy chủ Bazel khởi động lại.

Buộc tìm nạp lại các 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ó bất kỳ thay đổi nào đối với định nghĩa hoặc các phần phụ thuộc của kho lưu trữ đó. Ví dụ: một kho lưu trữ tìm nạp các nguồn có thể tuân theo một nhánh cụ thể của kho lưu trữ bên thứ ba và các cam kết 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 tất cả các kho lưu trữ bên ngoài vô điều kiện bằng cách gọi bazel fetch --force --all.

Ngoài ra, một số quy tắc của repo sẽ 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 những kho lưu trữ bên ngoài mà định nghĩa repository_rule có thuộc tính configure được đặt, hãy sử dụng bazel fetch --force --configure.

Ví dụ

Chuỗi công cụ C++ được định cấu hình tự động: chuỗi công cụ này sử dụng một 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ác 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 để sử dụng các quy tắc Go.
rules_jvm_external tạo một kho lưu trữ bên ngoài có tên là @maven theo mặc định, kho lưu trữ này sẽ tạo các mục tiêu xây dựng cho mọi cấu phần phần mềm Maven trong cây phần phụ thuộc bắc cầu.

Quy tắc kho lưu trữ Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.