Módulos 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_*. Confira um exemplo de definição de módulo para um binário do 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 saber mais sobre tipos de módulos específicos e exemplos de definições de módulo, consulte Módulos binários, Módulos de biblioteca ou Módulos de teste.

Observação: para conferir a documentação atual, gerada automaticamente para todos os tipos e propriedades de módulo, consulte a Referência do módulo Soong.

Tipos básicos de módulo

Tipo	Definição	Mais informações
rust_binary	Um binário do Rust.	Página de Módulos binários.
rust_library	Produz uma biblioteca do Rust e fornece as variantes rlib e dylib.	rust_library, página de Módulos de biblioteca.
rust_ffi	Produz uma biblioteca C do Rust utilizável por módulos cc e fornece variantes estáticas e compartilhadas.	rust_ffi, página de Módulos de biblioteca.
rust_proc_macro	Produz uma biblioteca proc-macro do Rust, análoga a plug-ins do compilador.	rust_proc_macro, página de Módulos de bibliotecas.
rust_test	Produz um binário de teste do Rust que usa o arcabouço de testes padrão Rust.	Página de Módulos de teste.
rust_fuzz	Produz um binário fuzz do Rust usando libfuzzer.	Exemplo do módulo rust_fuzz.
rust_protobuf	Gera a origem e produz uma biblioteca do Rust que fornece uma interface para um protobuf específico.	Páginas de Módulos de protobufs e Geradores de origem.
rust_bindgen	Gera a origem e produz uma biblioteca do Rust contendo vinculações Rust a bibliotecas C.	Páginas de Módulos 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 defini-lo.

stem

A propriedade stem (opcional) oferece controle direto sobre o nome do arquivo de saída, mas não à extensão do 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 vai 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.

Dica: srcs também processa a origem gerada referenciada pelo macro include!. Essas origens precisam ser fornecidas por outro módulo, como genrule ou rust_protobuf, entre outros. Para incluir a origem, adicione o nome do módulo que está fornecendo a origem gerada à srcs e use : como prefixo. Por exemplo, ":libmyproto". O arquivo de origem principal precisa ser a primeira entrada na matriz ao usar essa funcionalidade.

Sempre que possível, evite usar essa propriedade em códigos da plataforma. Consulte Geradores de origem para 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 esperado 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 saber mais, 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: o conjunto de lint mais rigoroso que se aplica a todo o código da Plataforma Android.
• vendor: um conjunto moderado de lints aplicado 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. Confira alguns valores possíveis:

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

Dica: defina lints como "none" durante o desenvolvimento para evitar erros do linter. No entanto, durante a revisão, talvez seja necessário justificar os módulos confirmados com lints menos rigorosos.

edition

A propriedade edition define a edição do Rust que vai ser usada para compilar o 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.

Observação: como elas são transmitidas ao Clang, as trate como sinalizações Clang. Use o prefixo padrão -Wl do Clang para as sinalizações que serão transmitidas ao lld.

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.

Observação: ao contrário de um build Cargo, não há um conjunto "default" (padrão) de recursos ativados implicitamente. O recurso "default" é uma palavra-chave especial do Cargo. A menos que o código processe explicitamente um recurso com o nome "default", definir um valor "default" não terá efeito.

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.

Definir dependências de biblioteca

Os módulos Rust podem depender das bibliotecas CC e do 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 build selecione a vinculação recomendada. Consulte a seção Ao vincular a bibliotecas do 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 do 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. Dica: isso impede que você declare as dependências dos dependentes dessa biblioteca. No entanto, em alguns casos, isso pode causar sobrecarga se a biblioteca estática estiver duplicada em uma árvore de dependências. Bibliotecas estáticas totalmente incluídas em "rlibs" serão incluídas totalmente em "dylibs" dependentes, o que proporciona outra fonte de possível sobrecarga.

Ao vincular a bibliotecas do 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 escolher uma dessas duas. Essa prática possibilita que o sistema de build 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 causaria falha na compilação.

Recursos de build com suporte limitado e sem suporte

O Rust do Soong oferece suporte limitado a imagens e snapshots de 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. Use 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 delas, garanta o controle de versões adequado para elas.

O suporte não é oferecido para imagens de recuperação, produto e VNDK.

Builds incrementais

Os desenvolvedores podem ativar a compilação incremental da origem 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.