设置 IDE 以进行 SDV 开发

Android Studio for Platform (ASfP) 是 Android Automotive OS (AAOS) 软件定义汽车 (SDV) 平台开发推荐使用的集成开发环境 (IDE)。ASfP 支持 AAOS SDV 平台使用的所有语言,包括用于 SDV 服务软件包的 Rust。

本页仅介绍 SDV 专用设置。如需详细了解 ASfP 的常规功能和工作流,请参阅 Android Studio for Platform。

ASfP 仅可在配备 x86-64 CPU 的 64 位 Linux 上运行。您可以在本地 Linux 工作站或云端使用它。如需详细了解云设置,请参阅云开发。

安装 ASfP

ASfP 默认的最大堆大小为 30 GB。为平台检出内容编制索引会占用大量内存,尤其是在同一台机器上运行多虚拟机 Cuttlefish 设备时。将项目范围限定在您处理的目录中,并根据需要在 ASfP 内存设置中调整最大堆大小。

ASfP 支持在 IDE 中自动更新。如需了解详情,请参阅更新 Android Studio for Platform。如需详细了解如何下载和安装 ASfP 以及如何查看系统要求,请参阅安装 Android Studio for Platform。

创建 SDV 项目

在开始之前,请先初始化、同步和构建 AAOS SDV 检出。如需详细了解如何设置检出,请参阅代码位置以及下载、构建和运行。

如需创建 SDV 项目,请按以下步骤操作:

  1. 在 ASfP 中创建一个新项目,然后选择 AAOS SDV 检出的根目录作为代码库检出。如需详细了解向导步骤,请参阅创建或导入项目。
  2. ASfP 创建项目后,依次选择 ASfP > Project > Open Config,打开 .asfp-project 文件。
  3. 将该文件的内容替换为以下示例,然后将 repo 设置为检出路径:

    repo: /path/to/sdv_source
    lunch: sdv_core_cf-aosp_current-userdebug
    directories:
      include:
        -   system/software_defined_vehicle/samples
    other_languages:
      -   rust
    
  4. 更新您负责区域的 lunch 和 directories。为了保持快速索引和同步,请仅添加您经常修改的目录。下表列出了常见的 SDV 目标和目录:

    SDV 开发重点 lunch 项目标 推荐directories
    SDV 服务包 sdv_core_cf-aosp_current-userdebug 您的 Service Catalog 和软件包目录,例如 system/software_defined_vehicle/samples
    SDV 核心平台集成 sdv_core_cf-aosp_current-userdebug system/software_defined_vehicle/middleware、system/software_defined_vehicle/automotive_services、device/google/sdv
    SDV IVI 上的 SDV 网关 sdv_ivi_cf-aosp_current-userdebug system/software_defined_vehicle/sdv_gateway、system/software_defined_vehicle/samples/sdv_gateway、packages/services/Car
    在 SDV 媒体上展示安全 sdv_media_har_cf-aosp_current-userdebug packages/services/display_safety、device/google/sdv_display_safety
    在 SDV IVI 上显示安全信息 sdv_ivi_cf_ds-aosp_current-userdebug packages/apps/Car/DriverUI、packages/services/display_safety/service

    如果您的结账流程使用 trunk_staging 清单,请将 -aosp_current-userdebug 替换为 -trunk_staging-userdebug。如需同时浏览原生平台代码,请将 cpp 添加到 other_languages。如需详细了解所有配置选项,请参阅配置参数。

  5. 如需应用更改,请依次选择 ASfP > Sync > Sync Project。如需详细了解同步模式(完全同步、部分同步和无 build 同步)以及为团队导出或导入可共享的 .asfp-project 模板,请参阅同步模式和 Soong 工具窗口以及可共享的项目模板(导出和导入)。

部署 SDV 服务软件包

ASfP 包含一个 SDV 插件,该插件可将包含服务软件包的 APEX 直接部署到正在运行的 SDV 设备。该插件默认处于停用状态。如需使用该功能,请在 Settings > Plugins 中启用 SDV 插件。如需详细了解 APEX 打包,请参阅构建和部署服务软件包。

部署方式取决于设备上是否已有 APEX:

  • 如果 APEX 已安装,您可以直接从 ASfP 部署更改。
  • 如果 APEX 是新文件,您必须先重新构建并重新启动系统映像,或者使用包含用于对 APEX 进行签名的密钥的系统映像。之后,您就可以从 ASfP 进行部署。

