Instructivo de Bazel: Compila un proyecto de C++

Informar un problema Ver fuente Por la noche · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Introducción

¿Es la primera vez que usas Bazel? Estás en el lugar correcto. Sigue este tutorial de primera compilación para ver una introducción simplificada al uso de Bazel. En este instructivo, se definen los términos clave según se usan en el contexto de Bazel y se explican los conceptos básicos del flujo de trabajo de Bazel. A partir de las herramientas que necesitas, compilarás y ejecutarás tres proyectos con una complejidad creciente y aprenderás cómo y por qué se vuelven más complejos.

Por otro lado, Bazel es un sistema de compilación que admite compilaciones de varios lenguajes. En este instructivo, se usa un proyecto de C++ como ejemplo. y proporciona las pautas generales y el flujo que se aplican a la mayoría de los lenguajes.

Tiempo estimado de finalización: 30 minutos.

Requisitos previos

Comienza por instalar Bazel, si aún no lo hiciste. En este instructivo, se usa Git para el control de código fuente, por lo que, para obtener los mejores resultados, también debes instalar Git.

A continuación, recupera el proyecto de ejemplo del repositorio de GitHub de Bazel. Para ello, ejecuta lo siguiente en la herramienta de línea de comandos que prefieras:

git clone https://github.com/bazelbuild/examples

El proyecto de muestra para este instructivo se encuentra en el directorio examples/cpp-tutorial.

A continuación, te mostramos cómo está estructurada:

examples
└── cpp-tutorial
    ├──stage1
    │  ├── main
    │  │   ├── BUILD
    │  │   └── hello-world.cc
    │  └── WORKSPACE
    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   └── hello-greet.h
    │  └── WORKSPACE
    └──stage3
       ├── main
       │   ├── BUILD
       │   ├── hello-world.cc
       │   ├── hello-greet.cc
       │   └── hello-greet.h
       ├── lib
       │   ├── BUILD
       │   ├── hello-time.cc
       │   └── hello-time.h
       └── WORKSPACE

Hay tres conjuntos de archivos, cada uno de los cuales representa una etapa de este instructivo. En la primera etapa, compilarás un solo objetivo que reside en un solo paquete. En la segunda etapa, compilarás un objeto binario y una biblioteca a partir de un solo paquete. En la tercera y última etapa, compilarás un proyecto con varios paquetes y lo compilarás con varios destinos.

Resumen: Introducción

Cuando instalas Bazel (y Git) y clonas el repositorio para este instructivo, puedes ya que sentaste las bases para tu primera compilación con Bazel. Continuar al siguiente para definir algunos términos y configurar tu lugar de trabajo.

Cómo comenzar

Configura el espacio de trabajo

Antes de compilar un proyecto, debes configurar su lugar de trabajo. Un espacio de trabajo es un directorio que contiene los archivos fuente de tu proyecto y los resultados de la compilación de Bazel. Integra también contiene estos archivos significativos:

  • El WORKSPACE file , que identifica el directorio y su contenido como un espacio de trabajo de Bazel y se encuentra en la raíz de la estructura de directorios del proyecto.
  • Uno o más BUILD files , que le indican a Bazel cómo compilar diferentes partes del proyecto R dentro del espacio de trabajo que contenga un archivo BUILD package. (Más información sobre paquetes más adelante en este instructivo).

En proyectos futuros, para designar un directorio como lugar de trabajo de Bazel, crea un archivo vacío llamado WORKSPACE en ese directorio. A los efectos de este instructivo, ya hay un archivo WORKSPACE en cada etapa.

NOTA: Cuando Bazel compila el proyecto, todas las entradas deben estar en el mismo lugar de trabajo. Los archivos que se encuentran en diferentes espacios de trabajo son independientes de entre sí, a menos que se vinculen. Puedes encontrar información más detallada sobre las reglas de los lugares de trabajo en esta guía.

Comprende el archivo BUILD

Un archivo BUILD contiene varios tipos diferentes de instrucciones para Bazel. Cada archivo BUILD requiere al menos una regla como un conjunto de instrucciones, que le indica a Bazel cómo compilar los resultados deseados, como bibliotecas o objetos binarios ejecutables. Cada instancia de una regla de compilación en el archivo BUILD se denomina objetivo y apunta a un conjunto específico de archivos de origen y dependencias. Un objetivo también puede dirigir a otros destinos.

Observa el archivo BUILD en el directorio cpp-tutorial/stage1/main:

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
)

En nuestro ejemplo, el objetivo hello-world crea una instancia de cc_binary rule integrado de Bazel. La regla le indica a Bazel que compile un ejecutable binario independiente a partir del archivo fuente hello-world.cc sin dependencias.

Resumen: cómo empezar

Ahora conoces algunos términos clave y su significado en el contexto de este proyecto y Bazel en general. En la próxima sección, compilarás y probarás Etapa 1 del proyecto.

Etapa 1: Un solo objetivo y un solo paquete

Es hora de construir la primera parte del proyecto. A modo de referencia visual, la estructura de la sección de la etapa 1 del proyecto es la siguiente:

examples
└── cpp-tutorial
    └──stage1
       ├── main
       │   ├── BUILD
       │   └── hello-world.cc
       └── WORKSPACE

Ejecuta el siguiente comando para moverte al directorio cpp-tutorial/stage1:

cd cpp-tutorial/stage1

Luego, ejecute el siguiente comando:

bazel build //main:hello-world

En la etiqueta de destino, la parte //main: es la ubicación del archivo BUILD en relación con la raíz del lugar de trabajo, y hello-world es el nombre de destino en el archivo BUILD.

