Phần này định nghĩa các thuật ngữ và khái niệm phổ biến cho nhiều hàm hoặc quy tắc xây dựng.
Nội dung
- Mã hoá mã hoá bằng shell Bourne
- Mở rộng nhãn
- Các thuộc tính điển hình được xác định theo hầu hết quy tắc xây dựng
- Thuộc tính chung cho mọi quy tắc bản dựng
- Thuộc tính chung cho tất cả quy tắc kiểm thử (*_test)
- Thuộc tính chung cho mọi quy tắc nhị phân (*_binary)
- Thuộc tính có thể định cấu hình
- Các mục tiêu đầu ra ngầm ẩn
Mã thông báo vỏ 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 các quy tắc phân tích mã thông báo của shell Bourne: dấu cách không trong dấu ngoặc kép phân cách các từ riêng biệt, đồng thời ký tự dấu ngoặc đơn và dấu ngoặc kép cùng dấu gạch chéo ngược được dùng để ngăn chặn việc mã hoá kỹ thuật số.
Các thuộc tính chịu sự điều chỉnh của quy trình mã hoá này được nêu rõ như vậy trong định nghĩa của tài liệu này.
Các thuộc tính cần mở rộng biến "Make" và mã hoá mã thông báo shell Bourne 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ác lựa chọn thay thế này kết hợp với nhau cho phép một biến chuỗi đơn mở rộng thành một danh sách các từ tuỳ chọn theo cấu hình cụ thể.
Mở rộng nhãn
Một số thuộc tính chuỗi của một số rất ít quy tắc có thể đượ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 chuỗi con, chẳng hạn như //mypkg:target
, và nhãn đó là điều kiện tiên quyết được khai báo của quy tắc hiện tại, thì nhãn đó sẽ được mở rộng thành tên đườ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 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, đối với các vấn đề như: nhãn tương đối có được mở rộng hay không; cách xử lý nhãn mở rộng thành 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 cụ thể.
Các thuộc tính điển hình được xác định theo hầu hết quy tắc xây dựng
Phần này mô tả các thuộc tính được xác định theo nhiều quy tắc xây dựng, nhưng không phải tất cả.
Thuộc tính | Nội dung mô tả |
---|---|
data |
Danh sách nhãn; mặc định là Các tệp mà quy tắc này cần trong thời gian chạy. Có thể liệt kê các mục tiêu của tệp hoặc quy tắc. Nhìn chung, mọi mục tiêu đều được phép.
Các đầu ra và tệp chạy mặc định của 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. Nói chung, bạn chỉ nên liệt kê các mục tiêu quy tắc. (Mặc dù một số quy tắc cho phép liệt kê trực tiếp các tệp trong Các 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 về ý nghĩa của một mục tiêu phụ thuộc vào một mục tiêu khác 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; giá trị 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 một API cấp phép không dùng nữa mà Bazel không còn sử dụng nữa. Đừng sử dụng tính năng này. |
srcs |
Danh sách nhãn; mặc định là
Tệp được xử lý hoặc bao gồm trong quy tắc này. Thường thì liệt kê các tệp trực tiếp, nhưng có thể liệt kê các mục tiêu quy tắc (như Các quy tắc dành riêng cho ngôn ngữ thường yêu cầu các tệp được liệt kê có đuôi tệp cụ thể. |
Thuộc tính chung cho mọi quy tắc bản dựng
Phần này mô tả các thuộc tính được ngầm thêm vào tất cả quy tắc xây dựng.
Thuộc tính | Nội dung mô tả |
---|---|
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 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 trong hệ thống 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 lẫn nhau. Ví dụ: các tệp nhị phân có thể triển khai bên ngoài không nên phụ thuộc vào 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; giá trị mặc định là Một 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, lệnh này dùng để thông báo cho người dùng rằng một mục tiêu đã trở nên lỗi thời hoặc đã được thay thế bằng một quy tắc khác, là dành riêng cho gói hoặc có thể bị coi là có hại vì lý do nào đó. Bạn nên cung cấp một số tài liệu tham khảo (chẳng hạn như trang web, số lỗi hoặc CL di chuyển mẫu) để người dùng có thể dễ dàng tìm ra những thay đổi cần thực hiện nhằm tránh thông báo này. Nếu có một mục tiêu mới có thể dùng làm mục tiêu giảm thay thế, 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 xây dựng mọi thứ, nhưng có thể ảnh hưởng đến kết quả chẩn đoán của công cụ xây dựng. Công cụ bản dựng đưa ra cảnh báo khi một quy tắc có thuộc tính Các phần phụ thuộc trong gói được miễn trừ khỏi cảnh báo này. Do đó, chẳng hạn như khi tạo hoạt động kiểm thử của một quy tắc không dùng nữa, thì không gặp phải 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ác không dùng nữa, thì sẽ không có thông báo cảnh báo nào được đưa ra. Sau khi mọi người 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; giá trị 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 một API cấp phép không dùng nữa mà Bazel không còn sử dụng nữa. Đừng sử dụng tính năng 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 |
exec_properties |
Từ điển chuỗi; giá trị mặc định là Từ điển các chuỗi sẽ được thêm vào Nếu một khoá có trong cả tài sản nền tảng và tài sản cấp đích, thì giá trị này sẽ được lấy từ mục tiêu. |
features |
Danh sách các chuỗi feature; 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; giá trị 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 trong hệ thống ràng buộc của Bazel. Hãy xem |
tags |
Danh sách chuỗi; không thể định cấu hình; giá trị mặc định là
Bạn có thể sử dụng thẻ trên mọi quy tắc. Thẻ trong 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ẻ trong kiểm thử thường được dùng để chú thích vai trò của một kiểm thử trong quy trình gỡ lỗi và phát hành. Thông thường, các thẻ hữu ích nhất cho các chương trình kiểm thử C++ và Python. Các thẻ này không có bất kỳ chức năng chú giải nào trong thời gian chạy. Việc sử dụng thẻ và phần tử kích thước giúp bạn linh hoạt 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 đang 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 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 sẽ bị coi là không tương thích. Các API này cũng được bỏ qua khi xây dựng và kiểm thử. Danh sách trống (là danh sách mặc định) cho biết mục tiêu tương thích với mọi nền tảng.
Tất cả các quy tắc khác ngoài Quy tắc của 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
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; giá trị mặc định là
Nếu là
Tương tự như vậy, một quy tắc không phải là
Theo mặc định, quy trình kiểm thử (quy tắc Thuộc tính này dùng để có nghĩa là mục tiêu không được nằm trong các tệp nhị phân được phát hành chính thức. Do chỉ kiểm thử được thực thi tại thời điểm xây dựng chứ không phải thời gian chạy và có hiệu quả lan truyền qua cây phụ thuộc, nên bạn cần phải áp dụng phương thức này một cách thận trọng. Ví dụ: các mã giả lập và mã giả lập hữu ích cho việc kiểm thử đơn vị cũng có thể hữu ích cho các kiểm thử tích hợp liên quan đến cùng các tệp nhị phân sẽ được phát hành chính thức và do đó có thể không nên được đánh dấu là chỉ kiểm thử. Ngược lại, các quy tắc nguy hiểm cần liên kết (có thể là do các quy tắc đó ghi đè vô điều kiện hành vi thông thường) chắc chắn sẽ được đánh dấu là chỉ kiểm thử. |
toolchains |
Danh sách nhãn;
không thể định cấu hình; giá trị mặc định là
Tập hợp các mục tiêu có Tạo biến 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 về độ phân giải chuỗi công cụ (được sử dụng trong các hoạt động triển khai quy tắc 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;
giá trị mặc định là
Thuộc tính |
Thuộc tính chung cho tất cả quy tắc kiểm thử (*_test)
Phần này mô tả các thuộc tính chung cho mọi quy tắc kiểm thử.
Thuộc tính | Nội dung mô tả | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Danh sách chuỗi; tuân theo việc thay thế $(location) và "Tạo biến" và mã hoá mã thông báo shell Bourne; giá trị mặc định là Các đối số dòng lệnh mà Bazel truyền đến mục tiêu khi được thực thi bằng
Các đối số này được truyền trước bất kỳ giá trị |
||||||||||||||||||||
env |
Từ điển chuỗi; các giá trị có sự thay thế $(location) và "Tạo biến"; mặc định là
Chỉ định các biến môi trường khác cần đặt khi
Thuộc tính này chỉ áp dụng cho các quy tắc gốc, như |
||||||||||||||||||||
env_inherit |
Danh sách chuỗi; mặc định là Chỉ định các biến môi trường khác để kế thừa từ
môi trường bên ngoài khi quy trình kiểm thử được
Thuộc tính này chỉ áp dụng cho các quy tắc gốc, như |
||||||||||||||||||||
size |
Chuỗi Chỉ định "độ nặng" của mục tiêu kiểm thử: thời gian/tài nguyên cần để chạy. Kiểm thử đơn vị được coi là "nhỏ", kiểm thử tích hợp là "trung bình" 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 này để xác định thời gian chờ mặc định. Bạn có thể ghi đè thời gian chờ này bằng thuộc tính Kích thước kiểm thử tương ứng với 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 được giả định:
Biến môi trường |
||||||||||||||||||||
timeout |
Chuỗi Thời gian chạy bài kiểm thử dự kiến trước khi quay lại.
Mặc dù thuộc tính kích thước của bài kiểm thử kiểm soát việc ước tính tài nguyên, nhưng thời gian chờ của bài kiểm thử có thể được đặt độc lập. Nếu không được 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 những thời điểm khác thời gian 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 kết quả kiểm tra là không ổn định. Nếu được thiết lập, hãy thực thi chương trình kiểm thử tối đa 3 lần, đánh dấu là chỉ kiểm thử không thành công nếu mỗi lần kiểm thử không đạt. Theo mặc định, thuộc tính này được đặt thành False và chỉ thực thi kiểm thử 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 bài kiểm thử phải truyền một cách đáng tin cậy khi câu nhận định được giữ nguyên. |
||||||||||||||||||||
shard_count |
Số nguyên không âm nhỏ hơn hoặc bằng 50; giá trị mặc định là Chỉ định số lượng phân đoạn song song cần dùng để 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 dùng để xác định số lượng phân đoạn song song để chạy chương trình kiểm thử. Lưu ý rằng đối với một số quy tắc kiểm thử, tham số này có thể được yêu cầu 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ử, thì biến môi trường Tính năng phân đoạn cần có trình chạy kiểm thử để hỗ trợ giao thức phân đoạn kiểm thử. Nếu không, rất có thể chương trình này sẽ chạy mọi quy trình kiểm thử trong mọi phân đoạn, đây không phải là điều bạn muốn. Vui lòng xem phần Kiểm thử phân đoạn trong Bách khoa toàn thư kiểm thử để biết thông tin chi tiết về tính năng phân đoạn. |
||||||||||||||||||||
local |
Boolean; không thể định cấu hình; giá trị mặc định là Buộc chạy quy trình kiểm thử trên máy mà không áp dụng 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" dưới dạng thẻ ( |
Những thuộc tính chung cho mọi quy tắc nhị phân (*_binary)
Phần này mô tả các thuộc tính chung cho tất cả các quy tắc nhị phân.
Thuộc tính | Nội dung mô tả |
---|---|
args |
Danh sách chuỗi; tuân theo việc thay thế $(location) và "Tạo biến" cũng như mã hoá mã thông báo shell Bourne; 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ố 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 trong |
env |
Từ điển chuỗi; các giá trị có sự 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 thiết lập khi mục tiêu được
Thuộc tính này chỉ áp dụng cho các quy tắc gốc, như
LƯU Ý: Các biến môi trường không được thiết lập 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 một API cấp phép không dùng nữa mà Bazel không còn sử dụng nữa. Đừng sử dụng tính năng 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", tức là giá trị của các thuộc tính đó có thể thay đổi khi mục tiêu được xây dựng theo nhiều cách. Cụ thể, các thuộc tính có thể định cấu hình có thể khác nhau 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 tuỳ chọn này chẳng hạn để 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 cho nhiều cấu trúc mục tiêu. 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ế cho một thuộc tính có thể định cấu hình dựa trên các 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 quy tắc xử lý (về mặt kỹ thuật là giữa
giai đoạn tải và phân tích).
Mọi quá trình xử lý trước khi đánh giá select()
đều không biết select()
chọn nhánh nào. Ví dụ: Macro không thể thay đổi hành vi dựa trên nhánh đã chọn và bazel query
chỉ có thể đưa ra dự đoán thận trọng về các phần phụ thuộc có thể định cấu hình của mục tiêu. Hãy xem phần
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 liên quan 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 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.
Các mục tiêu đầu ra ngầm ẩn
Kết quả ngầm định trong C++ không được dùng nữa. Vui lòng không sử dụng thuộc tính 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 rồi cũng sẽ không dùng nữa.
Khi xác định quy tắc bản dựng trong tệp BUILD, bạn sẽ khai báo rõ ràng 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 xây dựng cũng ngầm ẩn yêu cầu một hoặc nhiều mục tiêu tệp đầu ra, có nội dung và ý nghĩa dựa trên quy tắc cụ thể.
Ví dụ: khi khai báo rõ ràng một quy tắc java_binary(name='foo', ...)
, bạn cũng ngầm khai báo một tệp đầu ra mục tiêu foo_deploy.jar
là một thành phần của cùng một gói.
(Mục tiêu cụ thể này là một kho lưu trữ Java độc lập, phù hợp để triển khai.)
Các mục tiêu đầu ra ngầm ẩn là các thành phần hạng nhất của biểu đồ mục tiêu chung. 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 được tạo cấp cao nhất hoặc khi chúng 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. Các phần phụ thuộc này có thể được tham chiếu dưới dạng phần phụ thuộc trong tệp BUILD và có thể được ghi nhận 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 xây dựng, tài liệu của quy tắc chứa một phần đặc biệt trình bày chi tiết tên và nội dung của mọi kết quả ngầm ẩn kèm theo nội dung khai báo về loại quy tắc đó.
Một điểm khác biệt quan trọng nhưng hơi tinh tế giữa hai không gian tên mà hệ thống xây dựng sử dụng: nhãn 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 dữ liệu đầu vào) và mục tiêu tệp phát sinh (hoặc đầu ra). Dưới đây là những nội dung 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, một 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ụ: các tệp đối tượng .o
được tạo trong quá trình biên dịch C++ không thể được tham chiếu từ trong các tệp BUILD hoặc từ dòng lệnh.
Bằng cách này, công cụ bản dựng có thể ẩn một số chi tiết triển khai 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 XÂY DỰNG.