Introducción
¿Eres nuevo en Bazel? Está en el lugar correcto. Sigue este instructivo de Primera compilación para obtener una introducción simplificada al uso de Bazel. En este instructivo, se definen los términos clave, ya que se usan en el contexto de Bazel y se explican los conceptos básicos del flujo de trabajo de Bazel. Comenzarás con las herramientas que necesitas para compilar y ejecutar tres proyectos con una complejidad creciente, y aprender cómo y por qué se vuelven más complejos.
Si bien Bazel es un sistema de compilación compatible con compilaciones de varios idiomas, en este instructivo, se usa un proyecto de C++ como ejemplo y se proporcionan los lineamientos y el flujo generales que se aplican a la mayoría de los lenguajes.
Tiempo de finalización estimado: 30 minutos.
Requisitos previos
Primero, instala Bazel si aún no lo has hecho. En este instructivo, se usa Git para el control de la fuente, por lo que, para obtener mejores resultados, también debes instalar Git.
A continuación, recupera el proyecto de muestra del repositorio de GitHub de Bazel mediante la siguiente herramienta de línea de comandos de tu elección:
git clone https://github.com/bazelbuild/examples
El proyecto de muestra de este instructivo se encuentra en el directorio examples/cpp-tutorial
.
A continuación, se muestra su estructura:
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
En este instructivo, existen tres conjuntos de archivos que representan una etapa. En la primera etapa, compilarás un solo objetivo que resida en un solo paquete. En la segunda, 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
Si instalas Bazel (y Git) y clonas el repositorio de este instructivo, sentaste las bases de tu primera compilación con Bazel. Continúa con la siguiente sección para definir algunos términos y configurar tu lugar de trabajo.
Primeros pasos
Configure el lugar de trabajo
Antes de crear un proyecto, debes configurar su lugar de trabajo. Un lugar de trabajo es un directorio que contiene los archivos de origen de tu proyecto y los resultados de la compilación de Bazel. También contiene los siguientes archivos:
- El
, que identifica el directorio y su contenido como un lugar de trabajo de Bazel y se encuentra en la raíz de la estructura del directorio del proyecto.WORKSPACE
file - Uno o más
, que le indican a Bazel cómo compilar diferentes partes del proyecto. Un directorio dentro del lugar de trabajo que contiene un archivoBUILD
filesBUILD
es un paquete. Más adelante en este instructivo, encontrarás información adicional sobre los paquetes.
En proyectos futuros, crea un archivo vacío llamado WORKSPACE
en ese directorio para designar un directorio como lugar de trabajo de Bazel. 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 residen en diferentes lugares de trabajo son independientes entre sí, a menos que estén vinculados. Puedes encontrar información más detallada sobre las reglas del lugar de trabajo en esta guía.
Comprende el archivo BUILD
Un archivo BUILD
contiene varios tipos de instrucciones diferentes para Bazel. Cada
archivo BUILD
requiere al menos una regla
como 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 destino y apunta a un conjunto específico de archivos de origen y dependencias.
Un objetivo también puede apuntar 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 destino hello-world
crea una instancia del cc_binary rule
integrado de Bazel.
La regla le indica a Bazel que compile un objeto binario ejecutable independiente del
archivo fuente hello-world.cc
sin dependencias.
Resumen: cómo empezar
Ahora conoces algunos términos clave y lo que significan en el contexto de este proyecto y Bazel en general. En la siguiente sección, compilarás y probarás la etapa 1 del proyecto.
Etapa 1: destino único, paquete único
Es momento de crear la primera parte del proyecto. Para una 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 lo siguiente para ir 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 del destino en el archivo BUILD
.
Bazel produce algo similar a lo siguiente:
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 los resultados de la compilación en el directorio
bazel-bin
en la raíz del
lugar de trabajo.
Ahora, pruebe su objeto binario recién compilado, que es el siguiente:
bazel-bin/main/hello-world
Se mostrará el mensaje "Hello world
" impreso.
Este es el gráfico de dependencias de la etapa 1:
Resumen: etapa 1
Ahora que completaste tu primera compilación, tienes una idea básica de cómo se estructura una compilación. En la próxima etapa, agregarás otro objetivo para agregar complejidad.
Etapa 2: Varios destinos de compilación
Si bien un solo destino es suficiente para proyectos pequeños, te recomendamos dividir los proyectos más grandes en varios destinos y paquetes. Esto permite compilaciones incrementales rápidas, es decir, Bazel solo reconstruye los cambios y acelera tus compilaciones mediante la compilación de varias partes de un proyecto a la vez. En esta etapa del instructivo, se agrega un destino y, en la siguiente, se agrega un paquete.
Este es el directorio con el que trabajas para la etapa 2:
├──stage2
│ ├── main
│ │ ├── BUILD
│ │ ├── hello-world.cc
│ │ ├── hello-greet.cc
│ │ └── hello-greet.h
│ └── WORKSPACE
Observa a continuación el archivo BUILD
en el directorio cpp-tutorial/stage2/main
:
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
(mediante el cc_library rule
integrado de Bazel) y, luego, el objeto binario hello-world
. El atributo deps
del
destino hello-world
le indica a Bazel que se necesita la biblioteca hello-greet
para compilar el objeto binario hello-world
.
Antes de compilar esta versión nueva del proyecto, debes cambiar los directorios y cambiar al directorio cpp-tutorial/stage2
ejecutando lo siguiente:
cd ../stage2
Ahora puedes compilar el objeto binario nuevo con el siguiente comando conocido:
bazel build //main:hello-world
Una vez más, Bazel produce algo como lo siguiente:
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 tu objeto binario recién compilado, que muestra otro "Hello world
":
bazel-bin/main/hello-world
Si modificas hello-greet.cc
y vuelves a compilar el proyecto, Bazel solo volverá a compilar
ese archivo.
En el gráfico de dependencias, puedes ver que hello-world
depende de una entrada adicional llamada hello-greet
:
Resumen: etapa 2
Acabas de compilar el proyecto con dos destinos. El destino hello-world
compila 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 agrega otro paquete.
Etapa 3: varios paquetes
En la siguiente etapa, se agrega otra capa de complicación y se compila un proyecto con varios paquetes. Observa a continuación 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 que cada uno contiene un archivo BUILD
. Por lo tanto, en Bazel, el lugar 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
del paquete principal depende del destino hello-time
en el paquete lib
(por lo tanto, la etiqueta de destino //lib:hello-time
). Bazel lo sabe
a través del atributo deps
. Puedes ver esto reflejado en el gráfico de dependencias:
Para que la compilación se realice de forma correcta, debes hacer que el objetivo //lib:hello-time
de lib/BUILD
sea visible de forma explícita para los objetivos de main/BUILD
mediante el atributo de visibilidad.
Esto se debe a que, de forma predeterminada, los objetivos solo son visibles para otros destinos en el mismo
archivo BUILD
. Bazel usa la visibilidad de destino para evitar problemas como las bibliotecas
que contienen detalles de implementación que se filtran a las APIs públicas.
Ahora, compila esta versión final del proyecto. Para cambiar al directorio cpp-tutorial/stage3
, ejecuta lo siguiente:
cd ../stage3
Una vez más, ejecute el siguiente comando:
bazel build //main:hello-world
Bazel produce algo similar a lo siguiente:
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
Compilaste el proyecto como dos paquetes con tres destinos y comprendes las dependencias entre ellos, lo que te permite avanzar y compilar futuros proyectos con Bazel. En la siguiente sección, observa cómo continuar tu recorrido de Bazel.
Próximos pasos
Ya completaste tu primera compilación básica con Bazel, pero este es solo el comienzo. Estos son algunos recursos más para seguir aprendiendo con Bazel:
- Para seguir enfocándote en C++, lee acerca de los casos de uso comunes de compilación de C++.
- Para comenzar a compilar otras aplicaciones con Bazel, consulta los instructivos para Java, aplicación para Android o aplicación para iOS).
- Para obtener más información sobre cómo trabajar con repositorios locales y remotos, lee sobre las dependencias externas.
- Para obtener más información sobre las otras reglas de Bazel, consulta esta guía de referencia.
¡Feliz edificio!