Phần này xác định nhiều thuật ngữ và khái niệm phổ biến đối với nhiều hàm hoặc quy tắc xây dựng.
Nội dung
- Mã hoá mã thông báo Bourne shell
- Mở rộng nhãn
- Các thuộc tính thông thường do hầu hết các quy tắc bản dựng xác định
- Các thuộc tính phổ biến cho tất cả quy tắc bản dựng
- Các thuộc tính phổ biến cho tất cả quy tắc kiểm thử (*_test)
- Các thuộc tính phổ biến cho tất cả quy tắc nhị phân (*_binary)
- Thuộc tính có thể định cấu hình
- Mục tiêu đầu ra ngầm ẩn
Mã hoá mã thông báo shell Bourne
Một số thuộc tính chuỗi của một số quy tắc được chia thành nhiều từ theo quy tắc tạo mã thông báo của shell Bourne: dấu cách không được trích dẫn phân định các từ riêng biệt, còn dấu ngoặc kép đơn và kép cũng như dấu gạch chéo ngược được dùng để ngăn việc tạo mã thông báo.
Những thuộc tính chịu sự mã hoá này được chỉ định rõ ràng trong định nghĩa của chúng trong tài liệu này.
Các thuộc tính chịu sự mở rộng biến "Tạo" và mã hoá mã thông báo của Bourne shell thường được dùng để truyền các tuỳ chọn tuỳ ý đến trình biên dịch và các công cụ khác. Ví dụ về các thuộc tính như vậy là cc_library.copts
và java_library.javacopts
.
Cùng với nhau, các hoạt động thay thế này cho phép một biến chuỗi mở rộng thành một danh sách từ tuỳ chọn dành riêng cho cấu hình.
Mở rộng nhãn
Một số thuộc tính chuỗi của một số ít quy tắc phải tuân theo việc mở rộng nhãn: nếu các chuỗi đó chứa một nhãn hợp lệ dưới dạng một chuỗi con, chẳng hạn như //mypkg:target
và nhãn đó là điều kiện tiên quyết đã khai báo của quy tắc hiện tại, thì nhãn đó sẽ được mở rộng thành đường dẫn của tệp được biểu thị bằng mục tiêu
//mypkg:target
.
Ví dụ về các thuộc tính bao gồm genrule.cmd
và cc_binary.linkopts
. Thông tin chi tiết có thể khác nhau đáng kể trong từng trường hợp, về các vấn đề như: liệu nhãn tương đối có được mở rộng hay không; cách xử lý các nhãn mở rộng sang nhiều tệp, v.v. Hãy tham khảo tài liệu về thuộc tính quy tắc để biết thông tin chi tiết.
Các thuộc tính thông thường do hầu hết các quy tắc bản dựng xác định
Phần này mô tả các thuộc tính được xác định bởi nhiều quy tắc bản dựng, nhưng không phải tất cả.
Thuộc tính | Mô tả |
---|---|
data |
Danh sách nhãn; mặc định là Các tệp mà quy tắc này cần đến trong thời gian chạy. Có thể liệt kê các mục tiêu tệp hoặc quy tắc. Thường cho phép mọi mục tiêu.
Đầu ra mặc định và tệp chạy của các mục tiêu trong thuộc tính
Các quy tắc mới phải xác định thuộc tính |
deps |
Danh sách nhãn; mặc định là
Phần phụ thuộc cho mục tiêu này. Thường chỉ nên liệt kê các mục tiêu của quy tắc. (Mặc dù một số quy tắc cho phép liệt kê tệp trực tiếp trong Quy tắc theo ngôn ngữ cụ thể thường giới hạn các mục tiêu được liệt kê ở những mục tiêu có nhà cung cấp cụ thể.
Ngữ nghĩa chính xác của việc một mục tiêu phụ thuộc vào một mục tiêu khác bằng cách sử dụng
Thông thường, phần phụ thuộc |
licenses |
Danh sách chuỗi; không thể định cấu hình; mặc định là Danh sách các chuỗi loại giấy phép sẽ được sử dụng cho mục tiêu cụ thể này. Đây là một phần của API cấp phép không dùng nữa mà Bazel không còn sử dụng. Đừng sử dụng thuộc tính này. |
srcs |
Danh sách nhãn; mặc định là
Các tệp được quy tắc này xử lý hoặc đưa vào. Thường liệt kê trực tiếp các tệp, nhưng có thể liệt kê các mục tiêu quy tắc (như Các quy tắc theo ngôn ngữ thường yêu cầu các tệp được liệt kê phải có đuôi tệp cụ thể. |
Các thuộc tính phổ biến cho tất cả quy tắc bản dựng
Phần này mô tả các thuộc tính được thêm ngầm vào tất cả quy tắc xây dựng.
Thuộc tính | Mô tả |
---|---|
compatible_with |
Danh sách nhãn; không thể định cấu hình; mặc định là Danh sách các môi trường có thể tạo mục tiêu này, ngoài các môi trường được hỗ trợ mặc định. Đây là một phần của hệ thống quy tắc ràng buộc của Bazel, cho phép người dùng khai báo mục tiêu nào có thể và không thể phụ thuộc vào nhau. Ví dụ: tệp nhị phân có thể triển khai bên ngoài không được phụ thuộc vào các thư viện có mã bí mật của công ty. Hãy xem ConstraintSemantics để biết thông tin chi tiết. |
deprecation |
Chuỗi; không thể định cấu hình; mặc định là Thông báo cảnh báo giải thích liên quan đến mục tiêu này. Thông thường, thuộc tính này được dùng để thông báo cho người dùng rằng một mục tiêu đã lỗi thời hoặc đã bị một quy tắc khác thay thế, là riêng tư đối với một gói hoặc có thể bị coi là gây hại vì một số lý do. Bạn nên thêm một số tài liệu tham khảo (chẳng hạn như trang web, số lỗi hoặc ví dụ về CL di chuyển) để người dùng có thể dễ dàng tìm ra những thay đổi cần thiết để tránh thông báo này. Nếu có một mục tiêu mới có thể được dùng để thay thế mục tiêu cũ, bạn chỉ nên di chuyển tất cả người dùng của mục tiêu cũ.
Thuộc tính này không ảnh hưởng đến cách tạo các mục, nhưng có thể ảnh hưởng đến kết quả chẩn đoán của công cụ tạo bản dựng. Công cụ xây dựng sẽ đưa ra cảnh báo khi một mục tiêu trong một gói khác phụ thuộc vào một quy tắc có thuộc tính Các phần phụ thuộc trong gói sẽ được miễn cảnh báo này, ví dụ: việc tạo các bài kiểm thử của một quy tắc không dùng nữa sẽ không gặp cảnh báo. Nếu một mục tiêu không dùng nữa phụ thuộc vào một mục tiêu không dùng nữa khác, thì hệ thống sẽ không đưa ra thông báo cảnh báo. Sau khi người dùng ngừng sử dụng, bạn có thể xoá mục tiêu đó. |
distribs |
Danh sách chuỗi; không thể định cấu hình; mặc định là Danh sách các chuỗi phương thức phân phối sẽ được sử dụng cho mục tiêu cụ thể này. Đây là một phần của API cấp phép không dùng nữa mà Bazel không còn sử dụng. Đừng sử dụng thuộc tính này. |
exec_compatible_with |
Danh sách nhãn; không thể định cấu hình; mặc định là
Danh sách |
exec_properties |
Từ điển chuỗi; mặc định là Từ điển chuỗi sẽ được thêm vào Nếu một khoá có trong cả thuộc tính nền tảng và thuộc tính cấp mục tiêu, thì giá trị sẽ được lấy từ mục tiêu. |
features |
Danh sách các chuỗi tính năng; mặc định là Tính năng là thẻ chuỗi có thể được bật hoặc tắt trên một mục tiêu. Ý nghĩa của một tính năng phụ thuộc vào chính quy tắc đó. Thuộc tính |
restricted_to |
Danh sách nhãn; không thể định cấu hình; mặc định là Danh sách các môi trường có thể tạo mục tiêu này, thay vì các môi trường được hỗ trợ mặc định.
Đây là một phần của hệ thống quy tắc ràng buộc của Bazel. Hãy xem |
tags |
Danh sách chuỗi; không thể định cấu hình; mặc định là
Bạn có thể sử dụng thẻ trên bất kỳ quy tắc nào. Thẻ trên quy tắc kiểm thử và
Bazel sửa đổi hành vi của mã hộp cát nếu tìm thấy các từ khoá sau trong thuộc tính
Thẻ trên kiểm thử thường được dùng để chú thích vai trò của kiểm thử trong quá trình gỡ lỗi và phát hành. Thông thường, thẻ hữu ích nhất cho các chương trình kiểm thử C++ và Python, vì các chương trình này không có khả năng chú thích thời gian chạy. Việc sử dụng thẻ và các phần tử kích thước giúp bạn linh hoạt trong việc tập hợp các bộ kiểm thử dựa trên chính sách kiểm tra cơ sở mã.
Bazel sửa đổi hành vi chạy kiểm thử nếu tìm thấy các từ khoá sau trong thuộc tính
|
target_compatible_with |
Danh sách nhãn; mặc định là
Danh sách các Các mục tiêu phụ thuộc bắc cầu vào các mục tiêu không tương thích cũng được coi là không tương thích. Các lớp này cũng bị bỏ qua khi tạo và kiểm thử. Danh sách trống (mặc định) cho biết mục tiêu tương thích với tất cả nền tảng.
Tất cả quy tắc ngoại trừ Quy tắc Workspace đều hỗ trợ thuộc tính này.
Đối với một số quy tắc, thuộc tính này không có hiệu lực. Ví dụ: việc chỉ định
Hãy xem trang Nền tảng để biết thêm thông tin về việc bỏ qua mục tiêu không tương thích. |
testonly |
Boolean; không thể định cấu hình; mặc định là
Nếu là
Tương tự, một quy tắc không phải là
Theo mặc định, các chương trình kiểm thử (quy tắc Thuộc tính này có nghĩa là mục tiêu không được chứa trong các tệp nhị phân được phát hành cho bản phát hành chính thức. Vì testonly được thực thi tại thời điểm tạo bản dựng, chứ không phải thời gian chạy và được truyền tải mạnh mẽ thông qua cây phần phụ thuộc, nên bạn cần áp dụng tính năng này một cách thận trọng. Ví dụ: các mã giả và mã giả hữu ích cho kiểm thử đơn vị cũng có thể hữu ích cho kiểm thử tích hợp liên quan đến cùng một tệp nhị phân sẽ được phát hành cho bản phát hành chính thức, do đó, có thể không được đánh dấu là chỉ kiểm thử. Ngược lại, các quy tắc nguy hiểm ngay cả khi liên kết, có thể là do các quy tắc này ghi đè hành vi bình thường một cách vô điều kiện, chắc chắn phải được đánh dấu là chỉ kiểm thử. |
toolchains |
Danh sách nhãn; không thể định cấu hình; mặc định là
Tập hợp các mục tiêu có Biến tạo mà mục tiêu này được phép truy cập. Các mục tiêu này là các thực thể của quy tắc cung cấp
Xin lưu ý rằng điều này khác với khái niệm độ phân giải chuỗi công cụ mà các hoạt động triển khai quy tắc sử dụng cho cấu hình phụ thuộc vào nền tảng. Bạn không thể sử dụng thuộc tính này để xác định |
visibility |
Danh sách nhãn; không thể định cấu hình; mặc định thay đổi
Thuộc tính
Đối với các mục tiêu được khai báo trực tiếp trong tệp BUILD hoặc trong các macro cũ được gọi từ tệp BUILD, giá trị mặc định là |
Các thuộc tính phổ biến cho tất cả quy tắc kiểm thử (*_test)
Phần này mô tả các thuộc tính phổ biến cho tất cả quy tắc kiểm thử.
Thuộc tính | Mô tả | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Danh sách chuỗi; tuân theo quy tắc thay thế $(location) và "Tạo biến", cũng như tạo mã thông báo shell Bourne; mặc định là Các đối số dòng lệnh mà Bazel truyền đến mục tiêu khi mục tiêu đó được thực thi bằng
Các đối số này được truyền trước mọi giá trị |
||||||||||||||||||||
env |
Từ điển chuỗi; các giá trị phải tuân theo quy tắc thay thế $(location) và "Tạo biến"; mặc định là
Chỉ định các biến môi trường bổ sung cần đặt khi
Thuộc tính này chỉ áp dụng cho các quy tắc gốc, chẳng hạn như |
||||||||||||||||||||
env_inherit |
Danh sách chuỗi; mặc định là Chỉ định các biến môi trường bổ sung để kế thừa từ môi trường bên ngoài khi
Thuộc tính này chỉ áp dụng cho các quy tắc gốc, chẳng hạn như |
||||||||||||||||||||
size |
Chuỗi Chỉ định "độ nặng" của mục tiêu kiểm thử: lượng thời gian/tài nguyên cần thiết để chạy mục tiêu đó. Kiểm thử đơn vị được coi là "nhỏ", kiểm thử tích hợp là "vừa" và kiểm thử toàn diện là "lớn" hoặc "rất lớn". Bazel sử dụng kích thước để xác định thời gian chờ mặc định. Bạn có thể ghi đè thời gian chờ này bằng cách sử dụng thuộc tính Kích thước kiểm thử tương ứng với các thời gian chờ mặc định sau đây và mức sử dụng tài nguyên cục bộ cao nhất giả định:
Biến môi trường |
||||||||||||||||||||
timeout |
Chuỗi Thời gian dự kiến để kiểm thử chạy trước khi trả về.
Mặc dù thuộc tính kích thước của kiểm thử kiểm soát việc ước tính tài nguyên, nhưng bạn có thể đặt thời gian chờ của kiểm thử một cách độc lập. Nếu bạn không chỉ định rõ ràng, thời gian chờ sẽ dựa trên kích thước của kiểm thử. Bạn có thể ghi đè thời gian chờ kiểm thử bằng cờ
Đối với các thời gian khác với thời gian nêu trên, bạn có thể ghi đè thời gian chờ kiểm thử bằng cờ bazel
Biến môi trường |
||||||||||||||||||||
flaky |
Boolean; không thể định cấu hình; giá trị mặc định là Đánh dấu kiểm thử là không ổn định. Nếu được đặt, hãy thực thi kiểm thử tối đa 3 lần, chỉ đánh dấu kiểm thử là không thành công nếu kiểm thử không thành công mỗi lần. Theo mặc định, thuộc tính này được đặt thành False và quy trình kiểm thử chỉ được thực thi một lần. Xin lưu ý rằng bạn không nên sử dụng thuộc tính này – các kiểm thử phải vượt qua một cách đáng tin cậy khi các câu nhận định được duy trì. |
||||||||||||||||||||
shard_count |
Số nguyên không âm nhỏ hơn hoặc bằng 50; mặc định là Chỉ định số lượng phân đoạn song song để sử dụng khi chạy kiểm thử. Nếu được đặt, giá trị này sẽ ghi đè mọi phương pháp phỏng đoán được dùng để xác định số lượng phân đoạn song song để chạy kiểm thử. Xin lưu ý rằng đối với một số quy tắc kiểm thử, bạn có thể cần tham số này để bật tính năng phân đoạn ngay từ đầu. Xem thêm Nếu bạn bật tính năng phân đoạn kiểm thử, biến môi trường Tính năng phân đoạn yêu cầu trình chạy kiểm thử hỗ trợ giao thức phân đoạn kiểm thử. Nếu không, thì rất có thể nó sẽ chạy mọi chương trình kiểm thử trong mọi phân mảnh, điều này không phải là điều bạn muốn. Hãy xem phần Phân đoạn kiểm thử trong Bách khoa toàn thư về kiểm thử để biết thông tin chi tiết về phân đoạn. |
||||||||||||||||||||
local |
Boolean; không thể định cấu hình; giá trị mặc định là Buộc chạy kiểm thử cục bộ mà không cần hộp cát. Việc đặt giá trị này thành True tương đương với việc cung cấp "local" làm thẻ ( |
Các thuộc tính chung cho tất cả quy tắc nhị phân (*_binary)
Phần này mô tả các thuộc tính phổ biến cho tất cả quy tắc nhị phân.
Thuộc tính | Mô tả |
---|---|
args |
Danh sách chuỗi; tuân theo việc thay thế $(location) và "Tạo biến" và tổng hợp mã thông báo Bourne shell; không thể định cấu hình; mặc định là
Các đối số dòng lệnh mà Bazel sẽ truyền đến mục tiêu khi mục tiêu đó được thực thi bằng lệnh
LƯU Ý: Các đối số không được truyền khi bạn chạy mục tiêu bên ngoài Bazel (ví dụ: bằng cách thực thi tệp nhị phân theo cách thủ công trong |
env |
Từ điển chuỗi; các giá trị phải tuân theo quy tắc thay thế $(location) và "Tạo biến"; mặc định là Chỉ định các biến môi trường bổ sung cần đặt khi mục tiêu được
Thuộc tính này chỉ áp dụng cho các quy tắc gốc, chẳng hạn như
LƯU Ý: Các biến môi trường không được đặt khi bạn chạy mục tiêu bên ngoài Bazel (ví dụ: bằng cách thực thi tệp nhị phân theo cách thủ công trong |
output_licenses |
Danh sách chuỗi; mặc định là Giấy phép của các tệp đầu ra mà tệp nhị phân này tạo ra. Đây là một phần của API cấp phép không dùng nữa mà Bazel không còn sử dụng. Đừng sử dụng thuộc tính này. |
Thuộc tính có thể định cấu hình
Hầu hết các thuộc tính đều "có thể định cấu hình", nghĩa là giá trị của các thuộc tính này có thể thay đổi khi mục tiêu được tạo theo nhiều cách. Cụ thể, các thuộc tính có thể định cấu hình có thể thay đổi dựa trên các cờ được truyền đến dòng lệnh Bazel hoặc phần phụ thuộc hạ nguồn đang yêu cầu mục tiêu. Bạn có thể sử dụng tính năng này để tuỳ chỉnh mục tiêu cho nhiều nền tảng hoặc chế độ biên dịch.
Ví dụ sau đây khai báo các nguồn khác nhau cho các cấu trúc mục tiêu khác nhau. Việc chạy bazel build :multiplatform_lib --cpu x86
sẽ tạo mục tiêu bằng x86_impl.cc
, trong khi việc thay thế --cpu arm
sẽ khiến mục tiêu sử dụng arm_impl.cc
.
cc_library( name = "multiplatform_lib", srcs = select({ ":x86_mode": ["x86_impl.cc"], ":arm_mode": ["arm_impl.cc"] }) ) config_setting( name = "x86_mode", values = { "cpu": "x86" } ) config_setting( name = "arm_mode", values = { "cpu": "arm" } )
Hàm select()
chọn trong số các giá trị thay thế khác nhau cho một thuộc tính có thể định cấu hình dựa trên tiêu chí config_setting
hoặc constraint_value
mà cấu hình của mục tiêu đáp ứng.
Bazel đánh giá các thuộc tính có thể định cấu hình sau khi xử lý macro và trước khi xử lý quy tắc (về mặt kỹ thuật, giữa
giai đoạn tải và phân tích).
Mọi hoạt động xử lý trước khi đánh giá select()
đều không biết select()
chọn nhánh nào. Ví dụ: các macro không thể thay đổi hành vi của chúng dựa trên nhánh đã chọn và bazel query
chỉ có thể dự đoán một cách thận trọng về các phần phụ thuộc có thể định cấu hình của một mục tiêu. Hãy xem
câu hỏi thường gặp này để biết thêm thông tin về cách sử dụng select()
với các quy tắc và macro.
Các thuộc tính được đánh dấu là nonconfigurable
trong tài liệu của chúng không thể sử dụng tính năng này. Thông thường, một thuộc tính không thể định cấu hình được vì Bazel cần biết giá trị của thuộc tính đó trong nội bộ trước khi có thể xác định cách phân giải select()
.
Hãy xem phần Thuộc tính bản dựng có thể định cấu hình để biết thông tin tổng quan chi tiết.
Mục tiêu đầu ra ngầm ẩn
Không dùng đầu ra ngầm ẩn trong C++ nữa. Vui lòng không sử dụng tên này bằng các ngôn ngữ khác nếu có thể. Chúng tôi chưa có lộ trình ngừng sử dụng nhưng cuối cùng các lớp này cũng sẽ ngừng hoạt động.
Khi xác định quy tắc bản dựng trong tệp BUILD, bạn đang khai báo rõ ràng một mục tiêu quy tắc mới, được đặt tên trong một gói. Nhiều hàm quy tắc bản dựng cũng ngầm ẩn bao gồm một hoặc nhiều mục tiêu tệp đầu ra, nội dung và ý nghĩa của các mục tiêu này là dành riêng cho quy tắc.
Ví dụ: khi khai báo rõ ràng một quy tắc java_binary(name='foo', ...)
, bạn cũng ngầm ẩn khai báo mục tiêu tệp đầu ra foo_deploy.jar
là một thành viên của cùng một gói.
(Mục tiêu cụ thể này là một tệp lưu trữ Java độc lập phù hợp với việc triển khai.)
Mục tiêu đầu ra ngầm ẩn là các thành viên hạng nhất của đồ thị mục tiêu toàn cục. Giống như các mục tiêu khác, các mục tiêu này được tạo theo yêu cầu, khi được chỉ định trong lệnh tạo cấp cao nhất hoặc khi là điều kiện tiên quyết cần thiết cho các mục tiêu bản dựng khác. Bạn có thể tham chiếu các tệp này dưới dạng phần phụ thuộc trong tệp BUILD và có thể quan sát được trong kết quả của các công cụ phân tích như bazel query
.
Đối với mỗi loại quy tắc bản dựng, tài liệu của quy tắc đó sẽ chứa một phần đặc biệt nêu chi tiết tên và nội dung của mọi đầu ra ngầm ẩn bắt buộc phải có trong phần khai báo loại quy tắc đó.
Một điểm khác biệt quan trọng nhưng hơi khó nhận ra giữa hai không gian tên mà hệ thống xây dựng sử dụng: thẻ xác định mục tiêu, có thể là quy tắc hoặc tệp, và mục tiêu tệp có thể được chia thành mục tiêu tệp nguồn (hoặc đầu vào) và mục tiêu tệp phái sinh (hoặc đầu ra). Đây là những điều bạn có thể đề cập trong tệp BUILD, tạo từ dòng lệnh hoặc kiểm tra bằng bazel query
; đây là không gian tên mục tiêu. Mỗi mục tiêu tệp tương ứng với một tệp thực tế trên đĩa ("không gian tên hệ thống tệp"); mỗi mục tiêu quy tắc có thể tương ứng với 0, 1 hoặc nhiều tệp thực tế trên đĩa.
Có thể có các tệp trên ổ đĩa không có mục tiêu tương ứng; ví dụ: không thể tham chiếu các tệp đối tượng .o
được tạo trong quá trình biên dịch C++ từ trong các tệp BUILD hoặc từ dòng lệnh.
Bằng cách này, công cụ xây dựng có thể ẩn một số thông tin triển khai nhất định về cách thực hiện công việc. Điều này được giải thích đầy đủ hơn trong Tài liệu tham khảo về khái niệm BUILD.