El protocolo de eventos de compilación (BEP) permite que los programas de terceros obtengan información sobre una invocación de Bazel. Por ejemplo, podrías usar el BEP para recopilar información para un complemento de IDE o un panel que muestre los resultados de la compilación.
El protocolo es un conjunto de mensajes de búfer de protocolo con cierta semántica definida sobre él. Incluye información sobre los resultados de la compilación y las pruebas, el progreso de la compilación, la configuración de la compilación y mucho más. El BEP está diseñado para consumirse de forma programática y hace que el análisis de la salida de la línea de comandos de Bazel sea cosa del pasado.
El Build Event Protocol representa información sobre una compilación como eventos. Un evento de compilación es un mensaje de búfer de protocolo que consta de un identificador de evento de compilación, un conjunto de identificadores de eventos secundarios y una carga útil.
Identificador de evento de compilación: Según el tipo de evento de compilación, puede ser una cadena opaca o información estructurada que revele más detalles sobre el evento de compilación. Un identificador de evento de compilación es único dentro de una compilación.
Hijos: Un evento de compilación puede anunciar otros eventos de compilación si incluye sus identificadores en el campo hijos. Por ejemplo, el evento de compilación
PatternExpandedanuncia los destinos a los que se expande como elementos secundarios. El protocolo garantiza que todos los eventos, excepto el primero, se anuncien mediante un evento anterior.Carga útil: La carga útil contiene información estructurada sobre un evento de compilación, codificada como un mensaje de búfer de protocolo específico para ese evento. Ten en cuenta que es posible que la carga útil no sea del tipo esperado, pero podría ser un mensaje
Abortedsi la compilación se interrumpió de forma prematura.
Compila el gráfico de eventos
Todos los eventos de compilación forman un grafo acíclico dirigido a través de su relación principal y secundaria. Todos los eventos de compilación, excepto el evento de compilación inicial, tienen uno o más eventos principales. Ten en cuenta que no todos los eventos principales de un evento secundario deben publicarse necesariamente antes que este. Cuando se completa una compilación (con éxito o sin éxito), se habrán publicado todos los eventos anunciados. En caso de una falla de Bazel o un transporte de red fallido, es posible que algunos eventos de compilación anunciados nunca se publiquen.
La estructura del gráfico de eventos refleja el ciclo de vida de un comando. Cada gráfico de BEP tiene la siguiente forma característica:
- El evento raíz siempre es un evento
BuildStarted. Todos los demás eventos son sus descendientes. - Los elementos secundarios inmediatos del evento BuildStarted contienen metadatos sobre el comando.
- Los eventos que contienen datos producidos por el comando, como los archivos compilados y los resultados de las pruebas, aparecen antes del evento
BuildFinished. - Es posible que el evento
BuildFinishedesté seguido de eventos que contengan información resumida sobre la compilación (por ejemplo, datos de métricas o de generación de perfiles).
Consumo del Protocolo de eventos de compilación
Consumir en formato binario
Para consumir el BEP en formato binario, haz lo siguiente:
Haz que Bazel serialice los mensajes de búfer de protocolo en un archivo especificando la opción
--build_event_binary_file=/path/to/file. El archivo contendrá mensajes de búfer de protocolo serializados, y cada mensaje estará delimitado por su longitud. Cada mensaje tiene como prefijo su longitud codificada como un número entero de longitud variable. Este formato se puede leer con el métodoparseDelimitedFrom(InputStream)de la biblioteca de búferes de protocolo.Luego, escribe un programa que extraiga la información pertinente del mensaje del búfer de protocolo serializado.
Consumir en formatos de texto o JSON
Las siguientes marcas de línea de comandos de Bazel generarán el BEP en formatos legibles, como texto y JSON:
--build_event_text_file
--build_event_json_file
Servicio de evento de compilación
El protocolo del servicio de eventos de compilación es un servicio genérico de gRPC para publicar eventos de compilación. El protocolo del servicio de eventos de compilación es independiente del BEP y trata los eventos del BEP como bytes opacos.
Bazel se entrega con una implementación del cliente de gRPC del protocolo de Build Event Service que publica eventos del Build Event Protocol. Se puede especificar el extremo al que se enviarán los eventos con la marca --bes_backend=HOST:PORT. Si tu backend usa gRPC, debes anteponer a la dirección el esquema adecuado: grpc:// para gRPC de texto sin formato y grpcs:// para gRPC con TLS habilitado.
Marcas del servicio de evento de compilación
Bazel tiene varias marcas relacionadas con el protocolo del Servicio de eventos de compilación, incluidas las siguientes:
--bes_backend--[no]bes_lifecycle_events--bes_results_url--bes_timeout--bes_instance_name
Para obtener una descripción de cada una de estas marcas, consulta la referencia de la línea de comandos.
Autenticación y seguridad
La implementación del servicio de eventos de compilación de Bazel también admite la autenticación y TLS. Estos parámetros de configuración se pueden controlar con las marcas que se indican a continuación. Ten en cuenta que estas marcas también se usan para la ejecución remota de Bazel. Esto implica que el servicio de eventos de compilación y los extremos de ejecución remota deben compartir la misma infraestructura de autenticación y TLS.
--[no]google_default_credentials--google_credentials--google_auth_scopes--tls_certificate--[no]tls_enabled
Para obtener una descripción de cada una de estas marcas, consulta la referencia de la línea de comandos.
Servicio de evento de compilación y almacenamiento en caché remoto
Por lo general, el BEP contiene muchas referencias a archivos de registro (test.log, test.xml, etc. ) almacenados en la máquina en la que se ejecuta Bazel. Por lo general, un servidor BES remoto no puede acceder a estos archivos, ya que se encuentran en máquinas diferentes. Una forma de solucionar este problema es usar Bazel con almacenamiento en caché remoto. Bazel subirá todos los archivos de salida a la caché remota (incluidos los archivos a los que se hace referencia en el BEP), y el servidor de BES podrá recuperar los archivos a los que se hace referencia desde la caché.
Consulta el problema 3689 de GitHub para obtener más detalles.