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

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

Bazel 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ừ sổ đăng ký Bazel : cơ sở dữ liệu của các mô-đun Bazel. Bazel chỉ hỗ trợ một loại sổ đăng ký – sổ đăng ký chỉ mụ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ủ, người duy trì, tệp MODULE.bazel của mỗi phiên bản và cách tìm nạp nguồn của mỗi phiên bản. Đáng chú ý là sổ đăng ký này không cần tự phục vụ các kho lưu trữ nguồn.

Sổ đăng ký chỉ mục phải có định dạng sau:

  • /bazel_registry.json: Tệp JSON không bắt buộc chứa siêu dữ liệu cho sổ đăng ký.
  • /modules: Thư mục chứa một thư mục con cho mỗi mô-đun trong sổ đăng ký này
  • /modules/$MODULE: Thư mục chứa một thư mục con cho mỗi phiên bản của mô-đun có tên là $MODULE, cũng như tệp metadata.json chứa siêu dữ liệu cho mô-đun này.
  • /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. Xin lưu ý rằng đây là tệp MODULE.bazel được đọc trong quá trình phân giải phần phụ thuộc bên ngoài của Bazel, không phải tệp trong kho lưu trữ nguồn (trừ phi có một chế độ ghi đè không phải sổ đăng ký). Cũng xin lưu ý rằng bạn nên sử dụng tệp này để đặt phiên bản của bản phát hành và tránh làm như vậy trong tệp MODULE.bazel của kho lưu trữ nguồn. Để tìm hiểu thêm về việc kiểm soát phiên bản mô-đun, hãy xem Câu hỏi thường gặp.
    • 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
    • patches/: Thư mục không bắt buộc chứa các tệp bản vá, chỉ được dùng khi source.json có loại "archive"
    • overlay/: Thư mục không bắt buộc chứa các tệp lớp phủ, chỉ được dùng khi source.json có loại "archive"

bazel_registry.json

bazel_registry.json là một tệp không bắt buộc chỉ định siêu dữ liệu áp dụng cho toàn bộ sổ đăng ký. Tệp này có thể chứa các trường sau:

  • mirrors: một mảng các chuỗi, chỉ định danh sách các bản sao để sử dụng cho kho lưu trữ nguồn.
    • URL được sao chép là sự kết hợp của bản sao và URL nguồn của mô-đun được chỉ định bởi tệp source.json của mô-đun đó mà không có giao thức. Ví dụ: nếu URL nguồn của một mô-đun là https://foo.com/bar/baz, và mirrors chứa ["https://mirror1.com/", "https://example.com/mirror2/"], thì các URL mà Bazel sẽ thử theo thứ tự là https://mirror1.com/foo.com/bar/baz, https://example.com/mirror2/foo.com/bar/baz, và cuối cùng là URL nguồn gốc https://foo.com/bar/baz.
  • module_base_path: một chuỗi, chỉ định đường dẫn cơ sở cho các mô-đun có loại local_path trong tệp source.json

metadata.json

metadata.json là một tệp JSON không bắt buộc chứa thông tin về mô-đun, với các trường sau:

  • versions: Một mảng các chuỗi, mỗi chuỗi biểu thị một phiên bản của mô-đun có trong sổ đăng ký này. Mảng này phải khớp với các phần tử con của thư mục mô-đun.
  • yanked_versions: Đối tượng JSON chỉ định các phiên bản đã rút lại của mô-đun này. Khoá phải là các phiên bản cần rút lại và giá trị phải là nội dung mô tả lý do rút lại phiên bản đó, lý tưởng nhất là chứa một đường liên kết đến thông tin khác.

Xin lưu ý rằng BCR yêu cầu thêm thông tin trong tệp metadata.json.

source.json

