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,0 · 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.

Quy tắc

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 tí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 đó, nền tảng có thể khai báo rằng chúng có kiến trúc mips thay thế cho x86_64, arm, v.v.

Đối số

Thuộc tí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_settingconstraint_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, flags, licenses, parents, remote_execution_properties, required_settings, 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",
    ],
)

Cờ trên nền tảng

Nền tảng có thể dùng thuộc tính flags để chỉ định danh sách các cờ sẽ được thêm cho cấu hình bất cứ khi nào nền tảng được sử dụng làm nền tảng mục tiêu (tức là cờ --platforms).

Cờ được đặt từ nền tảng có mức độ ưu tiên cao nhất và sẽ ghi đè mọi cờ trước đó cho cờ đó, từ dòng lệnh, tệp rc hoặc chuyển đổi.

Ví dụ:

platform(
    name = "foo",
    flags = [
        "--dynamic_mode=fully",
        "--//bool_flag",
        "--no//package:other_bool_flag",
    ],
)

Thao tác này xác định một nền tảng có tên là foo. Khi đây là nền tảng mục tiêu (vì người dùng đã chỉ định --platforms//:foo vì một hiệu ứng chuyển đổi sẽ thiết lập //command_line_option:platforms gắn cờ thành ["//:foo"] hoặc vì //:foo được dùng làm nền tảng thực thi), sau đó các cờ đã cho sẽ được đặt trong .

Nền tảng và cờ lặp lại

Một số cờ sẽ tích luỹ các giá trị khi được lặp lại, chẳng hạn như --features, --copt, bất kỳ cờ Starlark nào được tạo dưới dạng config.string(repeatable = True). Những cờ này không tương thích với việc đặt cờ từ nền tảng: thay vào đó, tất cả cờ trước đó sẽ bị loại bỏ và ghi đè bằng các giá trị từ nền tảng.

Ví dụ: với nền tảng sau, lệnh gọi build --platforms=//:repeat_demo --features feature_a --features feature_b sẽ kết thúc bằng giá trị của Cờ --feature["feature_c", "feature_d"], sẽ xoá các tính năng này được thiết lập trên dòng lệnh.

platform(
    name = "repeat_demo",
    flags = [
        "--features=feature_c",
        "--features=feature_d",
    ],
)

Vì lý do này, bạn không nên sử dụng cờ có thể lặp lại trong thuộc tính flags.

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:

  1. 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.
  2. Nếu remote_execution_property được đặt trên nền tảng con và chứa chuỗi {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.
  3. 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.

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_propertiesexec_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 tí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@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.
flags

Danh sách các chuỗi; không thể định cấu hình; giá trị mặc định là []

Danh sách cờ sẽ được bật khi nền tảng này được dùng làm nền tảng mục tiêu trong một cấu hình. Bạn chỉ được phép sử dụng những cờ có thể đặt trong hiệu ứng chuyển đổi.
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.
required_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 để nền tảng này có thể được sử dụng làm nền tảng thực thi trong quá trình phân giải chuỗi công cụ. Các chế độ cài đặt bắt buộc không được kế thừa từ các nền tảng gốc.

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 tí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 tính
name

Tên; bắt buộc

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