Để xem tài liệu về bản phát hành ổn định, vui lòng sử dụng trình đơn thả xuống "Tài liệu được tạo phiên bản". Chế độ xem mặc định phản ánh phiên bản mới nhất ở HEAD.

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

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

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

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 xây dựng 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 phải quen thuộc với các khái niệm được giải thích tại đây.

cài đặt_quy tắc ràng buộc

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 để giới thiệu một loại quy tắc ràng buộc mới mà một 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" để cho biết khả năng các nền tảng có cài đặt các phiên bản khác nhau của thư viện glibc. Để biết thêm thông tin, hãy xem trang Nền tảng.

Mỗi constraint_setting có một tập hợp constraint_value được mở rộng. Thông thường, các gói này được xác định trong cùng một gói, nhưng đôi khi một gói khác sẽ đưa ra các giá trị mới cho cài đặt hiện có. Ví dụ: bạn có thể mở rộng chế độ cài đặt định sẵn @platforms//cpu:cpu bằng một giá trị tuỳ chỉnh để xác định nền tảng nhắm đến một cấu trúc cpu che khuất.

Đối số

Thuộc tính

name

Name; required

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

default_constraint_value

Name; optional; nonconfigurable

Nhãn của giá trị mặc định cho cài đặt này, được sử dụng nếu không có giá trị nào được cung cấp. Nếu có thuộc tính này, constraint_value mà nó trỏ đến phải được xác định trong cùng một gói với 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ị 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. Ngược lại, nếu không có giá trị mặc định thì chế độ cài đặt ràng buộc này sẽ được nền tảng xem là chưa xác định. Trong trường hợp đó, nền tảng sẽ không khớp với bất kỳ danh sách ràng buộc nào (chẳng hạn như đối với config_setting) yêu cầu một giá trị cụ thể cho chế độ cài đặt đó.

ràng buộc_giá trị

Xem nguồn quy tắc

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

Quy tắc này giới thiệu 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 thông tin, hãy xem trang Nền tảng.

Ví dụ:

Sau đây là một giá trị mới có thể có cho cấu trúc CPU đại diện constraint_value được xác định trước.

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

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

Name; required

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

constraint_setting

Label; required; nonconfigurable

constraint_setting mà constraint_value này có thể là một lựa chọn có thể áp dụng.

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 – một tập hợp các lựa chọn 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 mà phần nào của bản dựng có thể chạy. Để biết thêm thông tin, hãy xem trang Nền tảng.

Ví dụ:

Điều này xác định một nền tảng mô tả bất kỳ môi trường nào chạy Linux trên ARM.

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

Kế thừ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à các nền tảng đó sẽ kế thừa các giá trị ràng buộc. Mặc dù thuộc tính parents lấy một danh sách, nhưng hiện không hỗ trợ nhiều giá trị và việc chỉ định nhiều giá trị mẹ là một lỗi.

Khi kiểm tra giá trị của một chế độ cài đặt ràng buộc trong một nền tảng, trước tiên các giá trị ràng buộc trực tiếp được đặt (thông qua thuộc tính constraint_values) sẽ được đánh dấu, sau đó là các giá trị ràng buộc trên mẹ. Quá trình này tiếp tục định kỳ theo chuỗi các nền tảng mẹ. Bằng cách này, mọi giá trị được đặt trực tiếp trên nền tảng sẽ ghi đè các giá trị được đặt trên nền tảng mẹ.

Các nền tảng kế thừa thuộc tính exec_properties từ nền tảng mẹ. Các mục trong từ điển thuộc exec_properties của nền tảng mẹ và nền tảng con sẽ được kết hợp. Nếu cùng một khoá xuất hiện trong cả exec_properties của thành phần mẹ và thành phần con thì giá trị của thành phần 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ẽ không được đặ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 mẹ. Lưu ý: mã mới nên sử dụng exec_properties. Logic mô tả dưới đây đượ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ó nền tảng mẹ:

Nếu bạn không đặt remote_execution_property trên nền tảng con, thì remote_execution_properties của cha mẹ sẽ được sử 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_EDITcutION_PROPERTIES}, thì macro đó sẽ được thay thế bằng nội dung trong thuộc tính remote_execution_property của thành phần mẹ.
Nếu remote_execution_property được đặt trên nền tảng con và không chứa macro, thì remote_execution_property con sẽ không được sử dụng.

