Модули 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 Создает библиотеку Rust proc-macro . (Это аналог плагинов компилятора.) 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 и генераторов исходного кода

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

These properties are common across all Android Rust Modules. Любые дополнительные (уникальные) свойства, связанные с отдельными модулями Rust, перечислены на странице этого модуля.

имя

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

корень

stem (необязательно) обеспечивает прямой контроль над именем выходного файла (за исключением расширения файла и других суффиксов). Например, rust_library_rlib со значением основы 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 . Для модулей, создающих библиотеки, оно должно соответствовать ожидаемому имени крейта, используемому в исходном коде. For example, if the module libfoo_bar is referenced in source as extern crate foo_bar , then this must be crate_name: "foo_bar".

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

ворсы

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

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

клиппи_линтс

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

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

версия

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

флаги

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

ld_flags

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

функции

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

cfgs

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

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

  • Модули, созданные как dylib, будут иметь набор cfg 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 (что приведет к сбою компиляции).

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

Soong's Rust предлагает ограниченную поддержку образов и снимков vendor и vendor_ramdisk . Однако поддерживаются staticlibs , cdylibs , rlibs и binaries . Для целей сборки образа поставщика устанавливается свойство android_vndk cfg . Вы можете использовать это в коде, если существуют различия между целями системы и поставщика. rust_proc_macros aren't captured as part of vendor snapshots; если от них зависят, убедитесь, что вы правильно контролируете их версии.

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

Дополнительные сборки

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

Warning : This isn't guaranteed to produce binaries that are identical to those generated by buildbots. Адреса функций или данных, содержащихся в объектных файлах, могут быть разными. Чтобы гарантировать, что создаваемые артефакты на 100% идентичны артефактам, созданным инфраструктурой EngProd, оставьте это значение неустановленным.