Módulos Android Rust

Como princípio geral, as definições do módulo rust_* seguem de perto o uso e as expectativas do cc_* . O seguinte é um exemplo de uma 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ódulo específicos e definições de módulo de exemplo, consulte as páginas Binary Modules , Library Modules ou Test Modules .

Tipos de módulos básicos

Propriedades comuns importantes

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

nome

name é o nome do seu módulo. Como outros módulos Soong, isso deve 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 deve 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 de haste de libfoo produz um arquivo libfoo.rlib . Se você não fornecer um valor para a propriedade de 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 puder definir o nome do módulo para o nome de arquivo de saída desejado. Por exemplo, a rust_library para a caixa de log é denominada liblog_rust , porque já existe uma liblog cc_library . O uso da propriedade stem neste caso garante que o arquivo de saída seja denominado liblog.* em vez de liblog_rust.* .

srcs

srcs contém um único arquivo de origem que representa o ponto de entrada para seu módulo (geralmente main.rs ou lib.rs ). rustc lida com a resolução e a descoberta de todos os outros arquivos de origem necessários para a compilação, e estes são enumerados no arquivo deps que é 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 rustc --crate_name . Para módulos que produzem bibliotecas, isso deve corresponder ao nome de caixa esperado usado no código-fonte. Por exemplo, se o módulo libfoo_bar é referenciado na fonte como extern crate foo_bar , então deve ser crate_name: "foo_bar" .

Essa 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 os requisitos do 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ódulos, 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 (para o conjunto de lint mais estrito que se aplica a todos os códigos da plataforma Android)
• vendor (para um conjunto relaxado de lints aplicados ao código do fornecedor)
• none (para ignorar todos os avisos e erros de lint)

clippy_lints

O clippy linter também é executado por padrão para todos os tipos de módulos, exceto geradores de fonte. Alguns conjuntos de lints são definidos que são usados ​​para validar a origem do módulo. Estes são 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 estrito que se aplica a todos os códigos da plataforma Android)
• vendor (para um conjunto relaxado de lints aplicados ao código do fornecedor)
• none (para ignorar todos os avisos e erros de lint)

edição

edition define a edição Rust a ser usada para compilar esse código. Isso é semelhante às versões std 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 para o vinculador ao compilar o código-fonte. Estes são passados ​​pelo sinalizador -C linker-args rustc. clang é usado como o front-end do vinculador, invocando lld para a vinculação real.

recursos

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 é aditiva, portanto, em muitos casos, isso consiste no conjunto completo de recursos exigido por todos os módulos dependentes. No entanto, nos casos em que os recursos são exclusivos um do outro, defina módulos adicionais em qualquer arquivo de compilação que forneça 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 cfg android_dylib definido.
• Os módulos que usariam o VNDK terão o cfg android_vndk definido. Isso é semelhante à definição de __ANDROID_VNDK__ para C++.

faixa

strip controla se e como o arquivo de saída é removido (se aplicável). Se isso não estiver definido, os módulos de dispositivo padrão removerão tudo, exceto mini debuginfo. 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_supported

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

Definindo dependências de biblioteca

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

Ao vincular a 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 fazê-lo. Isso permite que o sistema de compilação selecione a ligação correta com base no que o módulo raiz requer 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 de suporte sem suporte e limitados

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

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

Builds Incrementais

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

Aviso : Isso não garante a produção de binários idênticos aos gerados por buildbots. Os endereços de funções ou dados contidos nos arquivos de objetos podem ser diferentes. Para garantir que os artefatos gerados sejam 100% idênticos aos construídos pela infraestrutura EngProd, deixe esse valor indefinido.