Quy tắc chung

Quy tắc

• bí danh
• config_setting
• nhóm tệp
• genquery
• genrule
• starlark_doc_extract
• test_suite

bí danh

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

Quy tắc alias tạo một tên khác mà bạn có thể dùng để tham chiếu đến quy tắc.

Gán biệt hiệu chỉ hoạt động đối với các mục tiêu "thông thường". Cụ thể, bạn không thể đặt bí danh cho package_group và test_suite.

Việc sử dụng bí danh có thể hữu ích trong các kho lưu trữ lớn, trong đó việc đổi tên một mục tiêu sẽ yêu cầu bạn thực hiện các thay đổi đối với nhiều tệp. Bạn cũng có thể sử dụng quy tắc đại diện để lưu trữ lệnh gọi hàm select (chọn) nếu muốn sử dụng lại logic đó cho nhiều mục tiêu.

Quy tắc bí danh có phần khai báo chế độ hiển thị riêng. Ở mọi khía cạnh khác, quy tắc này sẽ hoạt động giống như quy tắc mà nó tham chiếu (ví dụ: chỉ kiểm thử trên bí danh sẽ bị bỏ qua; hoạt động chỉ kiểm thử của quy tắc được tham chiếu sẽ được sử dụng) với một số ngoại lệ nhỏ:

• Các chương trình kiểm thử sẽ không chạy nếu bí danh của chúng được đề cập trên dòng lệnh. Để xác định một bí danh chạy kiểm thử được tham chiếu, hãy sử dụng quy tắc test_suite với một mục tiêu duy nhất trong thuộc tính tests.
• Khi xác định nhóm môi trường, các bí danh cho quy tắc environment không được hỗ trợ. Các tuỳ chọn này cũng không được hỗ trợ trong tuỳ chọn dòng lệnh --target_environment.

Ví dụ

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

Đối số

config_setting

config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

So khớp với trạng thái cấu hình dự kiến (được biểu thị dưới dạng cờ bản dựng hoặc quy tắc ràng buộc nền tảng) nhằm mục đích kích hoạt các thuộc tính có thể định cấu hình. Hãy xem select để biết cách sử dụng quy tắc này và Thuộc tính có thể định cấu hình để biết thông tin tổng quan về tính năng chung.

Ví dụ

Nội dung sau đây khớp với mọi bản dựng đặt --compilation_mode=opt hoặc -c opt (rõ ràng ở dòng lệnh hoặc ngầm ẩn từ tệp .bazelrc):

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

Mã sau đây khớp với mọi bản dựng nhắm mục tiêu ARM và áp dụng xác định tuỳ chỉnh FOO=bar (ví dụ: bazel build --cpu=arm --define FOO=bar ...):

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )
  

Phần sau đây khớp với mọi bản dựng đặt cờ do người dùng xác định --//custom_flags:foo=1 (thể hiện rõ ràng tại dòng lệnh hoặc ngầm ẩn trong các tệp .bazelrc):

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

Đoạn mã sau khớp với mọi bản dựng nhắm đến một nền tảng có cấu trúc x86_64 và glibc phiên bản 2.25, giả sử tồn tại một constraint_value có nhãn //example:glibc_2_25. Xin lưu ý rằng một nền tảng vẫn trùng khớp nếu nền tảng đó xác định thêm các giá trị ràng buộc khác ngoài 2 giá trị này.

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  

Ghi chú

