Интеграция пользовательских систем сборки C/C++ с помощью Ninja (экспериментальная функция)

Если вы не используете CMake или ndk-build, но хотите полностью интегрировать сборку C/C++ плагина Android Gradle (AGP) и Android Studio, вы можете создать собственную систему сборки C/C++, создав сценарий командной оболочки, который записывает информацию о сборке в формате файла сборки Ninja.

В Android Studio и AGP добавлена экспериментальная поддержка пользовательских систем сборки C/C++. Эта функция доступна в Android Studio Dolphin | 2021.3.1 Canary 4 и более поздних версиях.

Обзор

Распространенный шаблон для проектов C/C++, особенно тех, которые нацелены на несколько платформ, заключается в создании проектов для каждой из этих платформ на основе некоторого базового представления. Ярким примером такого шаблона является CMake. CMake может генерировать проекты для Android, iOS и других платформ на основе одного базового представления, сохраненного в файле CMakeLists.txt.

Хотя CMake напрямую поддерживается AGP, существуют и другие генераторы проектов, которые не поддерживаются напрямую:

Эти типы генераторов проектов либо поддерживают Ninja в качестве серверного представления сборки C/C++, либо могут быть адаптированы для создания Ninja в качестве серверного представления.

При правильной настройке проект AGP с интегрированным генератором системы проектов C/C++ позволяет пользователям:

  • Сборка из командной строки и Android Studio.

  • Редактируйте исходный код в Android Studio с полной поддержкой языковых сервисов, например переходом к определению.

  • Используйте отладчики Android Studio для отладки нативных и смешанных процессов.

Как изменить сборку, чтобы использовать собственный скрипт конфигурации сборки C/C++

В этом разделе описано, как использовать собственный скрипт конфигурации сборки C/C++ из AGP.

Шаг 1. Измените файл build.gradle на уровне модуля, чтобы он ссылался на скрипт конфигурации

Чтобы включить поддержку Ninja в AGP, настройте experimentalProperties в файле build.gradle на уровне модуля:

