Модули Android Rust

В целом, определения модулей rust_* в точности соответствуют использованию и ожиданиям cc_* . Ниже приведён пример определения модуля для двоичного файла Rust :

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/hello_rust.rs"],
    host_supported: true,
}

На этой странице описаны наиболее распространённые свойства модулей rust_* . Подробнее о конкретных типах модулей и примерах их определений см. в разделах Двоичные модули , Библиотечные модули или Тестовые модули .

Основные типы модулей

Тип Определение Для получения дополнительной информации
rust_binary Двоичный файл Rust Страница бинарных модулей
rust_library Создает библиотеку Rust и предоставляет варианты rlib и dylib . rust_library , страница «Библиотечные модули».
rust_ffi Создает библиотеку Rust C, используемую модулями cc, и предоставляет как статические, так и общие варианты. rust_ffi , страница «Библиотечные модули»
rust_proc_macro Создаёт библиотеку proc-macro Rust . (Они аналогичны плагинам компилятора.) rust_proc_macro , страница «Библиотеки и модули»
rust_test Создает тестовый двоичный файл Rust , использующий стандартный тестовый набор Rust . Страница тестовых модулей
rust_fuzz Создает двоичный файл Rust fuzz, использующий libfuzzer . пример модуля rust_fuzz
rust_protobuf Генерирует исходный код и создает библиотеку Rust , которая предоставляет интерфейс для конкретного protobuf. Страницы модулей Protobufs и генераторов исходного кода
rust_bindgen Генерирует исходный код и создает библиотеку Rust , содержащую привязки Rust к библиотекам C. Страницы модулей привязок Bindgen и генераторов исходного кода

Важные общие свойства

Эти свойства являются общими для всех модулей Android Rust . Любые дополнительные (уникальные) свойства, связанные с отдельными модулями Rust , перечислены на странице соответствующего модуля.

имя

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

корень

stem (необязательно) обеспечивает прямой контроль над именем выходного файла (исключая расширение и другие суффиксы). Например, библиотека rust_library_rlib со значением stem, равным libfoo , создаёт файл libfoo.rlib . Если значение свойства stem не указано, имя выходного файла по умолчанию соответствует имени модуля.

Используйте функцию stem , если невозможно задать имя модуля в соответствии с желаемым именем выходного файла. Например, библиотека rust_library для контейнера log называется liblog_rust , поскольку библиотека liblog cc_library уже существует. Использование свойства stem в этом случае гарантирует, что выходной файл будет назван liblog.* вместо liblog_rust.* .

источники

srcs содержит один исходный файл, который представляет собой точку входа в ваш модуль (обычно main.rs или lib.rs ). rustc обрабатывает разрешение и обнаружение всех остальных исходных файлов, необходимых для компиляции, и они перечислены в создаваемом файле deps .

По возможности избегайте такого использования для платформенного кода; более подробную информацию см. в разделе Генераторы исходного кода .

имя_ящика

crate_name задаёт метаданные имени контейнера с помощью флага rustc --crate_name . Для модулей, создающих библиотеки, это имя должно совпадать с ожидаемым именем контейнера, используемым в исходном коде. Например, если модуль libfoo_bar упоминается в исходном коде как extern crate foo_bar , то это должно быть crate_name: "foo_bar".

Это свойство является общим для всех модулей rust_* , но оно обязательно для модулей, создающих библиотеки Rust (таких как rust_library , rust_ffi , rust_bindgen , rust_protobuf и rust_proc_macro ). Эти модули обеспечивают соблюдение требований rustc к соотношению между crate_name и именем выходного файла. Подробнее см. в разделе «Библиотечные модули» .

ворс

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

  • default набор линтов по умолчанию, в зависимости от расположения модуля
  • android самый строгий набор линтинга, применяемый ко всему коду платформы Android
  • vendor набор нестрогих проверок, применяемых к коду поставщика
  • none — игнорировать все предупреждения и ошибки lint

clippy_lints

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

  • набор проверок по умолчанию по default в зависимости от расположения модуля
  • android самый строгий набор линтинга, применяемый ко всему коду платформы Android
  • vendor набор нестрогих проверок, применяемых к коду поставщика
  • none — игнорировать все предупреждения и ошибки lint

версия

edition определяет редакцию Rust , используемую для компиляции этого кода. Она аналогична версиям std для C и C++. Допустимые значения: 2015 , 2018 и 2021 (по умолчанию).

