Формат файла Android.bp

Файлы Android.bp имеют простую структуру. Они не содержат условных операторов или операторов управления потоком; вся сложность обрабатывается логикой сборки, написанной на Go.

Модули

Модуль в файле Android.bp начинается с типа модуля, за которым следует набор свойств в формате name: "value",:

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

У каждого модуля должно быть свойство name, значение которого должно быть уникальным для всех файлов Android.bp, за исключением значений свойства name в пространствах имен и предварительно созданных модулях, которые могут повторяться.

Свойство srcs указывает исходные файлы, используемые для создания модуля, в виде списка строк. Вы можете ссылаться на выходные данные других модулей, которые создают исходные файлы, например genrule или filegroup, используя синтаксис ссылки на модуль ":<module-name>".

Чтобы посмотреть список допустимых типов модулей и их свойств, ознакомьтесь со справочной документацией по модулям Soong, которая создается при выполнении команды m soong_docs. Результат будет на языке out/soong/docs/soong_build.html.

Типы

Переменные и свойства строго типизированы. Переменные динамически основаны на первом назначении, а свойства статически задаются типом модуля. Поддерживаются следующие типы:

  • Логические значения (true или false)
  • Целые числа (int)
  • Строки ("string")
  • Списки строк (["string1", "string2"])
  • Карты ({key1: "value1", key2: ["value2"]})

Карты могут содержать значения любого типа, включая вложенные карты. В списках и картах после последнего значения могут стоять запятые.

Шарики

Свойства, которые принимают список файлов, например srcs, также могут принимать шаблоны glob. Шаблоны glob могут содержать стандартный подстановочный знак UNIX *, например *.java. Шаблоны glob также могут содержать один подстановочный знак ** в качестве элемента пути, который соответствует нулю или нескольким элементам пути. Например, java/**/*.java соответствует шаблонам java/Main.java и java/com/android/Main.java.

Переменные

Файл Android.bp может содержать назначения переменных верхнего уровня:

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

Область действия переменных распространяется на оставшуюся часть файла, в котором они объявлены, а также на все дочерние файлы Blueprint. Переменные неизменяемы, за одним исключением: к ним можно добавлять значения с помощью оператора +=, но только до того, как на них будет сделана ссылка.

Комментарии

Файлы Android.bp могут содержать многострочные комментарии /* */ в стиле C и однострочные комментарии // в стиле C++.

Операторы

Строки, списки строк и карты можно добавлять с помощью оператора +. Целые числа можно суммировать с помощью оператора +. При добавлении карты создается объединение ключей в обеих картах, при этом добавляются значения всех ключей, присутствующих в обеих картах.

Модули по умолчанию

Разработчики могут использовать модуль defaults, чтобы повторять одни и те же свойства в нескольких модулях. Пример:

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

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

Готовые модули

Некоторые типы встроенных модулей могут иметь такое же название, как и их аналоги на основе исходного кода. Например, у вас может быть cc_prebuilt_binary с названием foo, даже если у вас уже есть cc_binary с таким же названием. Это позволяет разработчикам выбирать, какую версию включить в конечный продукт. Если конфигурация сборки содержит обе версии, значение флага prefer в определении предварительно созданного модуля определяет, какая версия имеет приоритет. Обратите внимание, что названия некоторых встроенных модулей не начинаются с prebuilt, например android_app_import.

Модули пространства имен

Пока Android не перейдет полностью с Make на Soong, в конфигурации продукта Make должно быть указано значение PRODUCT_SOONG_NAMESPACES. Его значением должен быть разделенный пробелами список пространств имен, которые Soong экспортирует в Make для сборки с помощью команды m. После завершения перехода Android на Soong сведения о включении пространств имен могут измениться.

Soong позволяет модулям в разных каталогах указывать одно и то же имя, если каждый модуль объявлен в отдельном пространстве имен. Разработчики могут объявить пространство имен:

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

Обратите внимание, что у пространства имен нет свойства name. Его путь автоматически назначается в качестве названия.

Каждому модулю Soong назначается пространство имен на основе его расположения в дереве. Считается, что каждый модуль Soong находится в пространстве имен, определенном свойством soong_namespace, которое указано в файле Android.bp в текущем каталоге или ближайшем родительском каталоге. Если такой модуль soong_namespace не найден, считается, что модуль находится в неявном корневом пространстве имен.

Пример: Soong пытается разрешить зависимость D, объявленную модулем M в пространстве имен N, которое импортирует пространства имен I1, I2, I3…

  1. Если D – полное имя в формате //namespace:module, то поиск указанного модуля выполняется только в указанном пространстве имен.
  2. В противном случае Soong сначала ищет модуль с именем D, объявленный в пространстве имен N.
  3. Если такого модуля нет, Soong ищет модуль с именем D в пространствах имен I1, I2, I3…
  4. Soong ищет в корневом пространстве имен.

Условные предложения

Soong не поддерживает условные выражения в файлах Android.bp. Вместо этого сложные правила сборки, требующие условных выражений, обрабатываются в Go, где можно использовать функции языка высокого уровня и отслеживать неявные зависимости, вводимые условными выражениями. Большинство условных выражений преобразуются в свойство map, в котором выбирается одно из значений и добавляется к свойствам верхнего уровня.

Например, чтобы поддерживать файлы для определенных архитектур:

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

Форматировщик

Soong включает канонический форматтер для файлов Blueprint, аналогичный gofmt. Чтобы рекурсивно переформатировать все файлы Android.bp в текущем каталоге, выполните следующую команду:

bpfmt -w .

Канонический формат включает отступы в четыре пробела, новые строки после каждого элемента многоэлементного списка и конечную запятую в списках и картах.