Tập hợp quy tắc này tồn tại để cho phép bạn mô hình hoá 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 cần phải làm quen với các khái niệm được giải thích ở đây.
Quy tắc
constraint_setting
Xem nguồn quy tắcconstraint_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 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ác nền tảng có thể 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 chi tiết, hãy xem trang
Nền tảng.
Mỗi constraint_setting có một tập hợp có thể mở rộng gồm các
constraint_value được liên kết. Thông thường, các giá trị này được xác định trong cùng một gói, nhưng đôi khi một
gói khác sẽ giới thiệu các giá trị mới cho một chế độ cài đặt hiện có. Ví dụ: bạn có thể mở rộng chế độ cài đặt được xác định trước
@platforms//cpu:cpu bằng một giá trị tuỳ 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 không rõ ràng.
Đố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; mặc định là constraint_value mà thuộc tính này trỏ đến phải được xác định trong cùng một gói với constraint_setting.
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 bao gồm
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. Nếu không có giá trị mặc định, thì chế độ cài đặt ràng buộc được coi là
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 ràng buộc nào (chẳng hạn như đối với |
constraint_value
Xem nguồn quy tắcconstraint_value(name, constraint_setting, deprecation, distribs, features, licenses, tags, testonly, visibility)
Ví dụ:
Sau đây sẽ tạo một giá trị mới có thể có cho constraint_value
được xác định trước, đại diện cho kiến trúc CPU.
constraint_value(
name = "mips",
constraint_setting = "@platforms//cpu:cpu",
)
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_setting mà constraint_value này là một lựa chọn có thể có.
|
nền tảng
Xem nguồn quy tắcplatform(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ó tên gồm các lựa chọn ràng buộc (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à một phần 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ụ:
Điều này xác định 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",
],
)
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à chú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 tại chỉ hỗ trợ một giá trị duy nhất và việc chỉ định nhiều mục 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ị được đặt trực tiếp
(thông qua thuộc tính constraint_values) sẽ được kiểm tra, sau đó là các giá trị ràng buộc trên
mục mẹ. Quá trình này tiếp tục đệ quy lên chuỗi nền tảng mẹ. Theo cách này, mọi
giá trị được đặt trực tiếp trên một nền tảng sẽ ghi đè các giá trị được đặt trên mục 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 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ùng một khoá xuất hiện trong cả exec_properties của mục mẹ và mục con,
thì giá trị của mục 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 thay thế. Logic được 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ó
nền tảng mẹ:
-
Nếu
remote_execution_propertykhông được đặt trên nền tảng con, thìremote_execution_propertiescủa mục 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_EXECUTION_PROPERTIES}, thì macro đó sẽ được thay thế bằng nội dung của thuộc tínhremote_execution_propertycủa mục mẹ. -
Nếu
remote_execution_propertyđược đặt trên nền tảng con và không chứa macro, thìremote_execution_propertycủa mục con sẽ được sử dụng mà không thay đổi.
Vì remote_execution_properties không dùng nữa và sẽ bị loại bỏ dần, nên bạn không được phép kết hợp
remote_execution_properties và exec_properties trong cùng một
chuỗi kế thừa.
Bạn nên sử dụng exec_properties thay vì
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_acó các giá trị ràng buộc@platforms//os:linux(kế thừa từ mục mẹ) và@platforms//cpu:x86_64(được đặt trực tiếp trên nền tảng). -
child_bkế thừa tất cả các giá trị ràng buộc từ mục mẹ và không đặt bất kỳ giá trị nào của riêng mình.
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_akế thừa "exec_properties" của mục mẹ và không đặt thuộc tính riêng. -
child_bkế thừaexec_propertiescủa mục mẹ và ghi đè giá trị củak1.exec_propertiescủa nó sẽ là:{ "k1": "child", "k2": "v2" }. -
child_ckế thừaexec_propertiescủa mục mẹ và không đặtk1.exec_propertiescủa nó sẽ là:{ "k2": "v2" }. -
child_dkế thừaexec_propertiescủa mục mẹ và thêm một thuộc tính mới.exec_propertiescủa nó 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; mặc định là Mỗi |
exec_properties
|
Từ điển: Chuỗi -> Chuỗi; không thể định cấu hình; mặc định là 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 nền tảng con sẽ được giữ lại. Mọi
khoá được liên kết với một giá trị là chuỗi trống đều bị xoá khỏi từ điển.
Thuộc tính này là một sự thay thế hoàn toàn cho
không dùng nữaremote_execution_properties.
|
parents
|
Danh sách nhãn; không thể định cấu hình; mặc định là platform mà nền tảng này sẽ kế thừa. Mặc dù
thuộc tính này lấy một danh sách, nhưng không được có nhiều hơn một nền tảng. Mọi
constraint_settings không được đặt trực tiếp trên nền tảng này sẽ được tìm thấy trong nền tảng mẹ.
Hãy xem phần về Kế thừa nền tảng để biết thông tin chi tiết.
|
remote_execution_properties
|
Chuỗi; không thể định cấu hình; mặc định là |
toolchain
Xem nguồn quy tắctoolchain(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 và các ràng buộc của một chuỗi công cụ cụ thể để có thể chọn trong quá trình phân giải chuỗi công cụ. Hãy xem trang Chuỗi công cụ để biết thêm thông tin 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; mặc định là constraint_value mà nền tảng thực thi phải đáp ứng để chuỗi công cụ này được chọn cho một bản dựng 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; mặc định là constraint_value mà nền tảng mục tiêu phải đá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
|
Danh sách nhãn; mặc định là config_setting mà cấu hình mục tiêu phải đáp ứng
để chuỗi công cụ này được chọn 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 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
|
Nhãn; không thể định cấu hình; bắt buộc Nhãn của mục tiêutoolchain_type đại diện cho vai trò mà chuỗi công cụ này
phục vụ.
|
toolchain_type
Xem nguồn quy tắctoolchain_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ụ có cùng vai trò 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ụ:
Điều này xác định một loại chuỗi công cụ cho một quy tắc tuỳ chỉnh.
toolchain_type(
name = "bar_toolchain_type",
)
Bạn có thể sử dụng điều 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. |