Android.bp-Dateiformat

Android.bp-Dateien sind von Natur aus unkompliziert. Sie enthalten keine Bedingungen oder Kontrollflussanweisungen. Die gesamte Komplexität wird durch die in Go geschriebene Build-Logik verarbeitet.

Module

Ein Modul in einer Android.bp-Datei beginnt mit einem Modultyp, gefolgt von einer Reihe von Attributen im name: "value",-Format:

cc_binary {
    name: "gzip",
    srcs: ["src/test/minigzip.c"],
    shared_libs: ["libz"],
    stl: "none",
}

Jedes Modul muss ein name-Attribut haben und der Wert muss in allen Android.bp-Dateien eindeutig sein. Eine Ausnahme bilden die name-Attributwerte in Namespaces und vorgefertigten Modulen, die sich wiederholen können.

Das Attribut srcs gibt die Quelldateien an, die zum Erstellen des Moduls verwendet werden, und zwar als Liste von Strings. Sie können mit der Modulreferenzsyntax ":<module-name>" auf die Ausgabe anderer Module verweisen, die Quelldateien erstellen, z. B. genrule oder filegroup.

Eine Liste der gültigen Modultypen und ihrer Attribute finden Sie in der Soong-Modulreferenz, die durch Ausführen von m soong_docs generiert wird. Die Ausgabe befindet sich in out/soong/docs/soong_build.html.

Typen

Variablen und Attribute sind stark typisiert. Variablen werden dynamisch basierend auf der ersten Zuweisung festgelegt und Attribute werden statisch durch den Modultyp festgelegt. Die unterstützten Typen sind:

  • Boolesche Werte (true oder false)
  • Ganzzahlen (int)
  • Strings ("string")
  • Listen von Strings (["string1", "string2"])
  • Zuordnungen ({key1: "value1", key2: ["value2"]})

Zuordnungen können Werte beliebigen Typs enthalten, einschließlich verschachtelter Zuordnungen. Listen und Zuordnungen können nach dem letzten Wert ein nachgestelltes Komma haben.

Globs

Attribute, die eine Liste von Dateien akzeptieren, z. B. srcs, können auch Glob-Muster akzeptieren. Glob-Muster können den normalen UNIX-Platzhalter * enthalten, z. B. *.java. Glob-Muster können auch einen einzelnen **-Platzhalter als Pfadelement enthalten, der mit null oder mehr Pfadelementen übereinstimmt. Beispielsweise stimmt java/**/*.java sowohl mit dem Muster java/Main.java als auch mit java/com/android/Main.java überein.

Variablen

Eine Android.bp-Datei kann Zuweisungen von Variablen auf oberster Ebene enthalten:

gzip_srcs = ["src/test/minigzip.c"],
cc_binary {
    name: "gzip",
    srcs: gzip_srcs,
    shared_libs: ["libz"],
    stl: "none",
}

Variablen sind auf den Rest der Datei beschränkt, in der sie deklariert werden, sowie auf alle untergeordneten Blueprint-Dateien. Variablen sind unveränderlich, mit einer Ausnahme: Sie können mit einer +=-Zuweisung angehängt werden, aber nur bevor auf sie verwiesen wird.

Kommentare

Android.bp -Dateien können mehrzeilige Kommentare im C-Stil /* */ und einzeilige Kommentare im C++-Stil // enthalten.

Operatoren

Strings, Listen von Strings und Zuordnungen können mit dem Operator „+“ angehängt werden. Ganzzahlen können mit dem Operator + addiert werden. Wenn Sie eine Zuordnung anhängen, wird die Vereinigung der Schlüssel in beiden Zuordnungen erstellt und die Werte aller Schlüssel angehängt, die in beiden Zuordnungen vorhanden sind.

Standardmodule

Entwickler können ein Standardmodul verwenden, um dieselben Attribute in mehreren Modulen zu wiederholen. Beispiel:

cc_defaults {
    name: "gzip_defaults",
    shared_libs: ["libz"],
    stl: "none",
}

cc_binary {
    name: "gzip",
    defaults: ["gzip_defaults"],
    srcs: ["src/test/minigzip.c"],
}

