Phần này định nghĩa các 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ã 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 theo quy tắc mã hoá của vỏ Bourne: dấu cách không trích dẫn phân cách các từ riêng biệt, và dấu- và ký tự dấu ngoặc kép và dấu gạch chéo ngược được dùng để ngăn mã hoá kỹ thuật số.
Những thuộc tính chịu ảnh hưởng của quá trình mã hoá kỹ thuật số này là được nêu rõ như vậy trong các định nghĩa trong tài liệu này.
Các thuộc tính tuỳ thuộc vào "Nhãn hiệu" mở rộng biến và vỏ Bourne
quá trình mã hoá 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 đó là
cc_library.copts
và java_library.javacopts
.
Những sự thay thế này đồng thời cho phép
biến chuỗi đơn để mở rộng thành danh sách theo cấu hình cụ thể
gồm các từ tuỳ chọn.
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ó áp dụng nhãn
mở rộng: 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 được khai báo của quy tắc hiện tại, nó được mở rộng thành
tên đường dẫn của tệp được biểu thị bằng giá trị
mục tiêu
//mypkg:target
.
Các thuộc tính mẫu bao gồm genrule.cmd
và
cc_binary.linkopts
. Các chi tiết có thể thay đổi đáng kể trong
từng trường hợp, đối với các vấn đề như: liệu nhãn tương đối có
đã mở rộng; cách nhãn mở rộng sang nhiều tệp
được xử lý, v.v. Hãy tham khảo tài liệu về thuộc tính quy tắc để
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 | Mô tả |
---|---|
data |
Danh sách nhãn; giá trị 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. Thông thường cho phép mọi mục tiêu.
Dữ liệu đầu ra và tệp run mặc định 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; giá trị 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 tệp được liệt kê trực tiếp trong Quy tắc theo ngôn ngữ cụ thể thường giới hạn mục tiêu được liệt kê ở những nhà cung cấp cụ thể.
Ngữ nghĩa chính xác về ý nghĩa 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 các 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. Không nên làm sử dụng tính năng này. |
srcs |
Danh sách nhãn; giá trị mặc định là
Tệp được xử lý hoặc bao gồm trong quy tắc này. Thường liệt kê 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 theo ngôn ngữ cụ thể thường yêu cầu các tệp được liệt kê có các chỉ số đuôi tệp. |
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ả bản dựng quy tắc.
Thuộc tính | 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 môi trường có thể xây dựng mục tiêu này, ngoài môi trường mặc định được hỗ trợ. Đây là một phần của hệ thống ràng buộc của Bazel, cho phép người dùng khai báo các mục tiêu có thể và không thể phụ thuộc lẫn nhau. Ví dụ: có thể triển khai bên ngoài tệp nhị phân không được phụ thuộc vào thư viện có mã bí mật của công ty. Xem ConstraintSemantics để biết chi tiết. |
deprecation |
String; 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 đã bị thay thế bởi một quy tắc khác, là riêng tư đối với một gói, hoặc có thể bị coi là gây hại vì lý do nào đó. Bạn nên thêm một số tài liệu tham khảo (như trang web, số lỗi hoặc CL di chuyển mẫu) để để mọi người có thể dễ dàng biết được cần phải thay đổi những gì để tránh thông báo đó. Nếu có một mục tiêu mới có thể dùng để thay thế, thì đó là 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 công trình, nhưng lại
có thể ảnh hưởng đến kết quả chẩn đoán của công cụ bản dựng. Công cụ bản dựng đưa ra
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 đó Ví dụ: việc xây dựng các bài kiểm thử của một quy tắc không được dùng nữa 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 được dùng nữa, thì không có cảnh báo tin nhắn sẽ được phát hành. Sau khi mọi người ngừng sử dụng, bạn có thể xoá mục tiêu. |
distribs |
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á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. Không nên làm 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; giá trị 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. Chiến lược phát hành đĩa đơn ý nghĩa của 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 môi trường có thể xây dựng mục tiêu này, thay vì môi trường mặc định được hỗ trợ.
Đây là một phần trong hệ thống ràng buộc của Bazel. Xem
|
tags |
Danh sách các 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 giai đoạn thử nghiệm và
Quy tắc
Bazel sửa đổi hành vi của mã hộp cát nếu phát hiện thấy:
từ khóa trong thuộc tính
Thẻ trong 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 đối với C++ và Python các kiểm thử này thiếu bất kỳ khả năng chú thích nào trong thời gian chạy. Việc sử dụng thẻ và kích thước các phần tử mang lại sự linh hoạt trong việc tập hợp các bộ kiểm thử dựa trên cơ sở mã chính sách xác nhận có mặt.
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; giá trị mặc định là
Danh sách
Những mục tiêu phụ thuộc bắc cầu vào những mục tiêu không tương thích chính là những mục tiêu đó 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 tất cả các nền tảng.
Tất cả các quy tắc khác ngoài Quy tắc của Workspace hỗ trợ quy tắc 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 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, quy tắc không phải là
Thử nghiệm ( Thuộc tính này có nghĩa là mục tiêu không được có 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 trong thời gian chạy và được áp dụng lan truyền mạnh mẽ thông qua cây phụ thuộc thì cần được áp dụng một cách thận trọng. Để Ví dụ: mã giả lập và mã giả mạo 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 chính tệp nhị phân sẽ được phát hành chính thức, và do đó, bạn không nên đánh dấu chỉ là kiểm thử. Ngược lại, quy tắc rất nguy hiểm khi liên kết, có thể là vì chúng vô điều kiện ghi đè hành vi bình thường, chắc chắn nên được đánh dấu là chỉ thử nghiệm. |
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ó mục tiêu Tạo biến này là
được phép truy cập. Các mục tiêu này là các trường hợp quy tắc cung cấp
Xin lưu ý rằng điều này khác với khái niệm
giải quyết chuỗi công cụ
được sử dụng bởi các 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
để xác định xem một thuộc tí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 | Mô tả | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Danh sách các chuỗi; phải tuân theo
$(location) và
Phép thế "Tạo biến" và
Mã hoá Bourne shell; giá trị mặc định là Đố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ị phải tuân theo
$(location) và
Thay thế "Tạo biến"; giá trị mặc định là
Chỉ định các biến môi trường bổ sung cần thiết lập khi thực thi kiểm thử
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 các chuỗi; giá trị 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 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, có thể được ghi đè bằng cách sử dụ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à tài nguyên cục bộ cao nhất được giả định sử dụng:
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ó thể được đặt một cách độc lập. Nếu không được chỉ định rõ ràng,
dựa trên kích thước của kiểm thử. Thử nghiệm
có thể bị ghi đè 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 hàm
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 đặt, 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 đạt lần nào cũng không thành công. Theo mặc định, thuộc tính này được đặt thành False và kiểm thử là chỉ thực thi một lần. Lưu ý rằng bạn không nên sử dụng thuộc tính này – các lượt kiểm thử phải đạt một cách đáng tin cậy khi câu nhận định của các lượt xác nhận đó đượ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 sử 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 kiểm thử. Lưu ý rằng đối với một số thử nghiệm
, 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 thì mã này có nhiều khả năng sẽ chạy mọi bài kiểm thử trong mọi phân đoạn, không phải là điều bạn muốn. Xem Kiểm thử phân đoạn trong Bách khoa toàn thư về 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 lựa chọn "cục bộ" 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 | Mô tả |
---|---|
args |
Danh sách các chuỗi; phải tuân theo
$(location) và
Phép thế "Tạo biến" và
Mã hoá 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 thực thi mục tiêu
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 thủ công tệp nhị phân trong
|
env |
Từ điển chuỗi; các giá trị phải tuân theo
$(location) và
Thay thế "Tạo biến"; giá trị mặc định là Chỉ định các biến môi trường bổ sung để đặt khi mục tiêu là
do
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 sẽ 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 thủ công tệp nhị phân trong
|
output_licenses |
Danh sách các chuỗi; giá trị 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. Không nên làm 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", nghĩa 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 khác nhau. Cụ thể, các thuộc tính có thể định cấu hình có thể thay đổi tuỳ theo các cờ được chuyể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 chẳng hạn như 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 từng mục tiêu
các kiến trúc khác nhau. Chạy bazel build :multiplatform_lib --cpu x86
sẽ tạo mục tiêu bằng cách sử dụng x86_impl.cc
, đồng thời thay thế
Thay vào đó, --cpu arm
sẽ khiến nó 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
trên đó config_setting
hoặc constraint_value
cấu hình của mục tiêu đáp ứng tiêu chí.
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
các quy tắc xử lý (về mặt kỹ thuật, giữa
giai đoạn tải và phân tích).
Mọi quá trình xử lý trước khi thực hiện kết quả của select()
đều không biết
nhánh select()
chọn. Ví dụ: macro không thể thay đổi
hành vi của mình dựa trên nhánh đã chọn và bazel query
có thể
chỉ đưa ra các phỏng đ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. Xem
phần câu hỏi thường gặp
để 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 không được phép
sử dụng tính năng này. Một thuộc tính thường không thể định cấu hình được vì Bazel
cần biết giá trị nội bộ của nó trước khi có thể xác định cách giải quyết
select()
.
Xem 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 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 chúng cũng sẽ không được dùng nữa.
Khi xác định quy tắc bản dựng trong tệp BUILD, bạn sẽ rõ ràng
khai báo mục tiêu quy tắc mới, được đặt tên trong một gói. Nhiều quy tắc xây dựng
các hàm cũng ngầm ẩn đòi hỏi một hoặc nhiều tệp đầu ra
mục tiêu, có nội dung và ý nghĩa riêng theo từng quy tắc.
Ví dụ: khi bạn tuyên bố rõ ràng một
java_binary(name='foo', ...)
quy tắc, bạn cũng
ngầm ẩn khai báo tệp đầu ra
nhắm đến foo_deploy.jar
làm 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
để 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. Giống như các mục tiêu khác, chúng đượ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à những đ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. Chúng có thể là
được tham chiếu dưới dạng phần phụ thuộc trong tệp BUILD và có thể được quan sát thấy 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 phần đặc biệt nêu chi tiết tên và nội dung của mọi ngầm ẩn đầu ra đòi hỏi phải khai báo 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,
đây có thể là các quy tắc hoặc tệp. Mục tiêu tệp có thể được chia thành
đích tệp nguồn (hoặc đầu vào) và tệp phái sinh (hoặc đầu ra)
mục tiêu. Sau đâ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
;
đó là không gian tên mục tiêu. Mỗi mục tiêu tệp tương ứng
một tệp thực trên đĩa ("không gian tên hệ thống tệp"); mỗi quy tắc
đích có thể tương ứng với 0, một hoặc nhiều tệp thực trên đĩa.
Có thể có các tệp trên ổ đĩa không có đích tương ứng; với
Ví dụ: tệp đối tượng .o
được tạo ra trong quá trình biên dịch C++
không thể được tham chiếu từ trong 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ố chi tiết triển khai nhất định của
cách ứng dụng hoạt động. Điều này được giải thích đầy đủ hơn trong
XÂY DỰNG Tài liệu tham khảo khái niệm.