флаги

flags содержит строковый список флагов для передачи в rustc во время компиляции.

ld_flags

ld-flags содержит строковый список флагов, передаваемых компоновщику при компиляции исходного кода. Они передаются с помощью флага -C linker-args rustc. В качестве интерфейса компоновщика используется clang , который вызывает lld для фактической компоновки.

функции

features — это строковый список функций, которые необходимо включить во время компиляции. Он передаётся в rustc с помощью --cfg 'feature="foo"' . Большинство функций являются аддитивными, поэтому во многих случаях это полный набор функций, требуемый всеми зависимыми модулями. Однако, если функции являются взаимоисключающими, определите дополнительные модули в любых файлах сборки, которые предоставляют конфликтующие функции.

конфигурации

cfgs содержит строковый список флагов cfg , которые необходимо включить во время компиляции. Он передаётся в rustc с помощью --cfg foo и --cfg "fizz=buzz" .

Система сборки автоматически устанавливает определенные флаги cfg в определенных ситуациях, перечисленных ниже:

  • Модули, созданные как dylib, будут иметь набор конфигурационных файлов android_dylib .

  • Модули, использующие VNDK, будут иметь конфигурацию android_vndk . Это похоже на определение __ANDROID_VNDK__ для C++.

полоска

strip управляет тем, будет ли и как будет очищаться выходной файл (если применимо). Если этот параметр не установлен, модули устройств по умолчанию очищают всё, кроме мини-отладочной информации. Модули хоста по умолчанию не очищают никакие символы. Допустимые значения: none (отключить очистку) и all (удалить всё, включая мини-отладочную информацию). Дополнительные значения можно найти в справочнике модулей Soong .

host_supported

Для модулей устройств параметр host_supported указывает, должен ли модуль также предоставлять вариант хоста.

Определить зависимости библиотеки

Модули Rust могут зависеть как от библиотек CC, так и от библиотек Rust посредством следующих свойств:

Имя объекта Описание
rustlibs Список модулей rust_library , которые также являются зависимостями. Используйте этот метод объявления зависимостей, поскольку он позволяет системе сборки выбирать предпочтительную компоновку. (См. раздел «Компоновка с библиотеками Rust» ниже.)
rlibs Список модулей rust_library , которые должны быть статически скомпонованы как rlibs . (Используйте с осторожностью; см. раздел «Компоновка с библиотеками Rust» ниже.)
shared_libs Список модулей cc_library , которые должны быть динамически подключены как общие библиотеки.
static_libs Список модулей cc_library , которые должны быть статически скомпонованы как статические библиотеки.
whole_static_libs Список модулей cc_library , которые следует статически скомпоновать как статические библиотеки и включить целиком в результирующую библиотеку. Для вариантов rust_ffi_static библиотеки whole_static_libraries будут включены в результирующий архив статической библиотеки. Для вариантов rust_library_rlib библиотеки whole_static_libraries будут включены в результирующую библиотеку rlib .

При компоновке с библиотеками Rust рекомендуется использовать свойство rustlibs , а не rlibs или dylibs если только у вас нет на это особых причин. Это позволяет системе сборки выбрать правильную компоновку в зависимости от требований корневого модуля и снижает вероятность того, что дерево зависимостей будет содержать как rlib , так и dylib версии библиотеки (что приведёт к сбою компиляции).

Неподдерживаемые и ограниченно поддерживаемые функции сборки

Rust Сунга предлагает ограниченную поддержку образов и снимков vendor и vendor_ramdisk . Однако поддерживаются staticlibs , cdylibs , rlibs и binaries . Для целей сборки образов Vendor установлено свойство android_vndk cfg . Вы можете использовать его в коде, если между системными и целевыми образами Vendor есть различия. rust_proc_macros не сохраняются как часть снимков Vendor; если они используются, убедитесь, что вы используете надлежащий контроль версий.

Образы продукта, VNDK и восстановления не поддерживаются.

Инкрементные сборки

Разработчики могут включить инкрементную компиляцию исходного кода Rust , установив переменную среды SOONG_RUSTC_INCREMENTAL в true .

Внимание : не гарантируется создание двоичных файлов, идентичных тем, что генерируются сборщиками. Адреса функций или данных в объектных файлах могут отличаться. Чтобы гарантировать 100% идентичность сгенерированных артефактов тем, что собраны инфраструктурой EngProd, оставьте это значение неустановленным.