Módulos do Rust para Android

Como princípio geral, as definições do módulo rust_* estão de acordo com o uso e as expectativas do cc_*. Veja a seguir um exemplo de definição de módulo para um binário Rust:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/hello_rust.rs"],
    host_supported: true,
}

Nesta página, as propriedades mais comuns para os módulos rust_* são explicadas. Para mais informações sobre tipos de módulos específicos e exemplos de definições de módulo, consulte as páginas Módulos binários, Módulos de biblioteca ou Módulos de teste.

Tipos básicos de módulo

TipoDefiniçãoMais informações
rust_binaryUm binário Rust. Página de Módulos binários.
rust_libraryProduz uma biblioteca Rust e fornece as variantes rlib e dylib. rust_library, página de Módulos de biblioteca.
rust_ffiProduz uma biblioteca Rust C utilizável por módulos cc e fornece variantes estáticas e compartilhadas. rust_ffi, página de Módulos de biblioteca.
rust_proc_macroProduz uma biblioteca Rust proc-macro, análoga a plug-ins do compilador. rust_proc_macro, página de Módulos de bibliotecas.
rust_testProduz um binário Rust de teste que usa o arcabouço de teste padrão do Rust. Página de Módulos de teste.
rust_fuzzProduz um binário Rust fuzz usando libfuzzer. Exemplo do módulo rust_fuzz.
rust_protobufGera a origem e produz uma biblioteca Rust que fornece uma interface para um protobuf específico. Páginas de Módulos de protobufs e Geradores de origem.
rust_bindgenGera a origem e produz uma biblioteca Rust contendo vinculações Rust a bibliotecas C. Páginas de Vinculações bindgen e Geradores de origem.

Propriedades comuns importantes

Essas propriedades são comuns em todos os módulos Rust do Android. Outras propriedades (exclusivas) associadas a módulos Rust individuais são listadas na página de cada módulo.

name

A propriedade name é o nome do módulo. Como outros módulos Soong, ele precisa ser exclusivo na maioria dos tipos de módulo Android.bp. Por padrão, o name é usado como o nome do arquivo de saída. Se o nome do arquivo de saída precisar ser diferente do nome do módulo, use a propriedade stem para o definir.

stem

A propriedade stem (opcional) oferece controle direto sobre o nome do arquivo de saída, excluindo a extensão de arquivo e outros sufixos. Por exemplo, uma biblioteca rust_library_rlib com um valor de libfoo para "stem" produz um arquivo libfoo.rlib. Se você não fornecer um valor para a propriedade stem, o nome de arquivo da saída adotará o nome do módulo por padrão.

Use a função stem quando não for possível definir o nome do módulo como o nome do arquivo de saída escolhido. Por exemplo, a rust_library para a caixa log recebe o nome liblog_rust, porque uma liblog cc_library já existe. O uso da propriedade stem nesse caso garante que o arquivo de saída seja nomeado como liblog.* em vez de liblog_rust.*.

srcs

A propriedade srcs contém um único arquivo de origem que representa o ponto de entrada do módulo (geralmente main.rs ou lib.rs). rustc processa a resolução e a descoberta de todos os outros arquivos de origem necessários para compilação e eles são enumerados no arquivo deps produzido.

Sempre que possível, evite usar essa propriedade em códigos da plataforma. Consulte Geradores de origem para ver mais informações.

crate_name

A propriedade crate_name define os metadados do nome da caixa com a sinalização rustc --crate_name. Para módulos que produzem bibliotecas, essa propriedade precisa corresponder ao nome da caixa esperada usado na origem. Por exemplo, se o módulo libfoo_bar for referenciado na origem como extern crate foo_bar, ele precisará ser crate_name: "foo_bar".

Essa propriedade é comum a todos os módulos rust_*, mas é obrigatória para módulos que produzem bibliotecas Rust, como rust_library, rust_ffi, rust_bindgen, rust_protobuf e rust_proc_macro. Esses módulos aplicam requisitos rustc para a relação entre crate_name e o nome do arquivo de saída. Para ver mais informações, consulte a seção Módulos de biblioteca.

lints

O rustc linter (link em inglês) é executado por padrão em todos os tipos de módulo, exceto nos geradores de origem. Alguns conjuntos de lint são definidos e usados para validar a origem do módulo. Os valores possíveis para esses conjuntos de lint são:

  • default: o conjunto padrão de lints, dependendo da localização do módulo.
  • android: para o conjunto de lint mais rigoroso que se aplica a todo o código da Plataforma Android.
  • vendor: para um conjunto moderado de lints aplicados ao código do fornecedor.
  • none: para ignorar todos os avisos e erros de lint.

clippy_lints

O clippy linter (link em inglês) também é executado por padrão para todos os tipos de módulo, exceto geradores de origem. Alguns conjuntos de lints são definidos e usados para validar a origem do módulo. Veja alguns valores possíveis:

  • default: o conjunto padrão de lints, dependendo da localização do módulo.
  • android: para o conjunto de lint mais rigoroso que se aplica a todo o código da Plataforma Android.
  • vendor: para um conjunto moderado de lints aplicados ao código do fornecedor.
  • none: para ignorar todos os avisos e erros de lint.

