Định nghĩa phổ biến

Báo cáo sự cố Xem nguồn

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á shell Bourne

Một số thuộc tính chuỗi nhất định của một số quy tắc được chia thành nhiều từ theo quy tắc mã hoá trong 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ự tác động của quá trình mã hoá này sẽ được nêu rõ trong phần định nghĩa của tài liệu này.

Các thuộc tính phải 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: cc_library.coptsjava_library.javacopts. Các phương thức thay thế này cùng nhau 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ố ít quy tắc có thể phải 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 đượ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 //mypkg:target mục tiêu.

Ví dụ về các thuộc tính bao gồm genrule.cmdcc_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ư: nhãn tương đối có được mở rộng hay không; cách xử lý những 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 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 các 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 cần thiết cho quy tắc này trong thời gian chạy. Có thể liệt kê các mục tiêu tệp hoặc quy tắc. Nhìn chung, mọi mục tiêu đều cho phép.

Các đầu ra và tệp chạy mặc định của các mục tiêu trong thuộc tính data sẽ xuất hiện trong vùng *.runfiles của bất kỳ tệp thực thi nào có xuất ra hoặc có phần phụ thuộc thời gian chạy trên mục tiêu này. Trong đó có thể bao gồm các tệp dữ liệu hoặc tệp nhị phân dùng khi srcs của mục tiêu này được thực thi. Hãy xem mục các phần phụ thuộc dữ liệu để biết thêm thông tin về cách phụ thuộc và sử dụng tệp dữ liệu.

Các quy tắc mới sẽ xác định thuộc tính data nếu xử lý các dữ liệu đầu vào có thể sử dụng các dữ liệu đầu vào khác trong thời gian chạy. Hàm triển khai của quy tắc cũng phải điền sẵn tệp chạy của mục tiêu từ dữ liệu đầu ra và tệp chạy của bất kỳ thuộc tính data nào, cũng như tệp chạy từ bất kỳ thuộc tính phần phụ thuộc nào cung cấp mã nguồn hoặc phần phụ thuộc thời gian chạy.

deps

Danh sách nhãn; mặc định là []

Các 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 theo 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 deps, nhưng bạn nên tránh thực hiện điều này khi có thể.)

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ó trì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 deps là dành riêng cho loại quy tắc đó, và tài liệu dành riêng cho quy tắc sẽ đi sâu hơn. Đối với các quy tắc xử lý mã nguồn, deps thường chỉ định các phần phụ thuộc của mã mà mã sử dụng trong srcs.

Thông thường, phần phụ thuộc deps được dùng để cho phép một mô-đun sử dụng ký hiệu được xác định trong một mô-đun khác viết bằng cùng một ngôn ngữ lập trình và được biên dịch riêng biệt. Các phần phụ thuộc trên nhiều ngôn ngữ cũng được chấp nhận trong nhiều trường hợp: Chẳng hạn như mục tiêu java_library có thể phụ thuộc vào mã C++ trong mục tiêu cc_library, bằng cách liệt kê mục tiêu sau trong thuộc tính deps. Xem định nghĩa về phần phụ thuộc để biết thêm thông tin.

licenses

Danh sách chuỗi; không thể định cấu hình; giá trị mặc định là ["none"]

Danh sách các chuỗi loại giấy phép 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 nữa. Đừng dùng tính năng này.

srcs

Danh sách nhãn; mặc định là []

Các tệp được xử lý hoặc đưa vào quy tắc này. Thường thì 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ư filegroup hoặc genrule) để đưa vào kết quả mặc định của chúng.

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ê phải có đuôi tệp cụ thể.

Thuộc tính chung cho mọi quy tắc xây dựng

Phần này mô tả các thuộc tính ngầm ẩn được thêm vào tất cả quy tắc bản 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; mặc định là []

Ngoài các môi trường được hỗ trợ mặc định, danh sách môi trường có thể tạo mục tiêu này.

Đâ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 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 được phụ thuộc vào các thư viện có mã bí mật của công ty. Vui lòng xem bài viết ConstraintSemantics để biết thông tin chi tiết.