Bazel produce algo que se ve de la siguiente manera:

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 2.267s, Critical Path: 0.25s

Acabas de compilar tu primer destino de Bazel. Bazel coloca las salidas de compilación en el bazel-bin en la raíz de la Workspace.

Ahora, prueba el objeto binario recién compilado, que es el siguiente:

bazel-bin/main/hello-world

Esto genera un mensaje “Hello world” impreso.

Este es el gráfico de dependencias de la etapa 1:

El gráfico de dependencia de hello-world muestra un solo destino con un solo archivo de origen.

Resumen: etapa 1

Ahora que has completado tu primera construcción, tienes una idea básica de cómo está estructurado. En la siguiente etapa, agregarás complejidad agregando otra objetivo.

Etapa 2: múltiples destinos de compilación

Si bien un solo objetivo es suficiente para proyectos pequeños, es posible que desees dividir proyectos más grandes en varios objetivos y paquetes. Esto permite compilaciones incrementales rápidas (es decir, Bazel solo vuelve a compilar lo que cambió) y acelera las compilaciones compilando varias partes de un proyecto a la vez. Esta etapa del instructivo agrega un destino y el siguiente, un paquete.

Este es el directorio con el que trabajas en la etapa 2:

    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   └── hello-greet.h
    │  └── WORKSPACE

Observa el archivo BUILD en el directorio cpp-tutorial/stage2/main a continuación:

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
    ],
)

Con este archivo BUILD, Bazel primero compila la biblioteca hello-greet. (con cc_library rule integrado de Bazel), y, luego, el objeto binario hello-world. El atributo deps en el destino hello-world le indica a Bazel que el hello-greet se requiere para compilar el objeto binario hello-world.

Antes de compilar esta nueva versión del proyecto, debes cambiar directorios y pasar al directorio cpp-tutorial/stage2 ejecutando lo siguiente:

cd ../stage2

Ahora puedes compilar el nuevo objeto binario con el siguiente comando que ya conoces:

bazel build //main:hello-world

Una vez más, Bazel produce algo que se ve de la siguiente manera:

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 2.399s, Critical Path: 0.30s

Ahora puedes probar el objeto binario recién compilado, que muestra otro "Hello world":

bazel-bin/main/hello-world

Si ahora modificas hello-greet.cc y vuelves a compilar el proyecto, Bazel solo volverá a compilar. ese archivo.

Si observas el gráfico de dependencias, puedes ver que hello-world depende de las mismas entradas que antes, pero la estructura de la compilación es diferente:

El gráfico de dependencias de "hello-world" muestra los cambios de estructura después de la modificación del archivo.

Resumen: etapa 2

Ahora compilaste el proyecto con dos destinos. Las compilaciones de destino hello-world un archivo fuente y depende de otro destino (//main:hello-greet), que compila dos archivos fuente adicionales. En la siguiente sección, ve más allá y agregar otro paquete.

Etapa 3: varios paquetes

En esta etapa, se agrega otra capa de complicación y se compila un proyecto con varios paquetes. A continuación, observa la estructura y el contenido del directorio cpp-tutorial/stage3:

└──stage3
   ├── main
   │   ├── BUILD
   │   ├── hello-world.cc
   │   ├── hello-greet.cc
   │   └── hello-greet.h
   ├── lib
   │   ├── BUILD
   │   ├── hello-time.cc
   │   └── hello-time.h
   └── WORKSPACE

Puedes ver que ahora hay dos subdirectorios y cada uno contiene un BUILD . Por lo tanto, para Bazel, el espacio de trabajo ahora contiene dos paquetes: lib y main

Observa el archivo lib/BUILD:

cc_library(
    name = "hello-time",
    srcs = ["hello-time.cc"],
    hdrs = ["hello-time.h"],
    visibility = ["//main:__pkg__"],
)

Y en el archivo main/BUILD:

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
        "//lib:hello-time",
    ],
)

El destino hello-world en el paquete principal depende del objetivo hello-time en el paquete lib (de ahí la etiqueta de destino //lib:hello-time). Bazel sabe esto a través del atributo deps. Puedes ver esto reflejado en el gráfico de dependencias:

El gráfico de dependencias de "hello-world" muestra cómo el destino del paquete principal depende del destino del paquete "lib".

Para que la compilación se realice correctamente, debes hacer que el destino //lib:hello-time en lib/BUILD sea visible de forma explícita para los destinos en main/BUILD con el atributo de visibilidad. Esto se debe a que, de forma predeterminada, los objetivos solo son visibles para otros objetivos del mismo BUILD. Bazel usa la visibilidad de destino para evitar problemas, como las bibliotecas. que contienen detalles de implementación que se filtran en APIs públicas.

Ahora, compila esta versión final del proyecto. Cambiar a cpp-tutorial/stage3 con lo que se muestra a continuación:

cd  ../stage3

Una vez más, ejecuta el siguiente comando:

bazel build //main:hello-world

Bazel produce algo que se ve de la siguiente manera:

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 0.167s, Critical Path: 0.00s

Ahora prueba el último objeto binario de este instructivo para obtener un mensaje Hello world final:

bazel-bin/main/hello-world

Resumen: etapa 3

Ahora compilaste el proyecto como dos paquetes con tres destinos y comprendes las dependencias entre ellos, lo que te permite seguir adelante y compilar proyectos futuros con Bazel. En la siguiente sección, veremos cómo continuar tu recorrido con Bazel.

Próximos pasos

Ya completaste tu primera compilación básica con Bazel, pero esta es solo la comenzar. Estos son algunos recursos más para seguir aprendiendo con Bazel:

¡Buena compilación!