Модули 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 crate называется liblog_rust , поскольку liblog cc_library уже существует. Использование свойства stem в этом случае гарантирует, что выходной файл будет назван liblog.* вместо liblog_rust.* .

srcs

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 linter запускается по умолчанию для всех типов модулей, кроме генераторов исходного кода. Некоторые наборы lint определены и используются для проверки исходного кода модуля. Возможные значения для таких наборов lint следующие:

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

clippy_lints

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

  • 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 используется как front-end компоновщика, вызывая lld для фактического связывания.

функции

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

cfgs

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

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

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

  • Модули, которые будут использовать VNDK, будут иметь набор android_vndk cfg. Это похоже на определение __ANDROID_VNDK__ для C++.

полоска

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

хост_поддерживается

Для модулей устройств параметр 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 .

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