Tạo quy tắc

Trong tệp .bzl, hãy dùng hàm rule để xác định một quy tắc mới và lưu trữ kết quả trong một biến chung. Lệnh gọi đến rule chỉ định các thuộc tính và một hàm triển khai:Thao tác này xác định một loại quy tắc có tên là example_library.Lệnh gọi đến rule cũng phải chỉ định xem quy tắc có tạo đầu ra có thể thực thi (với executable = True) hay cụ thể là một tệp thực thi kiểm thử (với test = True). Nếu là tệp thực thi kiểm thử, thì quy tắc này là một quy tắc kiểm thử và tên của quy tắc phải kết thúc bằng _test.

Hoạt động khởi tạo mục tiêu

Bạn có thể tải và gọi các quy tắc trong tệp BUILD:Mỗi lệnh gọi đến một quy tắc xây dựng đều không trả về giá trị nào, nhưng có tác dụng phụ là xác định một mục tiêu. Hành động này được gọi là khởi tạo quy tắc. Thao tác này chỉ định tên cho mục tiêu mới và các giá trị cho thuộc tính của mục tiêu.Bạn cũng có thể gọi các quy tắc từ các hàm Starlark và tải trong các tệp .bzl. Các hàm Starlark gọi các quy tắc được gọi là macro Starlark. Cuối cùng, các macro Starlark phải được gọi từ các tệp BUILD và chỉ có thể được gọi trong giai đoạn tải, khi các tệp BUILD được đánh giá để tạo thực thể cho các mục tiêu.

Thuộc tính

Thuộc tính là một đối số quy tắc. Các thuộc tính có thể cung cấp các giá trị cụ thể cho việc triển khai của mục tiêu hoặc có thể tham chiếu đến các mục tiêu khác, tạo ra một biểu đồ các phần phụ thuộc.Các thuộc tính dành riêng cho quy tắc, chẳng hạn như srcs hoặc deps, được xác định bằng cách truyền một bản đồ từ tên thuộc tính đến các giản đồ (được tạo bằng mô-đun attr) đến tham số attrs của rule. Các thuộc tính phổ biến, chẳng hạn như name và visibility, được thêm ngầm vào tất cả các quy tắc. Các thuộc tính bổ sung được thêm ngầm vào các quy tắc thực thi và kiểm thử một cách cụ thể. Bạn không thể thêm các thuộc tính được thêm ngầm vào một quy tắc vào từ điển được truyền đến attrs.

Thuộc tính phần phụ thuộc

Các quy tắc xử lý mã nguồn thường xác định các thuộc tính sau để xử lý nhiều loại phần phụ thuộc:Đây là các ví dụ về thuộc tính phần phụ thuộc. Mọi thuộc tính chỉ định nhãn đầu vào (những nhãn được xác định bằng attr.label_list, attr.label hoặc attr.label_keyed_string_dict) đều chỉ định các phần phụ thuộc thuộc một loại nhất định giữa một đích và các đích có nhãn (hoặc các đối tượng Label tương ứng) được liệt kê trong thuộc tính đó khi đích được xác định. Kho lưu trữ và có thể là đường dẫn cho các nhãn này được phân giải tương ứng với mục tiêu đã xác định.Trong ví dụ này, other_target là một phần phụ thuộc của my_target, do đó, other_target được phân tích trước. Đây là lỗi nếu có một chu kỳ trong biểu đồ phần phụ thuộc của các mục tiêu.

Thuộc tính riêng tư và các phần phụ thuộc ngầm

Thuộc tính phần phụ thuộc có giá trị mặc định sẽ tạo ra một phần phụ thuộc ngầm. Đây là một phần ngầm định vì nó là một phần của biểu đồ đích mà người dùng không chỉ định trong tệp BUILD. Các phần phụ thuộc ngầm định rất hữu ích khi mã hoá cứng mối qu...

Thuộc tính đầu ra

Thuộc tính đầu ra, chẳng hạn như attr.output và attr.output_list, khai báo một tệp đầu ra mà mục tiêu tạo ra. Các thuộc tính này khác với thuộc tính phụ thuộc ở hai điểm:Thông thường, các thuộc tính đầu ra chỉ được dùng khi một quy tắc cần tạo đầu ra có tên do người dùng xác định mà không thể dựa trên tên mục tiêu. Nếu một quy tắc có một thuộc tính đầu ra, thì thuộc tính đó thường có tên là out hoặc outs.Thuộc tính đầu ra là cách ưu tiên để tạo đầu ra được khai báo trước, có thể phụ thuộc cụ thể vào hoặc được yêu cầu tại dòng lệnh.

Hàm triển khai