• Hãy xem select để biết điều gì sẽ xảy ra khi nhiều config_setting khớp với trạng thái cấu hình hiện tại.
• Đối với các cờ hỗ trợ các dạng viết tắt (ví dụ: --compilation_mode so với -c), định nghĩa values phải sử dụng dạng đầy đủ. Các hàm này tự động khớp lệnh gọi bằng một trong hai biểu mẫu.
• Nếu một cờ nhận nhiều giá trị (chẳng hạn như --copt=-Da --copt=-Db hoặc cờ Starlark có kiểu danh sách), thì values = { "flag": "a" } sẽ khớp nếu "a" xuất hiện ở bất kỳ vị trí nào trong danh sách thực tế.

  values = { "myflag": "a,b" } hoạt động theo cách tương tự: khớp với --myflag=a --myflag=b, --myflag=a --myflag=b --myflag=c, --myflag=a,b và --myflag=c,b,a. Ngữ nghĩa chính xác khác nhau giữa các cờ. Ví dụ: --copt không hỗ trợ nhiều giá trị trong cùng một bản sao: --copt=a,b tạo ra ["a,b"] trong khi --copt=a --copt=b tạo ra ["a", "b"] (vì vậy, values = { "copt": "a,b" } khớp với giá trị trước nhưng không khớp với giá trị sau). Tuy nhiên, --ios_multi_cpus (đối với các quy tắc của Apple) có: -ios_multi_cpus=a,b và ios_multi_cpus=a --ios_multi_cpus=b đều tạo ra ["a", "b"]. Kiểm tra định nghĩa cờ và kiểm thử kỹ các điều kiện để xác minh chính xác các kỳ vọng.

• Nếu bạn cần xác định các điều kiện không được mô hình hoá bằng cờ bản dựng tích hợp, hãy sử dụng cờ do Starlark xác định. Bạn cũng có thể sử dụng --define, nhưng tính năng này cung cấp dịch vụ hỗ trợ yếu hơn và không nên dùng. Hãy xem nội dung thảo luận tại đây để biết thêm thông tin.
• Tránh lặp lại định nghĩa config_setting giống hệt nhau trong các gói khác nhau. Thay vào đó, hãy tham chiếu đến một config_setting chung được xác định trong một gói chính tắc.
• Bạn có thể sử dụng values, define_values và constraint_values theo bất kỳ tổ hợp nào trong cùng config_setting nhưng phải đặt ít nhất một tổ hợp cho config_setting bất kỳ.

Đối số

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })
          

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })
          

nhóm tệp

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

Sử dụng filegroup để đặt tên thuận tiện cho một tập hợp mục tiêu. Sau đó, bạn có thể tham chiếu các quy tắc này từ các quy tắc khác.

Bạn nên sử dụng filegroup thay vì tham chiếu trực tiếp các thư mục. Cách sau không hợp lý vì hệ thống xây dựng không có đầy đủ thông tin về tất cả các tệp bên dưới thư mục, vì vậy, hệ thống có thể không tạo lại khi các tệp này thay đổi. Khi được kết hợp với glob, filegroup có thể đảm bảo rằng hệ thống xây dựng đã biết rõ tất cả các tệp.

Ví dụ

Để tạo filegroup bao gồm hai tệp nguồn, hãy làm như sau

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

Hoặc sử dụng glob để tìm kiếm thư mục testdata:

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

Để sử dụng các định nghĩa này, hãy tham chiếu filegroup cùng với nhãn từ bất kỳ quy tắc nào:

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

Đối số

truy vấn tạo

genquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery() chạy một truy vấn được chỉ định bằng Ngôn ngữ truy vấn tăng dần và kết xuất kết quả vào một tệp.

Để đảm bảo bản dựng luôn nhất quán, truy vấn chỉ được phép truy cập vào đóng bắc cầu của các mục tiêu được chỉ định trong thuộc tính scope. Các truy vấn vi phạm quy tắc này sẽ không thực thi được nếu strict không được chỉ định hoặc là true (nếu strict là false, các mục tiêu nằm ngoài phạm vi sẽ chỉ bị bỏ qua kèm theo cảnh báo). Cách dễ nhất để đảm bảo điều này không xảy ra là đề cập đến các nhãn tương tự trong phạm vi như trong biểu thức truy vấn.

