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
Tipo | Definição | Mais informações |
---|---|---|
rust_binary | Um binário Rust. | Página de Módulos binários. |
rust_library | Produz uma biblioteca Rust e fornece as variantes rlib e
dylib . |
rust_library ,
página de 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 de Módulos de biblioteca. |
rust_proc_macro | Produz uma biblioteca Rust proc-macro ,
análoga a plug-ins do compilador. |
rust_proc_macro ,
página de Módulos de bibliotecas. |
rust_test | Produz 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_fuzz | Produz um binário Rust fuzz usando
libfuzzer . |
Exemplo do módulo rust_fuzz . |
rust_protobuf | Gera 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_bindgen | Gera 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.