Módulos do Android Rust

Como princípio geral, as definições do módulo rust_* seguem rigorosamente o uso e as expectativas cc_* . A seguir está 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,
}

Esta página cobre as propriedades mais comuns para módulos rust_* . Para obter mais informações sobre tipos de módulos específicos e exemplos de definições de módulos, consulte Módulos binários , Módulos de biblioteca ou Módulos de teste .

Tipos de módulos básicos

Tipo Definição Para maiores informações
rust_binary Um binário Rust Página Módulos Binários
rust_library Produz uma biblioteca Rust e fornece variantes rlib e dylib . rust_library , página Módulos de Biblioteca.
rust_ffi Produz uma biblioteca Rust C utilizável por módulos cc e fornece variantes estáticas e compartilhadas. rust_ffi , página Módulos de Biblioteca
rust_proc_macro Produz uma biblioteca Rust proc-macro . (Eles são análogos aos plug-ins do compilador.) rust_proc_macro , página Módulos de Bibliotecas
rust_test Produz um binário de teste Rust que usa o equipamento de teste Rust padrão. Página Módulos de teste
rust_fuzz Produz um binário Rust fuzz aproveitando libfuzzer . exemplo de módulo rust_fuzz
rust_protobuf Gera fonte e produz uma biblioteca Rust que fornece uma interface para um protobuf específico. Páginas de Módulos Protobufs e Geradores de Fonte
rust_bindgen Gera a fonte e produz uma biblioteca Rust contendo ligações Rust para bibliotecas C. Páginas de Módulos de Bindgen Bindings e Geradores de Origem

Propriedades comuns importantes

Essas propriedades são comuns a todos os módulos Android Rust . Quaisquer propriedades adicionais (exclusivas) associadas a módulos Rust individuais estão listadas na página desse módulo.

nome

name é o nome do seu módulo. Como outros módulos Soong, este deve ser exclusivo na maioria dos tipos de módulos Android.bp . Por padrão, name é usado como 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.

tronco

stem (opcional) fornece controle direto sobre o nome do arquivo de saída (excluindo a extensão do arquivo e outros sufixos). Por exemplo, uma biblioteca rust_library_rlib com um valor radical libfoo produz um arquivo libfoo.rlib . Se você não fornecer um valor para a propriedade stem , o nome do arquivo de 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 para o nome do arquivo de saída desejado. Por exemplo, a rust_library para a caixa log é denominada liblog_rust , porque já existe uma liblog cc_library . Usar a propriedade stem neste caso garante que o arquivo de saída seja denominado liblog.* em vez de liblog_rust.* .

fontes

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

Quando possível, evite esse uso para código de plataforma; consulte Geradores de origem para obter mais informações.

nome_da_caixa

crate_name define os metadados do nome da caixa por meio do sinalizador rustc --crate_name . Para módulos que produzem bibliotecas, este deve corresponder ao nome esperado da caixa usada na fonte. Por exemplo, se o módulo libfoo_bar for referenciado na fonte como extern crate foo_bar , então deverá ser crate_name: "foo_bar".

Esta propriedade é comum a todos os módulos rust_* , mas é necessária para módulos que produzem bibliotecas Rust (como rust_library rust_ffi , rust_bindgen , rust_protobuf e rust_proc_macro ). Esses módulos impõem requisitos rustc no relacionamento entre crate_name e o nome do arquivo de saída. Para obter mais informações, consulte a seção Módulos de Biblioteca .

fiapos

O linter Rustc é executado por padrão para todos os tipos de módulo, exceto 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 os seguintes:

  • 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 todos os códigos da plataforma Android
  • vendor um conjunto relaxado de lints aplicado ao código do fornecedor
  • none para ignorar todos os avisos e erros do lint

clippy_lints

O clippy linter também é executado por padrão para todos os tipos de módulos, exceto geradores de origem. São definidos alguns conjuntos de lints que são usados ​​para validar a origem do módulo. Estes são alguns valores possíveis:

  • conjunto default de lints dependendo da localização do módulo
  • android o conjunto de lint mais rigoroso que se aplica a todos os códigos da plataforma Android
  • vendor um conjunto relaxado de lints aplicado ao código do fornecedor
  • none para ignorar todos os avisos e erros do lint

