Quy tắc chung

Quy tắc

• alias
• config_setting
• filegroup
• genquery
• genrule
• 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 ra một tên khác mà quy tắc có thể được gọi.

Tính năng tạo bí danh 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.

Quy tắc bí danh có khai báo khả năng hiển thị riêng. Về mọi mặt khác, nó hoạt động giống như quy tắc mà nó tham chiếu (ví dụ: testonly trên bí danh sẽ bị bỏ qua; thay vào đó, tính chất testonly của quy tắc được tham chiếu sẽ được dùng) với một số trường hợp ngoại lệ nhỏ:

• Các 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, hệ thống không hỗ trợ các bí danh cho quy tắc environment. 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 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 các ràng buộc về nền tảng) cho mục đích kích hoạt các thuộc tính có thể định cấu hình. Hãy xem phần select để biết cách sử dụng quy tắc này và phần Các 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ụ

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

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

Sau đây là mọi bản dựng nhắm đến ARM và áp dụng định nghĩa 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"
      }
  )
  

Sau đây là mọi bản dựng đặt cờ do người dùng xác định --//custom_flags:foo=1 (một cách rõ ràng tại dòng lệnh hoặc một cách ngầm định từ các tệp .bazelrc):

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

Sau đây 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ử có một constraint_value có nhãn //example:glibc_2_25. Xin lưu ý rằng một nền tảng vẫn khớp nếu nền tảng đó xác định các giá trị ràng buộc bổ sung ngoài hai 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 phần 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ợ 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 lệnh gọi này sẽ tự động khớp bằng cách sử dụng một trong hai biểu mẫu.
• Nếu một cờ nhận nhiều giá trị (như --copt=-Da --copt=-Db hoặc cờ Starlark có kiểu danh sách), 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ự: điều này 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 phiên bản: --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). Nhưng --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 tra kỹ các điều kiện để xác minh kỳ vọng chính xác.

• 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 dùng cờ do Starlark xác định. Bạn cũng có thể sử dụng --define, nhưng cách này có khả năng hỗ trợ kém hơn và không nên dùng. Hãy xem tại đây để biết thêm thông tin thảo luận.
• Tránh lặp lại các đị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 một config_setting chung được xác định trong một gói chuẩn.
• values, define_values và constraint_values có thể được dùng theo mọi tổ hợp trong cùng một config_setting nhưng bạn phải đặt ít nhất một trong số các thành phần này cho bất kỳ config_setting nào.

Đố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",
                })
          

filegroup

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 nhóm 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 đến các thư mục. Cách thứ hai không ổn định 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, nên hệ thống có thể không tạo lại khi các tệp này thay đổi. Khi 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õ ràng tất cả các tệp.

Ví dụ

Để tạo một 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 một 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 bằng một 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ố

genquery

