Chương trình đăng ký tham gia sự kiện BazelCon 2024 đã bắt đầu!

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

Quy tắc cho nền tảng và chuỗi công cụ

Báo cáo sự cố Xem nguồn Hằng đêm · 7,3 · 7.2 · 7.1 · 7 · 6,5

Bộ quy tắc này tồn tại để cho phép bạn lập mô hình các nền tảng phần cứng cụ thể mà bạn đang sử dụng tạo và chỉ định các công cụ cụ thể mà bạn có thể cần để biên dịch mã cho các nền tảng đó. Người dùng cần làm quen với các khái niệm được giải thích tại đây.

constraint_setting

Xem nguồn quy tắc

constraint_setting(name, default_constraint_value, deprecation, distribs, features, licenses, tags, testonly, visibility)

Quy tắc này dùng để ra mắt một loại quy tắc ràng buộc mới mà nền tảng có thể chỉ định một giá trị. Ví dụ: bạn có thể xác định một constraint_setting có tên là "glibc_version" để biểu thị khả năng cài đặt các phiên bản khác nhau của thư viện glibc cho các nền tảng. Để biết thêm chi tiết, hãy xem Trang Nền tảng.

Mỗi constraint_setting có một tập hợp các liên kết có thể mở rộng constraint_value giây. Thông thường các thành phần này được xác định trong cùng một gói, nhưng đôi khi gói khác sẽ giới thiệu các giá trị mới cho cài đặt hiện có. Ví dụ: giá trị xác định trước bạn có thể mở rộng tùy chọn cài đặt @platforms//cpu:cpu bằng một giá trị tùy chỉnh để xác định một nền tảng nhắm mục tiêu đến một kiến trúc cpu ít người biết đến.

Đối số

Thuộc tính

name

Tên; bắt buộc

Tên duy nhất cho mục tiêu này.

default_constraint_value

Tên; không thể định cấu hình; giá trị mặc định là None

Nhãn của giá trị mặc định cho chế độ cài đặt này và sử dụng nếu không có giá trị nào được cung cấp. Nếu trường hợp này đã tồn tại, constraint_value mà nó trỏ đến phải được xác định trong giống như constraint_setting này.

Nếu một chế độ cài đặt ràng buộc có giá trị mặc định, thì bất cứ khi nào một nền tảng không có giá trị này bất kỳ giá trị ràng buộc nào cho chế độ cài đặt đó, thì cũng giống như khi nền tảng đã chỉ định giá trị mặc định. Còn nếu không có giá trị mặc định, thì chế độ cài đặt ràng buộc sẽ được xem xét không được nền tảng đó chỉ định. Trong trường hợp đó, nền tảng sẽ không khớp với bất kỳ danh sách quy tắc ràng buộc (chẳng hạn như config_setting) yêu cầu một giá trị cụ thể cho chế độ cài đặt đó.

constraint_value

Xem nguồn quy tắc

constraint_value(name, constraint_setting, deprecation, distribs, features, licenses, tags, testonly, visibility)

Quy tắc này áp dụng một giá trị mới cho một loại quy tắc ràng buộc nhất định. Để biết thêm chi tiết, hãy xem Trang Nền tảng.

Ví dụ:

Thao tác sau sẽ tạo ra một giá trị mới có thể có cho constraint_value được xác định trước biểu thị cấu trúc CPU.

constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)

Sau đó, các nền tảng có thể khai báo rằng chúng có cấu trúc mips thay thế cho x86_64, arm, v.v.

Đối số

Thuộc tính

name

Tên; bắt buộc

Tên duy nhất cho mục tiêu này.

constraint_setting

Nhãn; không thể định cấu hình; bắt buộc

constraint_setting mà constraint_value này là một lựa chọn có thể có.

platform

Xem nguồn quy tắc

platform(name, constraint_values, deprecation, distribs, exec_properties, features, licenses, parents, remote_execution_properties, tags, testonly, visibility)

Quy tắc này xác định một nền tảng mới – tập hợp các lựa chọn quy tắc ràng buộc được đặt tên (chẳng hạn như kiến trúc cpu hoặc phiên bản trình biên dịch) mô tả một môi trường trong phần nào của bản dựng có thể chạy. Để biết thêm thông tin chi tiết, hãy xem trang Nền tảng.

Ví dụ:

Định nghĩa này định nghĩa một nền tảng mô tả mọi môi trường chạy Linux trên ARM.

