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

Labels

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

Alle Ziele gehören genau zu einem Paket. Der Name eines Ziels wird als Label bezeichnet. Jedes Label identifiziert ein Ziel eindeutig. Ein typisches Label in kanonischer Form sieht so aus:

@myrepo//my/app/main:app_binary

Der erste Teil des Labels ist der Repository-Name @myrepo//. Wenn sich ein Label üblicherweise auf dasselbe Repository bezieht, mit dem es verwendet wird, kann die Repository-ID als // abgekürzt werden. In @myrepo lautet das Label normalerweise

//my/app/main:app_binary

Der zweite Teil des Labels ist der nicht qualifizierte Paketname my/app/main. Das ist der Pfad zum Paket im Verhältnis zum Stammverzeichnis des Repositorys. Zusammen bilden der Repository-Name und der nicht qualifizierte Paketname den voll qualifizierten Paketnamen @myrepo//my/app/main. Wenn das Label auf das Paket verweist, in dem es verwendet wird, kann der Paketname (und optional auch der Doppelpunkt) weggelassen werden. In @myrepo//my/app/main kann dieses Label also so geschrieben werden:

app_binary
:app_binary

Über den Doppelpunkt wird für Dateien ausgelassen, aber für Regeln beibehalten. Ansonsten ist er aber nicht signifikant.

Der Teil des Labels nach dem Doppelpunkt app_binary ist der nicht qualifizierte Zielname. Wenn sie mit der letzten Komponente des Paketpfads übereinstimmt, werden sie und der Doppelpunkt möglicherweise weggelassen. Diese beiden Labels sind also äquivalent:

//my/app/lib
//my/app/lib:lib

Der Name eines Dateiziels in einem Unterverzeichnis des Pakets ist der Pfad der Datei relativ zum Stammverzeichnis des Pakets (das Verzeichnis mit der Datei BUILD). Diese Datei befindet sich im Unterverzeichnis my/app/main/testdata des Repositorys:

//my/app/main:testdata/input.txt

Labels wie //my/app werden nicht mit Paketnamen verwechselt. Labels beginnen immer mit einer Repository-ID (abgekürzt von //), die Paketnamen werden jedoch nie geändert. Daher ist my/app das Paket mit //my/app/lib, das auch als //my/app/lib:lib geschrieben werden kann.

Es wird häufig darauf geachtet, dass sich //my/app auf ein Paket oder auf alle Ziele eines Pakets bezieht. Beides gilt nicht. Sie entspricht //my/app:app, sodass das Ziel app im Paket my/app des aktuellen Repositorys benannt wird.

Relative Labels können nicht auf Ziele in anderen Paketen verwendet werden. In diesem Fall müssen die Repository-ID und der Paketname immer angegeben werden. Wenn die Quellstruktur beispielsweise sowohl das Paket my/app als auch das Paket my/app/testdata enthält (jedes dieser beiden Verzeichnisse hat eine eigene BUILD-Datei), enthält das letzte Paket eine Datei namens testdepot.zip. Es gibt zwei Möglichkeiten, innerhalb von //my/app:BUILD auf diese Datei zu verweisen: eine falsche und eine richtige.

Falsch: testdata ist ein anderes Paket. Sie können also keinen relativen Pfad verwenden.

testdata/testdepot.zip

Richtig: Verweis mit testdata zum vollständigen Pfad

//my/app/testdata:testdepot.zip

Labels, die mit @// beginnen, sind Verweise auf das Haupt-Repository, das auch von externen Repositories funktioniert. Daher unterscheidet sich @//a/b/c von //a/b/c, wenn von einem externen Repository verwiesen wird. Ersteres bezieht sich auf das Haupt-Repository, während Letzteres nach //a/b/c im externen Repository selbst sucht. Dies ist besonders dann wichtig, wenn Regeln im Haupt-Repository erstellt werden, die sich auf Ziele im Haupt-Repository beziehen. Sie werden aus externen Repositories verwendet.

Informationen zu den verschiedenen Möglichkeiten, auf Verweise zu verweisen, finden Sie unter Zielmuster.

Lexische Spezifikation eines Labels

Von Labelsyntax wird die Verwendung von Metazeichen, die eine besondere Bedeutung für die Shell haben, davon abgeraten. So vermeiden Sie versehentliche Zitationen und es ist einfacher, Tools und Skripts zu erstellen, mit denen Labels wie die Bazel Query Language bearbeitet werden können.

Die genauen Details der zulässigen Zielnamen finden Sie weiter unten.

Zielnamen – package-name:target-name

target-name der Name des Ziels im Paket. Der Name einer Regel ist der Wert des Attributs name in der Deklaration der Regel in einer BUILD-Datei. Der Name einer Datei ist der Pfadname relativ zu dem Verzeichnis, das die Datei BUILD enthält.

Zielnamen müssen komplett aus Zeichen bestehen, die aus den Sätzen az, AZ, 09 und den Satzzeichen !%-@^_"#$&'()*-+,;<=>?[]{|}~/. bestehen.