如需部署服务 bundle APEX,请按以下步骤操作:

  1. 使用 Cuttlefish 插件启动 SDV 设备。如需了解详情,请参阅在 Cuttlefish 上运行 SDV 设备。
  2. 打开服务软件包的 apex/Android.bp 文件,然后点击 apex { 代码块旁边边线中的运行图标。
  3. 在打开的菜单中,选择 Run 'Deploy APEX_NAME'。您也可以在不部署 APEX 的情况下构建 APEX,或从同一菜单中更改运行配置。

在 Cuttlefish 上运行 SDV 设备

ASfP 包含一个 Cuttlefish 插件,用于创建和运行本地 Cuttlefish 设备。该插件需要 Cuttlefish 主机编排器。如果主机编排器不可用,ASfP 会显示设置说明。

如需创建 SDV 设备,请按照以下步骤操作:

  1. 依次选择 Tools > 设备管理器,点击 +,然后选择 Create Cuttlefish Device。
  2. 如需创建多虚拟机设置,请选择从规范配置,然后为您的设置创建或导入配置,例如 SDV Core 与 SDV IVI,或 SDV Media 与 SDV IVI for Display Safety。如需创建单个虚拟机,请改为选择从本地 Android 源代码树检出。

如需在单个屏幕上查看所有虚拟机显示屏并访问其他设备选项,请使用 Cuttlefish 工具窗口。如需打开该工具,请选择侧边栏中的 … 图标,然后选择 Cuttlefish,或在 Help > Find Action 中搜索 Cuttlefish。您还可以在正在运行的设备中查看各个显示屏。由于 SDV Core 在没有显示屏的情况下运行,因此请使用 Logcat 和终端对其进行检查。

调试和测试

ASfP 包含一个内置的 LLDB 调试程序,用于调试 C++ 和 Rust 代码。如需详细了解如何在 ASfP 中进行调试和测试,请参阅调试平台代码、调试 Rust 代码、使用 atest 测试平台代码以及在 LLDB 下调试 cc_test 和 rust_test 目标。

将调试程序附加到服务软件包时,请附加到托管该软件包的进程。进程名称采用 <bundle_name>:<instance_name> 格式,例如 OrchestratorSampleRustServiceBundle:sample-main-no-conditions。以下命令会列出匹配的进程及其进程 ID:

adb shell ps -A | grep <bundle_name>

如需详细了解 SDV 调试工作流(例如连接到多台设备和查看日志),请参阅调试 SDV。

修改 VSIDL 文件

ASfP 包含 VSIDL 语言服务器 (vsidl-lsp)。如需详细了解如何为语言服务器设置目录,请参阅自动目录更新和 LSP 集成。当您的目录包含 CATALOG_UPDATE 文件时,编辑器会为 .vsidl 文件提供以下功能:

  • 实时验证:编辑器会突出显示 VSIDL 关键字,并在问题窗口中显示语法错误、未解析的类型和 VSIDLC 验证错误。如需详细了解验证规则及其错误代码,请参阅 VSIDL 语言规范。
  • 自动补全和文档:您可以按 Ctrl+空格键获取关键字、消息、服务、主题和通道建议,然后按 Ctrl+Q 查看文档注释。
  • 导航和格式设置:您可以按 Ctrl+B 转到 .vsidl 或 .proto 定义,按 Alt+Shift+F7 查找引用,按 Ctrl+F12 查看文件结构,按 Ctrl+Alt+L 设置文件格式。

为 AI 助理添加 SDV 上下文

ASfP 包含 Android Studio 中的 AI 功能,以及一个内置智能体,该智能体具有 Soong build 和 atest 工具。由于 AGENTS.md 文件与源代码一起存储在版本控制系统中,因此您可以在 ASfP 的内置智能体与读取 AGENTS.md 的命令行或基于容器的编码智能体之间共享相同的 SDV 规则。当您在 ASfP 中打开文件并提交提示时,代理会从该文件的目录及其父级目录加载 AGENTS.md 文件(除非同一目录中的 GEMINI.md 文件优先),您可以在对话面板的上下文抽屉式导航栏中的 AGENTS.md 文件下验证活跃文件。如需了解详情,请参阅探索 Android Studio for Platform 和使用 AGENTS.md 文件自定义代理。

以下模板为创建 SDV 项目中的工作流提供了起点。

SDV 服务捆绑包

将此 AGENTS.md 文件放在 .asfp-project 中包含 catalog/、services/ 和 apex/ 文件夹的 bundle 目录中。如需了解详情,请参阅生成中间件、构建和部署服务包、编写 SOME/IP 映射文件和 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

SDV IVI 上的 SDV 网关

将此 AGENTS.md 文件放在 IVI 客户端模块目录或 system/software_defined_vehicle/sdv_gateway/ 中。如需了解详情,请参阅在 IVI 上使用 SDV 网关。

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

显示安全性

将此 AGENTS.md 文件放在 packages/services/display_safety/ 或您的仪表板应用目录中。如需了解详情,请参阅显示安全功能使用入门、HAR 平台抽象层、安全设计工具链和 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