Existen dos tipos de módulos de biblioteca de Rust: uno que produce bibliotecas de Rust y otro que genera bibliotecas compatibles con C. Además, para los fines del sistema de compilación, puedes considerar las macros de procedimiento de Rust (proc-macros) como un tipo especial de biblioteca.
rust_library
El módulo rust_library produce bibliotecas de Rust para que las usen otros módulos de Rust.
Además de las variantes _host, las bibliotecas de Rust cuentan con tipos de módulos que controlan la vinculación disponible.
| Tipo de módulo de la biblioteca de Rust | Definición |
|---|---|
| rust_library | Brinda ambas variantes de biblioteca: rlib y dylib. AOSP recomienda este tipo de módulo para las bibliotecas de Rust, ya que permite que los módulos funcionen, de manera correcta, cuando se muestran como una dependencia en la propiedad rustlibs. |
| rust_library_rlib | Brinda solo la variante rlib de una biblioteca de Rust; no se puede garantizar que los módulos que proporcionan solo variantes rlib funcionen con la propiedad rustlibs. |
| rust_library_dylib | Brinda solo la variante dylib de una biblioteca de Rust; no se puede garantizar que los módulos que proporcionan solo variantes dylib funcionen con la propiedad rustlibs. |
rust_ffi
El módulo rust_ffi produce bibliotecas compatibles con C para ofrecer interoperabilidad con módulos de CC.
Además de las variantes _host, las bibliotecas de FFI de Rust cuentan con tipos de módulos que controlan la vinculación disponible, como se muestra en la siguiente tabla.
| Tipo de módulo de la biblioteca de FFI de Rust | Definición |
|---|---|
| rust_ffi | Brinda ambas variantes de biblioteca de C: estáticas y compartidas. |
| rust_ffi_shared | Brinda solo la variante de biblioteca de C compartida. |
| rust_ffi_static | Brinda solo la variante de biblioteca de C estática. |
Si deseas ver un ejemplo básico de cómo usar rust_ffi para llamar a Rust desde C, consulta la página Patrones de Rust en Android.
Para obtener información sobre un uso más avanzado, consulta la documentación oficial de Rust.
rust_proc_macro
Las macros de procedimiento de Rust (proc-macros) pueden ser útiles para extender el compilador y así realizar transformaciones del código fuente o brindar atributos nuevos. Puedes obtener más información en la página sobre macros de procedimiento de la documentación oficial de Rust.
Para los fines del sistema de compilación, el módulo rust_proc_macro funciona de manera similar a los módulos rust_library. Para los módulos que dependen de rust_proc_macros, agrega el nombre del módulo a la propiedad proc_macros.
Como las macros proc_macros son complementos de compilador, se orientan, inevitablemente, al host y no producen ningún código que pueda ejecutarse en un dispositivo.
Propiedades notables de la biblioteca de Rust
Las propiedades que se definen en la siguiente tabla se suman a las propiedades comunes importantes que se aplican a todos los módulos. Estas son particularmente importantes para los módulos de la biblioteca de Rust o presentan un comportamiento único específico para el tipo de módulo rust_library.
| Propiedades de la biblioteca de Rust | Definición |
|---|---|
| stem / name | La propiedad stem controla el nombre de archivo de la biblioteca de salida, que, de lo contrario, se establecería como name de forma predeterminada.
El compilador de Rust exige ciertos requisitos para los nombres de archivo de la biblioteca y, como resultado, el sistema de compilación aplica, de manera forzosa, esos requisitos para evitar problemas de compilación.
El nombre de archivo de salida debe cumplir con el formato |
| crate_name | Es una propiedad obligatoria para los módulos que producen bibliotecas; además, tiene una relación con el nombre de archivo de salida (consulta la definición de stem). |
| export_include_dirs | Para los módulos rust_ffi, esta propiedad define una lista de cadenas que representan rutas de inclusión relativas: aquellas que incluyen encabezados que pueden usar los módulos cc dependientes. |
Vinculación de rust_library o rust_ffi
Según la configuración predeterminada, los módulos de la biblioteca de Rust que se orientan a dispositivos siempre están vinculados a libstd de forma dinámica. Sin embargo, los módulos de host siempre están vinculados a libstd de forma estática.
La vinculación que se usa para las dependencias de rustlibs depende de las preferencias de vinculación del módulo raíz. Por ejemplo, rust_binary con prefer_rlib: true usará variantes de biblioteca de Rust que vinculen rustlibs como rlibs.
Para permitir que se produzcan módulos raíz de dependencia que no necesiten de ninguna biblioteca dinámica de Rust (por ejemplo, los archivos ejecutables estáticos), rlibs brinda variantes de vinculación libstd dinámicas y estáticas. Soong vincula automáticamente la variante correcta.