Dateinamen müssen relative Pfadnamen in normaler Form sein. Das heißt, sie dürfen weder mit einem Schrägstrich beginnen oder enden (z. B. /foo und foo/ sind unzulässig) noch mehrere aufeinanderfolgende Schrägstriche als Pfadtrennzeichen enthalten (z. B. foo//bar). Ebenso sind Verweise auf höherer Ebene (..) und Verweise auf das aktuelle Verzeichnis (./) unzulässig.

Falsch: Verwenden Sie nicht „.“, um auf Dateien in anderen Paketen zu verweisen.

Richtig: Verwenden Sie „`package-name:filename“.

Es ist üblich, / im Namen eines Dateiziels zu verwenden. Vermeiden Sie jedoch / in den Namen von Regeln. Besonders wenn du die Kurzform eines Labels verwendest, kann es für die Leser verwirrend sein. Das Label //foo/bar/wiz ist immer eine Kurzform für //foo/bar/wiz:wiz, auch wenn kein solches Paket foo/bar/wiz vorhanden ist. Es bezieht sich nie auf //foo:bar/wiz, auch wenn dieses Ziel vorhanden ist.

In einigen Situationen ist die Verwendung eines Schrägstrichs aber praktisch oder sogar notwendig. Der Name bestimmter Regeln muss beispielsweise mit der Hauptquellquelldatei übereinstimmen, die sich in einem Unterverzeichnis des Pakets befindet.

Paketnamen – //package-name:target-name

Der Name eines Pakets ist der Name des Verzeichnisses, in dem die BUILD-Datei angegeben ist. Diese muss relativ zum obersten Verzeichnis des entsprechenden Repositories angegeben sein. Beispiel: my/app

Paketnamen dürfen nur aus Zeichen bestehen, die aus dem Satz A-Z, az, 09, '/', '-', '.', '@' sowie '_' stammen und nicht mit einem S-Zeichen beginnen.

Bei einer Sprache mit einer Verzeichnisstruktur, die für ihr Modulsystem wichtig ist (z. B. Java), ist es wichtig, Verzeichnisnamen auszuwählen, die in der Sprache gültige Kennungen sind.

Obwohl {5/} Ziele im Root-Paket des Arbeitsbereichs unterstützt (z. B. //:foo), sollte dieses Paket nicht leer sein, damit alle aussagekräftigen Pakete beschreibende Namen haben.

Paketnamen dürfen weder den Teilstring // noch einen Schrägstrich enthalten.

Regeln

Eine Regel gibt die Beziehung zwischen Ein- und Ausgaben sowie die Schritte zum Erstellen der Ausgaben an. Regeln können eine von vielen verschiedenen Arten sein (auch als Regelklasse bezeichnet). Sie produzieren kompilierte ausführbare Dateien und Bibliotheken, testen ausführbare Dateien und andere unterstützte Ausgaben, wie in der Build-Enzyklopädie beschrieben.

BUILD-Dateien deklarieren Ziele durch Aufrufen von Regeln.

Im Beispiel unten sehen Sie die Deklaration des Ziels my_app mithilfe der Regel cc_binary.

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)

Jeder Regelaufruf hat ein name-Attribut (muss ein gültiger Zielname sein), mit dem ein Ziel innerhalb des Pakets der Datei BUILD deklariert wird.

Jede Regel enthält eine Reihe von Attributen. Die anwendbaren Attribute für eine bestimmte Regel und die Bedeutung und Semantik jedes Attributs sind eine Funktion der Regel. Eine Liste der Regeln und der entsprechenden Attribute finden Sie in der Build-Enzyklopädie. Jedes Attribut hat einen Namen und einen Typ. Folgende Attribute können häufig verwendet werden: Ganzzahl, Label, Liste mit Labels, String, Liste mit Strings, Ausgabelabel, Liste mit Ausgabelabels. Nicht alle Attribute müssen in jeder Regel angegeben werden. Attribute bilden also ein Wörterbuch von Schlüsseln (Namen) bis zu optionalen Eingabewerten.

Das in vielen Regeln vorhandene srcs-Attribut hat den Typ „Liste der Labels“. Ist dieser Wert vorhanden, handelt es sich um eine Liste von Labels. Jeder Wert ist der Name eines Ziels, das als Eingabe für diese Regel gilt.

In einigen Fällen ist der Name der Regelart eher willkürlich. Interessanter sind die Namen der Dateien, die von der Regel generiert werden. Das trifft auch auf allgemeine Regeln zu. Weitere Informationen finden Sie unter Allgemeine Regeln: Genrule.

In anderen Fällen ist der Name signifikant: Für *_binary- und *_test-Regeln bestimmt der Regelname beispielsweise den Namen der ausführbaren Datei, die vom Build erzeugt wurde.

Dieser gerichtete azyklische Graph über Ziele wird als Zieldiagramm oder Build-Abhängigkeitsgrafik bezeichnet und ist die Domain, über die das Bazel-Abfragetool funktioniert.

Ziele Dateien erstellen