deprecation

Chuỗi; không thể định cấu hình; mặc định là None

Một thông báo cảnh báo giải thích về 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 đã được thay thế bằng một quy tắc khác, dành riêng cho 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ệp đối chiếu (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ày. Nếu có một mục tiêu mới có thể dùng để 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 các tính năng 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 deprecation phụ thuộc vào một mục tiêu trong một gói khác.

Các phần phụ thuộc trong gói được miễn trừ 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 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 người dùng ngừng sử dụng mục tiêu, bạn có thể xoá mục tiêu này.

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 đượ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 nữa. Đừng dùng tính năng 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 constraint_values phải có trong nền tảng thực thi cho mục tiêu này. Điều này bổ sung cho mọi quy tắc ràng buộc đã được đặt theo loại quy tắc này. Quy tắc ràng buộc được dùng để hạn chế danh sách các nền tảng thực thi có sẵn. Để biết thêm thông tin chi tiết, hãy xem nội dung mô tả về độ phân giải của chuỗi công cụ.

exec_properties

Từ điển chuỗi; giá trị mặc định là {}

Từ điển chuỗi sẽ được thêm vào exec_properties của nền tảng đã chọn cho mục tiêu này. Hãy xem exec_properties trong quy tắc nền tảng.

Nếu một khoá có trong cả tài sản nền tảng và tài sản cấp mục tiêu, thì giá trị sẽ được lấy từ mục tiêu.

features

Danh sách chuỗi tính năng; 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. Ý nghĩa của một tính năng phụ thuộc vào chính quy tắc đó.

Thuộc tính features này được kết hợp với thuộc tính gói cấp features. Ví dụ: nếu các tính năng ["a", "b"] được bật ở cấp gói và thuộc tính features của mục tiêu chứa ["-a", "c"], thì các tính năng được bật cho quy tắc sẽ là "b" và "c". Xem ví dụ.

restricted_to

Danh sách nhãn; không thể định cấu hình; mặc định là []

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 xem compatible_with để biết thông tin chi tiết.

tags

Danh sách chuỗi; không thể định cấu hình; giá trị mặc định là []

Có thể sử dụng Thẻ trên bất kỳ quy tắc nào. Các thẻ kiểm thử và quy tắc test_suite rất hữu ích khi phân loại các lượt kiểm thử. Thẻ trên các mục tiêu không kiểm thử được dùng để kiểm soát quá trình thực thi hộp cát của các hành động genruleStarlark, cũng như để phân tích cú pháp của con người và/hoặc các công cụ bên ngoài.

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 tags của mục tiêu kiểm thử hoặc mục tiêu genrule hoặc khoá của execution_requirements cho bất kỳ hành động nào Starlark.

  • Từ khoá no-sandbox dẫn đến hành động hoặc bài kiểm thử không bao giờ được đưa vào hộp cát; từ khoá này vẫn có thể được lưu vào bộ nhớ đệm hoặc chạy từ xa. Hãy sử dụng no-cache hoặc no-remote để ngăn một hoặc cả hai trường hợp đó.
  • Từ khoá no-cache dẫn đến hành động hoặc hoạt động kiểm thử không bao giờ được lưu vào bộ nhớ đệm (cục bộ hoặc từ xa). Lưu ý: để phục vụ mục đích của thẻ này, bộ nhớ đệm của ổ đĩa được coi là bộ nhớ đệm cục bộ, còn bộ nhớ đệm HTTP và gRPC được coi là bộ nhớ đệm từ xa. Các bộ nhớ đệm khác, chẳng hạn như Skyframe hoặc bộ nhớ đệm hành động liên tục, sẽ không bị ảnh hưởng.
  • Từ khoá no-remote-cache dẫn đến hành động hoặc bài kiểm thử không bao giờ được lưu từ xa vào bộ nhớ đệm (nhưng có thể được lưu vào bộ nhớ đệm cục bộ; cũng có thể được thực thi từ xa). Lưu ý: vì mục đích của thẻ này, bộ nhớ đệm của ổ đĩa được coi là bộ nhớ đệm cục bộ, trong khi bộ nhớ đệm HTTP và gRPC được coi là bộ nhớ đệm từ xa. Các bộ nhớ đệm khác, chẳng hạn như Skyframe hoặc bộ nhớ đệm hành động liên tục, sẽ không bị ảnh hưởng. Nếu bạn sử dụng kết hợp bộ nhớ đệm trên ổ đĩa cục bộ và bộ nhớ đệm từ xa (bộ nhớ đệm kết hợp), thì bộ nhớ đệm này được coi là bộ nhớ đệm từ xa và bị tắt hoàn toàn trừ phi bạn đặt --incompatible_remote_results_ignore_disk trong trường hợp các thành phần cục bộ sẽ được sử dụng.
  • Từ khoá no-remote-exec dẫn đến hành động hoặc bài kiểm thử không bao giờ được thực thi từ xa (nhưng có thể được lưu vào bộ nhớ đệm từ xa).
  • Từ khoá no-remote ngăn thực thi hành động hoặc bài kiểm thử từ xa hoặc lưu vào bộ nhớ đệm từ xa. Điều này tương đương với việc sử dụng cả no-remote-cacheno-remote-exec.
  • Từ khoá no-remote-cache-upload vô hiệu hoá thao tác tải lên của một phần lưu trữ dữ liệu từ xa vào bộ nhớ đệm. thao tác này không tắt tính năng thực thi từ xa.
  • Từ khoá local ngăn hành động hoặc thử nghiệm lưu vào bộ nhớ đệm từ xa, thực thi từ xa hoặc chạy bên trong hộp cát. Đối với quy tắc tạo sinh và quy tắc kiểm thử, việc đánh dấu quy tắc bằng thuộc tính local = True cũng có tác dụng tương tự.
  • Từ khoá requires-network cho phép truy cập vào mạng bên ngoài từ bên trong hộp cát. Thẻ này chỉ có hiệu lực nếu hộp cát được bật.
  • Từ khoá block-network chặn quyền truy cập vào mạng bên ngoài từ bên trong hộp cát. Trong trường hợp này, bạn chỉ được phép giao tiếp với localhost. Thẻ này chỉ có hiệu lực nếu hộp cát được bật.
  • requires-fakeroot chạy bài kiểm thử hoặc hành động dưới dạng uid và gid 0 (tức là người dùng gốc). Tính năng này chỉ được hỗ trợ trên Linux. Thẻ này được ưu tiên hơn so với tuỳ chọn dòng lệnh --sandbox_fake_username.

Thẻ trên quy trình kiểm thử thường được dùng để chú thích vai trò của chương trình 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 các kiểm thử C++ và Python, trong đó thiếu tính năng chú giải trong 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 tags của quy tắc kiểm thử:

  • exclusive sẽ buộc chạy chương trình kiểm thử ở chế độ "độc quyền" nhằm đảm bảo rằng không có hoạt động kiểm thử nào khác đang chạy cùng lúc. Các chương trình kiểm thử như vậy sẽ được thực thi theo kiểu nối tiếp sau khi tất cả hoạt động tạo bản dựng và các chương trình kiểm thử không độc quyền hoàn tất. Tính năng thực thi từ xa bị tắt cho các chương trình kiểm thử đó vì Bazel không có quyền kiểm soát nội dung đang chạy trên máy từ xa.
  • exclusive-if-local sẽ buộc chạy chương trình kiểm thử ở chế độ "độc quyền" nếu được thực thi cục bộ, nhưng sẽ chạy chương trình kiểm thử song song nếu được thực thi từ xa.
  • Từ khoá manual sẽ loại trừ mục tiêu khỏi việc mở rộng các ký tự đại diện mẫu mục tiêu (..., :*, :all, v.v.) và các quy tắc test_suite không liệt kê rõ ràng hoạt động kiểm thử khi tính toán tập hợp mục tiêu cấp cao nhất để tạo/chạy cho các lệnh build, testcoverage. Thao tác này không ảnh hưởng đến ký tự đại diện mục tiêu hoặc tính năng mở rộng bộ kiểm thử trong các ngữ cảnh khác, bao gồm cả lệnh query. Xin lưu ý rằng manual không ngụ ý rằng một mục tiêu không được các hệ thống xây dựng/kiểm thử liên tục tạo/chạy tự động. Ví dụ: bạn nên loại trừ một mục tiêu khỏi bazel test ... vì mục tiêu này yêu cầu các cờ Bazel cụ thể, nhưng vẫn có mục tiêu đó trong các lần gửi trước hoặc chạy kiểm thử liên tục được định cấu hình đúng cách.
  • Từ khoá external sẽ buộc hoạt động kiểm thử phải được thực thi vô điều kiện (bất kể giá trị --cache_test_results).
Xem Quy ước thẻ trong Bách khoa toàn thư thử nghiệm để biết thêm quy ước về các thẻ gắn với mục tiêu thử nghiệm.
target_compatible_with

Danh sách nhãn; mặc định là []

Danh sách constraint_value phải có trong nền tảng mục tiêu để mục tiêu này được coi là tương thích. Quy tắc này bổ sung cho mọi quy tắc ràng buộc đã đặt ra cho loại quy tắc. Nếu nền tảng mục tiêu không đáp ứng mọi điều kiện ràng buộc đã nêu thì mục tiêu sẽ bị coi là incompatible. Các mục tiêu không tương thích sẽ bị bỏ qua để tạo và kiểm thử khi mẫu mục tiêu được mở rộng (ví dụ: //..., :all). Khi được chỉ định rõ ràng trên dòng lệnh, các mục tiêu không tương thích sẽ khiến Bazel in ra lỗi và gây ra lỗi bản dựng hoặc kiểm thử.

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 thì được coi là không tương thích. Các phiên bản này cũng bị bỏ qua để tạo và thử nghiệm.

Danh sách trống (là danh sách mặc định) biểu thị mục tiêu tương thích với tất cả các nền tảng.

Tất cả quy tắ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. Chẳng hạn, việc chỉ định target_compatible_with cho cc_toolchain là không hữu ích.

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; giá trị mặc định là False ngoại trừ mục tiêu của bộ thử nghiệm và bộ thử nghiệm

Nếu là True, thì chỉ các mục tiêu chỉ kiểm thử (chẳng hạn như các hoạt động kiểm thử) mới có thể phụ thuộc vào mục tiêu này.

Tương đương, một quy tắc không phải là testonly sẽ không được phép phụ thuộc vào bất kỳ quy tắc nào là testonly.

Theo mặc định, các kiểm thử (quy tắc *_test) và bộ kiểm thử (quy tắc test_suite) là testonly.

Thuộc tính này nhằm có nghĩa là mục tiêu không được nằm trong 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 tạo bản dựng chứ không phải thời gian chạy và được truyền rộng rãi thông qua cây phần phụ thuộc, nên bạn cần áp dụng 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ác tệp nhị phân tương tự 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 khi liên kết (có thể là vì các quy tắc đó ghi đè vô điều kiện hành vi thông thường) chắc chắn nên được đánh dấu là chỉ dùng cho mục đí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 mục tiêu có Tạo các 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 quy tắc cung cấp TemplateVariableInfo hoặc mục tiêu đặc biệt cho các loại chuỗi công cụ được tích hợp vào Bazel. Những dịch vụ này bao gồm:

  • @bazel_tools//tools/cpp:current_cc_toolchain
  • @bazel_tools//tools/jdk:current_java_runtime

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 sử dụng trong các quá trình 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 cc_toolchain hoặc java_toolchain cụ thể mà một mục tiêu sẽ sử dụng.

visibility

Danh sách nhãn; không thể định cấu hình; giá trị mặc định là default_visibility trong gói nếu được chỉ định, hoặc "//visibility:private" nếu không được chỉ định

Thuộc tính visibility trên một mục tiêu kiểm soát việc mục tiêu đó có thể dùng được trong các gói khác hay không. Xem tài liệu về chế độ hiển thị.

Thuộc tính chung cho tất cả quy tắc kiểm thử (*_test)

Phần này mô tả thuộc tính chung cho tất cả các quy tắc kiểm thử.

Thuộc tính Nội dung mô tả
args

Danh sách các chuỗi; tuân theo $(location)"Tạo biến"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 thực thi bằng bazel test.

Các đối số này được chuyển trước bất kỳ giá trị --test_arg nào được chỉ định trên dòng lệnh bazel test.

env

Từ điển của chuỗi; các giá trị có thể được thay thế $(location)"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 hoạt động kiểm thử được bazel test thực thi.

Thuộc tính này chỉ áp dụng cho các quy tắc gốc, như cc_test, py_testsh_test. Quy tắc này không áp dụng cho các quy tắc kiểm thử do Starlark xác định. Đối với các quy tắc Starlark của riêng mình, bạn có thể thêm thuộc tính "env" và sử dụng thuộc tính này để điền sẵn một Nhà cung cấp TestEnvironment (Môi trường kiểm thử).

env_inherit

Danh sách chuỗi; giá trị 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 bazel test thực thi hoạt động kiểm thử.

Thuộc tính này chỉ áp dụng cho các quy tắc gốc, như cc_test, py_testsh_test. Giá trị này không áp dụng cho các quy tắc kiểm thử do Starlark xác định.

size

Chuỗi "enormous", "large", "medium" hoặc "small"; không thể định cấu hình; mặc định là "medium"

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.

Kiểm thử đơn vị được coi là "nhỏ", kiểm thử tích hợp "trung bình" và kiểm thử toàn diện được coi là "lớn" hoặc "lớn". Bazel sử dụng kích thước để xác định thời gian chờ mặc định (có thể bị ghi đè bằng thuộc tính timeout). Thời gian chờ là cho tất cả các kiểm thử trong mục tiêu XÂY DỰNG, không phải cho từng kiểm thử riêng lẻ. Khi kiểm thử được chạy cục bộ, size còn được dùng cho mục đích lên lịch: Bazel cố gắng tôn trọng --local_{ram,cpu}_resources và không áp đảo máy cục bộ bằng cách chạy nhiều kiểm thử nặng cùng một lúc.

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:

Kích thước RAM (tính bằng MB) CPU (tính theo lõi CPU) Thời gian chờ mặc định
nhỏ 20 1 ngắn (1 phút)
trung bình 100 1 vừa (5 phút)
lớn 300 1 dài (15 phút)
khổng lồ 800 1 vĩnh viễn (60 phút)

Biến môi trường TEST_SIZE sẽ được đặt thành giá trị của thuộc tính này khi tạo quy trình kiểm thử.

timeout

Chuỗi "short", "moderate", "long" hoặc "eternal"; không thể định cấu hình; giá trị mặc định bắt nguồn từ thuộc tính size của hoạt động kiểm thử

Khoảng thời gian dự kiến bài kiểm thử sẽ chạy trước khi quay lại.

Mặc dù thuộc tính kích thước của chương trình kiểm thử kiểm soát việc ước tính tài nguyên, nhưng thời gian chờ của chương trình 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 của chương trình kiểm thử. Bạn có thể ghi đè thời gian chờ kiểm thử bằng cờ --test_timeout, ví dụ: để chạy trong một số điều kiện nhất định được biết là chậm. Giá trị thời gian chờ kiểm thử tương ứng với các khoảng thời gian sau:

Giá trị thời gian chờ Khoảng thời gian
ngắn 1 phút
trung bình 5 phút
long 15 phút
vĩnh viễn 60 phút

Đối với những lần khác, thời gian chờ kiểm thử có thể được ghi đè bằng cờ bazel --test_timeout, ví dụ: khi chạy theo cách thủ công trong các điều kiện được xác định là chậm. Giá trị --test_timeout được tính bằng giây. Ví dụ: --test_timeout=120 sẽ đặt thời gian chờ kiểm thử thành 2 phút.

Biến môi trường TEST_TIMEOUT sẽ được đặt thành thời gian chờ kiểm thử (tính bằng giây) khi tạo chương trình kiểm thử.

flaky

Boolean; không thể định cấu hình; mặc định là False

Đánh dấu kiểm tra là không ổn định.

Nếu được đặt, hãy 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 không thành công. Theo mặc định, thuộc tính này được đặt thành False và chương trình kiểm thử chỉ được thực thi một lần. Xin lưu ý rằng bạn thường không nên sử dụng thuộc tính này – các bài kiểm thử phải đạt một cách đáng tin cậy khi xác nhận của chúng đượ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à -1

Chỉ định số lượng phân đoạn song song cần sử dụng để chạy kiểm thử.

Nếu được đặt, giá trị này sẽ ghi đè mọi thông tin 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 sử dụng tham số này để bật tính năng phân đoạn ngay từ đầu. Xem thêm --test_sharding_strategy.

Nếu tính năng phân đoạn kiểm thử được bật, biến môi trường TEST_TOTAL_SHARDS sẽ được đặt thành giá trị này khi tạo đối tượng kiểm thử.

Việc 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ì nhiều khả năng trình kiểm thử sẽ chạy 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

Boolean; không thể định cấu hình; mặc định là False

Buộc kiểm thử chạy cục bộ mà không có hộp cát.

Việc đặt thuộc tính này thành True tương đương với việc cung cấp "local" dưới dạng thẻ (tags=["local"]).

Thuộc tính chung cho tất cả các quy tắc nhị phân (*_binary)

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

Danh sách các chuỗi; chịu sự thay thế $(location)"Tạo biến"mã thông báo mã hoá shell Bourne; không thể định cấu hình; giá trị mặc định là []

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 run hoặc dưới dạng kiểm thử. Các đối số này được truyền trước các đối số được chỉ định trên dòng lệnh bazel run hoặc bazel test.

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 bazel-bin/).

env

Từ điển của chuỗi; các giá trị có thể được thay thế $(location)"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 bazel run thực thi.

Thuộc tính này chỉ áp dụng cho các quy tắc gốc, như cc_binary, py_binarysh_binary. Không áp dụng cho các quy tắc thực thi do Starlark xá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 bazel-bin/).

