Как правило, определения модулей 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 Modules и Source Generators |
rust_bindgen | Создает исходный код и создает библиотеку Rust, содержащую привязки Rust к библиотекам C. | Страницы Bindgen Bindings Modules и Source Generators |
Важные общие свойства
Эти свойства являются общими для всех модулей Android Rust. Любые дополнительные (уникальные) свойства, связанные с отдельными модулями 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
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 запускается по умолчанию для всех типов модулей, кроме генераторов исходников. Некоторые наборы lint определены и используются для проверки исходного кода модуля. Возможные значения для таких наборов ворса следующие:
-
default(набор линтов по умолчанию, в зависимости от расположения модуля) -
android(самый строгий набор lint, применимый ко всему коду платформы Android) -
vendor(для упрощенного набора анализов, применяемых к коду поставщика) -
none(для игнорирования всех предупреждений и ошибок lint)
clippy_lints
Clippy linter также запускается по умолчанию для всех типов модулей, кроме генераторов исходного кода. Определено несколько наборов анализов, которые используются для проверки исходного кода модуля. Вот некоторые возможные значения:
-
default(набор линтов по умолчанию в зависимости от расположения модуля) -
android(самый строгий набор lint, применимый ко всему коду платформы Android) -
vendor(для упрощенного набора анализов, применяемых к коду поставщика) -
none(для игнорирования всех предупреждений и ошибок lint)
версия
edition определяет версию Rust, используемую для компиляции этого кода. Это похоже на стандартные версии для C и C++. Допустимые значения: 2015 и 2018 (по умолчанию).
флаги
flags содержит строковый список флагов для передачи в rustc во время компиляции.
ld_flags
ld-flags содержит строковый список флагов для передачи компоновщику при компиляции исходного кода. Они передаются флагом -C linker-args rustc. clang используется в качестве внешнего интерфейса компоновщика, вызывая lld для фактического связывания.
Особенности
features — это строковый список функций, которые должны быть включены во время компиляции. Это передается в rustc с помощью --cfg 'feature="foo"' . Большинство функций являются аддитивными, поэтому во многих случаях они состоят из полного набора функций, требуемых всеми зависимыми модулями. Однако в случаях, когда функции исключают друг друга, определите дополнительные модули в любых файлах сборки, которые предоставляют конфликтующие функции.
cfgs
cfgs содержит строковый список флагов cfg , которые должны быть включены во время компиляции. Это передается в rustc с помощью --cfg foo и --cfg "fizz=buzz" .
Система сборки автоматически устанавливает определенные флаги cfg в определенных ситуациях, перечисленных ниже:
- Модули, созданные как dylib, будут иметь набор cfg
android_dylib. - Модули, которые будут использовать VNDK, будут иметь установленный cfg
android_vndk. Это похоже на определение__ANDROID_VNDK__для C++.
полоска
strip управляет тем, будет ли и как раздеваться выходной файл (если применимо). Если это не установлено, модули устройств по умолчанию удаляют все, кроме mini debuginfo. Хост-модули по умолчанию не удаляют никаких символов. Допустимые значения включают none , чтобы отключить удаление, и all , чтобы удалить все, включая мини-отладочную информацию. Дополнительные значения можно найти в справочнике модулей Soong .
host_supported
Для модулей устройств параметр host_supported указывает, должен ли модуль также предоставлять вариант хоста.
Определение зависимостей библиотеки
Модули Rust могут зависеть как от CC, так и от библиотек Rust через следующие свойства:
| Имя свойства | Описание |
|---|---|
rustlibs | Список модулей rust_library , которые также являются зависимостями. Используйте это как предпочтительный метод объявления зависимостей, поскольку он позволяет системе сборки выбирать предпочтительную связь. (См. раздел При компоновке библиотек Rust ниже) |
rlibs | Список модулей rust_library , которые должны быть статически связаны как rlibs . (Используйте с осторожностью; см. При компоновке с библиотеками Rust ниже.) |
dylibs | Список модулей rust_library для динамической компоновки как dylibs . (Используйте с осторожностью; см. При компоновке с библиотеками 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 . Однако поддерживаются cdylibs staticlibs rlibs и binaries . Для целей сборки образа поставщика установлено свойство android_vndk cfg . Вы можете использовать это в коде, если есть различия между целями системы и поставщика. rust_proc_macros не фиксируются как часть снапшотов поставщиков; если они зависят от них, убедитесь, что вы правильно управляете их версиями.
Образы продуктов, VNDK и Recovery не поддерживаются.
Инкрементальные сборки
Разработчики могут включить инкрементную компиляцию исходного кода Rust, установив для переменной среды SOONG_RUSTC_INCREMENTAL значение true .
Предупреждение . Это не гарантирует создание двоичных файлов, идентичных тем, которые создаются строительными ботами. Адреса функций или данных, содержащихся в объектных файлах, могут быть разными. Чтобы убедиться, что сгенерированные артефакты на 100 % идентичны тем, которые созданы инфраструктурой EngProd, оставьте это значение неустановленным.