O Android Studio for Platform (ASfP) é o ambiente de desenvolvimento integrado (IDE) recomendado para o desenvolvimento de plataformas de veículos definidos por software (SDV) do Android Automotive OS (AAOS). O ASfP é compatível com todos os idiomas usados pela plataforma de SDV do AAOS, incluindo Rust para pacotes de serviços de SDV.
Esta página aborda apenas a configuração específica para SDVs. Para mais informações sobre recursos e fluxos de trabalho gerais do ASfP, consulte Android Studio for Platform.
O ASfP é executado apenas no Linux de 64 bits com CPUs x86-64. É possível usá-la em uma estação de trabalho local do Linux ou na nuvem. Para mais informações sobre a configuração da nuvem, consulte Desenvolvimento na nuvem.
Instalar o ASfP
O ASfP usa como padrão um tamanho máximo de heap de 30 GB. A indexação de um checkout de plataforma usa muita memória, especialmente quando você também executa dispositivos Cuttlefish com várias VMs na mesma máquina. Mantenha o projeto limitado aos diretórios em que você trabalha e ajuste o tamanho máximo do heap nas configurações de memória do ASfP, se necessário.
O ASfP oferece suporte a atualizações automáticas no ambiente de desenvolvimento integrado. Para mais informações, consulte Atualizar o Android Studio para plataforma. Para mais informações sobre como baixar e instalar o ASfP e verificar os requisitos do sistema, consulte Instalar o Android Studio for Platform.
Criar um projeto de SDV
Inicialize, sincronize e crie seu checkout do SDV do AAOS antes de começar. Para mais informações sobre como configurar o checkout, consulte Local do código e Fazer o download, criar e executar.
Para criar um projeto de SDV, siga estas etapas:
- Crie um novo projeto no ASfP e selecione a raiz do checkout do SDV do AAOS como o checkout do repositório. Para mais informações sobre as etapas do assistente, consulte Criar ou importar um projeto.
- Depois que o ASfP criar o projeto, selecione ASfP > Project > Open Config para
abrir o arquivo
.asfp-project. Substitua o conteúdo do arquivo pelo exemplo a seguir e defina
repocomo o caminho do seu checkout:repo: /path/to/sdv_source lunch: sdv_core_cf-aosp_current-userdebug directories: include: - system/software_defined_vehicle/samples other_languages: - rustAtualize
lunchedirectoriespara a área em que você trabalha. Para manter a indexação e a sincronização rápidas, inclua apenas os diretórios que você modifica ativamente. A tabela a seguir lista os destinos e diretórios comuns de SDV:Foco no desenvolvimento de SDVs lunchmetaRecomendação: directoriesPacotes de serviços de SDV sdv_core_cf-aosp_current-userdebugSeu catálogo de serviços e diretório de pacotes, como system/software_defined_vehicle/samplesIntegração com a plataforma principal do SDV sdv_core_cf-aosp_current-userdebugsystem/software_defined_vehicle/middleware,system/software_defined_vehicle/automotive_services,device/google/sdvGateway de SDV no IVI de SDV sdv_ivi_cf-aosp_current-userdebugsystem/software_defined_vehicle/sdv_gateway,system/software_defined_vehicle/samples/sdv_gateway,packages/services/CarSegurança da tela na mídia do SDV sdv_media_har_cf-aosp_current-userdebugpackages/services/display_safety,device/google/sdv_display_safetySegurança da tela no IVI do SDV sdv_ivi_cf_ds-aosp_current-userdebugpackages/apps/Car/DriverUI,packages/services/display_safety/serviceSe a finalização de compra usar um manifesto
trunk_staging, substitua-aosp_current-userdebugpor-trunk_staging-userdebug. Para navegar também pelo código da plataforma nativa, adicionecppaother_languages. Para mais informações sobre todas as opções de configuração, consulte Parâmetros de configuração.Para aplicar as mudanças, selecione ASfP > Sync > Sync Project. Para mais informações sobre os modos de sincronização (completa, parcial e sem build) e como exportar ou importar modelos compartilháveis do
.asfp-projectpara sua equipe, consulte Modos de sincronização e janela de ferramentas do Soong e Modelos de projeto compartilháveis (exportação e importação).
Implantar pacotes de serviços de SDV
O ASfP inclui um plug-in de SDV que implanta um APEX com seus pacotes de serviço diretamente em um dispositivo SDV em execução. O plug-in fica desativado por padrão. Para usá-lo, ative o plug-in do SDV em Configurações > Plug-ins. Para mais informações sobre o empacotamento APEX, consulte Criar e implantar pacotes de serviços.
A implantação depende se o APEX já está no dispositivo:
- Se o APEX já estiver instalado, você poderá implantar as mudanças diretamente do ASfP.
- Se o APEX for novo, primeiro será necessário recriar e reiniciar a imagem do sistema ou usar uma imagem do sistema que inclua a chave usada para assinar o APEX. Depois disso, você poderá implantar usando o ASfP.
Para implantar um APEX de pacote de serviços, siga estas etapas:
- Inicie o dispositivo SDV com o plug-in do Cuttlefish. Para mais informações, consulte Executar dispositivos SDV no Cuttlefish.
- Abra o arquivo
apex/Android.bpdo pacote de serviços e clique no ícone Run na medianiz ao lado do blocoapex {. - No menu que aparece, selecione Run 'Deploy APEX_NAME'. Você também pode criar o APEX sem implantá-lo ou mudar a configuração de execução no mesmo menu.
Executar dispositivos SDV no Cuttlefish
O ASfP inclui um plug-in do Cuttlefish que cria e executa dispositivos locais do Cuttlefish. O plug-in precisa do orquestrador de host do Cuttlefish. Se o orquestrador de host não estiver disponível, o ASfP vai mostrar instruções para configurá-lo.
Para criar um dispositivo SDV, siga estas etapas:
- Selecione Ferramentas > Gerenciador de dispositivos, clique em + e selecione Create Cuttlefish Device.
- Para criar uma configuração de várias VMs, selecione Da configuração canônica e crie ou importe uma configuração, como SDV Core com SDV IVI ou SDV Media com SDV IVI para segurança de exibição. Para criar uma única VM, selecione Do checkout da árvore de origem local do Android.
Para ver todas as telas de VM em uma única tela e acessar outras opções de dispositivo, use a janela de ferramentas do Cuttlefish. Para abrir, selecione o ícone ... no painel lateral e selecione Cuttlefish ou pesquise Cuttlefish em Help > Find Action. Também é possível conferir telas individuais em Dispositivos em execução. Como o SDV Core é executado sem uma tela, use o Logcat e o Terminal para inspecioná-lo.
Depurar e testar
O ASfP inclui um depurador LLDB integrado para código C++ e Rust. Para mais informações sobre depuração e testes no ASfP, consulte Depurar código de plataforma, Depurar código Rust, Testar código de plataforma com atest e Depurar destinos cc_test e rust_test no LLDB.
Ao anexar o depurador a um pacote de serviços, anexe-o ao processo que o
hospeda. Os nomes de processos usam o formato <bundle_name>:<instance_name>, como
OrchestratorSampleRustServiceBundle:sample-main-no-conditions. O comando a seguir lista os processos correspondentes e os IDs de processo deles:
adb shell ps -A | grep <bundle_name>
Para mais informações sobre fluxos de trabalho de depuração de SDV, como conexão com vários dispositivos e visualização de registros, consulte Depurar SDV.
Editar arquivos VSIDL
O ASfP inclui o servidor de linguagem VSIDL (vsidl-lsp). Para mais informações
sobre como configurar seu catálogo para o servidor de linguagem, consulte
Atualizações automáticas de catálogo e integração com o LSP. Quando o catálogo inclui
um arquivo CATALOG_UPDATE, o editor oferece os seguintes recursos para
arquivos .vsidl:
- Validação em tempo real: o editor destaca as palavras-chave do VSIDL e mostra erros de sintaxe, tipos não resolvidos e erros de validação do VSIDLC na janela Problemas. Para mais informações sobre as regras de validação e os códigos do erro, consulte a especificação da linguagem VSIDL.
- Preenchimento automático e documentação: pressione Ctrl+Espaço para sugestões de palavras-chave, mensagens, serviços, tópicos e canais e pressione Ctrl+Q para ver os comentários da documentação.
- Navegação e formatação: pressione Ctrl+B para acessar as definições de
.vsidlou.proto, Alt+Shift+F7 para encontrar referências, Ctrl+F12 para conferir a estrutura do arquivo e Ctrl+Alt+L para formatar o arquivo.
Adicionar contexto de SDV para assistentes de IA
O ASfP inclui IA no Android Studio e um agente integrado com o build do Soong e as ferramentas
atest. Como os arquivos AGENTS.md ficam ao lado do código-fonte no
controle de versões, é possível compartilhar as mesmas regras de SDV entre o agente integrado do ASfP
e os agentes de programação baseados em contêiner ou linha de comando que leem AGENTS.md. Quando
você envia um comando com um arquivo aberto no ASfP, o agente carrega arquivos AGENTS.md
do diretório desse arquivo e dos diretórios pai (a menos que um arquivo GEMINI.md
no mesmo diretório tenha precedência). É possível verificar os arquivos ativos
no painel Contexto do painel de conversa em Arquivos AGENTS.md. Para mais
informações, consulte Conheça o Android Studio para Plataforma e
Personalizar o agente usando arquivos AGENTS.md.
Os modelos a seguir são pontos de partida para os fluxos de trabalho em Criar um projeto de SDV.
Pacotes de serviços de SDV
Coloque esse arquivo AGENTS.md no diretório do pacote incluído em .asfp-project
que contém as pastas catalog/, services/ e apex/. Para mais
informações, consulte Gerar middleware,
Criar e implantar pacotes de serviços, Criar um arquivo de mapeamento SOME/IP e
Visão geral da autorização de comunicações do SDV.
# AAOS SDV service bundle and VSIDL rules
## Build and test
- Initialize the build environment (`source build/envsetup.sh` and
`lunch sdv_core_cf-aosp_current-userdebug`) when running outside ASfP, build
modules with Soong (`m <module_name>`), and run tests with
`atest <TestModuleName>` (`rust_test`, `rust_test_host`, `cc_test`, or
`python_test_host`), without creating `Cargo.toml` files or running `cargo`
- In catalog `Android.bp` files, avoid `defaults` on `rust_protobuf` modules
(`vsidlc` uses a regex parser), include each `.proto` file in at most one
`rust_protobuf` target, and cover all catalog files in the first `filegroup`
(`srcs: ["**/*"]`)
## Protobuf, VSIDL, and AUTOSAR SOME/IP mapping conventions
- Keep `.proto` files limited to `message`, `enum`, and RPC `service` schemas
(using `sdv/vsidl/v1/annotations.proto` only for field size bounds), without
topic names, channel names, or queue capacities
- Write `.vsidl` files in TextProto `VsidlEntry` syntax (`package: "..."`,
`service_bundle { name: "..." }`, `publisher` or `subscriber` with `message`
and `topic`, and `server` or `client` with `service` and `channel`, without
`import` statements; RPCs support unary, client-streaming, and
server-streaming methods, not bidirectional streaming), and isolate
`some_ip_mapping` (`sdv_type_mapping` and `someip_service_mapping` for
AUTOSAR electronic control unit (ECU) `ARXML` or `vsomeip` IDs) or
`vhal_mapping` rules in dedicated `.vsidl` mapping files so core bundles stay
transport-independent
- Use `PascalCase` for `service_bundle` names (avoiding Rust, C++, and Java
keywords), `snake_case` for `build_cfg.target_name`, a globally unique
lowercase `package` with at least four segments (`com.<org>.sdv.<domain>`;
never reuse platform-reserved `com.android.sdv.*` or sample `com.sdv.*`
names), and lowercase dash-case starting with a letter (no consecutive or
trailing hyphens, underscores, or slashes) for `topic`, `channel`, and
instance names
- Set `capacity` on every `publisher` to an even integer greater than or equal
to 2, and pair every `subscriber` and RPC `client` with a matching
`publisher` or `server` in the catalog or its `-d` dependency catalogs
## Code generation, authorization, and APEX packaging
- Export `ANDROID_BUILD_TOP`, check `CATALOG_UPDATE` for catalog-relative
`output_path` (such as `".."`), `dependency_catalog_paths` (`-d`), and
`vsidlc_gen_args`, and run `vsidlc -c <catalog_dir> -o <output_dir>`; omit
`--services` from `vsidlc_gen_args` and avoid `-p` (`--purge`) or
`regenerator` when `output_path` holds handwritten `services/` code
- Leave generated files in `generated_rs/`, `apex/`, and `configs/` unmodified,
and implement Rust logic in `services/<ServiceBundleName>/src/main.rs` (even
though the initial `vsidlc --services` skeleton header says not to edit; C++
bundles do not use `vsidlc` C++ codegen and instead use
`libsdv_lifecycle_client_cpp`, `libsdv_comms_cpp`, and
`sdv_service_bundle_metadata` with `native_library_path: "lib64/lib<so>.so"`
in `sdv_service_bundles_manifest.textproto`)
- Keep communications authorization `.textproto` policies in `configs/` aligned
with every `publisher`, `subscriber`, `server`, and `client` unit (omitting
`capacity` inside manual authorization `.textproto` `publisher` entries) so
Service Discovery does not reject endpoints at runtime
- In Rust bundles, wait for publisher or RPC server availability before
creating subscribers or clients, stop active tasks in `on_stop`, and run
blocking work in `tokio::spawn_blocking`
- Generate Rust service bundle APEXes with `vsidlc --apex` (`updatable: true`,
`min_sdk_version: "35"`, and `product_specific: true` in `apex/Android.bp`,
never `vendor: true` or `soc_specific: true`, with matching unique `name` and
`version` >= 1 in `apex_manifest.json`), and do not set
`supportsRebootlessUpdate: true` or run `adb install --force-non-staged`
because SDV APEX updates require a reboot
Gateway de SDV no IVI de SDV
Coloque esse arquivo AGENTS.md no diretório do módulo do cliente IVI ou
system/software_defined_vehicle/sdv_gateway/. Para mais informações, consulte
Usar o gateway de SDV no IVI.
# AAOS SDV Gateway on SDV IVI rules
- Initialize the build environment (`source build/envsetup.sh` and
`lunch sdv_ivi_cf-aosp_current-userdebug`) when running outside ASfP, build
IVI modules with Soong (`m <module_name>`), and run verification with
`atest <TestModuleName>`
- For native C or C++ IVI clients (including vehicle hardware abstraction layer
(VHAL) integrations), link `libsdvgatewayclient`
(`#include "libsdvgatewayclient.h"`) or `ISdvGateway`; for in-tree system Java
or Kotlin clients, use `libsdvgatewayclient-java`,
`libsdvgatewayclient-java-sdk.stubs`, `libsdvgatewayclient-java-sdk`, and
`com.android.sdv.gateway.client`
- Start the Binder thread pool before calling `ASDVGateway_Client_new`, and
call `ASDVGateway_Client_initComms` (or `SdvGatewayClient.initComms`) before
any service discovery, data tunnel, or RPC calls
- Check `ASDVGateway_Client_isRpcAvailable` or
`ASDVGateway_Client_isProcessBoundToSdvRpcNetworkInterface` before opening
RPC sockets on early boot, treat `ASDVGateway_StatusCode_OK` with null
`ASDVGateway_RpcCredentials_t` as insecure `UNLOCKED` boot mode, and free
non-null credentials with `ASDVGateway_Client_deleteRpcCredentials`
- Grant `sdv_gateway_client_domain(<domain>)` in SELinux (do not add
`binder_use` on `/vendor` daemons, which violates Treble `neverallow`; add
`group inet` on native init services, and `INTERNET` plus
`CONNECTIVITY_USE_RESTRICTED_NETWORKS` privapp permissions for system Java
RPC clients)
Segurança da tela
Coloque esse arquivo AGENTS.md em packages/services/display_safety/ ou no
diretório do app do painel de instrumentos. Para mais informações, consulte
Começar a usar o Display Safety, Camada de abstração da plataforma HAR,
Conjunto de ferramentas de design de segurança e DriverUI.
# AAOS Display Safety partner integration rules
- Display Safety spans two guest VMs with separate `lunch` targets: keep
safety-critical telltales, gauges, camera views, chimes, and early-boot or
fallback placeholders in the Rust high availability renderer (HAR) and safety
monitor on SDV Media (`sdv_media_har_cf`), and build non-safety cluster UI on
SDV IVI (`sdv_ivi_cf_ds`) using `ClusterHomeManager` (`Cluster2` rather than
legacy `Cluster1`)
- Implement target OS and hardware subsystems (display, graphics, exterior view
system (EVS) cameras, audio, user input, and vehicle signals) in a dedicated
`har-platform-<target>` platform abstraction layer (PAL) crate implementing
`har-platform-api` traits rather than modifying core `harry` framework crates,
and verify PAL crates against the HAR platform test suite with `atest`
- Generate safety monitor configurations and telltale inspection artifacts from
the serialized Automotive Design for Compose document and safety JSON mapping
(`{"documents": [{"rootnode": "#...", "display_id": 1, "document_id": "...",`
`"states": {"<signal>": "#<node_id>"}}]}`) using the safety design compiler
rather than hardcoding telltale pixel coordinates
- Because the HAR display plane composites above Android IVI, ensure HAR clears
the cluster viewport region to `alpha = 0.0` while valid `HeartbeatRequest`
gRPC messages arrive from IVI, and set opaque pixels in custom HAR OpenGL ES
surfaces to `alpha = 1.0` (`0xFF`)
- Initialize the build environment (`source build/envsetup.sh` and `lunch`) when
running outside ASfP, integrate prebuilt cluster APKs into `sdv_ivi_cf_ds`
through `DriverUIPrebuilt` (`overrides: ["DriverUIStubApp"]`), launch dual-VM
Cuttlefish setups from ASfP or with `ds_toolkit launch`, pass `--user 0` to
`adb shell am` cluster commands, and note that
`adb shell dumpsys SurfaceFlinger` on SDV IVI inspects only Android layers
rather than the overlying HAR plane