edition

A propriedade edition define a edição do Rust a ser usada para compilar esse código. Ela é parecida com as versões std para C e C++. Os valores válidos são 2015 e 2018 (padrão).

flags

A propriedade flags contém uma lista de strings de sinalizações a serem transmitidas para rustc durante a compilação.

ld_flags

A propriedade ld-flags contém uma lista de strings de sinalizações a serem transmitidas para o vinculador ao compilar a origem. Elas são transmitidas pela sinalização rustc -C linker-args. O clang é usado como front-end do vinculador, invocando lld para a vinculação.

features

A propriedade features é uma lista de strings de recursos que precisam ser ativados durante a compilação. Ela é transmitida para o rustc por --cfg 'feature="foo"'. A maioria dos recursos é aditiva, portanto, em muitos casos, isso consiste nos recursos completos exigidos por todos os módulos dependentes. No entanto, nos casos em que os recursos são exclusivos, defina outros módulos nos arquivos de compilação que fornecem recursos conflitantes.

cfgs

A propriedade cfgs contém uma lista de strings de sinalizações cfg que serão ativadas durante a compilação. Ela é transmitida para rustc por --cfg foo e --cfg "fizz=buzz".

O sistema de compilação define automaticamente determinadas sinalizações cfg em situações específicas, listadas abaixo:

  • Os módulos criados como uma propriedade dylib terão a cfg android_dylib definida.
  • Os módulos que usam o VNDK terão a cfg android_vndk definida. Isso é parecido com a definição de __ANDROID_VNDK__ para C++.

strip

A propriedade strip controla como e se o arquivo de saída é removido (se aplicável). Se essa opção não estiver definida, os módulos do dispositivo serão removidos por padrão, exceto o mini debuginfo. Por padrão, os módulos do host não removem símbolos. Os valores válidos incluem none para desativar a remoção e all para remover tudo, incluindo o mini debuginfo. Outros valores podem ser encontrados na referência dos módulos Soong.

host_supported

Para módulos de dispositivos, o parâmetro host_supported indica se o módulo também precisa fornecer uma variante de host.

Como definir dependências da biblioteca

Os módulos Rust podem depender das bibliotecas CC e Rust usando estas propriedades:

Nome da propriedade Descrição
rustlibs Lista de módulos rust_library que também são dependências. Use essa lista como o método recomendado de declaração de dependências, porque ele permite que o sistema de compilação selecione a vinculação recomendada. Consulte a seção Ao vincular as bibliotecas da Rust abaixo.
rlibs Lista de módulos rust_library que precisam ser vinculados estaticamente como rlibs. Use com cuidado. Consulte a seção Ao vincular a bibliotecas da Rust abaixo.
dylibs Lista de módulos rust_library a serem vinculados dinamicamente como dylibs. Use com cuidado. Consulte a seção Ao vincular a bibliotecas da Rust abaixo.
shared_libs Lista de módulos cc_library que precisam ser vinculados dinamicamente como bibliotecas compartilhadas.
static_libs Lista de módulos cc_library que precisam ser estaticamente vinculados como bibliotecas estáticas.
whole_static_libs Lista de módulos cc_library que precisam ser vinculados estaticamente como bibliotecas estáticas e incluídos totalmente na biblioteca resultante. Para variantes rust_ffi_static, a propriedade whole_static_libraries será incluída no arquivo de biblioteca estática resultante. Para variantes rust_library_rlib, de bibliotecas, a propriedade whole_static_libraries será agrupada na biblioteca rlib resultante.

Ao vincular usando bibliotecas Rust, como prática recomendada, use a propriedade rustlibs em vez de rlibs ou dylibs, a menos que você tenha um motivo específico para fazer isso. Essa prática possibilita que o sistema de compilação selecione a vinculação correta com base no que o módulo raiz exige e reduz a chance de uma árvore de dependências conter as versões rlib e dylib de uma biblioteca, o que causará falha na compilação.

Recursos de build com suporte limitado e sem suporte

O Soong do Rust oferece suporte limitado a imagens e snapshots vendor e vendor_ramdisk. No entanto, ele oferece suporte total a staticlibs, cdylibs, rlibs e binaries. A propriedade android_vndk cfg é definida para destinos de build da imagem do fornecedor. Você poderá usar essa propriedade no código se houver diferenças entre os destinos do sistema e do fornecedor. rust_proc_macros não são capturadas como parte dos snapshots do fornecedor. Se outros componentes dependerem deles, garanta o controle de versões adequada para eles.

Não há suporte para imagens de recuperação, produto e VNDK.

Builds incrementais

Os desenvolvedores podem ativar a compilação incremental da fonte Rust definindo a variável de ambiente SOONG_RUSTC_INCREMENTAL como true.

Aviso: não podemos garantir que esse processo vá gerar binários idênticos aos gerados por buildbots. Os endereços das funções ou os dados contidos nos arquivos do objeto podem ser diferentes. Para garantir que os artefatos gerados sejam 100% idênticos aos criados pela infraestrutura do EngProd, não defina esse valor.