Konfigurowanie środowiska IDE na potrzeby tworzenia SDV

Android Studio for Platform (ASfP) to zalecane zintegrowane środowisko programistyczne (IDE) do tworzenia programowalnych platform SDV (Software-Defined Vehicle) na system operacyjny Android Automotive (AAOS). ASfP obsługuje wszystkie języki używane przez platformę AAOS SDV, w tym Rust w przypadku pakietów usług SDV.

Ta strona dotyczy tylko konfiguracji SDV. Więcej informacji o ogólnych funkcjach i przepływach pracy ASfP znajdziesz w artykule Android Studio for Platform.

ASfP działa tylko na 64-bitowym systemie Linux z procesorami x86-64. Możesz go używać na lokalnej stacji roboczej z systemem Linux lub w chmurze. Więcej informacji o konfiguracji w chmurze znajdziesz w artykule na temat programowania w chmurze.

Instalowanie ASfP

Domyślny maksymalny rozmiar sterty w ASfP to 30 GB. Indeksowanie platformy checkout wymaga dużej ilości pamięci, zwłaszcza gdy na tej samej maszynie uruchamiasz też urządzenia Cuttlefish z wieloma maszynami wirtualnymi. Ogranicz zakres projektu do katalogów, nad którymi pracujesz, i w razie potrzeby dostosuj maksymalny rozmiar sterty w ustawieniach pamięci ASfP.

ASfP obsługuje automatyczne aktualizacje w IDE. Więcej informacji znajdziesz w artykule Aktualizowanie Androida Studio for Platform. Więcej informacji o pobieraniu i instalowaniu ASfP oraz sprawdzaniu wymagań systemowych znajdziesz w artykule Instalowanie Android Studio for Platform.

Tworzenie projektu SDV

Zanim zaczniesz, zainicjuj, zsynchronizuj i skompiluj proces płatności SDV w AAOS. Więcej informacji o konfigurowaniu procesu płatności znajdziesz w sekcjach Lokalizacja kodu oraz Pobieranie, kompilowanie i uruchamianie.

Aby utworzyć projekt SDV, wykonaj te czynności:

  1. Utwórz nowy projekt w ASfP i wybierz katalog główny kasy AAOS SDV jako kasę repozytorium. Więcej informacji o krokach kreatora znajdziesz w artykule Tworzenie i importowanie projektu.
  2. Gdy ASfP utworzy projekt, wybierz ASfP > Project > Open Config (ASfP > Projekt > Otwórz konfigurację), aby otworzyć plik .asfp-project.
  3. Zastąp zawartość pliku tym przykładem, a następnie ustaw repo na ścieżkę do kasy:

    repo: /path/to/sdv_source
    lunch: sdv_core_cf-aosp_current-userdebug
    directories:
      include:
        -   system/software_defined_vehicle/samples
    other_languages:
      -   rust
    
  4. Zaktualizuj dane (lunch i directories) dotyczące obszaru, nad którym pracujesz. Aby indeksowanie i synchronizacja przebiegały szybko, uwzględnij tylko te katalogi, które aktywnie modyfikujesz. W tabeli poniżej znajdziesz listę typowych elementów docelowych i katalogów SDV:

    SDV development focus lunch cel Zalecane: directories
    Pakiety usług SDV sdv_core_cf-aosp_current-userdebug katalog usług i pakietów, np. system/software_defined_vehicle/samples;
    Integracja z platformą SDV Core sdv_core_cf-aosp_current-userdebug system/software_defined_vehicle/middleware, system/software_defined_vehicle/automotive_services, device/google/sdv
    Brama SDV w systemie multimedialnym SDV sdv_ivi_cf-aosp_current-userdebug system/software_defined_vehicle/sdv_gateway, system/software_defined_vehicle/samples/sdv_gateway, packages/services/Car
    Wyświetlanie informacji o bezpieczeństwie w SDV Media sdv_media_har_cf-aosp_current-userdebug packages/services/display_safety, device/google/sdv_display_safety
    Bezpieczeństwo wyświetlania w samochodowym systemie multimedialnym SDV sdv_ivi_cf_ds-aosp_current-userdebug packages/apps/Car/DriverUI, packages/services/display_safety/service

    Jeśli proces płatności korzysta z pliku manifestu trunk_staging, zastąp -aosp_current-userdebug ciągiem -trunk_staging-userdebug. Aby przeglądać też kod platformy natywnej, dodaj cpp do other_languages. Więcej informacji o wszystkich opcjach konfiguracji znajdziesz w artykule Parametry konfiguracji.

  5. Aby zastosować zmiany, wybierz ASfP > Sync > Sync Project (ASfP > Synchronizuj > Synchronizuj projekt). Więcej informacji o trybach synchronizacji (pełna synchronizacja, częściowa synchronizacja i synchronizacja bez kompilacji) oraz eksportowaniu i importowaniu szablonów .asfp-project, które można udostępniać zespołowi, znajdziesz w artykułach Tryby synchronizacji i okno narzędzia Soong oraz Szablony projektów, które można udostępniać (eksportowanie i importowanie).

