Configurare un IDE per lo sviluppo di SDV

Android Studio for Platform (ASfP) è l'ambiente di sviluppo integrato (IDE) consigliato per lo sviluppo della piattaforma SDV (Software-Defined Vehicle) di Android Automotive OS (AAOS). ASfP supporta tutte le lingue utilizzate dalla piattaforma SDV AAOS, incluso Rust per i bundle di servizi SDV.

Questa pagina illustra solo la configurazione specifica per gli SDV. Per saperne di più sulle funzionalità e sui workflow generali di ASfP, consulta Android Studio for Platform.

ASfP viene eseguito solo su Linux a 64 bit con CPU x86-64. Puoi utilizzarlo su una workstation Linux locale o nel cloud. Per saperne di più sulla configurazione del cloud, consulta Sviluppo cloud.

Installa ASfP

Per impostazione predefinita, ASfP ha una dimensione massima dell'heap di 30 GB. L'indicizzazione di un checkout della piattaforma utilizza molta memoria, soprattutto quando esegui anche dispositivi Cuttlefish multi-VM sulla stessa macchina. Limita l'ambito del progetto alle directory su cui lavori e, se necessario, regola la dimensione massima dell'heap nelle impostazioni della memoria di ASfP.

ASfP supporta gli aggiornamenti automatici nell'IDE. Per saperne di più, consulta Aggiorna Android Studio per la piattaforma. Per saperne di più sul download e sull'installazione di ASfP e sul controllo dei requisiti di sistema, consulta Installa Android Studio for Platform.

Crea un progetto SDV

Prima di iniziare, inizializza, sincronizza e crea il checkout SDV di AAOS. Per ulteriori informazioni sulla configurazione del checkout, consulta Posizione del codice e Scarica, crea ed esegui.

Per creare un progetto SDV, segui questi passaggi:

  1. Crea un nuovo progetto in ASfP e seleziona la directory principale del checkout dell'SDV AAOS come checkout del repository. Per saperne di più sui passaggi della procedura guidata, consulta Crea o importa un progetto.
  2. Dopo che ASfP ha creato il progetto, seleziona ASfP > Project > Open Config per aprire il file .asfp-project.
  3. Sostituisci i contenuti del file con il seguente esempio, quindi imposta repo sul percorso del tuo checkout:

    repo: /path/to/sdv_source
    lunch: sdv_core_cf-aosp_current-userdebug
    directories:
      include:
        -   system/software_defined_vehicle/samples
    other_languages:
      -   rust
    
  4. Aggiorna lunch e directories per l'area su cui lavori. Per mantenere l'indicizzazione e la sincronizzazione rapide, includi solo le directory che modifichi attivamente. La tabella seguente elenca i target e le directory SDV comuni:

    Focus sullo sviluppo di SDV lunch target directories consigliato
    Pacchetti di servizi SDV sdv_core_cf-aosp_current-userdebug Il tuo catalogo dei servizi e la directory dei bundle, ad esempio system/software_defined_vehicle/samples
    Integrazione della piattaforma SDV Core sdv_core_cf-aosp_current-userdebug system/software_defined_vehicle/middleware, system/software_defined_vehicle/automotive_services e device/google/sdv
    SDV Gateway su SDV IVI sdv_ivi_cf-aosp_current-userdebug system/software_defined_vehicle/sdv_gateway, system/software_defined_vehicle/samples/sdv_gateway e packages/services/Car
    Display Safety on SDV Media sdv_media_har_cf-aosp_current-userdebug packages/services/display_safety, device/google/sdv_display_safety
    Visualizza la sicurezza sull'IVI dell'SDV sdv_ivi_cf_ds-aosp_current-userdebug packages/apps/Car/DriverUI, packages/services/display_safety/service

    Se il tuo checkout utilizza un manifest trunk_staging, sostituisci -aosp_current-userdebug con -trunk_staging-userdebug. Per sfogliare anche il codice della piattaforma nativa, aggiungi cpp a other_languages. Per saperne di più su tutte le opzioni di configurazione, consulta Parametri di configurazione.

  5. Per applicare le modifiche, seleziona ASfP > Sincronizza > Sincronizza progetto. Per saperne di più sulle modalità di sincronizzazione (Sincronizzazione completa, Sincronizzazione parziale e Sincronizzazione senza build) e sull'esportazione o l'importazione di modelli .asfp-project condivisibili per il tuo team, consulta Modalità di sincronizzazione e finestra degli strumenti Soong e Modelli di progetto condivisibili (esportazione e importazione).

Esegui il deployment dei bundle di servizi SDV

ASfP include un plug-in SDV che esegue il deployment di un APEX contenente i bundle di servizi direttamente su un dispositivo SDV in esecuzione. Il plug-in è disattivato per impostazione predefinita. Per utilizzarlo, attiva il plug-in SDV in Impostazioni > Plug-in. Per saperne di più sul pacchetto APEX, consulta Crea ed esegui il deployment dei bundle di servizi.

La modalità di deployment dipende dal fatto che l'APEX sia già presente o meno sul dispositivo:

  • Se APEX è già installato, puoi eseguire il deployment delle modifiche direttamente da ASfP.
  • Se l'APEX è nuovo, devi prima ricreare e riavviare l'immagine di sistema o utilizzare un'immagine di sistema che includa la chiave utilizzata per firmare l'APEX. Dopodiché, puoi eseguire il deployment da ASfP.

