Como principio general, las definiciones del módulo rust_* se adhieren estrechamente al uso y las expectativas cc_* . El siguiente es un ejemplo de una definición de módulo para un binario de Rust :
rust_binary {
name: "hello_rust",
crate_name: "hello_rust",
srcs: ["src/hello_rust.rs"],
host_supported: true,
}
Esta página cubre las propiedades más comunes para los módulos rust_* . Para obtener más información sobre tipos de módulos específicos y definiciones de módulos de ejemplo, consulte Módulos binarios , Módulos de biblioteca o Módulos de prueba .
Tipos de módulos básicos
| Tipo | Definición | Para más información |
|---|---|---|
rust_binary | Un binario de Rust | Página de módulos binarios |
rust_library | Produce una biblioteca Rust y proporciona variantes rlib y dylib . | rust_library , página de módulos de biblioteca. |
rust_ffi | Produce una biblioteca Rust C utilizable por módulos cc y proporciona variantes estáticas y compartidas. | rust_ffi , página de módulos de biblioteca |
rust_proc_macro | Produce una biblioteca proc-macro Rust . (Estos son análogos a los complementos del compilador). | rust_proc_macro , página Módulos de bibliotecas |
rust_test | Produce un binario de prueba de Rust que utiliza el arnés de prueba estándar de Rust . | Página de módulos de prueba |
rust_fuzz | Produce un binario Rust fuzz aprovechando libfuzzer . | Ejemplo de módulo rust_fuzz |
rust_protobuf | Genera código fuente y produce una biblioteca Rust que proporciona una interfaz para un protobuf en particular. | Páginas de módulos de Protobufs y generadores de código fuente |
rust_bindgen | Genera código fuente y produce una biblioteca Rust que contiene enlaces de Rust a bibliotecas C. | Páginas de generadores de código fuente y módulos de enlaces de Bindgen |
Propiedades comunes importantes
Estas propiedades son comunes en todos los módulos de Android Rust . Cualquier propiedad adicional (única) asociada con módulos Rust individuales se enumera en la página de ese módulo.
nombre
name es el nombre de su módulo. Al igual que otros módulos de Soong, este debe ser único en la mayoría de los tipos de módulos Android.bp . De forma predeterminada, name se utiliza como nombre del archivo de salida. Si el nombre del archivo de salida debe ser diferente del nombre del módulo, use la propiedad stem para definirlo.
provenir
stem (opcional) proporciona control directo sobre el nombre del archivo de salida (excluyendo la extensión del archivo y otros sufijos). Por ejemplo, una biblioteca rust_library_rlib con un valor de raíz de libfoo produce un archivo libfoo.rlib . Si no proporciona un valor para la propiedad stem , el nombre del archivo de salida adopta el nombre del módulo de forma predeterminada.
Utilice la función stem cuando no pueda configurar el nombre del módulo con el nombre de archivo de salida deseado. Por ejemplo, la rust_library para la caja log se denomina liblog_rust , porque ya existe una liblog cc_library . El uso de la propiedad stem en este caso garantiza que el archivo de salida se llame liblog.* en lugar de liblog_rust.* .
srcs
srcs contiene un único archivo fuente que representa el punto de entrada a su módulo (generalmente main.rs o lib.rs ). rustc maneja la resolución y el descubrimiento de todos los demás archivos fuente necesarios para la compilación, y estos se enumeran en el archivo deps que se produce.
Cuando sea posible, evite este uso para el código de plataforma; consulte Generadores de fuentes para obtener más información.
nombre_caja
crate_name establece los metadatos del nombre de la caja a través del indicador rustc --crate_name . Para los módulos que producen bibliotecas, esto debe coincidir con el nombre de caja esperado utilizado en la fuente. Por ejemplo, si se hace referencia al módulo libfoo_bar en el código fuente como extern crate foo_bar , entonces debe ser crate_name: "foo_bar".
Esta propiedad es común a todos los módulos rust_* , pero es necesaria para los módulos que producen bibliotecas Rust (como rust_library rust_ffi , rust_bindgen , rust_protobuf y rust_proc_macro ). Estos módulos imponen requisitos rustc sobre la relación entre crate_name y el nombre del archivo de salida. Para obtener más información, consulte la sección Módulos de biblioteca .
pelusas
El linter rustc se ejecuta de forma predeterminada para todos los tipos de módulos excepto los generadores de código fuente. Algunos conjuntos de pelusas se definen y utilizan para validar el origen del módulo. Los valores posibles para dichos conjuntos de pelusa son los siguientes:
-
defaultel conjunto predeterminado de pelusas, dependiendo de la ubicación del módulo -
androidel conjunto de pelusas más estricto que se aplica a todo el código de la plataforma Android -
vendorun conjunto relajado de pelusas aplicadas al código del proveedor -
nonepara ignorar todas las advertencias y errores de pelusa
clippy_lints
El clippy linter también se ejecuta de forma predeterminada para todos los tipos de módulos excepto los generadores de fuentes. Se definen algunos conjuntos de pelusas que se utilizan para validar el origen del módulo. Estos son algunos valores posibles:
- conjunto
defaultde pelusas según la ubicación del módulo -
androidel conjunto de pelusas más estricto que se aplica a todo el código de la plataforma Android -
vendorun conjunto relajado de pelusas aplicadas al código del proveedor -
nonepara ignorar todas las advertencias y errores de pelusa
edición
edition define la edición de Rust que se utilizará para compilar este código. Esto es similar a las versiones estándar para C y C++. Los valores válidos son 2015 y 2018 (predeterminado).
banderas
flags contiene una lista de cadenas de indicadores para pasar a rustc durante la compilación.
ld_flags
ld-flags contiene una lista de cadenas de indicadores para pasar al vinculador al compilar el código fuente. Estos se pasan mediante el indicador -C linker-args rustc. clang se utiliza como interfaz del enlazador, invocando lld para el enlace real.
características
features es una lista de cadenas de características que deben habilitarse durante la compilación. Esto se pasa a Rustc mediante --cfg 'feature="foo"' . La mayoría de las funciones son aditivas, por lo que en muchos casos consisten en el conjunto completo de funciones requeridas por todos los módulos dependientes. Sin embargo, en los casos en que las funciones sean exclusivas entre sí, defina módulos adicionales en cualquier archivo de compilación que proporcione funciones en conflicto.
cfg
cfgs contiene una lista de cadenas de indicadores cfg que se habilitarán durante la compilación. Esto se pasa a rustc mediante --cfg foo y --cfg "fizz=buzz" .
El sistema de compilación establece automáticamente ciertos indicadores cfg en situaciones particulares, que se enumeran a continuación:
Los módulos creados como dylib tendrán el cfg
android_dylibconfigurado.Los módulos que usarían VNDK tendrán configurado el cfg
android_vndk. Esto es similar a la definición__ANDROID_VNDK__para C++.
banda
strip controla si se elimina el archivo de salida y cómo (si corresponde). Si esto no está configurado, los módulos del dispositivo eliminan de forma predeterminada todo excepto la mini información de depuración. Los módulos host, de forma predeterminada, no eliminan ningún símbolo. Los valores válidos incluyen none para deshabilitar la eliminación y all para eliminar todo, incluida la mini información de depuración. Se pueden encontrar valores adicionales en la Referencia de módulos de Soong .
host_compatible
Para los módulos de dispositivos, el parámetro host_supported indica si el módulo también debe proporcionar una variante de host.
Definir dependencias de biblioteca
Los módulos de Rust pueden depender de las bibliotecas CC y Rust a través de las siguientes propiedades:
| Nombre de la propiedad | Descripción |
|---|---|
rustlibs | Lista de módulos rust_library que también son dependencias. Utilice esto como su método preferido para declarar dependencias, ya que permite que el sistema de compilación seleccione el enlace preferido. (Consulte Cuando se vincula con bibliotecas de Rust , a continuación) |
rlibs | Lista de módulos rust_library que deben estar vinculados estáticamente como rlibs . (Úselo con precaución; consulte Al vincular con bibliotecas de Rust , a continuación). |
shared_libs | Lista de módulos cc_library que deben vincularse dinámicamente como bibliotecas compartidas. |
static_libs | Lista de módulos cc_library que deben vincularse estáticamente como bibliotecas estáticas. |
whole_static_libs | Lista de módulos cc_library que deben vincularse estáticamente como bibliotecas estáticas e incluirse completos en la biblioteca resultante. Para las variantes rust_ffi_static , whole_static_libraries se incluirán en el archivo de biblioteca estática resultante. Para las variantes rust_library_rlib , las bibliotecas whole_static_libraries se incluirán en la biblioteca rlib resultante. |
Al vincular bibliotecas de Rust , como práctica recomendada, hágalo utilizando la propiedad rustlibs en lugar de rlibs o dylibs , a menos que tenga una razón específica para hacerlo. Esto permite que el sistema de compilación seleccione el enlace correcto según lo que requiere el módulo raíz y reduce la posibilidad de que un árbol de dependencias contenga las versiones rlib y dylib de una biblioteca (lo que provocará que falle la compilación).
Funciones de compilación de soporte limitado y no admitido
Rust de Soong ofrece soporte limitado para imágenes e instantáneas vendor y vendor_ramdisk . Sin embargo, se admiten staticlibs , cdylibs , rlibs y binaries . Para los objetivos de creación de imágenes del proveedor, se establece la propiedad android_vndk cfg . Puede utilizar esto en el código si existen diferencias entre el sistema y los objetivos del proveedor. rust_proc_macros no se capturan como parte de las instantáneas del proveedor; Si depende de ellos, asegúrese de controlar sus versiones adecuadamente.
No se admiten imágenes de producto, VNDK ni de recuperación.
Construcciones incrementales
Los desarrolladores pueden habilitar la compilación incremental del código fuente de Rust configurando la variable de entorno SOONG_RUSTC_INCREMENTAL en true .
Advertencia : No se garantiza que esto produzca archivos binarios idénticos a los generados por los buildbots. Las direcciones de funciones o datos contenidos en los archivos objeto pueden ser diferentes. Para garantizar que los artefactos generados sean 100 % idénticos a los creados por la infraestructura de EngProd, deje este valor sin establecer.