Mỗi quy tắc đều yêu cầu một hàm implementation. Các hàm này được thực thi nghiêm ngặt trong giai đoạn phân tích và chuyển đổi biểu đồ mục tiêu được tạo trong giai đoạn tải thành biểu đồ hành động sẽ được thực hiện trong giai đoạn thực thi. Do đó, các hàm triển khai không thể đọc hoặc ghi tệp.Các hàm triển khai quy tắc thường là riêng tư (được đặt tên bằng dấu gạch dưới ở đầu). Theo quy ước, chúng được đặt tên giống như quy tắc của chúng, nhưng có thêm hậu tố _impl.Các hàm triển khai chỉ nhận đúng một tham số: ngữ cảnh quy tắc, theo quy ước có tên là ctx. Chúng trả về danh sách nhà cung cấp.

Mục tiêu

Các phần phụ thuộc được biểu thị tại thời điểm phân tích dưới dạng các đối tượng Target. Các đối tượng này chứa các trình cung cấp được tạo khi hàm triển khai của mục tiêu được thực thi.ctx.attr có các trường tương ứng với tên của từng thuộc tính phần...

Tệp

Các tệp được biểu thị bằng các đối tượng File. Vì Bazel không thực hiện thao tác I/O tệp trong giai đoạn phân tích, nên bạn không thể dùng các đối tượng này để đọc hoặc ghi trực tiếp nội dung tệp. Thay vào đó, chúng được truyền đến các hàm phát hành hà...

Khai báo đầu ra

Trong giai đoạn phân tích, hàm triển khai của một quy tắc có thể tạo ra các kết quả đầu ra. Vì tất cả nhãn phải được biết trong giai đoạn tải, nên các đầu ra bổ sung này không có nhãn. Bạn có thể tạo các đối tượng File cho đầu ra bằng cách sử dụng ctx.actions.declare_file và ctx.actions.declare_directory. Thông thường, tên của các đầu ra dựa trên tên của mục tiêu, ctx.label.name:Đối với đầu ra được khai báo trước, chẳng hạn như những đầu ra được tạo cho thuộc tính đầu ra, thay vào đó, bạn có thể truy xuất các đối tượng File từ các trường tương ứng của ctx.outputs.

Thao tác

Một hành động mô tả cách tạo một tập hợp đầu ra từ một tập hợp đầu vào, ví dụ: "chạy gcc trên hello.c và nhận hello.o". Khi một thao tác được tạo, Bazel sẽ không chạy lệnh ngay lập tức. Nó đăng ký trong biểu đồ phần phụ thuộc, vì một thao tác có thể ph...

Nhà cung cấp

Trình cung cấp là những phần thông tin mà một quy tắc hiển thị cho các quy tắc khác phụ thuộc vào quy tắc đó. Dữ liệu này có thể bao gồm các tệp đầu ra, thư viện, tham số để truyền trên dòng lệnh của một công cụ hoặc bất kỳ thông tin nào khác mà người dù...

Đầu ra mặc định

Đầu ra mặc định của mục tiêu là đầu ra được yêu cầu theo mặc định khi mục tiêu được yêu cầu để tạo bản dựng tại dòng lệnh. Ví dụ: đích java_library //pkg:foo có foo.jar làm đầu ra mặc định, do đó, đích này sẽ được tạo bằng lệnh bazel build //pkg:foo.Đầu ra mặc đị...

Runfiles

Runfile là một tập hợp các tệp mà mục tiêu sử dụng trong thời gian chạy (khác với thời gian tạo bản dựng). Trong giai đoạn thực thi, Bazel sẽ tạo một cây thư mục chứa các symlink trỏ đến runfile. Thao tác này dàn xếp môi trường cho tệp nhị phân để tệ...

Nhà cung cấp tuỳ chỉnh

Bạn có thể xác định nhà cung cấp bằng hàm provider để truyền tải thông tin cụ thể theo quy tắc:Sau đó, các hàm triển khai quy tắc có thể tạo và trả về các thực thể của trình cung cấp:

Khởi chạy tuỳ chỉnh các trình cung cấp

Bạn có thể bảo vệ quá trình tạo thực thể của một trình cung cấp bằng logic tiền xử lý và xác thực tuỳ chỉnh. Bạn có thể dùng cách này để đảm bảo rằng tất cả các thực thể nhà cung cấp đều đáp ứng một số bất biến nhất định hoặc để cung cấp cho người dù...

Quy tắc có thể thực thi và quy tắc kiểm thử

Các quy tắc có thể thực thi xác định những mục tiêu có thể được gọi bằng lệnh bazel run. Quy tắc kiểm thử là một loại quy tắc thực thi đặc biệt mà các mục tiêu của quy tắc này cũng có thể được gọi bằng lệnh bazel test. Bạn có thể tạo quy tắc có thể th...

Vị trí của tệp runfile

Khi một mục tiêu thực thi được chạy bằng bazel run (hoặc test), gốc của thư mục runfiles sẽ nằm cạnh tệp thực thi. Các đường dẫn liên quan như sau:Đường dẫn đến File trong thư mục runfiles tương ứng với File.short_path.Tệp nhị phân do bazel thực thi t...

Chủ đề nâng cao

Yêu cầu tệp đầu ra

