Bộ 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 nên 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 được 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à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; giá trị 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, nếu không có giá trị mặc định, thì nền tảng đó sẽ được coi là chưa chỉ định chế độ cài đặt ràng buộc. 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 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ó.
|
platform
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ụ
Quy tắc 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 nhận một danh sách, nhưng hiện chỉ hỗ trợ một giá trị duy nhất và việc chỉ định nhiều nền tảng 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
nền tảng 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 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 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 nền tảng mẹ và nền tảng con,
thì giá trị của nền tảng 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 đượ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 nền tảng 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 nền tảng 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 nền tảng 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 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ừ nền tảng 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ừ nền tảng 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 nền tảng mẹ và không đặt thuộc tính riêng. -
child_bkế thừaexec_propertiescủa nền tảng mẹ và ghi đè giá trị củak1.exec_propertiescủa nền tảng này sẽ là:{ "k1": "child", "k2": "v2" }. -
child_ckế thừaexec_propertiescủa nền tảng mẹ và không đặtk1.exec_propertiescủa nền tảng này sẽ là:{ "k2": "v2" }. -
child_dkế thừaexec_propertiescủa nền tảng mẹ và thêm một thuộc tính mới.exec_propertiescủa nền tảng 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à Mỗi |
exec_properties
|
Từ điển: Chuỗi -> Chuỗi; không thể định cấu hình; giá trị 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 sẽ bị xoá khỏi từ điển.
Thuộc tính này là sự thay thế hoàn toàn cho 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à platform mà nền tảng này sẽ kế thừa. Mặc dù
thuộc tính này nhận một danh sách, nhưng không được có nhiều hơn một nền tảng. Mọi
constraint_setting 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; giá trị 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 chuỗi công cụ đó 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; giá trị 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; giá trị 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; giá trị 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ụ
Quy tắc 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 quy tắ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. |