Exemplos de protocolo de evento de build

A especificação completa do protocolo de eventos de build pode ser encontrada na definição do buffer de protocolo. No entanto, pode ser útil criar alguma intuição antes de analisar a especificação.

Considere um espaço de trabalho simples do Bazel que consiste em dois scripts shell vazios foo.sh e foo_test.sh e o seguinte arquivo BUILD:

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

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

Ao executar bazel test ... nesse projeto, o gráfico de build dos eventos de build gerados será semelhante ao gráfico abaixo. As setas indicam a relação pai-filho mencionada. Alguns eventos de build e a maioria dos campos foram omitidos para simplificar.

Figura 1. Gráfico de BEP.

Inicialmente, um evento BuildStarted é publicado. O evento informa que o build foi invocado pelo comando bazel test e anuncia eventos filhos:

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

Os três primeiros eventos fornecem informações sobre como o Bazel foi invocado.

O evento de build PatternExpanded fornece insights sobre quais destinos específicos o padrão ... foi expandido: //foo:foo_lib e //foo:foo_test. Isso é feito declarando dois eventos TargetConfigured como filhos. O evento TargetConfigured declara o evento Configuration como filho, mesmo que Configuration tenha sido postado antes de TargetConfigured.

Além da relação entre pai e filho, os eventos também podem se referir uns aos outros usando os identificadores de eventos de build. Por exemplo, no gráfico acima, o evento TargetComplete se refere ao evento NamedSetOfFiles no campo fileSets.

Os eventos de build que se referem a arquivos geralmente não incorporam os nomes e caminhos dos arquivos no evento. Em vez disso, eles contêm o identificador do evento de build de um evento NamedSetOfFiles, que vai conter os nomes e caminhos reais dos arquivos. O evento NamedSetOfFiles permite que um conjunto de arquivos seja informado uma vez e referenciado por muitos destinos. Essa estrutura é necessária porque, caso contrário, em alguns casos, o tamanho da saída do Build Event Protocol aumentaria de forma quadrática com o número de arquivos. Um evento NamedSetOfFiles também pode não ter todos os arquivos incorporados, mas se referir a outros eventos NamedSetOfFiles pelos identificadores de eventos de build.

Confira abaixo uma instância do evento TargetComplete para o destino //foo:foo_lib do gráfico acima, impressa na representação JSON do buffer de protocolo. O identificador de evento de build contém o destino como uma string opaca e se refere ao evento Configuration usando o identificador de evento de build. O evento não anuncia nenhum evento filho. O payload contém informações sobre se o destino foi criado com sucesso, o conjunto de arquivos de saída e o tipo de destino criado.

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

Resultados de aspectos no BEP

Os builds comuns avaliam ações associadas a pares (target, configuration). Ao criar com aspectos ativados, o Bazel também avalia destinos associados a triplas (target, configuration, aspect) para cada destino afetado por um determinado aspecto ativado.

Os resultados da avaliação de aspectos estão disponíveis no BEP, apesar da ausência de tipos de eventos específicos de aspectos. Para cada par (target, configuration) com um aspecto aplicável, o Bazel publica um evento TargetConfigured e TargetComplete adicional com o resultado da aplicação do aspecto ao destino. Por exemplo, se //:foo_lib for criado com --aspects=aspects/myaspect.bzl%custom_aspect, esse evento também vai aparecer no 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"
      }]
    }]
  }
}

Consumindo NamedSetOfFiles

Determinar os artefatos produzidos por um determinado destino (ou aspecto) é um caso de uso comum do BEP que pode ser feito de maneira eficiente com alguma preparação. Esta seção discute a estrutura recursiva e compartilhada oferecida pelo evento NamedSetOfFiles, que corresponde à estrutura de um Depset do Starlark.

Os consumidores precisam evitar algoritmos quadráticos ao processar eventos NamedSetOfFiles, porque builds grandes podem conter dezenas de milhares desses eventos, exigindo centenas de milhões de operações em uma travessia com complexidade quadrática.

Figura 2. Gráfico de NamedSetOfFiles BEP.

Um evento NamedSetOfFiles sempre aparece no fluxo do BEP antes de um evento TargetComplete ou NamedSetOfFiles que o referencia. Essa é a relação inversa do evento "pai-filho", em que todos os eventos, exceto o primeiro, aparecem depois de pelo menos um evento que os anuncia. Um evento NamedSetOfFiles é anunciado por um evento Progress sem semântica.

Devido a essas restrições de ordenação e compartilhamento, um consumidor típico precisa armazenar em buffer todos os eventos de NamedSetOfFiles até que o fluxo BEP seja esgotado. O fluxo de eventos JSON e o código Python a seguir demonstram como preencher um mapa de destino/aspecto para artefatos criados no grupo de saída "default" e como processar as saídas para um subconjunto de destinos/aspectos criados:

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)