Trang này giải thích kiến thức cơ bản và lợi ích của việc sử dụng các khía cạnh, đồng thời cung cấp các ví dụ đơn giản và nâng cao.
Các khía cạnh cho phép tăng cường các biểu đồ phần phụ thuộc của bản dựng bằng các thông tin và thao tác bổ sung. Sau đây là một số trường hợp điển hình trong đó các khía cạnh có thể hữu ích:
- Các IDE tích hợp Bazel có thể sử dụng các khía cạnh để thu thập thông tin về dự án.
- Các công cụ tạo mã có thể tận dụng các khía cạnh để thực thi dữ liệu đầu vào theo cách không phân biệt mục tiêu. Ví dụ: tệp
BUILDcó thể chỉ định một hệ phân cấp các định nghĩa thư viện protobuf và quy tắc dành riêng cho ngôn ngữ có thể dùng các khía cạnh để đính kèm các hành động tạo mã hỗ trợ protobuf cho một ngôn ngữ cụ thể.
Thông tin cơ bản về Aspect
Tệp BUILD cung cấp nội dung mô tả mã nguồn của dự án: tệp nguồn nào thuộc dự án, cấu phần phần mềm nào (mục tiêu) nên được tạo từ các tệp đó, phần phụ thuộc giữa các tệp đó là gì, v.v. Bazel sử dụng thông tin này để tạo bản dựng, tức là xác định tập hợp hành động cần thiết để tạo cấu phần phần mềm (chẳng hạn như chạy trình biên dịch hoặc trình liên kết) và thực thi các hành động đó. Bazel làm được điều này bằng cách xây dựng biểu đồ phần phụ thuộc giữa các mục tiêu và truy cập vào biểu đồ này để thu thập các hành động đó.
Hãy xem xét tệp BUILD sau:
java_library(name = 'W', ...)
java_library(name = 'Y', deps = [':W'], ...)
java_library(name = 'Z', deps = [':W'], ...)
java_library(name = 'Q', ...)
java_library(name = 'T', deps = [':Q'], ...)
java_library(name = 'X', deps = [':Y',':Z'], runtime_deps = [':T'], ...)
Tệp BUILD này xác định một biểu đồ phần phụ thuộc như trong hình sau:
Hình 1. Biểu đồ phần phụ thuộc tệp BUILD.
Bazel phân tích biểu đồ phần phụ thuộc này bằng cách gọi một hàm triển khai của quy tắc tương ứng (trong trường hợp này là "java_library") cho mọi mục tiêu trong ví dụ trên. Các hàm triển khai quy tắc sẽ tạo ra các thao tác tạo cấu phần phần mềm (chẳng hạn như tệp .jar) và truyền thông tin (chẳng hạn như vị trí và tên của các cấu phần phần mềm) đến các phần phụ thuộc ngược của các mục tiêu đó trong trình cung cấp.
Các khía cạnh tương tự như các quy tắc ở chỗ chúng có một hàm triển khai tạo ra các thao tác và trình cung cấp trả về. Tuy nhiên, sức mạnh của chúng đến từ cách xây dựng biểu đồ phần phụ thuộc. Một khía cạnh có phần triển khai và danh sách tất cả thuộc tính mà nó sẽ được lan truyền cùng. Hãy xem xét một khía cạnh A lan truyền dọc theo các thuộc tính có tên là "deps". Khía cạnh này có thể được áp dụng cho một mục tiêu X, tạo ra một nút của ứng dụng khung hình A(X). Trong ứng dụng, khía cạnh A được áp dụng đệ quy cho mọi mục tiêu mà X tham chiếu đến trong thuộc tính "deps" (tất cả các thuộc tính trong danh sách truyền của A).
Do đó, chỉ một hành động áp dụng khía cạnh A cho một mục tiêu X cũng tạo ra "biểu đồ bóng" của biểu đồ phần phụ thuộc ban đầu của các mục tiêu như trong hình sau:
Hình 2. Xây dựng biểu đồ có các khía cạnh.
Các cạnh duy nhất bị đổ bóng là các cạnh dọc theo các thuộc tính trong tập hợp truyền tải, do đó, cạnh runtime_deps không bị đổ bóng trong ví dụ này. Sau đó, hàm triển khai khung hình được gọi trên tất cả các nút trong biểu đồ bóng, tương tự như cách gọi phương thức triển khai quy tắc trên các nút của biểu đồ ban đầu.
Ví dụ đơn giản
Ví dụ này minh hoạ cách in đệ quy các tệp nguồn cho một quy tắc và tất cả phần phụ thuộc có thuộc tính deps của quy tắc đó. Công cụ này cho thấy cách triển khai khung hình, định nghĩa khung hình và cách gọi khung hình đó từ dòng lệnh Bazel.
def _print_aspect_impl(target, ctx):
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the files that make up the sources and
# print their paths.
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
print(f.path)
return []
print_aspect = aspect(
implementation = _print_aspect_impl,
attr_aspects = ['deps'],
)
Hãy chia nhỏ ví dụ này thành nhiều phần rồi kiểm tra riêng từng phần.
Định nghĩa khung hình
print_aspect = aspect(
implementation = _print_aspect_impl,
attr_aspects = ['deps'],
)
Các định nghĩa về khung hình tương tự như định nghĩa quy tắc và được xác định bằng hàm aspect.
Tương tự như quy tắc, một khía cạnh cũng có hàm triển khai trong trường hợp này là _print_aspect_impl.
attr_aspects là danh sách các thuộc tính quy tắc mà khung hình sẽ được phổ biến theo đó.
Trong trường hợp này, khung hình sẽ được truyền dọc theo thuộc tính deps của các quy tắc được áp dụng.
Một đối số phổ biến khác cho attr_aspects là ['*'] sẽ phổ biến phương diện đến tất cả các thuộc tính của một quy tắc.
Cách triển khai Aspect
def _print_aspect_impl(target, ctx):
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the files that make up the sources and
# print their paths.
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
print(f.path)
return []
Các hàm triển khai Aspect tương tự như các hàm triển khai quy tắc. Các phương thức này trả về trình cung cấp, có thể tạo thao tác và nhận 2 đối số:
target: mục tiêu mà khung hình đang được áp dụng.ctx: Đối tượngctxcó thể dùng để truy cập vào các thuộc tính cũng như tạo đầu ra và hành động.
Hàm triển khai có thể truy cập vào các thuộc tính của quy tắc mục tiêu thông qua
ctx.rule.attr. Công cụ này có thể kiểm tra các nhà cung cấp được cung cấp bởi mục tiêu mà nó được áp dụng (thông qua đối số target).
Cần có các phương diện để trả về danh sách nhà cung cấp. Trong ví dụ này, thành phần không cung cấp bất kỳ giá trị nào, do đó sẽ trả về một danh sách trống.
Gọi khung hình bằng dòng lệnh
Cách đơn giản nhất để áp dụng một khía cạnh là từ dòng lệnh bằng cách sử dụng đối số --aspects. Giả sử khía cạnh ở trên đã được xác định trong tệp có tên print.bzl, thì:
bazel build //MyExample:example --aspects print.bzl%print_aspect
sẽ áp dụng print_aspect cho example mục tiêu và tất cả các quy tắc mục tiêu có thể truy cập đệ quy thông qua thuộc tính deps.
Cờ --aspects nhận một đối số, là thông số kỹ thuật của khung hình ở định dạng <extension file label>%<aspect top-level name>.
Ví dụ nâng cao
Ví dụ sau minh hoạ việc sử dụng một khía cạnh của quy tắc mục tiêu đếm các tệp trong mục tiêu, có thể lọc các tệp đó theo tiện ích. Hướng dẫn này cho biết cách sử dụng trình cung cấp để trả về giá trị, cách sử dụng tham số để chuyển đối số vào phương thức triển khai khung hình và cách gọi một khía cạnh từ quy tắc.
Tệp file_count.bzl:
FileCountInfo = provider(
fields = {
'count' : 'number of files'
}
)
def _file_count_aspect_impl(target, ctx):
count = 0
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the sources counting files
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
count = count + 1
# Get the counts from our dependencies.
for dep in ctx.rule.attr.deps:
count = count + dep[FileCountInfo].count
return [FileCountInfo(count = count)]
file_count_aspect = aspect(
implementation = _file_count_aspect_impl,
attr_aspects = ['deps'],
attrs = {
'extension' : attr.string(values = ['*', 'h', 'cc']),
}
)
def _file_count_rule_impl(ctx):
for dep in ctx.attr.deps:
print(dep[FileCountInfo].count)
file_count_rule = rule(
implementation = _file_count_rule_impl,
attrs = {
'deps' : attr.label_list(aspects = [file_count_aspect]),
'extension' : attr.string(default = '*'),
},
)
Tệp BUILD.bazel:
load('//:file_count.bzl', 'file_count_rule')
cc_library(
name = 'lib',
srcs = [
'lib.h',
'lib.cc',
],
)
cc_binary(
name = 'app',
srcs = [
'app.h',
'app.cc',
'main.cc',
],
deps = ['lib'],
)
file_count_rule(
name = 'file_count',
deps = ['app'],
extension = 'h',
)
Định nghĩa khung hình
file_count_aspect = aspect(
implementation = _file_count_aspect_impl,
attr_aspects = ['deps'],
attrs = {
'extension' : attr.string(values = ['*', 'h', 'cc']),
}
)
Ví dụ này cho thấy cách truyền tải một khung hình thông qua thuộc tính deps.
attrs xác định một tập hợp các thuộc tính của một khung hình. Các thuộc tính khung hình công khai xác định các tham số và chỉ có thể thuộc kiểu bool, int hoặc string.
Đối với các khía cạnh được truyền tải theo quy tắc, tham số int và string phải được chỉ định values. Ví dụ này có một tham số có tên là extension. Tham số này được phép có giá trị là "*", "h" hoặc "cc".
Đối với các khía cạnh được truyền tải theo quy tắc, giá trị tham số được lấy từ quy tắc yêu cầu khía cạnh đó, bằng cách sử dụng thuộc tính của quy tắc có cùng tên và kiểu.
(xem định nghĩa của file_count_rule).
Đối với các khía cạnh dòng lệnh, bạn có thể chuyển các giá trị tham số bằng cờ --aspects_parameters. Quy định hạn chế values đối với các tham số int và string có thể bị bỏ qua.
Các khía cạnh cũng được phép có thuộc tính riêng tư thuộc loại label hoặc label_list. Bạn có thể dùng thuộc tính nhãn riêng tư để chỉ định các phần phụ thuộc trên các công cụ hoặc thư viện cần thiết cho những thao tác do các chương trình thành phần tạo ra. Không có thuộc tính riêng tư được xác định trong ví dụ này, nhưng đoạn mã sau đây minh hoạ cách bạn có thể truyền một công cụ đến một khung hình:
...
attrs = {
'_protoc' : attr.label(
default = Label('//tools:protoc'),
executable = True,
cfg = "exec"
)
}
...
Cách triển khai Aspect
FileCountInfo = provider(
fields = {
'count' : 'number of files'
}
)
def _file_count_aspect_impl(target, ctx):
count = 0
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the sources counting files
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
count = count + 1
# Get the counts from our dependencies.
for dep in ctx.rule.attr.deps:
count = count + dep[FileCountInfo].count
return [FileCountInfo(count = count)]
Tương tự như hàm triển khai quy tắc, hàm triển khai khía cạnh trả về một cấu trúc gồm các trình cung cấp có thể truy cập được từ các phần phụ thuộc của nó.
Trong ví dụ này, FileCountInfo được định nghĩa là trình cung cấp có một trường count. Tốt nhất là bạn nên xác định rõ các trường của trình cung cấp bằng thuộc tính fields.
Tập hợp các trình cung cấp cho một ứng dụng khung hình A(X) là tập hợp các trình cung cấp đến từ việc triển khai một quy tắc cho mục tiêu X và từ việc triển khai khía cạnh A. Các trình cung cấp mà quá trình triển khai quy tắc sẽ truyền sẽ được tạo và cố định trước khi áp dụng các khía cạnh, đồng thời không thể sửa đổi từ một khía cạnh. Sẽ là lỗi nếu một mục tiêu và một khía cạnh được áp dụng, mỗi mục tiêu cung cấp cho một trình cung cấp cùng loại, với ngoại lệ là OutputGroupInfo (được hợp nhất, miễn là quy tắc và khung hình chỉ định các nhóm đầu ra khác nhau) và InstrumentedFilesInfo (được lấy từ khung hình). Điều này có nghĩa là các phương thức triển khai khung hình có thể không bao giờ trả về DefaultInfo.
Các tham số và thuộc tính riêng tư được truyền vào các thuộc tính của ctx. Ví dụ này tham chiếu đến tham số extension và xác định những tệp cần được tính.
Đối với các trình cung cấp trả về, giá trị của các thuộc tính mà theo đó khía cạnh được truyền tải (từ danh sách attr_aspects) sẽ được thay thế bằng kết quả của một ứng dụng của khía cạnh đó. Ví dụ: nếu mục tiêu X có Y và Z trong các phần phụ thuộc, thì ctx.rule.attr.deps cho A(X) sẽ là [A(Y), A(Z)].
Trong ví dụ này, ctx.rule.attr.deps là các đối tượng Mục tiêu là kết quả của việc áp dụng khung hình cho "deps" của mục tiêu ban đầu mà khía cạnh được áp dụng.
Trong ví dụ này, khung hình truy cập vào trình cung cấp FileCountInfo từ các phần phụ thuộc của mục tiêu để tích luỹ tổng số tệp bắc cầu.
Gọi phương diện từ một quy tắc
def _file_count_rule_impl(ctx):
for dep in ctx.attr.deps:
print(dep[FileCountInfo].count)
file_count_rule = rule(
implementation = _file_count_rule_impl,
attrs = {
'deps' : attr.label_list(aspects = [file_count_aspect]),
'extension' : attr.string(default = '*'),
},
)
Việc triển khai quy tắc minh hoạ cách truy cập vào FileCountInfo thông qua ctx.attr.deps.
Định nghĩa quy tắc minh hoạ cách xác định một tham số (extension) và đặt cho tham số đó một giá trị mặc định (*). Xin lưu ý rằng việc có giá trị mặc định không phải là "cc", "h" hoặc "*" sẽ gây ra lỗi do các hạn chế đặt ra với tham số trong định nghĩa khung hình.
Gọi một khía cạnh thông qua quy tắc mục tiêu
load('//:file_count.bzl', 'file_count_rule')
cc_binary(
name = 'app',
...
)
file_count_rule(
name = 'file_count',
deps = ['app'],
extension = 'h',
)
Minh hoạ cách truyền tham số extension vào khung hình thông qua quy tắc. Vì tham số extension có giá trị mặc định trong quá trình triển khai quy tắc, nên extension sẽ được coi là một tham số không bắt buộc.
Khi mục tiêu file_count được tạo, khía cạnh của chúng ta sẽ được tự đánh giá và tất cả mục tiêu có thể truy cập theo cách đệ quy thông qua deps.