Tổ chức quản lý tên miền

Báo cáo sự cố Xem nguồn

Bzlmod phát hiện các phần phụ thuộc bằng cách yêu cầu thông tin của các phần phụ thuộc đó từ hệ thống đăng ký Bazel: cơ sở dữ liệu của các mô-đun Bazel. Hiện tại, Bzlmod chỉ hỗ trợ sổ đăng ký chỉ mục – các thư mục cục bộ hoặc máy chủ HTTP tĩnh tuân theo một định dạng cụ thể.

Sổ đăng ký chỉ mục

Sổ đăng ký chỉ mục là một thư mục cục bộ hoặc máy chủ HTTP tĩnh chứa thông tin về danh sách các mô-đun – bao gồm trang chủ, trình bảo trì, tệp MODULE.bazel của từng phiên bản và cách tìm nạp nguồn của từng phiên bản. Đáng chú ý là nó không cần tự phân phát các bản lưu trữ nguồn.

Sổ đăng ký chỉ mục phải tuân theo định dạng bên dưới:

  • /bazel_registry.json: Tệp JSON chứa siêu dữ liệu cho sổ đăng ký như:
    • mirrors: chỉ định danh sách bản sao để sử dụng cho bản lưu trữ nguồn
    • module_base_path: chỉ định đường dẫn cơ sở cho các mô-đun có loại local_repository trong tệp source.json
  • /modules: Thư mục chứa một thư mục con cho mỗi mô-đun trong hệ thống đăng ký này
  • /modules/$MODULE: Một thư mục chứa một thư mục con cho mỗi phiên bản của mô-đun này, cũng như:
    • metadata.json: Tệp JSON chứa thông tin về mô-đun với các trường sau đây:
      • homepage: URL trang chủ của dự án
      • maintainers: Danh sách các đối tượng JSON, mỗi đối tượng tương ứng với thông tin của trình bảo trì mô-đun trong sổ đăng ký. Xin lưu ý rằng giá trị này không nhất thiết giống với các tác giả của dự án
      • versions: Danh sách tất cả phiên bản của mô-đun này có trong sổ đăng ký này
      • yanked_versions: Bản đồ các phiên bản được kéo của mô-đun này. Các khoá phải là phiên bản để kéo và giá trị phải là nội dung mô tả lý do phiên bản bị giật, lý tưởng nhất là chứa một đường liên kết đến thông tin chi tiết hơn
  • /modules/$MODULE/$VERSION: Thư mục chứa các tệp sau:
    • MODULE.bazel: Tệp MODULE.bazel của phiên bản mô-đun này
    • source.json: Tệp JSON chứa thông tin về cách tìm nạp nguồn của phiên bản mô-đun này
      • Loại mặc định là "lưu trữ", đại diện cho một kho lưu trữ http_archive, với các trường sau đây:
        • url: URL của bản lưu trữ nguồn
        • integrity: Tổng kiểm tra Tính toàn vẹn của tài nguyên phụ của bản lưu trữ
        • strip_prefix: Tiền tố thư mục cần xoá khi trích xuất tệp lưu trữ nguồn
        • patches: Một bản đồ chứa các tệp bản vá để áp dụng cho kho lưu trữ được trích xuất. Các tệp bản vá nằm trong thư mục /modules/$MODULE/$VERSION/patches. Khoá là tên tệp bản vá và các giá trị là giá trị tổng kiểm tra tính toàn vẹn của các tệp bản vá
        • patch_strip: Giống như đối số --strip của patch trong Unix.
        • archive_type: Loại lưu trữ của tệp đã tải xuống (Giống như type trên http_archive). Theo mặc định, loại lưu trữ được xác định từ đuôi tệp của URL. Nếu tệp không có đuôi, bạn có thể chỉ định rõ một trong các phần sau: "zip", "jar", "war", "aar", "tar", "tar.gz", "tgz", "tar.xz", "txz", "tar.zst", "tzst", tar.bz2, "ar" hoặc "deb".
      • Bạn có thể thay đổi loại này để sử dụng đường dẫn cục bộ, đại diện cho một kho lưu trữ local_repository, với các trường sau:
        • type: local_path
        • path: Đường dẫn cục bộ đến kho lưu trữ, được tính như sau:
          • Nếu path là một đường dẫn tuyệt đối, thì đường dẫn này sẽ không thay đổi
          • Nếu path là đường dẫn tương đối và module_base_path là đường dẫn tuyệt đối, thì đường dẫn đó sẽ phân giải thành <module_base_path>/<path>
          • Nếu path và module_base_path đều là đường dẫn tương đối, thì giá trị này sẽ phân giải thành <registry_path>/<module_base_path>/<path>. Sổ đăng ký phải được lưu trữ cục bộ và được --registry=file://<registry_path> sử dụng. Nếu không, Bazel sẽ gửi ra lỗi
    • patches/: Thư mục không bắt buộc chứa các tệp bản vá, chỉ dùng khi source.json có loại "lưu trữ"

Hệ thống đăng ký trung tâm Bazel

Bazel Central Registry (BCR) tại https://bcr.bazel.build/ là một tổ chức đăng ký chỉ mục có nội dung được kho lưu trữ GitHub bazelbuild/bazel-central-registry hỗ trợ. Bạn có thể duyệt qua nội dung của thư viện bằng giao diện người dùng web tại https://registry.bazel.build/.

Cộng đồng Bazel duy trì BCR và những người đóng góp có thể gửi yêu cầu kéo. Xem nguyên tắc đóng góp cho BCR.

Ngoài việc tuân theo định dạng của sổ đăng ký chỉ mục thông thường, BCR cần có tệp presubmit.yml cho từng phiên bản mô-đun (/modules/$MODULE/$VERSION/presubmit.yml). Tệp này chỉ định một số mục tiêu bản dựng và kiểm thử thiết yếu mà bạn có thể dùng để kiểm tra tính hợp lệ của phiên bản mô-đun này. Quy trình CI của BCR cũng sử dụng quy trình này để đảm bảo khả năng tương tác giữa các mô-đun.

Chọn sổ đăng ký

Bạn có thể dùng cờ Bazel lặp lại --registry để chỉ định danh sách sổ đăng ký cần yêu cầu mô-đun. Nhờ đó, bạn có thể thiết lập dự án để tìm nạp các phần phụ thuộc từ sổ đăng ký nội bộ hoặc bên thứ ba. Các tổ chức quản lý tên miền trước đây được ưu tiên. Để thuận tiện, bạn có thể đưa danh sách các cờ --registry vào tệp .bazelrc của dự án.

Nếu sổ đăng ký của bạn được lưu trữ trên GitHub (ví dụ: dưới dạng một nhánh của bazelbuild/bazel-central-registry), thì giá trị --registry của bạn cần địa chỉ GitHub thô trong raw.githubusercontent.com. Ví dụ: trên nhánh main của nhánh phát triển my-org, bạn sẽ đặt --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/.

Việc sử dụng cờ --registry sẽ khiến Sổ đăng ký trung tâm Bazel ngừng sử dụng theo mặc định, nhưng bạn có thể thêm lại bằng cách thêm --registry=https://bcr.bazel.build.