Ví dụ về giao thức sự kiện cho bản dựng

Báo cáo sự cố Xem nguồn

Bạn có thể xem toàn bộ thông số kỹ thuật của Giao thức sự kiện bản dựng trong phần định nghĩa vùng đệm giao thức. Tuy nhiên, việc xây dựng một số trực giác trước khi xem quy cách có thể sẽ hữu ích.

Hãy cân nhắc một không gian làm việc Bazel đơn giản bao gồm 2 tập lệnh shell trống foo.sh và foo_test.sh cùng tệp BUILD sau:

sh_library(
    name = "foo_lib",
    srcs = ["foo.sh"],
)

sh_test(
    name = "foo_test",
    srcs = ["foo_test.sh"],
    deps = [":foo_lib"],
)

Khi chạy bazel test ... trên dự án này, biểu đồ bản dựng của các sự kiện bản dựng đã tạo sẽ giống như biểu đồ bên dưới. Các mũi tên cho biết mối quan hệ mẹ và con nêu trên. Xin lưu ý rằng một số sự kiện bản dựng và hầu hết các trường đã bị bỏ qua để cho ngắn gọn.

đồ thị nhật ký

Hình 1. Biểu đồ BEP.

Ban đầu, một sự kiện BuildStarted sẽ được xuất bản. Sự kiện này thông báo cho chúng tôi rằng bản dựng đã được gọi thông qua lệnh bazel test và sẽ thông báo các sự kiện con:

  • OptionsParsed
  • WorkspaceStatus
  • CommandLine
  • UnstructuredCommandLine
  • BuildMetadata
  • BuildFinished
  • PatternExpanded
  • Progress

Ba sự kiện đầu tiên cung cấp thông tin về cách Bazel được gọi.

Sự kiện tạo PatternExpanded cung cấp thông tin chi tiết về mục tiêu cụ thể mà mẫu ... được mở rộng thành: //foo:foo_lib và //foo:foo_test. Hàm này thực hiện việc này bằng cách khai báo 2 sự kiện TargetConfigured là phần tử con. Xin lưu ý rằng sự kiện TargetConfigured khai báo sự kiện Configuration là sự kiện con, mặc dù Configuration đã được đăng trước sự kiện TargetConfigured.

Ngoài mối quan hệ mẹ và con, các sự kiện cũng có thể tham chiếu đến nhau bằng cách sử dụng giá trị nhận dạng sự kiện bản dựng. Ví dụ: trong biểu đồ trên, sự kiện TargetComplete đề cập đến sự kiện NamedSetOfFiles trong trường fileSets.

Các sự kiện tạo bản dựng tham chiếu đến tệp thường không nhúng tên và đường dẫn tệp vào sự kiện đó. Thay vào đó, các đối tượng này chứa giá trị nhận dạng sự kiện bản dựng của sự kiện NamedSetOfFiles, sau đó sẽ chứa đường dẫn và tên tệp thực tế. Sự kiện NamedSetOfFiles cho phép một tập hợp các tệp được báo cáo một lần và được nhiều mục tiêu tham chiếu đến. Cấu trúc này là cần thiết vì nếu không, trong một số trường hợp, kích thước đầu ra của Giao thức sự kiện bản dựng sẽ tăng theo cấp bậc hai với số lượng tệp. Sự kiện NamedSetOfFiles cũng có thể không được nhúng tất cả các tệp, mà sẽ tham chiếu đến các sự kiện NamedSetOfFiles khác thông qua giá trị nhận dạng sự kiện bản dựng.

Dưới đây là một bản sao của sự kiện TargetComplete cho mục tiêu //foo:foo_lib từ biểu đồ trên, được in trong cách biểu diễn JSON của vùng đệm giao thức. Giá trị nhận dạng sự kiện bản dựng chứa mục tiêu dưới dạng một chuỗi mờ và tham chiếu đến sự kiện Configuration bằng cách sử dụng giá trị nhận dạng sự kiện bản dựng của sự kiện đó. Sự kiện này không thông báo bất kỳ sự kiện con nào. Tải trọng chứa thông tin về việc mục tiêu có được tạo thành công hay không, tập hợp các tệp đầu ra và loại mục tiêu đã tạo.

{
  "id": {
    "targetCompleted": {
      "label": "//foo:foo_lib",
      "configuration": {
        "id": "544e39a7f0abdb3efdd29d675a48bc6a"
      }
    }
  },
  "completed": {
    "success": true,
    "outputGroup": [{
      "name": "default",
      "fileSets": [{
        "id": "0"
      }]
    }],
    "targetKind": "sh_library rule"
  }
}