platform(
    name = "linux_arm",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

Tính kế thừa của nền tảng

Các nền tảng có thể sử dụng thuộc tính parents để chỉ định một nền tảng khác mà họ sẽ kế thừa các giá trị ràng buộc từ đó. Mặc dù thuộc tính parents lấy danh sách, nhưng không hiện có nhiều hơn một giá trị đơn lẻ được hỗ trợ và việc chỉ định nhiều giá trị gốc là một lỗi.

Khi kiểm tra giá trị của một chế độ cài đặt quy tắc ràng buộc trong một nền tảng, trước tiên, các giá trị được đặt trực tiếp (thông qua thuộc tính constraint_values) được kiểm tra, sau đó các giá trị ràng buộc trên phần tử mẹ. Thao tác này tiếp tục đệ quy lên chuỗi các nền tảng mẹ. Bằng cách này, bất kỳ các giá trị được thiết lập trực tiếp trên một nền tảng sẽ ghi đè các giá trị được thiết lập trong đơn vị quảng cáo mẹ.

Nền tảng kế thừa thuộc tính exec_properties của nền tảng mẹ. Các mục từ điển trong exec_properties của nền tảng mẹ và nền tảng con sẽ được kết hợp. Nếu có cùng một khoá xuất hiện trong cả exec_properties của nhà xuất bản mẹ và nhà xuất bản con, giá trị của phần tử con sẽ được sử dụng. Nếu nền tảng con chỉ định một chuỗi trống làm giá trị, thì thuộc tính tương ứng sẽ bị huỷ đặt.

Các nền tảng cũng có thể kế thừa thuộc tính remote_execution_properties (không dùng nữa) từ nền tảng gốc. Lưu ý: mã mới sẽ sử dụng exec_properties. Chiến lược phát hành đĩa đơn logic mô tả bên dưới được duy trì để tương thích với hành vi cũ nhưng sẽ bị xoá trong tương lai. Logic để đặt remote_execution_platform như sau khi có là nền tảng gốc:

Nếu remote_execution_property không được thiết lập trên nền tảng con, thì remote_execution_properties sẽ được dùng.
Nếu remote_execution_property được đặt trên nền tảng con và chứa chuỗi ký tự {PARENT_REMOTE_EXECUTION_PROPERTIES}, macro đó sẽ là được thay thế bằng nội dung của thuộc tính mẹ remote_execution_property.
Nếu remote_execution_property được đặt trên nền tảng con và không chứa thì remote_execution_property của thành phần con sẽ được dùng không thay đổi.

Vì remote_execution_properties không được dùng nữa và sẽ bị loại bỏ, nên việc kết hợp remote_execution_properties và exec_properties trong cùng một thiết bị chuỗi kế thừa. Muốn sử dụng exec_properties thay vì những giá trị không dùng nữa remote_execution_properties.

Ví dụ: Giá trị ràng buộc

platform(
    name = "parent",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)
platform(
    name = "child_a",
    parents = [":parent"],
    constraint_values = [
        "@platforms//cpu:x86_64",
    ],
)
platform(
    name = "child_b",
    parents = [":parent"],
)

Trong ví dụ này, các nền tảng con có các thuộc tính sau:

child_a có các giá trị ràng buộc @platforms//os:linux (kế thừa từ cấp độ gốc) và @platforms//cpu:x86_64 (được đặt trực tiếp trên nền tảng).
child_b kế thừa mọi giá trị ràng buộc từ cấp độ gốc và không đặt bất kỳ giá trị nào của chính nó.

Ví dụ: Thuộc tính thực thi

platform(
    name = "parent",
    exec_properties = {
      "k1": "v1",
      "k2": "v2",
    },
)
platform(
    name = "child_a",
    parents = [":parent"],
)
platform(
    name = "child_b",
    parents = [":parent"],
    exec_properties = {
      "k1": "child"
    }
)
platform(
    name = "child_c",
    parents = [":parent"],
    exec_properties = {
      "k1": ""
    }
)
platform(
    name = "child_d",
    parents = [":parent"],
    exec_properties = {
      "k3": "v3"
    }
)

Trong ví dụ này, các nền tảng con có các thuộc tính sau:

child_a kế thừa "exec_properties" của thành phần mẹ và không đặt giá trị của chính nó.
child_b kế thừa exec_properties của thành phần mẹ và ghi đè phương thức giá trị của k1. exec_properties của thành phần này sẽ là: { "k1": "child", "k2": "v2" }.
child_c kế thừa exec_properties của nhà xuất bản mẹ nhưng không đặt k1. exec_properties của thành phần này sẽ là: { "k2": "v2" }.
child_d kế thừa exec_properties của nhà xuất bản mẹ và thêm một phương thức mới thuộc tính này. exec_properties của thành phần này sẽ là: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Đối số

Thuộc tính
`name`	Tên; bắt buộc Tên duy nhất cho mục tiêu này.
`constraint_values`	Danh sách nhãn; không thể định cấu hình; giá trị mặc định là `[]` Sự kết hợp của các lựa chọn ràng buộc mà nền tảng này bao gồm. Để đảm bảo một nền tảng để áp dụng cho một môi trường nhất định, môi trường phải có ít nhất giá trị trong danh sách này. Mỗi `constraint_value` trong danh sách này phải dành cho một `constraint_setting`. Ví dụ: bạn không thể xác định một nền tảng yêu cầu cấu trúc cpu ở cả `@platforms//cpu:x86_64` và `@platforms//cpu:arm`.
`exec_properties`	Từ điển: Chuỗi -> String; không thể định cấu hình; giá trị mặc định là `{}` Sơ đồ liên kết các chuỗi ảnh hưởng đến cách thực thi các thao tác từ xa. Bazel không cố gắng để diễn giải điều này, dữ liệu này được coi là dữ liệu mờ được chuyển tiếp qua trường Nền tảng của giao thức thực thi từ xa. Dữ liệu này bao gồm mọi dữ liệu từ các thuộc tính `exec_properties` của nền tảng gốc. Nếu nền tảng con và nền tảng mẹ xác định các khoá giống nhau, thì các giá trị của nền tảng con sẽ được giữ lại. Bất kỳ hạng nào các khoá liên kết với một giá trị là chuỗi trống sẽ bị xoá khỏi từ điển. Thuộc tính này thay thế hoàn toàn cho thuộc tính không dùng nữa `remote_execution_properties`.
`parents`	Danh sách nhãn; không thể định cấu hình; giá trị mặc định là `[]` Nhãn của mục tiêu `platform` mà nền tảng này cần kế thừa. Mặc dù thuộc tính này sẽ nhận một danh sách, nên chỉ được có tối đa một nền tảng. Bất kỳ hạng nào Bạn có thể tìm thấy Constraintt_settings không được thiết lập trực tiếp trên nền tảng này trong nền tảng mẹ. Hãy xem phần Tính kế thừa của nền tảng để biết thông tin chi tiết.
`remote_execution_properties`	String; không thể định cấu hình; giá trị mặc định là `""` ĐÃ NGỪNG HOẠT ĐỘNG. Thay vào đó, vui lòng sử dụng thuộc tính exec_properties. Một chuỗi dùng để định cấu hình nền tảng thực thi từ xa. Các bản dựng thực tế không cố gắng diễn giải điều này thì nó được coi là dữ liệu mờ mà một SpawnRunner cụ thể có thể sử dụng. Dữ liệu này có thể bao gồm dữ liệu từ "remote_execution_properties" của nền tảng gốc phân bổ, bằng cách sử dụng macro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Xem phần này trên Bài viết Kế thừa nền tảng để biết thông tin chi tiết.

chuỗi công cụ

Xem nguồn quy tắc

toolchain(name, deprecation, distribs, exec_compatible_with, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, visibility)

Quy tắc này khai báo loại chuỗi công cụ cụ thể và các điều kiện ràng buộc để bạn có thể chọn chuỗi công cụ trong quá trình phân giải chuỗi công cụ. Xem Trang Chuỗi công cụ để tìm hiểu thêm chi tiết.

Đối số

Thuộc tính
`name`	Tên; bắt buộc Tên duy nhất cho mục tiêu này.
`exec_compatible_with`	Danh sách nhãn; không thể định cấu hình; giá trị mặc định là `[]` Danh sách `constraint_value` mà nền tảng thực thi phải đáp ứng trong để chọn chuỗi công cụ này cho một toà nhà mục tiêu trên nền tảng đó.
`target_compatible_with`	Danh sách nhãn; không thể định cấu hình; giá trị mặc định là `[]` Danh sách các `constraint_value` mà nền tảng mục tiêu phải đáp ứng trong để chọn chuỗi công cụ này cho một bản dựng mục tiêu cho nền tảng đó.
`target_settings`	Danh sách nhãn; giá trị mặc định là `[]` Danh sách các `config_setting` mà cấu hình mục tiêu phải đáp ứng để chọn chuỗi công cụ này trong quá trình phân giải chuỗi công cụ.
`toolchain`	Tên; bắt buộc Mục tiêu đại diện cho bộ công cụ hoặc bộ công cụ thực tế được cung cấp khi chuỗi công cụ được chọn.
`toolchain_type`	Nhãn; không thể định cấu hình; bắt buộc Nhãn của mục tiêu `toolchain_type` thể hiện vai trò của chuỗi công cụ phân phát.

toolchain_type

Xem nguồn quy tắc

toolchain_type(name, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

Quy tắc này xác định một loại chuỗi công cụ mới -- một mục tiêu đơn giản đại diện cho một lớp công cụ đều đóng vai trò như nhau cho các nền tảng khác nhau.

Hãy xem trang Chuỗi công cụ để biết thêm thông tin chi tiết.

Ví dụ:

Thao tác này xác định loại chuỗi công cụ cho quy tắc tuỳ chỉnh.

toolchain_type(
    name = "bar_toolchain_type",
)

Bạn có thể dùng mục này trong tệp bzl.

bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        # No `_compiler` attribute anymore.
    },
    toolchains = ["//bar_tools:toolchain_type"]
)

Đối số

Thuộc tính

name

Tên; bắt buộc

Tên duy nhất cho mục tiêu này.