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

Repository-Regeln

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

Auf dieser Seite wird beschrieben, wie Sie Repository-Regeln erstellen. Außerdem finden Sie dort Beispiele für weitere Informationen.

Ein externes Repository ist eine Regel, die nur in der Datei WORKSPACE verwendet werden kann und einen nicht-hermetischen Vorgang in der Ladephase von Bazel ermöglicht. Jede externe Repository-Regel erstellt einen eigenen Arbeitsbereich mit eigenen BUILD-Dateien und Artefakten. Sie können verwendet werden, um auf Bibliotheken von Drittanbietern (z. B. gepackte Bibliotheken in Maven) zuzugreifen, aber auch um BUILD-Dateien zu generieren, die spezifisch für den Host sind, auf dem Bazel ausgeführt wird.

Repository-Regel erstellen

Erstellen Sie in einer .bzl-Datei die Funktion repository_rule, um eine neue Repository-Regel zu erstellen und in einer globalen Variablen zu speichern.

Eine benutzerdefinierte Repository-Regel kann genau wie eine native Repository-Regel verwendet werden. Es hat ein obligatorisches name-Attribut und jedes Ziel in seinen Build-Dateien kann als @<name>//package:target bezeichnet werden, wobei <name> der Wert des name-Attributs ist.

Die Regel wird geladen, wenn Sie sie explizit erstellen oder wenn sie eine Abhängigkeit des Builds ist. In diesem Fall führt Bazel die Funktion implementation aus. Diese Funktion beschreibt, wie das Repository, sein Inhalt und die BUILD-Dateien erstellt werden.

Attribute

Ein Attribut ist ein Regelargument, z. B. url oder sha256. Sie müssen die Attribute und ihre Typen auflisten, wenn Sie eine Repository-Regel definieren.

local_repository = repository_rule(
    implementation=_impl,
    local=True,
    attrs={"path": attr.string(mandatory=True)})

Verwenden Sie repository_ctx.attr.<attribute_name>, um auf ein Attribut zuzugreifen.

Alle repository_rules haben implizit definierte Attribute (wie Build-Regeln). Die beiden impliziten Attribute sind name (wie bei Build-Regeln) und repo_mapping. Der Name einer Repository-Regel ist mit repository_ctx.name zugänglich. Die Bedeutung von repo_mapping ist die gleiche wie für die nativen Repository-Regeln local_repository und new_local_repository.

Wenn ein Attributname mit _ beginnt, ist er privat und Nutzer können ihn nicht festlegen.

Implementierungsfunktion

Für jede Repository-Regel ist eine implementation-Funktion erforderlich. Sie enthält die tatsächliche Logik der Regel und wird ausschließlich in der Ladephase ausgeführt.

Die Funktion hat genau einen Eingabeparameter, repository_ctx. Die Funktion gibt entweder None zurück, um anzugeben, dass die Regel mit den angegebenen Parametern reproduzierbar ist, oder ein Wörterbuch mit einer Reihe von Parametern für diese Regel, die diese Regel in einen reproduzierbaren Wert umwandeln würde, der dasselbe Repository generiert. Für eine Regel, die ein Git-Repository aufzeichnet, würde beispielsweise die Rückgabe einer bestimmten Commit-ID anstelle eines unverankerten Zweigs zurückgegeben, der ursprünglich angegeben wurde.

Mit dem Eingabeparameter repository_ctx kann auf Attributwerte und nicht hermetische Funktionen zugegriffen werden (Suchen einer Binärdatei, Ausführen einer Binärdatei, Erstellen einer Datei im Repository oder Herunterladen einer Datei aus dem Internet). Weitere Informationen finden Sie in der Bibliothek. Beispiel:

def _impl(repository_ctx):
  repository_ctx.symlink(repository_ctx.attr.path, "")

local_repository = repository_rule(
    implementation=_impl,
    ...)

Wann wird die Implementierungsfunktion ausgeführt?

Wenn das Repository als local deklariert ist, führt die Änderung in einer Abhängigkeit im Abhängigkeitsdiagramm (einschließlich der Datei WORKSPACE selbst) zur Ausführung der Implementierungsfunktion.

Die Implementierungsfunktion kann neu gestartet werden, wenn eine von ihr angeforderte Abhängigkeit fehlt. Der Beginn der Implementierungsfunktion wird noch einmal ausgeführt, nachdem die Abhängigkeit behoben wurde. Zur Vermeidung unnötiger Neustarts (die teuer sind, da der Netzwerkzugriff möglicherweise wiederholt werden muss), werden Labelargumente vorab abgerufen, sofern alle Labelargumente in eine vorhandene Datei aufgelöst werden können. Beachten Sie, dass das Auflösen eines Pfades aus einem String oder einem Label, das nur während der Ausführung der Funktion erstellt wurde, möglicherweise einen Neustart verursacht.

Bei Nicht-local-Repositories kann bereits eine Änderung der folgenden Abhängigkeiten einen Neustart verursachen:

  • .bzl Dateien erforderlich, um die Repository-Regel zu definieren.
  • Deklaration der Repository-Regel in der Datei WORKSPACE.
  • Wert einer Umgebungsvariablen, die mit dem Attribut environ der Funktion repository_rule deklariert wurde. Der Wert dieser Umgebungsvariablen kann über die Befehlszeile mit dem Flag --action_env erzwungen werden. Dieses Flag führt jedoch dazu, dass jede Aktion des Builds ungültig wird.
  • Inhalt einer Datei, die von einem Label verwendet und auf die verwiesen wird (z. B. //mypkg:label.txt, nicht mypkg/label.txt).

Erneutes Abrufen externer Repositories erzwingen

Manchmal kann ein externes Repository veraltet sein, ohne dass sich die Definition oder Abhängigkeiten ändern. Beispiel: Ein Repository, das Quellen abruft, könnte einem bestimmten Zweig eines Drittanbieter-Repositorys folgen und für diesen Zweig sind neue Commits verfügbar. In diesem Fall können Sie Bazel anfordern, um alle externen Repositories bedingungslos abzurufen. Dazu rufen Sie bazel sync auf.

Darüber hinaus prüfen einige Regeln den lokalen Computer und sind möglicherweise veraltet, wenn ein Upgrade für den lokalen Computer durchgeführt wurde. Hier können Sie festlegen, dass Bazel nur die externen Repositories abrufen soll, in denen die Attribut repository_rule das Attribut configure festgelegt hat. Verwenden Sie dafür bazel sync --configure.

Beispiele

  • Automatisch konfigurierte C++-Toolchain: Es verwendet eine Repository-Regel, um die C++-Konfigurationsdateien für Bazel automatisch zu erstellen. Dazu wird nach dem lokalen C++-Compiler, der Umgebung und den Flags gesucht, die der C++-Compiler unterstützt.

  • Go-Repositories verwenden mehrere repository_rule, um die Liste der Abhängigkeiten zu definieren, die für die Verwendung der Go-Regeln erforderlich sind.

  • rules_jvm_external erstellt standardmäßig ein externes Repository mit dem Namen @maven, das Build-Ziele für jedes Maven-Artefakt in der temporären Abhängigkeitsstruktur generiert.