Módulos de biblioteca

Há dois tipos de módulos de biblioteca do Rust: um que produz bibliotecas do Rust e outro que produz bibliotecas compatíveis com C. Além disso, para fins do sistema de compilação, considere as macros procedurais do Rust (proc-macros) como um tipo especial de biblioteca.

rust_library

O módulo rust_library produz bibliotecas Rust para serem usadas por outros módulos Rust.

Além das variantes _host, as bibliotecas Rust têm tipos de módulos que controlam a vinculação disponível.

Tipo de módulo da biblioteca Rust Definição
rust_library Fornece as variantes de biblioteca rlib e dylib. O AOSP recomenda esse tipo de módulo para bibliotecas Rust, porque ele possibilita que os módulos funcionem corretamente quando listados como uma dependência na propriedade rustlibs
rust_library_rlib Fornece apenas a variante rlib de uma biblioteca Rust. Os módulos que fornecem apenas variantes rlib não têm garantia de funcionar com a propriedade rustlibs.
rust_library_dylib Fornece apenas a variante dylib de uma biblioteca Rust. Os módulos que fornecem apenas variantes dylib não têm garantia de funcionar com a propriedade rustlibs.

rust_ffi

O módulo rust_ffi produz bibliotecas compatíveis com o código C para possibilitar a interoperabilidade com módulos CC.

Além das variantes _host, as bibliotecas Rust de FFI têm tipos de módulos que controlam a vinculação disponível, como mostrado na tabela a seguir.

Tipo de módulo da biblioteca Rust de FFI Definição
rust_ffi Fornece variantes da biblioteca C: estática e compartilhada.
rust_ffi_shared Fornece apenas a variante da biblioteca C compartilhada.
rust_ffi_static Fornece apenas a variante da biblioteca C estática.

Para ver um exemplo básico do uso de rust_ffi para chamar o Rust no código C, consulte a página Padrões do Rust no Android.

Para informações sobre uso mais avançado, acesse a documentação oficial do Rust (em inglês).

rust_proc_macro

As macros procedurais do Rust (proc-macros) podem ser úteis para ampliar o compilador a fim de realizar transformações no código-fonte ou fornecer novos atributos. Veja mais informações na página Macros procedurais (link em inglês) da documentação oficial do Rust.

Para fins do sistema de compilação, o módulo rust_proc_macro funciona de maneira parecida com os módulos rust_library. Para módulos que dependem de rust_proc_macros, adicione o nome do módulo à propriedade proc_macros.

Como as proc_macros são plug-ins do compilador, elas necessariamente são direcionados ao host e não produzem nenhum código que seja executado em um dispositivo.

Propriedades importantes das bibliotecas Rust

As propriedades definidas na tabela abaixo funcionam em conjunto com as Propriedades comuns importantes que se aplicam a todos os módulos. Elas são particularmente importantes para módulos de biblioteca Rust ou exibem comportamentos únicos específicos ao tipo de módulo rust_library.

Propriedades das bibliotecas Rust Definição
stem / name A propriedade stem controla o nome de arquivo da biblioteca de saída. Do contrário, o padrão é name.

O compilador Rust impõe determinados requisitos em nomes de arquivos de biblioteca e, como resultado, o sistema de compilação impõe esses requisitos para evitar problemas de compilação. O nome do arquivo de saída precisa estar em conformidade com o formato lib<crate_name><suffix>. Aqui, há uma dependência na propriedade crate_name.

crate_name Essa é uma propriedade obrigatória para módulos de produção de bibliotecas, além de ter um relacionamento com o nome do arquivo de saída. Consulte a definição de stem.
export_include_dirs Para módulos rust_ffi, essa propriedade define uma lista de strings que representam caminhos de inclusão relativos: caminhos que contêm cabeçalhos que os módulos cc dependentes podem usar.

Vinculação da rust_library ou rust_ffi

Por padrão, os módulos da biblioteca Rust destinados a dispositivos são sempre vinculados dinamicamente a libstd. No entanto, os módulos de host são sempre vinculados estaticamente à libstd.

A vinculação usada para dependências de rustlibs depende das preferências dos módulos raiz. Por exemplo, um rust_binary com prefer_rlib: true vai usar variantes da biblioteca Rust que vinculam rustlibs como rlibs.

Para autorizar a produção de módulos de dependência raiz que não dependem de nenhuma biblioteca Rust dinâmica (como executáveis estáticos), rlibs fornece variantes de vinculação libstd dinâmicas e estáticas. A variante correta é vinculada automaticamente pelo Soong.