Menyiapkan IDE untuk pengembangan SDV

Android Studio untuk Platform (ASfP) adalah lingkungan pengembangan terintegrasi (IDE) yang direkomendasikan untuk pengembangan platform Software-Defined Vehicle (SDV) Android Automotive OS (AAOS). ASfP mendukung semua bahasa yang digunakan platform SDV AAOS, termasuk Rust untuk paket layanan SDV.

Halaman ini hanya membahas penyiapan khusus SDV. Untuk mengetahui informasi selengkapnya tentang fitur dan alur kerja ASfP umum, lihat Android Studio untuk Platform.

ASfP hanya berjalan di Linux 64-bit dengan CPU x86-64. Anda dapat menggunakannya di workstation Linux lokal atau di cloud. Untuk mengetahui informasi selengkapnya tentang penyiapan cloud, lihat Pengembangan cloud.

Menginstal ASfP

ASfP secara default memiliki ukuran heap maksimum 30 GB. Mengindeks checkout platform menggunakan banyak memori, terutama saat Anda juga menjalankan perangkat Cuttlefish multi-VM di mesin yang sama. Pastikan project Anda terbatas pada direktori yang Anda kerjakan, dan sesuaikan ukuran heap maksimum di setelan memori ASfP jika diperlukan.

ASfP mendukung update otomatis dalam IDE. Untuk mengetahui informasi selengkapnya, lihat Mengupdate Android Studio untuk Platform. Untuk mengetahui informasi selengkapnya tentang cara mendownload dan menginstal ASfP serta memeriksa persyaratan sistem, lihat Menginstal Android Studio for Platform.

Membuat project SDV

Lakukan inisialisasi, sinkronisasi, dan build checkout SDV AAOS Anda sebelum memulai. Untuk mengetahui informasi selengkapnya tentang cara menyiapkan checkout, lihat Lokasi kode dan Mendownload, mem-build, dan menjalankan.

Untuk membuat project SDV, ikuti langkah-langkah berikut:

  1. Buat project baru di ASfP dan pilih root checkout SDV AAOS Anda sebagai checkout repositori. Untuk mengetahui informasi selengkapnya tentang langkah-langkah wizard, lihat Membuat atau mengimpor project.
  2. Setelah ASfP membuat project, pilih ASfP > Project > Open Config untuk membuka file .asfp-project.
  3. Ganti konten file dengan contoh berikut, lalu tetapkan repo ke jalur checkout Anda:

    repo: /path/to/sdv_source
    lunch: sdv_core_cf-aosp_current-userdebug
    directories:
      include:
        -   system/software_defined_vehicle/samples
    other_languages:
      -   rust
    
  4. Perbarui lunch dan directories untuk area yang Anda kerjakan. Agar pengindeksan dan sinkronisasi tetap cepat, sertakan hanya direktori yang Anda ubah secara aktif. Tabel berikut mencantumkan target dan direktori SDV umum:

    Fokus pengembangan SDV lunch target directories yang direkomendasikan
    Paket layanan SDV sdv_core_cf-aosp_current-userdebug Katalog layanan dan direktori paket Anda, seperti system/software_defined_vehicle/samples
    Integrasi platform SDV Core sdv_core_cf-aosp_current-userdebug system/software_defined_vehicle/middleware, system/software_defined_vehicle/automotive_services, device/google/sdv
    Gateway SDV di IVI SDV sdv_ivi_cf-aosp_current-userdebug system/software_defined_vehicle/sdv_gateway, system/software_defined_vehicle/samples/sdv_gateway, packages/services/Car
    Menampilkan Keselamatan di Media SDV sdv_media_har_cf-aosp_current-userdebug packages/services/display_safety, device/google/sdv_display_safety
    Keamanan Layar di IVI SDV sdv_ivi_cf_ds-aosp_current-userdebug packages/apps/Car/DriverUI, packages/services/display_safety/service

    Jika checkout Anda menggunakan manifes trunk_staging, ganti -aosp_current-userdebug dengan -trunk_staging-userdebug. Untuk menjelajahi kode platform native juga, tambahkan cpp ke other_languages. Untuk mengetahui informasi selengkapnya tentang semua opsi konfigurasi, lihat Parameter konfigurasi.

  5. Untuk menerapkan perubahan, pilih ASfP > Sync > Sync Project. Untuk mengetahui informasi selengkapnya tentang mode sinkronisasi (Sinkronisasi Penuh, Sinkronisasi Parsial, dan Sinkronisasi Tanpa Build) serta mengekspor atau mengimpor template .asfp-project yang dapat dibagikan untuk tim Anda, lihat Mode sinkronisasi dan jendela alat Soong dan Template project yang dapat dibagikan (ekspor dan impor).

