BazelCon 2022 findet vom 16. bis 17. November in New York und online statt.
Jetzt anmelden

BUILD-Dateien

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

In den vorherigen Abschnitten wurden Pakete, Ziele und Labels sowie die Build-Abhängigkeitsgrafik abstrakt beschrieben. In diesem Abschnitt wird die konkrete Syntax für die Definition eines Pakets beschrieben.

Per Definition enthält jedes Paket eine BUILD-Datei, ein kurzes Programm. BUILD-Dateien werden mithilfe der imperativen Sprache Starlark ausgewertet.

Sie werden als sequenzielle Liste von Anweisungen interpretiert.

Im Allgemeinen ist die Reihenfolge wichtig: Variablen müssen beispielsweise vor ihrer Verwendung definiert werden. Die meisten BUILD-Dateien bestehen jedoch nur aus Deklarationen für Build-Regeln. Die relative Reihenfolge dieser Anweisungen ist dabei unerheblich. Wichtig ist nur, welche Regeln mit welchen Werten bei der Auswertung des Pakets deklariert wurden.

Wenn eine Build-Regelfunktion wie cc_library ausgeführt wird, wird ein neues Ziel im Diagramm erstellt. Auf dieses Ziel kann später mithilfe eines Labels verwiesen werden.

In einfachen BUILD-Dateien können Regeldeklarationen kostenlos neu angeordnet werden, ohne das Verhalten zu ändern.

Um eine saubere Trennung zwischen Code und Daten zu fördern, dürfen BUILD-Dateien keine Funktionsdefinitionen, for- oder if-Anweisungen enthalten (aber Listenlisten und if-Ausdrücke sind zulässig) aus. Funktionen können stattdessen in .bzl-Dateien deklariert werden. Außerdem sind die Argumente *args und **kwargs in BUILD-Dateien nicht zulässig. führen Sie stattdessen alle Argumente explizit auf.

Entscheidend ist, dass Programme in Starlark keine beliebigen E/A-Vorgänge ausführen können. Dadurch wird die Interpretation von BUILD-Dateien hermetisch – nur abhängig von einem bekannten Satz von Eingaben, der für die Sicherstellung der Reproduzierbarkeit von Builds unerlässlich ist. Weitere Informationen finden Sie unter Hermeticity.

BUILD-Dateien sollten nur mit ASCII-Zeichen geschrieben werden, obwohl sie technisch mit dem Zeichensatz Latin-1 interpretiert werden.

Da BUILD-Dateien aktualisiert werden müssen, wenn sich die Abhängigkeiten des zugrunde liegenden Codes ändern, werden sie in der Regel von mehreren Teammitgliedern verwaltet. BUILD-Dateiautoren sollten umfassend kommentieren, um die Rolle jedes Build-Ziels zu dokumentieren, unabhängig davon, ob sie für die öffentliche Verwendung vorgesehen ist und die Rolle des Pakets selbst zu dokumentieren.

Erweiterung laden

Bazel-Erweiterungen sind Dateien, die auf ..bzl“ enden. Verwenden Sie die Anweisung load, um ein Symbol aus einer Erweiterung zu importieren.

load("//foo/bar:file.bzl", "some_library")

Mit diesem Code wird die Datei foo/bar/file.bzl geladen und das Symbol some_library der Umgebung hinzugefügt. Hiermit können neue Regeln, Funktionen oder Konstanten geladen werden (z. B. ein String oder eine Liste). Mehrere Symbole können mithilfe zusätzlicher Argumente importiert werden, um load aufzurufen. Argumente müssen Stringliterale sein (keine Variable) und load-Anweisungen müssen auf oberster Ebene angegeben werden. Sie können sich nicht in einem Funktionstext befinden.

Das erste Argument von load ist ein Label, das eine .bzl-Datei identifiziert. Wenn es sich um ein relatives Label handelt, wird es in Bezug auf das Paket (nicht Verzeichnis) aufgelöst, das die aktuelle bzl-Datei enthält. Relative Labels in load-Anweisungen sollten eine führende : verwenden.

Da load auch Aliasse unterstützt, können Sie den importierten Symbolen unterschiedliche Namen zuweisen.

load("//foo/bar:file.bzl", library_alias = "some_library")

Sie können innerhalb einer load-Anweisung mehrere Aliasse definieren. Darüber hinaus kann die Argumentliste sowohl Aliasse als auch reguläre Symbolnamen enthalten. Das folgende Beispiel ist absolut rechtlich (Hinweise zur Verwendung von Anführungszeichen).

load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")

In einer .bzl-Datei werden Symbole, die mit _ beginnen, nicht exportiert und können nicht aus einer anderen Datei geladen werden. Die Sichtbarkeit wirkt sich noch nicht auf das Laden aus: Sie müssen exports_files nicht verwenden, um eine .bzl-Datei sichtbar zu machen.

Arten von Build-Regeln

Die meisten Build-Regeln sind in Familien zusammengefasst, gruppiert nach Sprache. Beispielsweise sind cc_binary, cc_library und cc_test die Build-Regeln für C++-Binärdateien, -Bibliotheken und -Tests. Andere Sprachen verwenden das gleiche Namensschema mit einem anderen Präfix, z. B. java_* für Java. Einige dieser Funktionen sind in der Build-Enzyklopädie dokumentiert. Sie können jedoch neue Regeln erstellen.

  • Mit *_binary-Regeln werden ausführbare Programme in einer bestimmten Sprache erstellt. Nach einem Build befindet sich die ausführbare Datei im binären Ausgabebaum des Build-Tools unter dem entsprechenden Namen für das Label der Regel. //my:program wird also beispielsweise unter $(BINDIR)/my/program angezeigt.

    In einigen Sprachen erstellen solche Regeln auch ein Runfiles-Verzeichnis, das alle Dateien enthält, die in einem data-Attribut der Regel oder einer Regel bei ihrer vorübergehenden Schließung von Abhängigkeiten enthalten sind. diese Dateien werden an einem Ort zusammengefasst, um die Bereitstellung in der Produktion zu vereinfachen.

  • *_test-Regeln sind eine Spezialisierung einer *_binary-Regel für automatisierte Tests. Tests sind einfach Programme, die bei Erfolg null zurückgeben.

    Wie Binärdateien haben Tests auch Runfiles-Strukturen und unter den Dateien sind nur die Dateien zulässig, die zur Laufzeit ordnungsgemäß geöffnet werden können. Ein Programm cc_test(name='x', data=['//foo:bar']) kann beispielsweise während der Ausführung $TEST_SRCDIR/workspace/foo/bar öffnen und lesen. (Jede Programmiersprache hat eine eigene Dienstfunktion für den Zugriff auf den Wert von $TEST_SRCDIR, aber sie entspricht alle direkt der Verwendung der Umgebungsvariablen.) Wird die Regel nicht beachtet, schlägt der Test fehl, wenn er auf einem Remote-Testhost ausgeführt wird.

  • *_library-Regeln geben separat kompilierte Module in der angegebenen Programmiersprache an. Bibliotheken können von anderen Bibliotheken abhängen. Binärdateien und Tests können Bibliotheken mit dem erwarteten Verhalten zur separaten Kompilierung sein.

Labels Abhängigkeiten