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.
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.
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.
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.
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.
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.
|
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.