Điểm khác biệt duy nhất giữa các truy vấn được phép ở đây và trên dòng lệnh là các truy vấn chứa thông số kỹ thuật của mục tiêu ký tự đại diện (ví dụ: //pkg:* hoặc //pkg:all) không được phép ở đây. Có hai lý do cho việc này: thứ nhất, vì genquery phải chỉ định một phạm vi để ngăn các mục tiêu bên ngoài tập hợp đóng bắc cầu của truy vấn ảnh hưởng đến kết quả của truy vấn; và thứ hai, vì các tệp BUILD không hỗ trợ các phần phụ thuộc ký tự đại diện (ví dụ: không cho phép deps=["//a/..."]).

Đầu ra của genquery được sắp xếp theo thứ tự bảng chữ cái để thực thi đầu ra có thể xác định, ngoại trừ --output=graph|minrank|maxrank hoặc khi somepath được dùng làm hàm cấp cao nhất.

Tên của tệp đầu ra là tên của quy tắc.

Ví dụ

Ví dụ này ghi danh sách các nhãn trong tập hợp đóng bắc cầu của mục tiêu được chỉ định vào một tệp.

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

Đối số

quy tắc tạo sinh

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule tạo một hoặc nhiều tệp bằng lệnh Bash do người dùng xác định.

Genrules là các quy tắc xây dựng chung mà bạn có thể sử dụng nếu không có quy tắc cụ thể nào cho tác vụ. Ví dụ: bạn có thể chạy một dòng chữ Bash. Tuy nhiên, nếu bạn cần biên dịch tệp C++, hãy tuân theo các quy tắc cc_* hiện có vì mọi công việc phức tạp đã được thực hiện cho bạn.

Lưu ý rằng quy tắc gen yêu cầu một shell để diễn giải đối số lệnh. Bạn cũng có thể dễ dàng tham chiếu các chương trình tuỳ ý có trên PATH, tuy nhiên điều này khiến lệnh không kín và có thể không tái tạo được. Nếu bạn chỉ cần chạy một công cụ duy nhất, hãy cân nhắc sử dụng run_binary.

Không sử dụng genrule để chạy kiểm thử. Có những sự khác biệt đặc biệt đối với các kiểm thử và kết quả kiểm thử, bao gồm cả các chính sách lưu vào bộ nhớ đệm và các biến môi trường. Các chương trình kiểm thử thường cần được chạy sau khi bản dựng hoàn tất và trên cấu trúc mục tiêu, trong khi genrules được thực thi trong quá trình tạo bản dựng và trên cấu trúc thực thi (hai cấu trúc này có thể khác nhau). Nếu bạn cần một quy tắc kiểm thử cho mục đích chung, hãy sử dụng sh_test.

Những điều cần cân nhắc khi biên dịch chéo

Xem hướng dẫn sử dụng để biết thêm thông tin về quá trình biên dịch chéo.

Mặc dù genrules chạy trong quá trình tạo bản dựng, nhưng kết quả của chúng thường được sử dụng sau khi tạo bản dựng, để triển khai hoặc kiểm thử. Hãy xem xét ví dụ về việc biên dịch mã C cho một bộ vi điều khiển: trình biên dịch chấp nhận các tệp nguồn C và tạo mã chạy trên vi điều khiển. Rõ ràng là mã được tạo không thể chạy trên CPU dùng để tạo mã đó, nhưng chính trình biên dịch C (nếu được biên dịch từ nguồn) phải chạy.

Hệ thống xây dựng sử dụng cấu hình thực thi để mô tả(các) máy mà bản dựng chạy và cấu hình mục tiêu để mô tả(các) máy mà đầu ra của bản dựng sẽ chạy trên đó. Lớp này cung cấp các tuỳ chọn để định cấu hình từng yếu tố trong số này và tách các tệp tương ứng vào các thư mục riêng biệt để tránh xung đột.

Đối với genrules, hệ thống xây dựng đảm bảo rằng các phần phụ thuộc được tạo một cách thích hợp: srcs được tạo (nếu cần) cho cấu hình target, tools được tạo cho cấu hình exec và đầu ra được coi là dành cho cấu hình target. Tệp này cũng cung cấp các biến "Tạo" mà lệnh genrule có thể truyền đến các công cụ tương ứng.

Có chủ ý khi genRule không xác định thuộc tính deps: các quy tắc tích hợp sẵn khác sử dụng siêu thông tin tuỳ thuộc vào ngôn ngữ được truyền giữa các quy tắc để tự động xác định cách xử lý các quy tắc phụ thuộc, nhưng không thể tự động hoá quy tắc genrules. Genrules hoạt động hoàn toàn ở cấp tệp và runfiles.

Trường hợp đặc biệt

Biên dịch thực thi: trong một số trường hợp, hệ thống xây dựng cần chạy genrules để đầu ra cũng có thể được thực thi trong quá trình tạo bản dựng. Ví dụ: nếu một genrule tạo một số trình biên dịch tuỳ chỉnh được một genrule khác sử dụng sau đó, thì genrule đầu tiên phải tạo đầu ra cho cấu hình thực thi, vì đó là nơi trình biên dịch sẽ chạy trong genrule khác. Trong trường hợp này, hệ thống xây dựng sẽ tự động thực hiện đúng việc: tạo srcs và outs của genrule đầu tiên cho cấu hình thực thi thay vì cấu hình mục tiêu. Hãy xem hướng dẫn sử dụng để biết thêm thông tin.

Công cụ JDK và C++: để sử dụng một công cụ trong bộ biên dịch JDK hoặc C++, hệ thống xây dựng sẽ cung cấp một tập hợp các biến để sử dụng. Hãy xem biến "Make" để biết chi tiết.

Môi trường genrule

Lệnh genrule được thực thi bằng một shell Bash được định cấu hình để không thành công khi một lệnh hoặc quy trình không thành công, sử dụng set -e -o pipefail.

Công cụ bản dựng thực thi lệnh Bash trong một môi trường quy trình đã được dọn dẹp chỉ xác định các biến cốt lõi như PATH, PWD, TMPDIR và một số biến khác. Để đảm bảo các bản dựng có thể tái tạo, hầu hết các biến được xác định trong môi trường shell của người dùng sẽ không được truyền đến lệnh của genrule. Tuy nhiên, Bazel (nhưng không phải Blaze) chuyển qua giá trị của biến môi trường PATH của người dùng. Mọi thay đổi đối với giá trị của PATH sẽ khiến Bazel thực thi lại lệnh trên bản dựng tiếp theo.

Lệnh genRules không được truy cập vào mạng, ngoại trừ việc kết nối các quy trình là con của chính lệnh đó, mặc dù lệnh này hiện không được thực thi.

Hệ thống xây dựng sẽ tự động xoá mọi tệp đầu ra hiện có, nhưng tạo mọi thư mục mẹ cần thiết trước khi chạy genrule. Thao tác này cũng sẽ xoá mọi tệp đầu ra trong trường hợp không thành công.

Lời khuyên chung

• Đảm bảo rằng các công cụ chạy theo quy tắc tạo sinh có tính tất định và mang tính khép kín. Các hàm này không được ghi dấu thời gian vào đầu ra và phải sử dụng thứ tự ổn định cho các tập hợp và bản đồ, cũng như chỉ ghi đường dẫn tệp tương đối vào đầu ra, không có đường dẫn tuyệt đối. Việc không tuân thủ quy tắc này sẽ dẫn đến hành vi xây dựng không mong muốn (Bazel không tạo lại genrule mà bạn nghĩ là sẽ tạo lại) và làm giảm hiệu suất bộ nhớ đệm.
• Hãy sử dụng $(location) rộng rãi cho các đầu ra, công cụ và nguồn. Do việc phân tách các tệp đầu ra cho nhiều cấu hình, genrules không thể dựa vào các đường dẫn tuyệt đối và/hoặc được mã hoá cứng.
• Hãy viết một macro Starlark phổ biến trong trường hợp các genrules giống nhau hoặc rất giống nhau được sử dụng ở nhiều vị trí. Nếu quy tắc tạo sinh phức tạp, hãy cân nhắc triển khai quy tắc này trong một tập lệnh hoặc dưới dạng quy tắc Starlark. Điều này giúp cải thiện khả năng đọc cũng như khả năng kiểm thử.
• Hãy đảm bảo rằng mã thoát cho biết chính xác quy tắc gen được tạo thành công hay không thành công.
• Không viết thư cung cấp thông tin cho stdout hoặc stderr. Mặc dù hữu ích cho việc gỡ lỗi, nhưng điều này có thể dễ dàng trở thành tiếng ồn; một genrule thành công sẽ không có âm thanh. Mặt khác, quy tắc gen không thành công sẽ phát ra các thông báo lỗi tốt.
• $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x).
• Tránh tạo đường liên kết tượng trưng và thư mục. Bazel không sao chép cấu trúc thư mục/đường liên kết tượng trưng do genrules tạo ra và việc kiểm tra phần phụ thuộc các thư mục là không phù hợp.
• Khi tham chiếu genrule trong các quy tắc khác, bạn có thể sử dụng nhãn của genrule hoặc nhãn của từng tệp đầu ra. Đôi khi, một phương pháp dễ đọc hơn, đôi khi là phương pháp khác: tham chiếu đầu ra theo tên trong srcs của quy tắc sử dụng sẽ tránh vô tình chọn các đầu ra khác của genrule, nhưng có thể gây phiền toái nếu genrule tạo ra nhiều đầu ra.