Vorgefertigte Module

Bei einigen vorgefertigten Modultypen kann ein Modul denselben Namen wie seine quellbasierten Gegenstücke haben. Beispielsweise kann es ein cc_prebuilt_binary mit dem Namen foo geben, wenn bereits ein cc_binary mit demselben Namen vorhanden ist. So können Entwickler flexibel auswählen, welche Version in ihr Endprodukt aufgenommen werden soll. Wenn eine Build-Konfiguration beide Versionen enthält, bestimmt der Wert des Flags prefer in der Definition des vorgefertigten Moduls, welche Version Priorität hat. Einige vorgefertigte Module haben Namen, die nicht mit prebuilt beginnen, z. B. android_app_import.

Namespace-Module

Bis Android vollständig von Make zu Soong migriert ist, muss in der Make-Produktkonfiguration ein PRODUCT_SOONG_NAMESPACES-Wert angegeben werden. Der Wert sollte eine durch Leerzeichen getrennte Liste von Namespaces sein, die von Soong nach Make exportiert werden, um mit dem Befehl m erstellt zu werden. Nach Abschluss der Migration von Android zu Soong können sich die Details zum Aktivieren von Namespaces ändern.

Soong ermöglicht es Modulen in verschiedenen Verzeichnissen, denselben Namen anzugeben, sofern jedes Modul in einem separaten Namespace deklariert wird. Entwickler können einen Namespace deklarieren:

soong_namespace {
    imports: ["path/to/otherNamespace1", "path/to/otherNamespace2"],
}

Ein Namespace hat kein name-Attribut. Sein Pfad wird automatisch als Name zugewiesen.

Jedem Soong-Modul wird basierend auf seiner Position in der Struktur ein Namespace zugewiesen. Jedes Soong-Modul befindet sich im Namespace, der durch das soong_namespace definiert wird, das in einer Android.bp-Datei im aktuellen Verzeichnis oder im nächstgelegenen übergeordneten Verzeichnis gefunden wird. Wenn kein solches soong_namespace-Modul gefunden wird, befindet sich das Modul im impliziten Stamm-Namespace.

Beispiel: Soong versucht, die Abhängigkeit D aufzulösen, die von Modul M im Namespace N deklariert wurde, der die Namespaces I1, I2, I3… importiert.

  1. Wenn D ein voll qualifizierter Name der Form //namespace:module ist, wird nur im angegebenen Namespace nach dem angegebenen Modulnamen gesucht.
  2. Andernfalls sucht Soong zuerst nach einem Modul mit dem Namen D, das im Namespace N deklariert wurde.
  3. Wenn dieses Modul nicht vorhanden ist, sucht Soong nach einem Modul mit dem Namen D in den Namespaces I1, I2, I3…
  4. Soong sucht im Stamm-Namespace.

Bedingungen

Soong unterstützt keine Bedingungen in Android.bp-Dateien. Stattdessen wird die Komplexität in Build-Regeln, die Bedingungen erfordern würden, in Go verarbeitet. Dort können Sprachfunktionen auf hoher Ebene verwendet und implizite Abhängigkeiten verfolgt werden, die durch Bedingungen eingeführt werden. Die meisten Bedingungen werden in ein Zuordnungsattribut konvertiert, wobei einer der Werte in der Zuordnung ausgewählt und an die Attribute auf oberster Ebene angehängt wird.

Beispiel zur Unterstützung architekturabhängiger Dateien:

cc_library {
    ...
    srcs: ["generic.cpp"],
    arch: {
        arm: {
            srcs: ["arm.cpp"],
        },
        x86: {
            srcs: ["x86.cpp"],
        },
    },
}

Formatter

Soong enthält einen kanonischen Formatter für Blueprint-Dateien, ähnlich wie gofmt. Führen Sie Folgendes aus, um alle Android.bp-Dateien im aktuellen Verzeichnis rekursiv neu zu formatieren:

bpfmt -w .

Das kanonische Format umfasst Einzüge mit vier Leerzeichen, neue Zeilen nach jedem Element einer Liste mit mehreren Elementen und ein nachgestelltes Komma in Listen und Zuordnungen.