Kết quả Aspect tính bằng BEP

Các bản dựng thông thường sẽ đánh giá các hành động liên kết với cặp (target, configuration). Khi tạo bản dựng khi bật các khía cạnh, Bazel sẽ đánh giá thêm các mục tiêu liên kết với (target, configuration, aspect) bộ ba, cho mỗi mục tiêu chịu ảnh hưởng của một khía cạnh được bật nhất định.

Hiện đã có kết quả đánh giá cho các khía cạnh trong BEP mặc dù không có các loại sự kiện theo từng khía cạnh cụ thể. Đối với mỗi cặp (target, configuration) có một khía cạnh có thể áp dụng, Bazel xuất bản một sự kiện TargetConfigured và TargetComplete bổ sung mang kết quả từ việc áp dụng khung hình đó cho mục tiêu. Ví dụ: nếu //:foo_lib được tạo bằng --aspects=aspects/myaspect.bzl%custom_aspect, thì sự kiện này cũng sẽ xuất hiện trong BEP:

{
  "id": {
    "targetCompleted": {
      "label": "//foo:foo_lib",
      "configuration": {
        "id": "544e39a7f0abdb3efdd29d675a48bc6a"
      },
      "aspect": "aspects/myaspect.bzl%custom_aspect"
    }
  },
  "completed": {
    "success": true,
    "outputGroup": [{
      "name": "default",
      "fileSets": [{
        "id": "1"
      }]
    }]
  }
}

Đang tiêu thụ NamedSetOfFiles

Việc xác định các cấu phần phần mềm do một mục tiêu (hoặc khía cạnh) nhất định tạo ra là một trường hợp sử dụng BEP phổ biến, có thể thực hiện hiệu quả với một số chuẩn bị. Phần này thảo luận về cấu trúc đệ quy, dùng chung mà sự kiện NamedSetOfFiles cung cấp, khớp với cấu trúc của Depset Starlark.

Người tiêu dùng cần phải cẩn trọng để tránh các thuật toán bậc hai khi xử lý các sự kiện NamedSetOfFiles vì các bản dựng lớn có thể chứa hàng chục nghìn sự kiện như vậy, đòi hỏi hàng trăm triệu thao tác trong một lần truyền tải với độ phức tạp bậc bốn.

tênsetoffiles-bep-graph

Hình 2. Biểu đồ BEP NamedSetOfFiles.

Sự kiện NamedSetOfFiles luôn xuất hiện trong luồng BEP trước một sự kiện TargetComplete hoặc NamedSetOfFiles tham chiếu đến sự kiện đó. Đây là nghịch đảo của mối quan hệ sự kiện "parent-child", trong đó tất cả trừ sự kiện đầu tiên xuất hiện sau ít nhất một sự kiện thông báo sự kiện đó. Sự kiện NamedSetOfFiles được thông báo bằng một sự kiện Progress không có ngữ nghĩa.

Với những hạn chế về thứ tự và chia sẻ này, người dùng thông thường phải lưu tất cả sự kiện NamedSetOfFiles vào vùng đệm cho đến khi luồng BEP hết. Luồng sự kiện JSON và mã Python sau đây minh hoạ cách điền sẵn bản đồ từ mục tiêu/khía cạnh đến cấu phần phần mềm đã tạo trong nhóm đầu ra "mặc định" và cách xử lý kết quả cho một tập hợp con mục tiêu/khía cạnh đã tạo:

named_sets = {}  # type: dict[str, NamedSetOfFiles]
outputs = {}     # type: dict[str, dict[str, set[str]]]

for event in stream:
  kind = event.id.WhichOneof("id")
  if kind == "named_set":
    named_sets[event.id.named_set.id] = event.named_set_of_files
  elif kind == "target_completed":
    tc = event.id.target_completed
    target_id = (tc.label, tc.configuration.id, tc.aspect)
    outputs[target_id] = {}
    for group in event.completed.output_group:
      outputs[target_id][group.name] = {fs.id for fs in group.file_sets}

for result_id in relevant_subset(outputs.keys()):
  visit = outputs[result_id].get("default", [])
  seen_sets = set(visit)
  while visit:
    set_name = visit.pop()
    s = named_sets[set_name]
    for f in s.files:
      process_file(result_id, f)
    for fs in s.file_sets:
      if fs.id not in seen_sets:
        visit.add(fs.id)
        seen_sets.add(fs.id)