genquery(name, deps, data, compatible_with, 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 trong ngôn ngữ truy vấn Blaze và kết xuất kết quả vào một tệp.

Để duy trì bản dựng nhất quán, truy vấn chỉ được phép truy cập vào bao đóng 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 hiện được trong quá trình thực thi nếu strict không được chỉ định hoặc có giá trị true (nếu strict có giá trị false, các mục tiêu ngoài phạm vi sẽ chỉ bị bỏ qua kèm theo một 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ố mục tiêu có 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 bao đóng bắc cầu của truy vấn ảnh hưởng đến đầu ra 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 có ký tự đại diện (ví dụ: deps=["//a/..."] không được phép).

Đầu ra của genquery được sắp xếp bằng cách sử dụng --order_output=full để thực thi đầu ra xác định.

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 nhãn trong bao đóng bắc cầu của mục tiêu đã chỉ định vào một tệp.

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

Đối số

genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exec_tools, 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.

Genrule là các quy tắc chung về bản dựng 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 lệnh Bash. Tuy nhiên, nếu bạn cần biên dịch các tệp C++, hãy tuân thủ các quy tắc cc_* hiện có, vì mọi công việc nặng nhọc đã được thực hiện cho bạn.

Không sử dụng genrule để chạy các kiểm thử. Có những quy định đặc biệt đối với các bài kiểm thử và kết quả kiểm thử, bao gồm cả chính sách lưu vào bộ nhớ đệm và các biến môi trường. Thông thường, bạn cần chạy các kiểm thử sau khi bản dựng hoàn tất và trên cấu trúc mục tiêu, trong khi genrule được thực thi trong quá trình tạo bản dựng và trên cấu trúc máy chủ lưu trữ (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ề quy 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 đầu ra của chúng thường được 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 một bộ 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 trình biên dịch C (nếu được biên dịch từ nguồn) thì phải chạy.

Hệ thống xây dựng sử dụng cấu hình máy chủ lưu trữ để 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. Công cụ này cung cấp các lựa chọn để định cấu hình từng thành phần trong số này và phân tách các tệp tương ứng thành 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 xây dựng một cách thích hợp: srcs được xây dựng (nếu cần) cho cấu hình target, tools được xây dựng cho cấu hình host và đầu ra được coi là cho cấu hình target. Công cụ này cũng cung cấp các biến "Make" mà các lệnh genrule có thể truyền đến các công cụ tương ứng.

Việc genrule không xác định thuộc tính deps là có chủ ý: các quy tắc tích hợp khác sử dụng thông tin meta phụ 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 được mức độ tự động hoá này đối với genrule. Genrules hoạt động hoàn toàn ở cấp độ tệp và tệp chạy.

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

Biên dịch máy chủ lưu trữ: trong một số trường hợp, hệ thống dựng cần chạy genrules để đầu ra cũng có thể được thực thi trong quá trình dựng. Ví dụ: nếu một genrule tạo một trình biên dịch tuỳ chỉnh mà sau đó được một genrule khác sử dụng, thì genrule đầu tiên phải tạo ra đầu ra cho cấu hình máy chủ lưu trữ, 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 bản dựng sẽ tự động thực hiện đúng thao tác: hệ thống sẽ tạo srcs và outs của genrule đầu tiên cho cấu hình máy chủ lưu trữ 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.

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

Môi trường Genrule

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

Công cụ tạo sẽ 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 rằng 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 đều không được truyền qua lệnh genrule. Tuy nhiên, Bazel (nhưng không phải Blaze) sẽ truyền 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 trong lần tạo tiếp theo.

Lệnh genrule không được truy cập vào mạng, ngoại trừ để kết nối các quy trình là các lệnh con của chính lệnh đó, mặc dù hiện tại điều này 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 sẽ 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 xảy ra lỗi.

Lời khuyên chung

• Đảm bảo rằng các công cụ do genrule chạy là xác định và khép kín. Chúng 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 ghi đường dẫn tuyệt đối. Việc không tuân theo quy tắc này sẽ dẫn đến hành vi xây dựng không mong muốn (Bazel không xây dựng lại một genrule mà bạn nghĩ là nó sẽ xây dựng) và làm giảm hiệu suất bộ nhớ đệm.
• Hãy sử dụng $(location) một cách rộng rãi cho đầu ra, công cụ và nguồn. Do sự phân tách các tệp đầu ra cho các cấu hình khác nhau, genrules không thể dựa vào các đường dẫn được mã hoá cứng và/hoặc tuyệt đối.
• Viết một macro Starlark chung trong trường hợp các genrule giống nhau hoặc rất giống nhau được dùng ở nhiều nơi. Nếu genrule phức tạp, hãy cân nhắc việc triển khai genrule đó trong một tập lệnh hoặc dưới dạng một 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ử.
• Đảm bảo rằng mã thoát cho biết chính xác trạng thái thành công hay thất bại của genrule.
• Không ghi thông báo thông tin vào 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ó tiếng ồn. Mặt khác, một genrule không thành công sẽ phát ra thông báo lỗi phù hợp.
• $$ 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 các đườ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 và việc kiểm tra phần phụ thuộc của các thư mục là không hợp lý.
• 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 phương pháp còn lại: việc tham chiếu các đầ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ể tẻ nhạt 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 nhận bất kỳ dữ liệu đầu vào nào. "Nhị phân" do lệnh này chạy là một tập lệnh perl trong cùng 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 filegroup và đầu ra của một genrule khác. Xin lưu ý rằng việc sử dụng $(SRCS) thay vì các chỉ thị $(location) rõ ràng cũng sẽ hoạt động; ví dụ này sử dụng chỉ thị 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ố

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 nhóm các 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 bộ kiểm thử, chẳng hạn như "các kiểm thử bạn phải chạy trước khi đăng ký", "các kiểm thử tải của dự án" hoặc "tất cả các kiểm thử nhỏ". Lệnh blaze test tuân theo cách sắp xếp này: Đối với một lệnh gọi như blaze test //some/test:suite, trước tiên, Blaze sẽ liệt kê tất cả các mục tiêu kiểm thử được bao gồm một cách bắc cầu theo mục tiêu //some/test:suite (chúng ta 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 tất cả các 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 kiểm thử được 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ử không ổn định trong gói hiện tại.

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

Đối số