Một đích đến có thể có nhiều tệp đầu ra. Khi lệnh bazel build được chạy, một số đầu ra của các mục tiêu được đưa ra cho lệnh này sẽ được coi là được yêu cầu. Bazel chỉ tạo những tệp được yêu cầu này và những tệp mà chúng phụ thuộc trực tiếp hoặc gián ti...

Cấu hình

Hãy tưởng tượng rằng bạn muốn tạo một tệp nhị phân C++ cho một cấu trúc khác. Quy trình tạo có thể phức tạp và bao gồm nhiều bước. Một số tệp nhị phân trung gian, chẳng hạn như trình biên dịch và trình tạo mã, phải chạy trên nền tảng thực thi (có thể là...

Mảnh cấu hình

Các quy tắc có thể truy cập vào các mảnh cấu hình, chẳng hạn như cpp và java. Tuy nhiên, bạn phải khai báo tất cả các mảnh bắt buộc để tránh lỗi truy cập:

Đường liên kết tượng trưng Runfiles

Thông thường, đường dẫn tương đối của một tệp trong cây runfiles giống với đường dẫn tương đối của tệp đó trong cây nguồn hoặc cây đầu ra được tạo. Nếu cần phải thay đổi các giá trị này vì một lý do nào đó, bạn có thể chỉ định đối số root_symlinks ho...

Mức độ sử dụng mã

Khi lệnh coverage được chạy, bản dựng có thể cần thêm công cụ đo lường mức độ phù hợp cho một số mục tiêu nhất định. Bản dựng cũng thu thập danh sách các tệp nguồn được đo lường. Tập hợp con của các mục tiêu được xem xét do cờ -instrumentation_filter ki...

Kiểm thử quy tắc

Các quy tắc kiểm thử cần có chế độ thiết lập bổ sung để tạo báo cáo về mức độ phù hợp. Bản thân quy tắc phải thêm các thuộc tính ngầm sau:Bằng cách sử dụng configuration_field, bạn có thể tránh được sự phụ thuộc vào công cụ hợp nhất LCOV của Java miễn là bạn không yêu cầu phạm vi.Khi chạy, kiểm thử sẽ phát ra thông tin về mức độ phù hợp dưới dạng một hoặc nhiều tệp LCOV có tên riêng biệt vào thư mục do biến môi trường COVERAGE_DIR chỉ định. Sau đó, Bazel sẽ hợp nhất các tệp này thành một tệp LCOV duy nhất bằng công cụ _lcov_merger. Nếu có, công cụ này cũng sẽ thu thập mức độ phù hợp của C/C++ bằng công cụ _collect_cc_coverage.

Mức độ bao phủ cơ sở

Vì mức độ sử dụng chỉ được thu thập cho mã nằm trong cây phần phụ thuộc của một kiểm thử, nên báo cáo về mức độ sử dụng có thể gây hiểu lầm vì không nhất thiết phải bao gồm tất cả mã khớp với cờ -instrumentation_filter.Vì lý do này, Bazel cho phép các ...

Hành động xác thực

Đôi khi, bạn cần xác thực một số thông tin về bản dựng và thông tin cần thiết để thực hiện quy trình xác thực đó chỉ có trong các cấu phần phần mềm (tệp nguồn hoặc tệp được tạo). Vì thông tin này nằm trong các cấu phần phần mềm, nên các quy tắc không th...

Nhóm đầu ra xác thực

Nhóm đầu ra xác thực là một nhóm đầu ra được thiết kế để giữ các đầu ra không dùng đến của các thao tác xác thực, để không cần phải thêm các đầu ra này một cách nhân tạo vào đầu vào của các thao tác khác.Nhóm này đặc biệt ở chỗ các đầu ra của nhóm luôn...

Sử dụng Nhóm đầu ra xác thực

Nhóm đầu ra xác thực có tên là _validation và được dùng như mọi nhóm đầu ra khác:Lưu ý rằng tệp đầu ra xác thực không được thêm vào DefaultInfo hoặc đầu vào cho bất kỳ thao tác nào khác. Thao tác xác thực cho đích của loại quy tắc này vẫn sẽ chạy nếu ...

Cờ thao tác xác thực

Việc chạy các thao tác xác thực được kiểm soát bằng cờ dòng lệnh -run_validations, theo mặc định là true.

Những tính năng đã ngừng hoạt động

Đầu ra được khai báo trước không được dùng nữa

Có 2 cách không dùng nữa để sử dụng các đầu ra được khai báo trước:

Các tính năng runfile cần tránh

ctx.runfiles và loại runfiles có một bộ tính năng phức tạp, nhiều tính năng trong số đó được giữ lại vì lý do kế thừa. Các đề xuất sau đây giúp giảm độ phức tạp:

Di chuyển từ các nhà cung cấp cũ

Trước đây, các nhà cung cấp Bazel là các trường đơn giản trên đối tượng Target. Chúng được truy cập bằng toán tử dấu chấm và được tạo bằng cách đặt trường trong struct do hàm triển khai của quy tắc trả về thay vì danh sách các đối tượng nhà cung cấp:Bạn có thể tr...