Wdrażanie pakietów usług SDV

ASfP zawiera wtyczkę SDV, która wdraża APEX zawierający pakiety usług bezpośrednio na działającym urządzeniu SDV. Wtyczka jest domyślnie wyłączona. Aby go użyć, włącz wtyczkę SDV w sekcji Ustawienia > Wtyczki. Więcej informacji o pakowaniu APEX znajdziesz w artykule Tworzenie i wdrażanie pakietów usług.

Sposób wdrażania zależy od tego, czy plik APEX jest już na urządzeniu:

  • Jeśli rozszerzenie APEX jest już zainstalowane, możesz wdrożyć zmiany bezpośrednio z ASfP.
  • Jeśli APEX jest nowy, musisz najpierw ponownie utworzyć i uruchomić obraz systemu lub użyć obrazu systemu, który zawiera klucz użyty do podpisania APEX. Po tym czasie możesz wdrożyć usługę z ASfP.

Aby wdrożyć pakiet APEX pakietu usług, wykonaj te czynności:

  1. Uruchom urządzenie SDV z wtyczką Cuttlefish. Więcej informacji znajdziesz w artykule Uruchamianie urządzeń SDV na Cuttlefish (w języku angielskim).
  2. Otwórz plik apex/Android.bp pakietu usług i kliknij ikonę Uruchom w rynnie obok bloku apex {.
  3. W menu, które się otworzy, wybierz Run 'Deploy APEX_NAME' (Uruchom „Wdróż”). W tym samym menu możesz też skompilować APEX bez wdrażania lub zmienić konfigurację uruchamiania.

Uruchamianie urządzeń SDV na Cuttlefish

ASfP zawiera wtyczkę Cuttlefish, która tworzy i uruchamia lokalne urządzenia Cuttlefish. Wtyczka wymaga koordynatora hosta Cuttlefish. Jeśli koordynator hosta jest niedostępny, ASfP wyświetla instrukcje jego konfiguracji.

Aby utworzyć urządzenie SDV, wykonaj te czynności:

  1. Wybierz Narzędzia > Menedżer urządzeń, kliknij + i wybierz Utwórz urządzenie Cuttlefish.
  2. Aby utworzyć konfigurację z wieloma maszynami wirtualnymi, wybierz Z konfiguracji kanonicznej i utwórz lub zaimportuj konfigurację, np. SDV Core z SDV IVI lub SDV Media z SDV IVI na potrzeby Display Safety. Aby utworzyć pojedynczą maszynę wirtualną, wybierz Z lokalnego drzewa źródeł Androida.

Aby wyświetlić wszystkie ekrany maszyn wirtualnych na jednym ekranie i uzyskać dostęp do dodatkowych opcji urządzenia, użyj okna narzędzia Cuttlefish. Aby go otworzyć, kliknij ikonę … w panelu bocznym i wybierz Cuttlefish lub wyszukaj Cuttlefish w sekcji Pomoc > Znajdź działanie. Możesz też wyświetlić poszczególne wyświetlacze w sekcji Działające urządzenia. SDV Core działa bez wyświetlacza, więc do jego sprawdzania używaj Logcata i terminala.

Debugowanie i testowanie

ASfP zawiera wbudowany debuger LLDB do kodu w językach C++ i Rust. Więcej informacji o debugowaniu i testowaniu w ASfP znajdziesz w artykułach Debugowanie kodu platformy, Debugowanie kodu w Rust, Testowanie kodu platformy za pomocą atest i Debugowanie elementów docelowych cc_test i rust_test w LLDB.

Gdy dołączasz debuger do pakietu usług, dołącz go do procesu, który go hostuje. Nazwy procesów mają format <bundle_name>:<instance_name>, np. OrchestratorSampleRustServiceBundle:sample-main-no-conditions. To polecenie wyświetla listę pasujących procesów i ich identyfikatorów procesów:

adb shell ps -A | grep <bundle_name>

Więcej informacji o procesach debugowania SDV, takich jak łączenie się z wieloma urządzeniami i wyświetlanie dzienników, znajdziesz w artykule Debugowanie SDV.

Edytowanie plików VSIDL

ASfP obejmuje serwer języka VSIDL (vsidl-lsp). Więcej informacji o konfigurowaniu katalogu na potrzeby serwera języka znajdziesz w artykule o automatycznych aktualizacjach katalogu i integracji z LSP. Gdy katalog zawiera plik CATALOG_UPDATE, edytor udostępnia te funkcje dla plików .vsidl:

  • Weryfikacja na żywo: edytor wyróżnia słowa kluczowe VSIDL i wyświetla błędy składni, nierozwiązane typy i błędy weryfikacji VSIDLC w oknie Problemy. Więcej informacji o regułach sprawdzania poprawności i kodach błędów znajdziesz w specyfikacji języka VSIDL.
  • Autouzupełnianie i dokumentacja: możesz nacisnąć Ctrl + Spacja, aby wyświetlić sugestie dotyczące słów kluczowych, komunikatów, usług, tematów i kanałów, oraz Ctrl + Q, aby wyświetlić komentarze do dokumentacji.
  • Nawigacja i formatowanie: możesz nacisnąć Ctrl + B, aby przejść do definicji .vsidl lub .proto, Alt + Shift + F7, aby znaleźć odwołania, Ctrl + F12, aby wyświetlić strukturę pliku, oraz Ctrl + Alt + L, aby sformatować plik.

Dodawanie kontekstu SDV dla asystentów AI

ASfP obejmuje AI w Android Studio i wbudowanego agenta z narzędziami do kompilacji Soong i atest. Pliki AGENTS.md znajdują się obok kodu źródłowego w systemie kontroli wersji, więc możesz udostępniać te same reguły SDV wbudowanemu agentowi ASfP oraz agentom kodowania opartym na wierszu poleceń lub kontenerach, które odczytują pliki AGENTS.md. Gdy prześlesz prompta z plikiem otwartym w ASfP, agent wczyta pliki AGENTS.md z katalogu tego pliku i jego katalogów nadrzędnych (chyba że plik GEMINI.md w tym samym katalogu ma pierwszeństwo). Aktywne pliki możesz sprawdzić w panelu czatu w szufladzie Kontekst w sekcji Pliki AGENTS.md. Więcej informacji znajdziesz w artykułach Android Studio for Platform i Dostosowywanie agenta za pomocą plików AGENTS.md.

Te szablony stanowią punkt wyjścia do przepływów pracy opisanych w artykule Tworzenie projektu SDV.

Pakiety usług SDV

Umieść ten plik AGENTS.md w katalogu pakietu zawartym w pliku .asfp-project, który zawiera foldery catalog/, services/ i apex/. Więcej informacji znajdziesz w artykułach Generowanie oprogramowania pośredniczącego, Tworzenie i wdrażanie pakietów usług, Tworzenie pliku mapowania SOME/IP i Omówienie autoryzacji komunikacji 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

Brama SDV w samochodowym systemie multimedialnym SDV

Umieść ten plik AGENTS.md w katalogu modułu klienta IVI lub system/software_defined_vehicle/sdv_gateway/. Więcej informacji znajdziesz w artykule Korzystanie z bramy SDV w samochodowym systemie multimedialnym.

# 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)

Bezpieczeństwo wyświetlania

Umieść ten plik AGENTS.md w packages/services/display_safety/ lub w katalogu aplikacji tablicy wskaźników. Więcej informacji znajdziesz w artykułach Pierwsze kroki z Display Safety, Warstwa abstrakcji platformy HAR, Łańcuch narzędzi do projektowania bezpieczeństwa i 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