Phần này định nghĩa 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ã thông báo shell shell
- Mở rộng nhãn
- Các thuộc tính điển hình được xác định theo hầu hết các quy tắc tạo bản dựng
- Thuộc tính chung cho mọi quy tắc xây dựng
- Thuộc tính chung cho mọi quy tắc kiểm thử (*_test)
- Thuộc tính chung cho mọi quy tắc nhị phân (*_nhị phân)
- Thuộc tính có thể định cấu hình
- Mục tiêu đầu ra ngầm ẩn
Mã hoá vỏ Bourne
Một số thuộc tính chuỗi nhất định của một số quy tắc được phân tách thành nhiều từ theo quy tắc mã hoá mã thông báo của shell Bourne: dấu cách không trong dấu ngoặc kép phân tách các từ riêng biệt, ký tự dấu ngoặc đơn và dấu ngoặc kép cũng như dấu gạch chéo ngược được dùng để ngăn việc mã hoá.
Các thuộc tính chịu sự điều chỉnh của mã thông báo này sẽ được nêu rõ trong phần định nghĩa của các thuộc tính đó.
Các thuộc tính có thể mở rộng biến "Make" và mã hoá 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 này là cc_library.copts
và java_library.javacopts
.
Các phương pháp thay thế này cho phép một biến chuỗi đơn mở rộng thành 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ể mở rộng nhãn: nếu các chuỗi đó chứa 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 đã 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 đại diện bởi //mypkg:target
mục tiêu.
Ví dụ về các thuộc tính bao gồm genrule.cmd
và cc_binary.linkopts
. Thông tin có thể thay đổi đáng kể trong từng trường hợp, về các vấn đề như: các nhãn tương đối có được mở rộng hay không, cách xử lý các nhãn mở rộng ra nhiều tệp, v.v. Hãy tham khảo tài liệu về thuộc tính của quy tắc để biết cá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 các quy tắc tạo bản dựng
Phần này mô tả các thuộc tính được xác định theo nhiều quy tắc tạo bản dựng, nhưng không phải tất cả.
Thuộc tính | Nội dung mô tả |
---|---|
data |
Số tệp cần thiết cho quy tắc này vào thời gian chạy. Có thể liệt kê các mục tiêu quy tắc hoặc tệp. Thường cho phép mục tiêu bất kỳ.
Các đầu ra mặc định và tệp chạy của mục tiêu trong thuộc tính
Các quy tắc mới sẽ xác định thuộc tính |
deps |
Phần phụ thuộc cho mục tiêu này. Thường thì 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 các tệp được liệt kê trực tiếp trong Các quy tắc theo ngôn ngữ 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 việc 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 các chuỗi loại giấy phép sẽ được 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 |
Tệp được xử lý hoặc đưa vào quy tắc này. Thường thì trực tiếp liệt kê 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ữ cụ thể thường yêu cầu các tệp được liệt kê phải có đuôi tệp cụ thể. |
Thuộc tính chung cho tất cả quy tắc xây dựng
Phần này mô tả các thuộc tính được ngầm thêm vào tất cả các quy tắc xây dựng.
Thuộc tính | Nội dung mô tả |
---|---|
compatible_with |
Danh sách 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 các 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 (Ngữ nghĩa ràng buộc) để biết thông tin chi tiết. |
deprecation |
Thông báo cảnh báo giải thích về mục tiêu này. Thường thì thuộc tính này 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ị thay thế bằng một quy tắc khác, là mục tiêu riêng tư đối với một gói hoặc có thể bị coi là có hại vì lý do nào đó. Bạn nên đưa vào một số tệp tham chiếu (chẳng hạn như trang web, số lỗi hoặc ví dụ về CL di chuyển) để có thể dễ dàng tìm ra những thay đổi cần thiết để tránh thông báo. Nếu có mục tiêu mới có thể dùng làm mục tiêu thay thế, 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 tạo 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 sẽ đư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 khỏi cảnh báo này để chẳng hạn như việc tạo kiểm thử của một quy tắc không dùng nữa sẽ 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 đã ngừng sử dụng, 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, mục tiêu có thể bị xoá. |
distribs |
Danh sách các chuỗi phương thức phân phối được 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 |
exec_properties |
Từ điển gồm các chuỗi sẽ được thêm vào Nếu có một khoá trong cả tài sản cấp mục tiêu và nền tảng, thì giá trị sẽ được lấy từ mục tiêu. |
features |
Tính năng là thẻ chuỗi có thể bật hoặc tắt trên 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 môi trường có thể tạo mục tiêu này, thay vì 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 truy cập vào |
tags |
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à quy tắc
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 hoạt động kiểm thử thường được dùng để chú thích vai trò của hoạt động kiểm thử trong quy trình gỡ lỗi và phát hành. Thông thường, thẻ hữu ích nhất cho chương trình kiểm thử C++ và Python, vốn thiếu khả năng chú giải thời gian chạy. Việc sử dụng thẻ và các phần tử kích thước mang lại sự linh hoạt trong việc tập hợp các bộ kiểm thử dựa trên chính sách đăng ký 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 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 cấu phần phần mềm này cũng bị bỏ qua để tạo và kiểm thử. Danh sách trống (là mặc định) biểu thị mục tiêu tương thích với tất cả nền tảng.
Mọi quy tắc khác ngoài 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ề cách bỏ qua mục tiêu không tương thích. |
testonly |
Nếu đúng, thì chỉ những mục tiêu chỉ kiểm thử (chẳng hạn như thử nghiệm) mới có thể phụ thuộc vào mục tiêu này.
Tương tự, một quy tắc không phải là
Theo mặc định, các quy 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 nằm trong các tệp nhị phân được phát hành chính thức. Vì 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à truyền mã lực 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ụ: mã giả lập và mã giả mạo hữu ích cho việc kiểm thử đơn vị cũng có thể hữu ích cho các chương trình kiểm thử tích hợp liên quan đến các tệp nhị phân sẽ được phát hành chính thức, do đó, có lẽ 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 khi liên kết (có thể là vì chúng ghi đè hành vi thông thường) vô điều kiện nên được đánh dấu là chỉ dành cho mục đích kiểm thử. |
toolchains |
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à thực thể của các 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 của chuỗi công cụ được 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ể dùng thuộc tính này để xác định |
visibility |
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 tất cả quy tắc kiểm thử.
Thuộc tính | Nội dung mô tả | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Các đối số dòng lệnh mà Bazel truyền đến mục tiêu khi thực thi bằng
Các đối số này được chuyển trước bất kỳ giá trị |
||||||||||||||||||||
env |
Chỉ định các biến môi trường bổ sung để thiết lập khi
Thuộc tính này chỉ áp dụng cho các quy tắc gốc, như |
||||||||||||||||||||
env_inherit |
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, như |
||||||||||||||||||||
size |
Chỉ định "mức độ nặng" của mục tiêu kiểm thử: thời gian/tài nguyên cần thiết để chạy mục tiêu kiểm thử. Kiểm thử đơn vị được coi là kiểm thử "nhỏ", kiểm thử tích hợp "trung bình" và kiểm thử toàn diện "lớn" hoặc "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 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 |
Khoảng thời gian thử nghiệm dự kiến sẽ chạy trước khi quay lại.
Mặc dù thuộc tính kích thước của hoạt động 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 một cách độ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 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 chờ kiểm thử có thể được ghi đè bằng cờ bazel Biến môi trường |
||||||||||||||||||||
flaky |
Các dấu hiệu kiểm tra là không ổn định. Nếu được thiết lập, sẽ thực thi kiểm thử tối đa 3 lần và chỉ đánh dấu kiểm thử là không thành công nếu mỗi lần kiểm thử đều thất bại. 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. Lưu ý rằng thường thì 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ác câu nhận định của chúng được giữ nguyên. |
||||||||||||||||||||
shard_count |
Chỉ định số lượng phân đoạn song song cần sử dụng để chạy kiểm thử. 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 cần chạy kiểm thử. Lưu ý rằng đối với một số quy tắc kiểm thử, bạn có thể phải có tham số này để bật tính năng phân đoạn ngay từ đầu. Xem thêm Nếu tính năng phân đoạn kiểm thử đang bật, 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ể mã này sẽ chạy mọi bài kiểm thử trong mọi phân đoạ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ư kiểm thử để biết thông tin chi tiết về cách phân đoạn. |
||||||||||||||||||||
local |
Buộc chạy thử nghiệm cục bộ mà không tạo 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ẻ ( |
Các thuộc tính chung cho mọi quy tắc nhị phân (*_nhị phân)
Phần này mô tả 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 |
Các đối số dòng lệnh mà Bazel sẽ truyền đến mục tiêu khi đượ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 theo cách thủ công trong |
env |
Chỉ định các biến môi trường bổ sung để 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 đặ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 |
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 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. Ví dụ: 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 nhiều nguồn 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 cách sử dụng x86_impl.cc
, còn 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 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
các 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ụ: các 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 tương ứ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 vì nội bộ Bazel cần biết giá trị của thuộc tính đó trước khi có thể xác định cách phân giải select()
.
Hãy 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.
Mục tiêu đầu ra ngầm ẩn
Không dùng kết quả đầu ra ngầm trong C++ nữa. Nếu có thể, vui lòng không dùng thuộc tính này bằng các ngôn ngữ khác. Chúng tôi chưa có lộ trình ngừng sử dụng nhưng sau cùng, chúng cũng sẽ không được dùng nữa.
Khi xác định quy tắc xây 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 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 riêng theo quy tắc.
Ví dụ: khi khai báo rõ ràng quy tắc java_binary(name='foo', ...)
, bạn cũng sẽ ngầm ẩn khai báo tệp đầu ra mục tiêu foo_deploy.jar
là thành phầ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 để triển khai.)
Mục tiêu đầu ra ngầm ẩn là thành phần hạng nhất của biểu đồ mục tiêu toàn cục. Cũng 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 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. Bạn có thể tham chiếu các phần phụ thuộc này dưới dạng phần phụ thuộc trong tệp BUILD và bạn có thể quan sát các tài sản nà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 một phần đặc biệt nêu chi tiết tên và nội dung của mọi kết quả ngầm ẩn bắt nguồn từ việc khai báo loại quy tắc đó.
Một điểm khác biệt quan trọng nhưng có phần tinh vi giữa 2 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à các 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át sinh (hoặc đầu ra). Bạn có thể đề cập đến những nội dung sau trong các tệp BUILD (Xây dựng) 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 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ó 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ể tham chiếu đượ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 công cụ thực hiện nhiệm vụ. Đ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 về BUILD.