Módulos de óxido de Android

Como principio general, las definiciones del módulo rust_* se adhieren estrechamente al uso y las expectativas de 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 las páginas Módulos binarios, Módulos de biblioteca o Módulos de prueba .

Tipos de módulos básicos

Propiedades comunes importantes

Estas propiedades son comunes en todos los módulos Rust de Android. Cualquier propiedad adicional (única) asociada con módulos individuales de Rust se enumeran 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, debe ser único en la mayoría de los tipos de módulos de Android.bp . De forma predeterminada, name se utiliza como nombre de archivo de salida. Si el nombre del archivo de salida debe ser diferente del nombre del módulo, use la propiedad stem para definirlo.

madre

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 genera 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 establecer el nombre del módulo en el nombre de archivo de salida deseado. Por ejemplo, la rust_library para la caja de 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 la 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 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 la 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 los requisitos de rustc en 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 rustc linter se ejecuta de forma predeterminada para todos los tipos de módulos, excepto los generadores de fuentes. Algunos conjuntos de lint se definen y utilizan para validar la fuente del módulo. Los valores posibles para dichos conjuntos de pelusa son los siguientes:

• default (El conjunto predeterminado de pelusas, dependiendo de la ubicación del módulo)
• android (para el conjunto de pelusa más estricto que se aplica a todo el código de la plataforma Android)
• vendor (para un conjunto relajado de pelusas aplicadas al código del proveedor)
• none (para 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 la fuente del módulo. Estos son algunos valores posibles:

• default (El conjunto predeterminado de pelusas según la ubicación del módulo)
• android (para el conjunto de pelusa más estricto que se aplica a todo el código de la plataforma Android)
• vendor (para un conjunto relajado de pelusas aplicadas al código del proveedor)
• none (para ignorar todas las advertencias y errores de pelusa)

edición

edition define la edición de Rust que se usará 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 banderas para pasar a rustc durante la compilación.

ld_flags

ld-flags contiene una lista de cadenas de banderas para pasar al enlazador al compilar la fuente. Estos son pasados ​​por 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 se excluyen entre sí, defina módulos adicionales en cualquier archivo de compilación que proporcione funciones en conflicto.

cfgs

cfgs contiene una lista de cadenas de indicadores de 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 de cfg en situaciones particulares, que se enumeran a continuación:

• Los módulos creados como dylib tendrán el conjunto android_dylib cfg.
• Los módulos que usarían el android_vndk tendrán el conjunto de cfg de android_vndk. Esto es similar a la definición de __ANDROID_VNDK__ para C++.

banda

strip controla si se elimina el archivo de salida y cómo se elimina (si corresponde). Si esto no está configurado, los módulos del dispositivo eliminan por defecto todo excepto la mini información de depuración. Los módulos host, por defecto, 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_supported

Para módulos de dispositivos, el parámetro host_supported indica si el módulo también debe proporcionar una variante de host.

Definición de dependencias de biblioteca

Los módulos de Rust pueden depender de las bibliotecas CC y Rust a través de las siguientes propiedades:

Cuando se vincule con las bibliotecas de Rust , como práctica recomendada, hágalo usando 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 en función de 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 hará que la compilación falle).

Funciones de compilación de soporte limitado y sin soporte

Soong's Rust ofrece soporte limitado para imágenes e vendor_ramdisk del vendor y del proveedor_ramdisk. Sin embargo, staticlibs , cdylibs , rlibs y binaries . Para objetivos de creación de imágenes de proveedores, se establece la propiedad android_vndk cfg . Puede usar esto en el código si hay diferencias entre el sistema y los objetivos del proveedor. rust_proc_macros no se capturan como parte de las instantáneas del proveedor; si se depende de ellos, asegúrese de controlarlos adecuadamente.

Las imágenes de producto, VNDK y recuperación no son compatibles.

Construcciones incrementales

Los desarrolladores pueden habilitar la compilación incremental de la fuente de Rust configurando la variable de entorno SOONG_RUSTC_INCREMENTAL en true .

Advertencia : no se garantiza que esto produzca binarios idénticos a los generados por los buildbots. Las direcciones de funciones o datos contenidos en los archivos objeto pueden ser diferentes. Para asegurarse de que los artefactos generados sean 100 % idénticos a los creados por la infraestructura de EngProd, deje este valor sin configurar.