Espaces de travail, packages et cibles

Bazel crée des logiciels à partir du code source organisé dans une arborescence de répertoires appelée "espace de travail". Les fichiers sources de l'espace de travail sont organisés dans une hiérarchie imbriquée de packages, chaque package étant un répertoire contenant un ensemble de fichiers sources associés et un fichier BUILD. Le fichier BUILD spécifie les sorties logicielles que vous pouvez créer à partir de la source.

Workspace

Un espace de travail est une arborescence de répertoires de votre système de fichiers qui contient les fichiers sources du logiciel que vous souhaitez créer. Chaque espace de travail comporte un fichier texte nommé WORKSPACE, qui peut être vide ou contenir des références aux dépendances externes requises pour générer les résultats.

Les répertoires contenant un fichier nommé WORKSPACE sont considérés comme racines d'un espace de travail. C'est pourquoi Bazel ignore les arborescences de répertoires d'un espace de travail racine dans un sous-répertoire contenant un fichier WORKSPACE, car elles forment un autre espace de travail.

Bazel accepte également les fichiers WORKSPACE.bazel en tant qu'alias des fichiers WORKSPACE. Si les deux fichiers existent, WORKSPACE.bazel est utilisé.

Dépôts

Le code est organisé en dépôts. Le répertoire contenant le fichier WORKSPACE est la racine du dépôt principal, également appelé @. Les autres dépôts (externes) sont définis dans le fichier WORKSPACE à l'aide de règles d'espace de travail.

Les règles d'espace de travail fournies avec Bazel sont décrites dans la section Règles d'espace de travail de la page Créer une encyclopédie et dans la documentation du dépôt Starlark intégré. règles.

Les dépôts externes étant eux-mêmes des dépôts, ils contiennent souvent un fichier WORKSPACE. Toutefois, ces fichiers WORKSPACE supplémentaires sont ignorés par Bazel. En particulier, les dépôts dépendants de manière transitoire ne sont pas ajoutés automatiquement.

Colis

L'unité principale de l'organisation du code dans un dépôt est le package. Un package est une collection de fichiers associés et une spécification de leur utilisation pour produire des artefacts de sortie.

Un package est défini comme un répertoire contenant un fichier nommé BUILD (ou BUILD.bazel). Un package contient tous les fichiers de son répertoire, ainsi que tous les sous-répertoires situés en dessous, à l'exception de ceux qui contiennent un fichier BUILD. D'après cette définition, aucun fichier ou répertoire ne peut faire partie de deux packages différents.

Par exemple, l'arborescence de répertoires suivante contient deux packages, my/app et le sous-package my/app/tests. Notez que my/app/data n'est pas un package, mais un répertoire appartenant au package my/app.

src/my/app/BUILD
src/my/app/app.cc
src/my/app/data/input.txt
src/my/app/tests/BUILD
src/my/app/tests/test.cc

Cibles

Un package est un conteneur de cibles, définies dans le fichier BUILD du package. La plupart des cibles sont l'un des deux genres principaux, fichiers et règles.

Les fichiers sont également répartis en deux catégories. Les fichiers sources sont généralement écrits par les utilisateurs et sont enregistrés dans le dépôt. Les fichiers générés, parfois appelés fichiers dérivés ou fichiers de sortie, ne sont pas archivés, mais sont générés à partir de fichiers sources.

Le second type de cible est déclaré avec une règle. Chaque instance de règle spécifie la relation entre un ensemble d'entrées et un ensemble de fichiers de sortie. Les entrées d'une règle peuvent être des fichiers sources, mais elles peuvent également être les sorties d'autres règles.

Dans la plupart des cas, l'entrée dans une règle est un fichier source ou un fichier généré. ce qui importe uniquement le contenu de ce fichier. Cela facilite le remplacement d'un fichier source complexe par un fichier généré par une règle, par exemple lorsque la gestion manuelle d'un fichier très structuré devient trop fastidieuse et que quelqu'un écrit un fichier. pour le calculer. Aucune modification n'est requise pour les utilisateurs de ce fichier. Inversement, un fichier généré peut facilement être remplacé par un fichier source ne contenant que des modifications locales.

Les entrées d'une règle peuvent également inclure d'autres règles. La signification exacte de ces relations est souvent assez complexe et dépende du langage ou de la règle, mais de manière intuitive, c'est simple: une règle de bibliothèque C++ A peut avoir une autre règle de bibliothèque C++ B pour une entrée. Cette dépendance implique que les fichiers d'en-tête B sont disponibles pour A pendant la compilation, que les symboles sont disponibles pour A pendant l'association et que les données d'exécution de B sont disponibles pour A pendant l'exécution.

Toutes les règles sont invariantes, car les fichiers générés par une règle appartiennent toujours au même package que la règle. il est impossible de générer des fichiers dans un autre package. Toutefois, il n'est pas rare que les entrées d'une règle proviennent d'un autre package.

Les groupes de packages sont des ensembles de packages dont l'objectif est de limiter l'accessibilité de certaines règles. Les groupes de packages sont définis par la fonction package_group. Elles présentent trois propriétés: la liste des packages qu'elles contiennent, leur nom et les autres groupes de packages qu'elles incluent. Les seuls moyens autorisés de y faire référence sont l'attribut de règle visibility ou l'attribut default_visibility de la fonction package. ni générer, ni consommer de fichiers. Pour en savoir plus, consultez la documentation sur package_group.

Libellés