Модули 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 , используя libfuzzer . пример модуля rust_fuzz
rust_protobuf Генерирует исходный код и создает библиотеку Rust , которая предоставляет интерфейс для конкретного протокола protobuf. Страницы модулей и генераторов исходного кода Protobufs
rust_bindgen Генерирует исходный код и создает библиотеку Rust , содержащую привязки Rust к библиотекам C. Страницы модулей привязок и генераторов исходного кода Bindgen

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

Эти свойства являются общими для всех модулей Rust для Android. Любые дополнительные (уникальные) свойства, связанные с отдельными модулями 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 будет игнорировать все предупреждения и ошибки линтера.

clippy_lints

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

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

версия

edition определяет версию Rust , используемую для компиляции этого кода. Это аналогично стандартным версиям для 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 cfg.

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

полоска

strip определяет, следует ли и каким образом удалять символы из выходного файла (если применимо). Если этот параметр не задан, модули устройств по умолчанию удаляют все символы, кроме mini debuginfo. Модули хоста по умолчанию не удаляют никаких символов. Допустимые значения включают none для отключения удаления символов и all для удаления всего, включая mini debuginfo. Дополнительные значения можно найти в справочнике модулей 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 от Soong предлагает ограниченную поддержку образов vendor и vendor_ramdisk , а также снимков. Однако поддерживаются staticlibs , cdylibs , rlibs и binaries . Для целевых объектов сборки образов vendor устанавливается свойство cfg android_vndk . Вы можете использовать его в коде, если есть различия между системными и целевыми объектами vendor. rust_proc_macros не включаются в снимки vendor; если они являются зависимостью, убедитесь, что вы соответствующим образом контролируете их версии.

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

Поэтапная сборка

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

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