Men-deploy paket layanan SDV

ASfP menyertakan plugin SDV yang men-deploy APEX yang berisi paket layanan Anda langsung ke perangkat SDV yang sedang berjalan. Plugin ini dinonaktifkan secara default. Untuk menggunakannya, aktifkan plugin SDV di Settings > Plugins. Untuk mengetahui informasi selengkapnya tentang paket APEX, lihat Mem-build dan men-deploy paket layanan.

Cara Anda men-deploy bergantung pada apakah APEX sudah ada di perangkat:

  • Jika APEX sudah diinstal, Anda dapat men-deploy perubahan secara langsung dari ASfP.
  • Jika APEX baru, Anda harus membangun ulang dan meluncurkan kembali image sistem terlebih dahulu, atau menggunakan image sistem yang menyertakan kunci yang digunakan untuk menandatangani APEX. Setelah itu, Anda dapat men-deploy dari ASfP.

Untuk men-deploy APEX paket layanan, ikuti langkah-langkah berikut:

  1. Mulai perangkat SDV Anda dengan plugin Cuttlefish. Untuk mengetahui informasi selengkapnya, lihat Menjalankan perangkat SDV di Cuttlefish.
  2. Buka file apex/Android.bp dari paket layanan Anda, lalu klik ikon Run di gutter di samping blok apex {.
  3. Di menu yang terbuka, pilih Run 'Deploy APEX_NAME'. Anda juga dapat mem-build APEX tanpa men-deploy-nya atau mengubah konfigurasi run dari menu yang sama.

Menjalankan perangkat SDV di Cuttlefish

ASfP menyertakan plugin Cuttlefish yang membuat dan menjalankan perangkat Cuttlefish lokal. Plugin memerlukan orchestrator host Cuttlefish. Jika orchestrator host tidak tersedia, ASfP akan menampilkan petunjuk untuk menyiapkannya.

Untuk membuat perangkat SDV, ikuti langkah-langkah berikut:

  1. Pilih Tools > Pengelola Perangkat, klik +, lalu pilih Create Cuttlefish Device.
  2. Untuk membuat penyiapan multi-VM, pilih From canonical configuration dan buat atau impor konfigurasi untuk penyiapan Anda, seperti SDV Core dengan SDV IVI, atau SDV Media dengan SDV IVI untuk Display Safety. Untuk membuat satu VM, pilih From local Android source tree checkout.

Untuk melihat semua tampilan VM di satu layar dan mengakses opsi perangkat tambahan, gunakan jendela alat Cuttlefish. Untuk membukanya, pilih ikon ... di panel samping, lalu pilih Cuttlefish, atau telusuri Cuttlefish di Help > Find Action. Anda juga dapat melihat setiap layar di Running Devices. Karena SDV Core berjalan tanpa layar, gunakan Logcat dan Terminal untuk memeriksanya.

Men-debug dan menguji

ASfP menyertakan debugger LLDB bawaan untuk kode C++ dan Rust. Untuk mengetahui informasi selengkapnya tentang proses debug dan pengujian di ASfP, lihat Men-debug kode platform, Men-debug kode Rust, Menguji kode platform dengan atest, dan Men-debug target cc_test dan rust_test di LLDB.

Saat Anda memasang debugger ke paket layanan, pasang ke proses yang menghostingnya. Nama proses menggunakan format <bundle_name>:<instance_name>, seperti OrchestratorSampleRustServiceBundle:sample-main-no-conditions. Perintah berikut mencantumkan proses yang cocok dan ID prosesnya:

adb shell ps -A | grep <bundle_name>

Untuk mengetahui informasi selengkapnya tentang alur kerja proses debug SDV, seperti menghubungkan ke beberapa perangkat dan melihat log, lihat Men-debug SDV.

Mengedit file VSIDL

ASfP menyertakan Server Bahasa VSIDL (vsidl-lsp). Untuk mengetahui informasi selengkapnya tentang cara menyiapkan katalog untuk server bahasa, lihat Pembaruan katalog otomatis dan integrasi LSP. Jika katalog Anda menyertakan file CATALOG_UPDATE, editor akan menyediakan fitur berikut untuk file .vsidl:

  • Validasi langsung: Editor menandai kata kunci VSIDL dan menampilkan error sintaksis, jenis yang belum terselesaikan, dan error validasi VSIDLC di jendela Problems. Untuk mengetahui informasi selengkapnya tentang aturan validasi dan kode errornya, lihat spesifikasi bahasa VSIDL.
  • Pelengkapan otomatis dan dokumentasi: Anda dapat menekan Ctrl+Spasi untuk saran kata kunci, pesan, layanan, topik, dan saluran, serta menekan Ctrl+Q untuk melihat komentar dokumentasi.
  • Navigasi dan pemformatan: Anda dapat menekan Ctrl+B untuk membuka definisi .vsidl atau .proto, Alt+Shift+F7 untuk menemukan referensi, Ctrl+F12 untuk melihat struktur file, dan Ctrl+Alt+L untuk memformat file.

Menambahkan konteks SDV untuk asisten AI

ASfP menyertakan AI di Android Studio dan agen bawaan dengan alat build Soong dan atest. Karena file AGENTS.md berada bersama kode sumber Anda dalam kontrol versi, Anda dapat membagikan aturan SDV yang sama di seluruh agen bawaan ASfP dan agen coding berbasis container atau command line yang membaca AGENTS.md. Saat Anda mengirimkan perintah dengan file yang terbuka di ASfP, agen akan memuat file AGENTS.md dari direktori file tersebut dan direktori induknya (kecuali jika file GEMINI.md di direktori yang sama lebih diutamakan), dan Anda dapat memverifikasi file aktif di panel Percakapan Context panel chat di bagian AGENTS.md Files. Untuk mengetahui informasi selengkapnya, lihat Mengenal Android Studio for Platform dan Menyesuaikan agen menggunakan file AGENTS.md.

Template berikut memberikan titik awal untuk alur kerja di Membuat project SDV.

Paket layanan SDV

Tempatkan file AGENTS.md ini di direktori paket yang disertakan dalam .asfp-project yang mencakup folder catalog/, services/, dan apex/ Anda. Untuk mengetahui informasi selengkapnya, lihat Membuat middleware, Membangun dan men-deploy paket layanan, Menulis file pemetaan SOME/IP, dan Ringkasan otorisasi komunikasi 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 di IVI SDV

Tempatkan file AGENTS.md ini di direktori modul klien IVI atau system/software_defined_vehicle/sdv_gateway/. Untuk mengetahui informasi selengkapnya, lihat Menggunakan Gateway SDV di 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)

Keselamatan Layar

Tempatkan file AGENTS.md ini di packages/services/display_safety/ atau direktori aplikasi panel instrumen Anda. Untuk informasi selengkapnya, lihat Memulai Display Safety, Lapisan abstraksi platform HAR, Toolchain desain keselamatan, dan 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