android {
  defaultConfig {
    externalNativeBuild {
      experimentalProperties["ninja.abiFilters"] = [ "x86", "arm64-v8a" ]
      experimentalProperties["ninja.path"] = "source-file-list.txt"
      experimentalProperties["ninja.configure"] = "configure-ninja"
      experimentalProperties["ninja.arguments"] = [
            "\${ndk.moduleMakeFile}",
            "--variant=\${ndk.variantName}",
            "--abi=Android-\${ndk.abi}",
            "--configuration-dir=\${ndk.configurationDir}",
            "--ndk-version=\${ndk.moduleNdkVersion}",
            "--min-sdk-version=\${ndk.minSdkVersion}"
       ]
     }
   }

AGP интерпретирует свойства следующим образом:

  • ninja.abiFilters – список ABI для сборки. Допустимые значения: x86, x86-64, armeabi-v7a и arm64-v8a.

  • ninja.path – путь к файлу проекта C/C++. Формат этого файла может быть любым. Изменения в этом файле вызовут запрос на синхронизацию Gradle в Android Studio.

  • ninja.configure – путь к файлу скрипта, который будет выполняться Gradle, когда потребуется настроить проект C/C++. Проект настраивается при первой сборке, во время синхронизации Gradle в Android Studio или при изменении одного из входных данных скрипта настройки.

  • ninja.arguments – список аргументов, которые будут переданы скрипту, определенному в ninja.configure. Элементы в этом списке могут ссылаться на набор макросов, значения которых зависят от текущего контекста конфигурации в AGP:

    • ${ndk.moduleMakeFile} – полный путь к файлу ninja.configure. В нашем примере это C:\path\to\configure-ninja.bat.

    • ${ndk.variantName} – название текущего варианта AGP, который создается. например отладочная или рабочая.

    • ${ndk.abi} – название текущего ABI плагина Android для Gradle, который создается. Примеры: x86 или arm64-v8a.

    • ${ndk.buildRoot} – это название папки, созданной AGP, в которую скрипт записывает выходные данные. Подробные сведения об этом приведены в разделе Шаг 2. Создайте скрипт настройки.

    • ${ndk.ndkVersion} – версия NDK, которую нужно использовать. Обычно это значение, переданное в android.ndkVersion в файле build.gradle, или значение по умолчанию, если оно не указано.

    • ${ndk.minPlatform} – минимальная целевая платформа Android, запрашиваемая AGP.

  • ninja.targets – список конкретных целей Ninja, которые нужно создать.

Шаг 2. Создайте скрипт настройки

Минимальная задача скрипта configure (configure-ninja.bat в примере выше) – создать файл build.ninja, который при сборке с помощью Ninja будет компилировать и связывать все нативные выходные данные проекта. Обычно это файлы .o (объект), .a (архив) и .so (общий объект).

Скрипт configure может записать файл build.ninja в два разных места в зависимости от ваших потребностей.

  • Если AGP может выбрать местоположение, скрипт настройки записывает build.ninja в местоположение, заданное в макросе ${ndk.buildRoot}.

  • Если скрипту configure нужно выбрать местоположение файла build.ninja, он также записывает файл с именем build.ninja.txt в местоположение, заданное в макросе ${ndk.buildRoot}. Этот файл содержит полный путь к файлу build.ninja, записанному скриптом configure.

Структура файла build.ninja

Как правило, большинство структур, которые точно представляют сборку Android C/C++, будут работать. Ключевые элементы, необходимые для AGP и Android Studio:

  • Список исходных файлов C/C++ и флаги, необходимые Clang для их компиляции.

  • Список выходных библиотек. Обычно это файлы .so (общий объект), но также могут быть файлы .a (архив) или исполняемые файлы (без расширения).

Если вам нужны примеры создания файла build.ninja, посмотрите выходные данные CMake при использовании генератора build.ninja.

Ниже приведен пример минимального шаблона build.ninja.

rule COMPILE
   command = /path/to/ndk/clang -c $in -o $out {other flags}
rule LINK
   command = /path/to/ndk/clang $in -o $out {other flags}

build source.o : COMPILE source.cpp
build lib.so : LINK source.o

Рекомендации

Помимо требований (список исходных файлов и выходных библиотек), есть несколько рекомендаций.

Объявление именованных выходных данных с помощью правил phony

По возможности рекомендуется, чтобы структура build.ninja использовала правила phony, чтобы дать выходным данным сборки человекочитаемые имена. Например, если у вас есть выходные данные с названием c:/path/to/lib.so, вы можете присвоить им человекочитаемое название, как показано ниже.

build curl: phony /path/to/lib.so

Преимущество такого подхода заключается в том, что вы можете указать это имя в качестве цели сборки в файле build.gradle. Например:

android {
  defaultConfig {
    externalNativeBuild {
      ...
      experimentalProperties["ninja.targets"] = [ "curl" ]

Укажите цель "все"

Если вы укажете цель all, AGP будет по умолчанию создавать этот набор библиотек, когда в файле build.gradle не заданы цели.

rule COMPILE
   command = /path/to/ndk/clang $in -o $out {other flags}
rule LINK
   command = /path/to/ndk/clang $in -o $out {other flags}

build foo.o : COMPILE foo.cpp
build bar.o : COMPILE bar.cpp
build libfoo.so : LINK foo.o
build libbar.so : LINK bar.o
build all: phony libfoo.so libbar.so

Укажите альтернативный метод сборки (необязательно)

Более сложный вариант использования – обернуть существующую систему сборки, не основанную на Ninja. В этом случае вам все равно нужно указать все источники с их флагами вместе с выходными библиотеками, чтобы Android Studio могла предоставлять правильные функции языкового сервиса, такие как автозаполнение и переход к определению. Однако вы хотите, чтобы AGP уступал базовой системе сборки во время фактической сборки.

Для этого можно использовать выходные данные сборки Ninja с определенным расширением .passthrough.

Рассмотрим более конкретный пример. Чтобы упаковать MSBuild, скрипт настройки сгенерирует build.ninja как обычно, но также добавит сквозную цель, которая определяет, как AGP будет вызывать MSBuild.

rule COMPILE
   command = /path/to/ndk/clang $in -o $out {other flags}
rule LINK
   command = /path/to/ndk/clang $in -o $out {other flags}

rule MBSUILD_CURL
  command = /path/to/msbuild {flags to build curl with MSBuild}

build source.o : COMPILE source.cpp
build lib.so : LINK source.o
build curl : phony lib.so
build curl.passthrough : MBSUILD_CURL

Оставить отзыв

Это экспериментальная функция, поэтому мы будем рады вашим отзывам. Вы можете оставить отзыв следующими способами:

  • Если вы хотите оставить общий отзыв, добавьте комментарий к соответствующей ошибке.

  • Чтобы сообщить об ошибке, откройте Android Studio и выберите Help (Справка) > Submit Feedback (Отправить отзыв). Чтобы помочь нам разобраться с ошибкой, укажите, что она связана с пользовательскими системами сборки C/C++.

  • Если у вас не установлена Android Studio, сообщите об ошибке, используя шаблон.