Quy tắc kho lưu trữ

Báo cáo vấn đề Xem nguồn Hằng đêm · 7,3 · 7.2 · 7.1 · 7 · 6,5

Trang này trình bày cách tạo quy tắc về kho lưu trữ và cung cấp ví dụ cho chi tiết hơn.

Kho lưu trữ bên ngoài là một quy tắc chỉ có thể sử dụng trong tệp WORKSPACE và cho phép thao tác không kín ở giai đoạn tải Bazel. Mỗi quy tắc của kho lưu trữ bên ngoài sẽ tạo không gian làm việc riêng, với tệp và cấu phần phần mềm BUILD riêng. Họ có thể được dùng để phụ thuộc vào bên thứ ba các thư viện (chẳng hạn như thư viện đóng gói Maven), mà còn để tạo các tệp BUILD dành riêng cho máy chủ lưu trữ Bazel đang chạy.

Tạo quy tắc kho lưu trữ

Trong tệp .bzl, hãy sử dụng Hàm repository_rule để tạo một quy tắc mới quy tắc kho lưu trữ và lưu trữ quy tắc đó trong biến toàn cục.

Bạn có thể sử dụng quy tắc kho lưu trữ tuỳ chỉnh giống như quy tắc kho lưu trữ gốc. Nó có thuộc tính name bắt buộc và mọi mục tiêu có trong tệp bản dựng có thể được gọi là @<name>//package:target, trong đó <name> là giá trị của Thuộc tính name.

Quy tắc này được tải khi bạn tạo quy tắc rõ ràng hoặc nếu quy tắc là phần phụ thuộc của bản dựng. Trong trường hợp này, Bazel sẽ thực thi hàm implementation. Chiến dịch này hàm mô tả cách tạo kho lưu trữ, nội dung và tệp BUILD của kho lưu trữ đó.

Thuộc tính

Thuộc tính là đối số quy tắc, chẳng hạn như url hoặc sha256. Bạn phải liệt kê các thuộc tính và loại của các thuộc tính đó khi bạn xác định quy tắc về kho lưu trữ.

local_repository = repository_rule(
    implementation=_impl,
    local=True,
    attrs={"path": attr.string(mandatory=True)})

Để truy cập vào một thuộc tính, hãy dùng repository_ctx.attr.<attribute_name>.

Tất cả repository_rule đều đã được xác định ngầm các thuộc tính (giống như bản dựng quy tắc). Hai thuộc tính ngầm ẩn là name (cũng giống như đối với quy tắc xây dựng) và repo_mapping. Bạn có thể truy cập tên của quy tắc kho lưu trữ bằng repository_ctx.name. Ý nghĩa của repo_mapping giống như ý nghĩa của quy tắc kho lưu trữ gốc local_repository và new_local_repository.

Nếu tên thuộc tính bắt đầu bằng _ thì thuộc tính đó là riêng tư và người dùng không đặt được.

Chức năng triển khai

Mỗi quy tắc kho lưu trữ đều cần có một hàm implementation. Chiến dịch này có 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 trả về None để biểu thị rằng quy tắc có thể tái tạo được các tham số được chỉ định hoặc một lệnh chính tả có tập hợp các tham số cho quy tắc đó sẽ biến quy tắc đó thành quy tắc có thể tái tạo tạo ra cùng một kho lưu trữ. Để ví dụ: đối với quy tắc theo dõi kho lưu trữ git, 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 ban đầu đã chỉ định.

Tham số đầu vào repository_ctx có thể được dùng để truy cập các giá trị thuộc tính và các hàm không gián đoạn (tìm một tệp nhị phân, thực thi một tệp nhị phân, tạo một tệp trong kho lưu trữ hoặc tải tệp xuống từ Internet). Xem thư viện để tìm hiểu 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?

Nếu kho lưu trữ được khai báo là local thì sẽ thay đổi trong một phần phụ thuộc trong biểu đồ phần phụ thuộc (bao gồm cả tệp WORKSPACE) sẽ kích hoạt quá trình thực thi hàm triển khai.

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

Cuối cùng, đối với các kho lưu trữ không phải local, chỉ có một thay đổi trong các phần phụ thuộc có thể gây ra khởi động lại:

Các tệp .bzl cần để xác định quy tắc về kho lưu trữ.
Khai báo quy tắc kho lưu trữ trong tệp WORKSPACE.
Giá trị của bất kỳ biến môi trường nào được khai báo bằng environ của trang web repository_rule . Hệ thống có thể thực thi giá trị của các biến môi trường đó từ dòng lệnh có --action_env cờ (nhưng cờ này sẽ vô hiệu hoá mọi hành động của bản dựng).
Nội dung của bất kỳ tệp nào được một nhãn sử dụng và tham chiếu đến (ví dụ: //mypkg:label.txt chứ không phải mypkg/label.txt).

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ó sự thay đổi nào phần định nghĩa hoặc phần phụ thuộc. Ví dụ: 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 thay đổi mới là 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 một cách vô điều kiện bằng cách gọi bazel sync.

Ngoài ra, một số quy tắc kiểm tra máy cục bộ và có thể trở thành 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 đó khi repository_rule có tập hợp thuộc tính configure, hãy sử dụng bazel sync --configure.

Ví dụ

Chuỗi công cụ được tự động định cấu hình C++: mã này sử dụng quy tắc kho lưu trữ để tự động tạo 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ợ.
Truy cập vào kho lưu trữ sử dụng một vài 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 có chức năng tạo mục tiêu bản 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.