Định nghĩa phổ biến Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Phần này xác định nhiều thuật ngữ và khái niệm thường gặp trong nhiều hàm hoặc quy tắc xây dựng.

Nội dung

• Phân tích cú pháp Bourne shell
• Mở rộng nhãn
• Các thuộc tính điển hình do hầu hết các quy tắc xây dựng xác định
• Các thuộc tính chung cho tất cả quy tắc xây dựng
• Các thuộc tính chung cho tất cả các quy tắc kiểm thử (*_test)
• Các thuộc tính chung 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

Phân tích cú pháp Bourne shell

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 mã hoá của Bourne shell: khoảng trắng không được trích dẫn sẽ phân tách các từ riêng biệt, còn các ký tự dấu nháy đơn và dấu nháy kép cũng như dấu gạch chéo ngược được dùng để ngăn chặn việc mã hoá.

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 "Make" và mã hoá Bourne shell thường được dùng để truyền các lựa chọn tuỳ ý cho 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 phép thay thế này cho phép một biến chuỗi duy nhất mở rộng thành một danh sách các 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 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 do target //mypkg:target đại diện.

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, chẳng hạn như: nhãn tương đối có được mở rộng hay không; cách xử lý các 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 do hầu hết các quy tắc xây dựng xác định

Phần này mô tả các thuộc tính do nhiều quy tắc xây dựng xác định, 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 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 cho phép mọi mục tiêu.

runfiles của các mục tiêu trong thuộc tính data xuất hiện trong vùng *.runfiles của mọi tệp thực thi đượ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. Điều này có thể bao gồm các tệp dữ liệu hoặc tệp nhị phân được dùng khi srcs của mục tiêu này được thực thi. Thông thường, điều này bao gồm các đầu ra mặc định của mục tiêu và các tệp thời gian chạy bắc cầu của chúng, nhưng điều này phụ thuộc vào việc triển khai các quy tắc cho những mục tiêu đó; hầu hết các quy tắc đều bao gồm các đầu ra mặc định trong runfiles. Hãy xem phần phụ thuộc dữ liệu để biết thêm thông tin về cách phụ thuộc vào và sử dụng tệp dữ liệu.

Các quy tắc mới phải xác định một thuộc tính data nếu chúng xử lý các đầu vào có thể sử dụng các đầu vào khác trong thời gian chạy. Các hàm triển khai của quy tắc cũng phải điền sẵn runfile của mục tiêu từ đầu ra và runfile của mọi thuộc tính data, cũng như runfile từ mọi thuộc tính phần phụ thuộc 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 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ê trực tiếp các tệp trong deps, nhưng bạn nên tránh làm việc này nếu có thể.)

Các quy tắc theo từng 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 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 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ẽ trình bày chi tiết 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 mã do 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 các biểu tượng được xác định trong một mô-đun khác được viết bằng cùng một ngôn ngữ lập trình và được biên dịch riêng. Các phần phụ thuộc đa ngôn ngữ cũng được cho phép trong nhiều trường hợp: Ví dụ: đích java_library có thể phụ thuộc vào mã C++ trong đích cc_library bằng cách liệt kê đích sau trong thuộc tính deps. Hãy xem định nghĩa về phần phụ thuộc để biết thêm thông tin.

licenses

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

Một 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. Không sử dụng cách 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 của quy tắc (chẳng hạn như filegroup hoặc genrule) để đưa các đầu ra mặc định của chúng vào.

Các quy tắc theo từng 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 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 thêm ngầm vào tất cả các quy tắc xây dựng.

Thuộc tính Mô tả aspect_hints

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

Một danh sách các nhãn tuỳ ý được hiển thị cho các khía cạnh (đặc biệt là các khía cạnh được gọi bởi các phần phụ thuộc đảo ngược của quy tắc này), nhưng không được hiển thị cho việc triển khai riêng của quy tắc này. Tham khảo tài liệu về các bộ quy tắc theo ngôn ngữ cụ thể để biết thông tin chi tiết về tác động của một gợi ý cụ thể về khía cạnh.

Bạn có thể coi gợi ý về khía cạnh là một lựa chọn thay thế phong phú hơn cho thẻ: trong khi thẻ chỉ truyền tải trạng thái boolean (thẻ có trong danh sách tags hoặc không), gợi ý về khía cạnh có thể truyền tải thông tin có cấu trúc tuỳ ý trong nhà cung cấp.

