Format pliku Android.bp

Pliki Android.bp są z założenia proste. Nie zawierają one instrukcji warunkowych ani instrukcji sterujących przepływem. Cała złożoność jest obsługiwana przez logikę kompilacji napisaną w języku Go.

Moduły

Moduł w pliku Android.bp zaczyna się od typu modułu, a następnie zawiera zestaw właściwości w formacie name: "value",:

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

Każdy moduł musi mieć właściwość name, a jej wartość musi być unikalna we wszystkich plikach Android.bp, z wyjątkiem wartości właściwości name w przestrzeniach nazw i gotowych modułach, które mogą się powtarzać.

Właściwość srcs określa pliki źródłowe używane do tworzenia modułu jako listę ciągów znaków. Możesz odwoływać się do danych wyjściowych innych modułów, które generują pliki źródłowe, np. genrule lub filegroup, używając składni odwołania do modułu ":<module-name>".

Listę prawidłowych typów modułów i ich właściwości znajdziesz w dokumentacji modułów Soong.

Typy

Zmienne i właściwości mają silne typy. Zmienne są określane dynamicznie na podstawie pierwszego przypisania, a właściwości są ustawiane statycznie przez typ modułu. Obsługiwane typy to:

  • Wartości logiczne (true lub false)
  • Liczby całkowite (int)
  • Ciągi znaków ("string")
  • Listy ciągów znaków (["string1", "string2"])
  • Mapy ({key1: "value1", key2: ["value2"]})

Mapy mogą zawierać wartości dowolnego typu, w tym zagnieżdżone mapy. Listy i mapy mogą zawierać przecinki po ostatniej wartości.

Globs

Właściwości, które przyjmują listę plików, np. srcs, mogą też przyjmować wzorce glob. Wzorce glob mogą zawierać zwykły symbol wieloznaczny UNIX *, np. *.java. Wzorce glob mogą też zawierać pojedynczy symbol wieloznaczny ** jako element ścieżki, który pasuje do zera lub większej liczby elementów ścieżki. Na przykład wzorzec java/**/*.java pasuje do wzorców java/Main.java i java/com/android/Main.java.

Zmienne

Plik Android.bp może zawierać przypisania zmiennych najwyższego poziomu:

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

Zmienne są ograniczone do pozostałej części pliku, w którym zostały zadeklarowane, a także do wszystkich podrzędnych plików Blueprint. Zmienne są niezmienne z jednym wyjątkiem: można do nich dodawać wartości za pomocą przypisania +=, ale tylko zanim zostaną użyte.

Komentarze

Pliki Android.bp mogą zawierać wielowierszowe komentarze w stylu C /* */ i jednowierszowe komentarze w stylu C++ //.

Operatorzy

Ciągi tekstowe, listy ciągów tekstowych i mapy można dołączać za pomocą operatora +. Liczby całkowite można sumować za pomocą operatora +. Dołączenie mapy powoduje utworzenie sumy kluczy z obu map i dołączenie wartości kluczy, które występują na obu mapach.

Moduły domyślne

Deweloperzy mogą używać modułu domyślnego, aby powtarzać te same właściwości w wielu modułach. Na przykład:

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

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

Gotowe moduły

Niektóre gotowe typy modułów umożliwiają nadanie modułowi takiej samej nazwy jak jego odpowiednik oparty na źródle. Na przykład może istnieć cc_prebuilt_binary o nazwie foo, jeśli istnieje już cc_binary o tej samej nazwie. Daje to deweloperom elastyczność w wyborze wersji, którą chcą uwzględnić w produkcie końcowym. Jeśli konfiguracja kompilacji zawiera obie wersje, wartość flagi prefer w definicji wstępnie skompilowanego modułu określa, która wersja ma priorytet. Pamiętaj, że niektóre gotowe moduły mają nazwy, które nie zaczynają się od prebuilt, np. android_app_import.

Moduły przestrzeni nazw

Dopóki Android nie przejdzie w pełni z Make na Soong, konfiguracja produktu Make musi określać wartość PRODUCT_SOONG_NAMESPACES. Jej wartość powinna być listą przestrzeni nazw rozdzielonych spacjami, które Soong eksportuje do Make, aby można je było skompilować za pomocą polecenia m. Po zakończeniu konwersji Androida na Soong szczegóły włączania przestrzeni nazw mogą się zmienić.

Soong umożliwia modułom w różnych katalogach określanie tej samej nazwy, o ile każdy moduł jest zadeklarowany w osobnej przestrzeni nazw. Deweloperzy mogą zadeklarować przestrzeń nazw:

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

Pamiętaj, że przestrzeń nazw nie ma właściwości name. Jej ścieżka jest automatycznie przypisywana jako nazwa.

Każdy moduł Soong ma przypisaną przestrzeń nazw na podstawie jego lokalizacji w drzewie. Każdy moduł Soong jest uważany za znajdujący się w przestrzeni nazw zdefiniowanej przez soong_namespace w pliku Android.bp w bieżącym katalogu lub w najbliższym katalogu nadrzędnym. Jeśli nie znaleziono takiego modułu soong_namespace, moduł jest traktowany jako znajdujący się w niejawnej głównej przestrzeni nazw.

Przykład: Soong próbuje rozwiązać zależność D zadeklarowaną przez moduł M w przestrzeni nazw N, która importuje przestrzenie nazw I1, I2, I3…

  1. Jeśli D jest w pełni kwalifikowaną nazwą w formacie //namespace:module, wyszukiwana jest tylko określona przestrzeń nazw dla określonej nazwy modułu.
  2. W przeciwnym razie Soong najpierw szuka modułu o nazwie D zadeklarowanego w przestrzeni nazw N.
  3. Jeśli ten moduł nie istnieje, Soong szuka modułu o nazwie D w przestrzeniach nazw I1, I2, I3…
  4. Soong szuka w głównej przestrzeni nazw.

Warunki

Soong nie obsługuje warunków w plikach Android.bp. Zamiast tego złożoność reguł kompilacji, które wymagałyby warunków, jest obsługiwana w Go, gdzie można używać funkcji języka wysokiego poziomu, a zależności niejawne wprowadzone przez warunki można śledzić. Większość warunków jest przekształcana we właściwość mapy, w której jedna z wartości na mapie jest wybierana i dołączana do właściwości najwyższego poziomu.

Aby na przykład obsługiwać pliki specyficzne dla architektury:

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

Formatter

Soong zawiera kanoniczny program formatujący pliki Blueprint, podobny do gofmt. Aby rekurencyjnie sformatować wszystkie pliki Android.bp w bieżącym katalogu, uruchom:

bpfmt -w .

Format kanoniczny obejmuje wcięcia 4-znakowe, nowe wiersze po każdym elemencie listy wieloelementowej oraz przecinek na końcu list i map.