edição

edition define a edição Rust a ser usada para compilar este código. Isso é semelhante às versões padrão para C e C++. Os valores válidos são 2015 e 2018 (padrão).

bandeiras

flags contém uma lista de strings de flags para passar para rustc durante a compilação.

ld_flags

ld-flags contém uma lista de strings de sinalizadores para passar ao vinculador ao compilar o código-fonte. Eles são passados ​​​​pelo sinalizador -C linker-args rustc. clang é usado como front-end do vinculador, invocando lld para a vinculação real.

características

features é uma lista de strings de recursos que devem ser habilitados durante a compilação. Isso é passado para rustc por --cfg 'feature="foo"' . A maioria dos recursos são aditivos, portanto, em muitos casos, consiste no conjunto completo de recursos exigidos por todos os módulos dependentes. No entanto, nos casos em que os recursos são exclusivos entre si, defina módulos adicionais em quaisquer arquivos de construção que forneçam recursos conflitantes.

cfgs

cfgs contém uma lista de strings de sinalizadores cfg a serem habilitados durante a compilação. Isso é passado para rustc por --cfg foo e --cfg "fizz=buzz" .

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

  • Módulos construídos como dylib terão o conjunto android_dylib cfg.

  • Os módulos que usariam o VNDK terão o android_vndk cfg definido. Isso é semelhante à definição __ANDROID_VNDK__ para C++.

faixa

strip controla se e como o arquivo de saída é removido (se aplicável). Se isso não for definido, os módulos do dispositivo padrão removerão tudo, exceto mini informações de depuração. Os módulos host, por padrão, não removem nenhum símbolo. Os valores válidos incluem none para desabilitar a remoção e all para remover tudo, incluindo o mini debuginfo. Valores adicionais podem ser encontrados na Referência de Módulos Soong .

host_suportado

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

Definir dependências de biblioteca

Os módulos Rust podem depender das bibliotecas CC e Rust por meio das seguintes propriedades:

Nome da propriedade Descrição
rustlibs Lista de módulos rust_library que também são dependências. Use este como seu método preferido de declaração de dependências, pois permite que o sistema de compilação selecione a ligação preferida. (Consulte Ao vincular às bibliotecas Rust , abaixo)
rlibs Lista de módulos rust_library que devem ser vinculados estaticamente como rlibs . (Use com cuidado; consulte Ao vincular com bibliotecas Rust , abaixo.)
shared_libs Lista de módulos cc_library que devem ser vinculados dinamicamente como bibliotecas compartilhadas.
static_libs Lista de módulos cc_library que devem ser vinculados estaticamente como bibliotecas estáticas.
whole_static_libs Lista de módulos cc_library que devem ser vinculados estaticamente como bibliotecas estáticas e incluídos inteiros na biblioteca resultante. Para variantes rust_ffi_static , whole_static_libraries serão incluídos no arquivo da biblioteca estática resultante. Para variantes rust_library_rlib , as bibliotecas whole_static_libraries serão agrupadas na biblioteca rlib resultante.

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

Recursos de compilação com suporte limitado e sem suporte

Rust de Soong oferece suporte limitado para imagens e instantâneos vendor e vendor_ramdisk . No entanto, staticlibs , cdylibs , rlibs e binaries são suportados. Para destinos de criação de imagens de fornecedores, a propriedade android_vndk cfg é definida. Você pode usar isso no código se houver diferenças entre o sistema e os destinos do fornecedor. rust_proc_macros não são capturados como parte dos instantâneos do fornecedor; se eles dependem deles, certifique-se de controlá-los adequadamente.

Imagens de produto, VNDK e recuperação não são suportadas.

Construções incrementais

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

Aviso : não é garantido que isso produza binários idênticos aos gerados pelos buildbots. Os endereços das funções ou dados contidos nos arquivos objeto podem ser diferentes. Para garantir que os artefatos gerados sejam 100% idênticos aos construídos pela infraestrutura EngProd, deixe este valor sem definição.