source.json là một tệp JSON bắt buộc chứa thông tin về cách tìm nạp một phiên bản cụ thể của mô-đun. Lược đồ của tệp này phụ thuộc vào trường type, mặc định là archive.

  • Nếu type là archive (mặc định), thì phiên bản mô-đun này được hỗ trợ bởi quy tắc kho lưu trữ http_archive; phiên bản này được tìm nạp bằng cách tải một kho lưu trữ xuống từ một URL nhất định và trích xuất nội dung của kho lưu trữ đó. Tệp này hỗ trợ các trường sau:
    • url: Một chuỗi, URL của kho lưu trữ nguồn
    • mirror_urls: Danh sách chuỗi, URL bản sao của kho lưu trữ nguồn. Các URL được thử theo thứ tự sau url dưới dạng bản sao lưu.
    • integrity: Một chuỗi, tổng kiểm tra Tính toàn vẹn Tài nguyên phụ của kho lưu trữ
    • strip_prefix: Một chuỗi, tiền tố thư mục cần loại bỏ khi trích xuất kho lưu trữ nguồn
    • overlay: Đối tượng JSON chứa các tệp lớp phủ để xếp lớp trên kho lưu trữ đã trích xuất. Các tệp bản vá nằm trong thư mục /modules/$MODULE/$VERSION/overlay. Khoá là tên tệp lớp phủ và giá trị là tổng kiểm tra tính toàn vẹn của các tệp lớp phủ. Các lớp phủ được áp dụng trước các tệp bản vá.
    • patches: Đối tượng JSON chứa các tệp bản vá để áp dụng cho kho lưu trữ đã 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à giá trị là tổng kiểm tra tính toàn vẹn của các tệp bản vá. Các bản vá được áp dụng sau các tệp lớp phủ và theo thứ tự xuất hiện trong patches.
    • patch_strip: Một số; giống như đối số --strip của Unix patch.
    • archive_type: Một chuỗi, loại kho lưu trữ của tệp đã tải xuống (Giống như type trên http_archive).
  • Nếu type là git_repository, thì phiên bản mô-đun này được hỗ trợ bởi quy tắc kho lưu trữ git_repository; phiên bản này được tìm nạp bằng cách sao chép một kho lưu trữ Git.
    • Các trường sau được hỗ trợ và được chuyển tiếp trực tiếp đến quy tắc kho lưu trữ git_repository cơ bản: remote, commit, shallow_since, tag, init_submodules, verbose, và strip_prefix.
  • Nếu type là local_path, thì phiên bản mô-đun này được hỗ trợ bởi quy tắc kho lưu trữ local_repository; phiên bản này được liên kết tượng trưng với một thư mục trên đĩa cục bộ. Tệp này hỗ trợ trường sau: trường:
    • path: Đường dẫn cục bộ đến kho lưu trữ, được tính như sau:
      • Nếu path là đường dẫn tuyệt đối, thì đường dẫn này vẫn giữ nguyên
      • 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 này 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ì đường dẫn 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 sử dụng bởi --registry=file://<registry_path>. Nếu không, Bazel sẽ đưa ra lỗi

Sổ đăng ký trung tâm Bazel

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

Cộng đồng Bazel duy trì BCR và người đóng góp có thể gửi yêu cầu kéo. Xem hướng dẫn đóng góp cho BCR guidelines.

Ngoài việc tuân theo định dạng của sổ đăng ký chỉ mục thông thường, BCR yêu cầu tệp presubmit.yml cho mỗi phiên bản mô-đun (/modules/$MODULE/$VERSION/presubmit.yml). Tệp này chỉ định một vài mục tiêu kiểm thử và bản dựng 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. Các quy trình CI của BCR cũng sử dụng tệp 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ể sử dụng cờ Bazel có thể 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 của bên thứ ba. Các sổ đăng ký trước đó sẽ được ưu tiên. Để thuận tiện, bạn có thể đặt danh sách các cờ --registry trong 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ần có địa chỉ GitHub thô trong raw.githubusercontent.com. Ví dụ: trên main nhánh của my-org nhánh, bạn sẽ đặt --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/.

Việc sử dụng cờ --registry sẽ ngăn không cho Sổ đăng ký trung tâm Bazel được 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.