Ví dụ

Ví dụ này tạo ra foo.h. Không có nguồn nào vì lệnh này không lấy bất kỳ dữ liệu đầu vào nào. "Tệp nhị phân" do lệnh này chạy là một tập lệnh perl trong cùng một gói với genrule.

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

Ví dụ sau đây cho thấy cách sử dụng một filegroup và kết quả của một genrule khác. Hãy lưu ý rằng bạn cũng có thể dùng $(SRCS) thay vì $(location) rõ ràng. Ví dụ này dùng lệnh sau cho mục đích minh hoạ.

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

Đối số

starlark_doc_extract

starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract() trích xuất tài liệu cho các quy tắc, hàm (bao gồm cả macro), khía cạnh và trình cung cấp được xác định hoặc xuất lại trong tệp .bzl hoặc .scl nhất định. Đầu ra của quy tắc này là một proto nhị phân ModuleInfo như được xác định trong stardoc_output.proto trong cây nguồn Bazel.

Các mục tiêu đầu ra ngầm ẩn

• name.binaryproto (đầu ra mặc định): Một proto nhị phân ModuleInfo.
• name.textproto (chỉ được tạo nếu được yêu cầu rõ ràng): phiên bản proto văn bản của name.binaryproto.

Cảnh báo: định dạng đầu ra của quy tắc này không đảm bảo sẽ ổn định. API này chủ yếu dành cho Stardoc sử dụng nội bộ.

Đối số

test_suite

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

test_suite xác định một tập hợp các bài kiểm thử được coi là "hữu ích" đối với con người. Điều này cho phép các dự án xác định các tập hợp kiểm thử, chẳng hạn như "các chương trình kiểm thử bạn phải chạy trước khi nhận phòng", "kiểm thử nghiêm ngặt của dự án" hoặc "tất cả các chương trình kiểm thử nhỏ". Lệnh blaze test tuân theo kiểu tổ chức này: Đối với lệnh gọi như blaze test //some/test:suite, trước tiên, Blaze liệt kê tất cả mục tiêu kiểm thử được mục tiêu //some/test:suite đưa vào một cách bắc cầu (chúng tôi gọi đây là "mở rộng test_suite"), sau đó Blaze sẽ tạo và kiểm thử các mục tiêu đó.

Ví dụ

Một bộ kiểm thử để chạy mọi bài kiểm thử nhỏ trong gói hiện tại.

test_suite(
    name = "small_tests",
    tags = ["small"],
)

Một bộ kiểm thử chạy một tập hợp các chương trình kiểm thử đã chỉ định:

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

Một bộ kiểm thử để chạy tất cả các kiểm thử trong gói hiện tại mà không bị gián đoạn.

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

Đối số