Per eseguire il deployment di un APEX del bundle di servizi, segui questi passaggi:

  1. Avvia il dispositivo SDV con il plug-in Cuttlefish. Per saperne di più, consulta Esegui i dispositivi SDV su Cuttlefish.
  2. Apri il file apex/Android.bp del tuo bundle di servizi e fai clic sull'icona Esegui nel margine accanto al blocco apex {.
  3. Nel menu che si apre, seleziona Esegui "Esegui il deployment di APEX_NAME". Puoi anche creare l'APEX senza eseguirne il deployment o modificare la configurazione di esecuzione dallo stesso menu.

Esegui dispositivi SDV su Cuttlefish

ASfP include un plug-in Cuttlefish che crea ed esegue dispositivi Cuttlefish locali. Il plug-in richiede l'orchestratore host Cuttlefish. Se l'orchestratore host non è disponibile, ASfP mostra le istruzioni per configurarlo.

Per creare un dispositivo SDV, segui questi passaggi:

  1. Seleziona Strumenti > Gestione dispositivi, fai clic su + e seleziona Crea dispositivo Cuttlefish.
  2. Per creare una configurazione multi-VM, seleziona Da configurazione canonica e crea o importa una configurazione per la tua configurazione, ad esempio SDV Core con SDV IVI o SDV Media con SDV IVI per la sicurezza del display. Per creare una singola VM, seleziona Dal checkout dell'albero di origine Android locale.

Per visualizzare tutti i display delle VM su un'unica schermata e accedere ad altre opzioni del dispositivo, utilizza la finestra degli strumenti Cuttlefish. Per aprirlo, seleziona l'icona … nel riquadro laterale e seleziona Cuttlefish oppure cerca Cuttlefish in Guida > Trova azione. Puoi anche visualizzare i singoli display in Running Devices. Poiché SDV Core viene eseguito senza display, utilizza Logcat e il Terminale per ispezionarlo.

Debug e test

ASfP include un debugger LLDB integrato per il codice C++ e Rust. Per ulteriori informazioni sul debug e sui test in ASfP, consulta Esegui il debug del codice della piattaforma, Esegui il debug del codice Rust, Testa il codice della piattaforma con atest ed Esegui il debug dei target cc_test e rust_test in LLDB.

Quando colleghi il debugger a un bundle di servizi, collegalo al processo che lo ospita. I nomi dei processi utilizzano il formato <bundle_name>:<instance_name>, ad esempio OrchestratorSampleRustServiceBundle:sample-main-no-conditions. Il seguente comando elenca i processi corrispondenti e i relativi ID di processo:

adb shell ps -A | grep <bundle_name>

Per saperne di più sui workflow di debug degli SDV, ad esempio sulla connessione a più dispositivi e sulla visualizzazione dei log, consulta Esegui il debug degli SDV.

Modifica i file VSIDL

ASfP include il server di linguaggio VSIDL (vsidl-lsp). Per saperne di più su come configurare il catalogo per il server di linguaggio, consulta Aggiornamenti automatici del catalogo e integrazione LSP. Quando il catalogo include un file CATALOG_UPDATE, l'editor fornisce le seguenti funzionalità per i file .vsidl:

  • Convalida in tempo reale: l'editor evidenzia le parole chiave VSIDL e mostra gli errori di sintassi, i tipi non risolti e gli errori di convalida VSIDLC nella finestra Problemi. Per ulteriori informazioni sulle regole di convalida e sui relativi codici di errore, consulta la specifica del linguaggio VSIDL.
  • Completamento automatico e documentazione: puoi premere Ctrl+Spazio per visualizzare suggerimenti su parole chiave, messaggi, servizi, argomenti e canali e premere Ctrl+Q per visualizzare i commenti della documentazione.
  • Navigazione e formattazione: puoi premere Ctrl+B per andare alle definizioni .vsidl o .proto, Alt+Maiusc+F7 per trovare i riferimenti, Ctrl+F12 per visualizzare la struttura del file e Ctrl+Alt+L per formattare il file.

Aggiungi il contesto SDV per gli assistenti AI

ASfP include AI in Android Studio e un agente integrato con strumenti di build Soong e atest. Poiché i file AGENTS.md si trovano insieme al codice sorgente nel controllo della versione, puoi condividere le stesse regole SDV tra l'agente integrato di ASfP e gli agenti di programmazione basati su container o riga di comando che leggono AGENTS.md. Quando invii un prompt con un file aperto in ASfP, l'agente carica i file AGENTS.md dalla directory del file e dalle relative directory principali (a meno che un file GEMINI.md nella stessa directory non abbia la precedenza) e puoi verificare i file attivi nel riquadro Contesto del riquadro Chat in File AGENTS.md. Per saperne di più, consulta Scopri Android Studio for Platform e Personalizza l'agente utilizzando i file AGENTS.md.

I seguenti modelli forniscono punti di partenza per i workflow descritti in Crea un progetto SDV.

Bundle di servizi SDV

Inserisci questo file AGENTS.md nella directory del bundle inclusa in .asfp-project che contiene le cartelle catalog/, services/ e apex/. Per saperne di più, consulta Genera middleware, Crea ed esegui il deployment dei bundle di servizi, Scrivi un file di mappatura SOME/IP e Panoramica dell'autorizzazione delle comunicazioni 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 SDV su IVI SDV

Inserisci questo file AGENTS.md nella directory del modulo client IVI o in system/software_defined_vehicle/sdv_gateway/. Per saperne di più, consulta Utilizza il gateway SDV su 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)

Sicurezza del display

Inserisci questo file AGENTS.md in packages/services/display_safety/ o nella directory dell'app del quadro strumenti. Per saperne di più, consulta Inizia a utilizzare Display Safety, Livello di astrazione della piattaforma HAR, Toolchain di progettazione della sicurezza 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