output_licenses

Danh sách 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 API cấp phép không dùng nữa mà Bazel không còn sử dụng nữa. Đừng 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. 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. Ví dụ: bạn có thể 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 cách sử dụ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ố nhiều 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ý các quy tắc (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ụ: 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 phán đ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 này để biết thêm 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 bài viết 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

Kết quả đầu ra ngầm ẩn trong C++ không còn được dùng nữa. Vui lòng không 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ó đường dẫn về việc ngừng sử dụng nhưng cuối cùng các đường dẫn này 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 đang 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 tạo bản dựng cũng ngầm đòi hỏi một hoặc nhiều mục tiêu tệp đầu ra, có nội dung và ý nghĩa riêng cho từng 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 khai báo một tệp đầu ra nhắm mục tiêu foo_deploy.jar là thành viê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à thành phần hạng nhất của biểu đồ mục tiêu toàn cầu. 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 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. Bạn có thể tham chiếu các phần tử này dưới dạng phần phụ thuộc trong tệp BUILD và bạn có thể quan sát chúng 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 về 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 kết quả ngầm ẩn do việc khai báo loại quy tắc đó đòi hỏi.

Một điểm khác biệt quan trọng nhưng hơi khó thấy 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à 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). Đây là những điều bạn có thể đề cập trong các 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 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ụ: 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ố chi tiết triển khai nhất định về cách công cụ xây dựng thực hiện công việc của mình. Điều này được giải thích đầy đủ hơn trong Tài liệu tham khảo về tính năng XÂY DỰNG.