Vì remote_execution_properties không được dùng nữa và sẽ bị loại bỏ, nên chúng tôi không cho phép kết hợp remote_execution_properties và exec_properties trong cùng một chuỗi kế thừa. Ưu tiên sử dụng exec_properties hơn remote_execution_properties không dùng nữa.

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ừ thành phần mẹ) và @platforms//cpu:x86_64 (được đặt trực tiếp trên nền tảng).
child_b thừa hưởng tất cả các giá trị ràng buộc từ mẹ và không đặt bất kỳ giá trị riêng nào.

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 thừa hưởng "exec_properties" của mẹ và không đặt giá trị riêng.
child_b kế thừa exec_properties của lớp mẹ và ghi đè giá trị của k1. exec_properties của lớp này sẽ là: { "k1": "child", "k2": "v2" }.
child_c kế thừa exec_properties của cha mẹ và bỏ k1. exec_properties của lớp này sẽ là: { "k2": "v2" }.
child_d kế thừa exec_properties của mẹ và thêm một thuộc tính mới. exec_properties của lớp này sẽ là: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Đối số

Thuộc tính
`name`	`Name; required` Tên duy nhất cho mục tiêu này.
`constraint_values`	`List of labels; optional; nonconfigurable` Sự kết hợp các lựa chọn ràng buộc mà nền tảng này bao gồm. Để 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 các 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` khác nhau. Ví dụ: bạn không thể xác định nền tảng yêu cầu cấu trúc cpu cả ở `@platforms//cpu:x86_64` và `@platforms//cpu:arm`.
`exec_properties`	`Dictionary: String -> String; optional` Một bản đồ các chuỗi ảnh hưởng đến cách thực thi các hành động từ xa. Bazel không cố gắng diễn giải điều này, nó đượ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ừ thuộc tính `exec_properties` của nền tảng mẹ. Nếu nền tảng con và nền tảng mẹ xác định cùng một khoá, thì các giá trị của khoá con sẽ được giữ lại. Mọi khoá liên kết với một giá trị là một chuỗi trống sẽ bị xoá khỏi từ điển. Thuộc tính này là sự thay thế hoàn toàn cho `remote_execution_properties` không dùng nữa.
`parents`	`List of labels; optional; nonconfigurable` Nhãn của mục tiêu `platform` mà nền tảng này sẽ kế thừa. Mặc dù thuộc tính này lấy danh sách, nhưng không được có nhiều nền tảng. Bạn có thể tìm thấy mọi constraint_settings không được đặt trực tiếp trên nền tảng này trong nền tảng mẹ. Xem mục Kế thừa nền tảng để biết thông tin chi tiết.
`remote_execution_properties`	`String; optional` ĐÃ NGỪNG HOẠT ĐỘNG. Thay vào đó, hãy 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, nó được coi là dữ liệu mờ mà một SpawnRunner cụ thể có thể sử dụng. Trong đó có thể bao gồm dữ liệu từ thuộc tính "remote_execution_properties" của nền tảng mẹ, bằng cách sử dụng macro "{Parent_REMOTE_EDITcutION_PROPERTIES}". Vui lòng xem phần 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 một loại chuỗi công cụ và các quy tắc ràng buộc cụ thể để bạn có thể chọn loại quy trình đó trong quá trình phân giải chuỗi công cụ. Xem trang Chuỗi công cụ để biết thêm thông tin chi tiết.

Đối số

Thuộc tính
`name`	`Name; required` Tên duy nhất cho mục tiêu này.
`exec_compatible_with`	`List of labels; optional; nonconfigurable` Danh sách `constraint_value` phải được nền tảng thực thi đáp ứng để chuỗi công cụ này được chọn cho mục tiêu tạo bản dựng trên nền tảng đó.
`target_compatible_with`	`List of labels; optional; nonconfigurable` Danh sách `constraint_value` phải được nền tảng mục tiêu đáp ứng để chuỗi công cụ này được chọn cho một bản dựng mục tiêu cho nền tảng đó.
`target_settings`	`List of labels; optional` Danh sách `config_setting` phải được cấu hình mục tiêu đáp ứng để có thể chọn chuỗi công cụ này trong quá trình phân giải chuỗi công cụ.
`toolchain`	`Name; required` Mục tiêu thể hiệ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ụ này được chọn.
`toolchain_type`	`Label; required; nonconfigurable` Nhãn của mục tiêu `toolchain_type` đại diện cho vai trò của chuỗi công cụ này.

chuỗi_công_cụ

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ụ đóng vai trò tương tự đối với các nền tảng khác nhau.

Xem trang Chuỗi công cụ để biết thêm chi tiết.

Ví dụ:

Quy 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ể sử dụng tính năng 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

Name; required

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