Trong thực tế, các gợi ý về khía cạnh được dùng để tương tác giữa các bộ quy tắc dành riêng cho từng ngôn ngữ. Ví dụ: giả sử bạn có một mục tiêu mylang_binary cần phụ thuộc vào mục tiêu otherlang_library. Logic dành riêng cho MyLang cần thêm một số thông tin về mục tiêu OtherLang để sử dụng mục tiêu đó, nhưng otherlang_library không cung cấp thông tin này vì không biết gì về MyLang. Một giải pháp có thể là để bộ quy tắc MyLang xác định một quy tắc mylang_hint có thể dùng để mã hoá thông tin bổ sung đó; người dùng có thể thêm gợi ý vào aspect_hints của otherlang_library và mylang_binary có thể dùng một khía cạnh để thu thập thông tin bổ sung từ một nhà cung cấp dành riêng cho MyLang trong mylang_hint.

Để biết ví dụ cụ thể, hãy xem swift_interop_hint và swift_overlay trong rules_swift.

Các phương pháp hay nhất:

• Các mục tiêu được liệt kê trong aspect_hints phải gọn nhẹ và tối giản.
• Logic dành riêng cho ngôn ngữ chỉ nên xem xét những gợi ý về khía cạnh có nhà cung cấp liên quan đến ngôn ngữ đó và nên bỏ qua mọi gợi ý khác về khía cạnh.

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 mà mục tiêu này có thể được tạo, 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 ràng buộc của Bazel, cho phép người dùng khai báo những mục tiêu có thể và không thể phụ thuộc vào 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. 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à None

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, điều này được 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à riêng tư đối với một gói hoặc có thể được coi là gây hại vì một lý do nào đó. Bạn nên thêm một số thông tin tham khảo (chẳng hạn như trang web, số lỗi hoặc ví dụ về các 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 làm giải pháp thay thế tức thì, thì bạn 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 thành phần, nhưng có thể ảnh hưởng đến đầu ra chẩn đoán của một công cụ tạo. Công cụ tạo bản dựng sẽ đưa ra cảnh báo khi một quy tắc có thuộc tính deprecation được một mục tiêu trong gói khác phụ thuộc vào.

Các phần phụ thuộc trong gói được miễn cảnh báo này, do đó, chẳng hạn như việc tạo các 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ông dùng nữa khác, 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.

exec_compatible_with

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

Một danh sách constraint_values phải có trong nền tảng thực thi của nhóm thực thi mặc định của mục tiêu này. Điều này bổ sung cho mọi ràng buộc mà loại quy tắc đã đặt. Các điều kiện 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 chuỗi công cụ. và nhóm thực thi

exec_group_compatible_with

Từ điển gồm các chuỗi đến danh sách nhãn; không thể định cấu hình; mặc định là {}

Từ điển tên nhóm thực thi đến danh sách constraint_values phải có trong nền tảng thực thi cho nhóm thực thi đã cho. Điều này bổ sung cho mọi ràng buộc đã được đặt trong định nghĩa của nhóm thực thi. Các điều kiện 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 chuỗi công cụ. và nhóm thực thi

exec_properties

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

Một từ điển gồm các chuỗi sẽ được thêm vào exec_properties của một nền tảng được chọn cho mục tiêu này. Xem exec_properties của quy tắc nền tảng.

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

Bạn có thể thêm tiền tố cho các khoá bằng tên của một nhóm thực thi, sau đó là . để chỉ áp dụng các khoá đó cho nhóm thực thi cụ thể đó.

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ể 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 features ở cấp package. 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ụ.

package_metadata

Danh sách nhãn; không thể định cấu hình; mặc định là default_package_metadata của gói

Danh sách các nhãn là siêu dữ liệu liên kết về mục tiêu này. Thông thường, các nhãn là những quy tắc đơn giản trả về một nhà cung cấp các giá trị hằng số. Các quy tắc và khía cạnh có thể sử dụng những nhãn này để thực hiện một số phân tích bổ sung trên biểu đồ bản dựng.

Trường hợp sử dụng chuẩn tắc là trường hợp rules_license. Đối với trường hợp sử dụng đó, package_metadata và default_package_metadata được dùng để đính kèm thông tin về giấy phép hoặc phiên bản của một gói vào các mục tiêu. Bạn có thể dùng một khía cạnh được áp dụng cho tệp nhị phân cấp cao nhất để thu thập những khía cạnh đó và tạo báo cáo tuân thủ.

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 mà mục tiêu này có thể được tạo, 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 compatible_with để biết thông tin chi tiết.

tags

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

Bạn có thể dùng thẻ cho mọi quy tắc. Thẻ trên các quy tắc kiểm thử và test_suite rất hữu ích để phân loại các kiểm thử. Thẻ trên các mục tiêu không phải mục tiêu kiểm thử được dùng để kiểm soát quá trình thực thi trong hộp cát của genrule và các thao tác Starlark, cũng như để phân tích cú pháp bởi con người và/hoặc các công cụ bên ngoài.

Bazel sẽ 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 bất kỳ mục tiêu kiểm thử hoặc genrule nào, hoặc các khoá của execution_requirements cho bất kỳ thao tác Starlark nào.

• no-sandbox từ khoá dẫn đến hành động hoặc thử nghiệm không bao giờ được đưa vào hộp cát; nó 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 chặn một hoặc cả hai điều đó.
• no-cache kết quả từ khoá trong thao tác hoặc thử nghiệm không bao giờ được lưu vào bộ nhớ đệm (trên thiết bị hoặc từ xa). Lưu ý: đối với 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.
• no-remote-cache kết quả từ khoá trong thao tác hoặc kiểm thử không bao giờ được lưu vào bộ nhớ đệm từ xa (nhưng có thể được lưu vào bộ nhớ đệm cục bộ; thao tác hoặc kiểm thử cũng có thể được thực thi từ xa). Lưu ý: đối với 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 dùng kết hợp bộ nhớ đệm của ổ đĩa cục bộ và bộ nhớ đệm từ xa (bộ nhớ đệm kết hợp), thì bộ nhớ đệm này sẽ được coi là bộ nhớ đệm từ xa và bị vô hiệu hoá hoàn toàn, trừ phi -incompatible_remote_results_ignore_disk được đặt. Trong trường hợp đó, các thành phần cục bộ sẽ được dùng.
• Kết quả từ khoá no-remote-exec trong thao tác hoặc 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 không cho hành động hoặc kiểm thử được thực thi từ xa hoặc đượ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-cache và no-remote-exec.
• Từ khoá no-remote-cache-upload sẽ tắt phần tải lên của tính năng lưu vào bộ nhớ đệm từ xa của một spawn. thao tác này không vô hiệu hoá việc thực thi từ xa.
• Từ khoá local ngăn không cho hành động hoặc thử nghiệm được lưu vào bộ nhớ đệm từ xa, thực thi từ xa hoặc chạy trong hộp cát. Đối với genrules và cá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 bạn bật tính năng chạy trong môi trường hộp cát.
• Khối 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 bạn bật tính năng chạy trong môi trường hộp cát.
• requires-fakeroot chạy thử nghiệm 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 tuỳ chọn dòng lệnh -sandbox_fake_username.

Thẻ trong các 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 kiểm thử C++ và Python, vốn không có khả năng chú thích thời gian chạy. Việc sử dụng các thẻ và 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 thử nghiệm 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 kiểm thử chạy ở chế độ "độc quyền", đảm bảo rằng không có kiểm thử nào khác đang chạy cùng lúc. Các kiểm thử như vậy sẽ được thực thi theo tuần tự sau khi tất cả hoạt động xây dựng và kiểm thử không độc quyền đã hoàn tất. Tính năng thực thi từ xa bị vô hiệu hoá đối với các kiểm thử như vậy vì Bazel không kiểm soát được những gì đang chạy trên một máy từ xa.
• exclusive-if-local sẽ buộc kiểm thử chạy ở chế độ "độc quyền" nếu được thực thi cục bộ, nhưng sẽ chạy 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 ký tự đại diện của 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 kiểm thử khi tính toán tập hợp các mục tiêu cấp cao nhất để tạo/chạy cho các lệnh build, test và coverage. Việc này không ảnh hưởng đến ký tự đại diện mục tiêu hoặc việc mở rộng bộ thử nghiệm trong các bối cảnh khác, kể cả lệnh query. Xin lưu ý rằng manual không có nghĩa là các hệ thống bản dựng/kiểm thử liên tục không được tự động tạo/chạy một mục tiêu. Ví dụ: bạn có thể muốn loại trừ một mục tiêu khỏi bazel test ... vì mục tiêu đó yêu cầu các cờ Bazel cụ thể, nhưng vẫn đưa mục tiêu đó vào các lần chạy kiểm thử liên tục hoặc kiểm thử trước khi gửi được định cấu hình đúng cách.
• Từ khoá external sẽ buộc kiểm thử được thực thi vô điều kiện (bất kể giá trị -cache_test_results).

Xem phần Quy ước về thẻ trong Bách khoa toàn thư về kiểm thử để biết thêm các quy ước về thẻ được đính kèm vào mục tiêu kiểm thử. target_compatible_with

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

Một danh sách các constraint_value phải có trong nền tảng nhắm mục tiêu để mục tiêu này được coi là tương thích. Điều này bổ sung cho mọi ràng buộc mà loại quy tắc đã đặt. Nếu nền tảng nhắm mục tiêu không đáp ứng tất cả các giới hạn được liệt kê, thì mục tiêu đó sẽ được coi là không tương thích. Các mục tiêu không tương thích sẽ bị bỏ qua khi 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 khi tạo hoặc thất bại trong 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 cũng được coi là không tương thích. Chúng cũng bị bỏ qua khi xây dựng và kiểm thử.

Một danh sách trống (theo 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 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 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 định cấu hình được; mặc định là False, ngoại trừ các mục tiêu kiểm thử và bộ kiểm thử

Nếu True, chỉ các mục tiêu testonly (chẳng hạn như các kiểm thử) 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à testonly sẽ không được phép phụ thuộc vào bất kỳ quy tắc nào là testonly.

Các kiểm thử (quy tắc *_test) và bộ kiểm thử (quy tắc test_suite) được testonly theo mặc định.

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 cho bản phát hành công khai.

Vì testonly được thực thi tại thời gian xây dựng, chứ không phải thời gian chạy và lan 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 một cách thận trọng. Ví dụ: các phần giữ chỗ và dữ liệu 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 đó, bạn không nên đánh dấu testonly. Ngược lại, những quy tắc nguy hiểm ngay cả khi được liên kết, có lẽ vì chúng ghi đè vô điều kiện hành vi bình thường, chắc chắn phải được đánh dấu là testonly.

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 mà Biến tạo của mục tiêu này được phép truy cập. Các mục tiêu này là các phiên bản của quy tắc cung cấp TemplateVariableInfo hoặc cá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 quốc gia/khu vực này bao gồm:

• @bazel_tools//tools/cpp:toolchain_type
• @rules_java//toolchains:current_java_runtime

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ụ 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ể 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; mặc định sẽ khác nhau

Thuộc tính visibility kiểm soát việc các mục tiêu ở những vị trí khác có thể phụ thuộc vào mục tiêu hay không. Hãy xem tài liệu về khả năng hiển thị.

Đố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à default_visibility của gói nếu được chỉ định, nếu không thì là ["//visibility:private"]. Đối với các mục tiêu được khai báo trong một hoặc nhiều macro tượng trưng, giá trị mặc định luôn chỉ là ["//visibility:private"] (điều này khiến mục tiêu chỉ có thể sử dụng được trong gói chứa mã của macro).

Các 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ả các quy tắc kiểm thử.

Thuộc tính Mô tả args

Danh sách các chuỗi; tuỳ thuộc vào việc thay thế $(location) và "Tạo biến", cũng như phân tích cú pháp Bourne shell; giá trị 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 bazel test.

Các đối số này được truyền trước mọi giá trị -test_arg được chỉ định trên dòng lệnh bazel test.

env

Từ điển gồm các chuỗi; các giá trị phải tuân theo quy tắc thay thế $(location) và "Make variable"; 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 kiểm thử được thực thi bằng bazel test.

Thuộc tính này chỉ áp dụng cho các quy tắc gốc, chẳng hạn như cc_test, py_test và sh_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 bạn, bạn có thể thêm một thuộc tính "env" và sử dụng thuộc tính đó để điền thông tin cho Trình cung cấp RunEnvironmentInfo.

TestEnvironment Nhà cung cấp. env_inherit

Danh sách các 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 kiểm thử được thực thi bằng bazel test.

Thuộc tính này chỉ áp dụng cho các quy tắc gốc, chẳng hạn như cc_test, py_test và sh_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.

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ử: cần bao nhiêu thời gian/tài nguyê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 để 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 timeout. Thời gian chờ áp dụng cho tất cả các kiểm thử trong mục tiêu BUILD, chứ không phải cho từng kiểm thử riêng lẻ. Khi kiểm thử chạy cục bộ, size cũng được dùng cho mục đích lập lịch: Bazel cố gắng tuân thủ -local_{ram,cpu}_resources và không làm quá tải 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 các thời gian chờ mặc định sau đây và giả định mức sử dụng tài nguyên cục bộ cao nhất:

Kích thước RAM (tính bằng MB) CPU (tính bằng số 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) to lớn 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 thử nghiệm.

timeout

Chuỗi "short", "moderate", "long" hoặc "eternal"; không thể định cấu hình; giá trị mặc định được lấy từ thuộc tính size của kiểm thử

Thời gian dự kiến chạy thử nghiệm trước khi trả về.

Mặc dù thuộc tính kích thước của một 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 một kiểm thử 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 kiểm thử. Bạn có thể ghi đè thời gian chờ kiểm thử bằng cờ -test_timeout, chẳng hạn như để 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 cửu 60 phút

Đối với những lần khác ngoài các lần nêu trên, bạn có thể ghi đè thời gian chờ kiểm thử bằng cờ -test_timeout bazel, chẳng hạn như để chạy theo cách thủ công trong các điều kiện được biết là chậm. Các giá trị -test_timeout 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 kiểm thử.

flaky

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

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

Nếu được đặt, sẽ thực thi kiểm thử tối đa 3 lần, chỉ đánh dấu 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à quá 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 chạy thành công một cách đáng tin cậy khi các câu khẳng định được duy trì.

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 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ể phải 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 bạn bật tính năng phân đoạn kiểm thử, biến môi trường TEST_TOTAL_SHARDS sẽ được đặt thành giá trị này khi tạo kiểm thử.

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ì có nhiều khả năng nó sẽ chạy mọi kiểm thử trong mọi phân đoạn, điều này không phải là điều bạn muốn.

Hãy xem bài viết 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ề việc 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ầ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ẻ (tags=["local"]).

Các thuộc tính chung cho tất cả các 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; tuỳ thuộc vào việc thay thế $(location) và "Make variable", cũng như Bourne shell tokenization; nonconfigurable; mặc định là []

Đối số dòng lệnh mà Bazel sẽ chuyển đến mục tiêu khi mục tiêu đó được thực thi bằng lệnh run hoặc dưới dạng một 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ố 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 gồm các chuỗi; các giá trị phải tuân theo quy tắc thay thế $(location) và "Make variable"; 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, chẳng hạn như cc_binary, py_binary và sh_binary. Việc này không áp dụng cho các quy tắc thực thi 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 một thuộc tính "env" và sử dụng thuộc tính đó để điền thông tin cho Nhà cung cấp RunEnvironmentInfo.

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 các 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. Không sử dụng cách này.

Thuộc tính có thể thiết lập

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 chúng 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 những gì mà phần phụ thuộc hạ lưu đ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 đích 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ý các quy tắc (về mặt kỹ thuật, giữa giai đoạn tải và phân tích). Mọi quy 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 những 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. 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.

Những thuộc tính được đánh dấu 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 sẽ không thể định cấu hình vì 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 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

Đầu ra ngầm trong C++ không được dùng nữa. Vui lòng tránh sử dụng cụm từ 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 ngừng cung cấp nhưng chúng cũng sẽ ngừng cung cấp.

Khi xác định một 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 kéo theo 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 khai báo mục tiêu tệp đầu ra 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 kho lưu trữ Java độc lập phù hợp để triển khai.)

Các mục tiêu đầu ra ngầm định là thành viê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, 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 chúng là điều kiện tiên quyết cần thiết cho các mục tiêu tạo khác. Chúng có thể được tham chiếu dưới dạng các phần phụ thuộc trong tệp BUILD và có thể được quan sát trong đầu ra của các công cụ phân tích như bazel query.

Đối với mỗi loại quy tắc tạo bản dựng, tài liệu của quy tắc sẽ có 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 định do một khai báo về loại quy tắc đó gây ra.

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 đầu vào) và mục tiêu tệp phái sinh (hoặc đầu ra). Đây là những thứ 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 cách sử dụ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 không, một hoặc nhiều tệp thực tế trên ổ đĩa. Có thể có những 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ừ bên trong tệp BUILD hoặc từ dòng lệnh. Bằng cách này, công cụ tạo có thể ẩn một số thông tin chi tiết về cách triển khai của cách công cụ này 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.