راه‌اندازی IDE برای توسعه SDV

استودیو Android برای پلاتفرم (ASfP) محیط توسعه یکپارچه (IDE) توصیه‌شده برای توسعه پلاتفرم «خودرو نرم‌افزارمحور» (SDV) در «سیستم‌عامل Android Automotive» (AAOS) است. ‫ASfP از همه زبان‌هایی که پلاتفرم خودروی نرم‌افزارمحور سیستم عامل Android Automotive استفاده می‌کند، ازجمله Rust برای بسته‌های سرویس خودروی نرم‌افزارمحور، پشتیبانی می‌کند.

این صفحه فقط راه‌اندازی مختص «خودرو نرم‌افزارمحور» را پوشش می‌دهد. برای کسب اطلاعات بیشتر درباره ویژگی‌ها و گردش‌های کاری عمومی ASfP، به Android Studio ویژه پلاتفرم مراجعه کنید.

ASfP فقط در Linux‏ ۶۴ بیتی با واحد پردازش مرکزی x86-64 اجرا می‌شود. می‌توانید از آن در ایستگاه کاری محلی Linux یا در فضای ابری استفاده کنید. برای اطلاعات بیشتر درباره راه‌اندازی ابری، به توسعه ابری مراجعه کنید.

نصب ASfP

ASfP به‌طور پیش‌فرض حداکثر اندازه توده ۳۰ گیگابایت دارد. نمایه‌سازی یک پلاتفرم پرداخت حافظه زیادی مصرف می‌کند، به‌ویژه زمانی که دستگاه‌های Cuttlefish چند VM را نیز روی همان ماشین اجرا می‌کنید. پروژه‌تان را به دایرکتوری‌هایی که روی آن‌ها کار می‌کنید محدود کنید، و درصورت نیاز، حداکثر اندازه توده را در تنظیمات حافظه ASfP تنظیم کنید.

‫ASfP از به‌روزرسانی‌های خودکار درون IDE پشتیبانی می‌کند. برای اطلاعات بیشتر، به به‌روزرسانی Android Studio برای پلاتفرم مراجعه کنید. برای کسب اطلاعات بیشتر درباره بارگیری و نصب ASfP و بررسی الزامات سیستم، نصب Android Studio for Platform را ببینید.

ایجاد پروژه SDV

قبل‌از شروع، AAOS SDV checkout را مقداردهی اولیه، همگام‌سازی، و ایجاد کنید. برای کسب اطلاعات بیشتر درباره راه‌اندازی تسویه‌حساب، به مکان کد و بارگیری، ساخت، و اجرا مراجعه کنید.

برای ایجاد پروژه «خودروی نرم‌افزارمحور»، این مراحل را دنبال کنید:

  1. پروژه جدیدی در ASfP ایجاد کنید و ریشه تسویه‌حساب AAOS SDV را به‌عنوان تسویه‌حساب مخزن انتخاب کنید. برای اطلاعات بیشتر درباره مراحل جادوگر، ایجاد یا وارد کردن پروژه را ببینید.
  2. پس‌از اینکه ASfP پروژه را ایجاد کرد، ASfP > پروژه > باز کردن پیکربندی را انتخاب کنید تا فایل .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 کاتالوگ سرویس و فهرست راهنمای بسته شما، مثل 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 در سیستم سرگرمی-اطلاعاتی درون‌خودرو SDV sdv_ivi_cf-aosp_current-userdebug system/software_defined_vehicle/sdv_gateway، system/software_defined_vehicle/samples/sdv_gateway، packages/services/Car
    نمایش ایمنی در رسانه خودروی نرم‌افزارمحور sdv_media_har_cf-aosp_current-userdebug packages/services/display_safety، device/google/sdv_display_safety
    ایمنی نمایشگر در سیستم سرگرمی-اطلاعاتی درون‌خودرو نرم‌افزارمحور 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 > همگام‌سازی > همگام‌سازی پروژه را انتخاب کنید. برای اطلاعات بیشتر درباره حالت‌های همگام‌سازی («همگام‌سازی کامل»، «همگام‌سازی جزئی»، و «همگام‌سازی بدون ساخت») و صادر کردن یا وارد کردن الگوهای .asfp-project قابل‌هم‌رسانی برای تیمتان، به حالت‌های همگام‌سازی و پنجره ابزار Soong و الگوهای پروژه قابل‌هم‌رسانی (صادر کردن و وارد کردن) مراجعه کنید.

پیاده‌سازی کردن دسته‌های سرویس SDV

ASfP شامل یک افزونه SDV است که APEX حاوی بسته‌های سرویس شما را مستقیماً در دستگاه SDV درحال اجرا مستقر می‌کند. افزایه به‌طور پیش‌فرض غیرفعال است. برای استفاده از آن، افزایه SDV را در تنظیمات > افزایه‌ها فعال کنید. برای اطلاعات بیشتر درباره بسته‌بندی APEX، به ساختن و پیاده‌سازی بسته‌های سرویس مراجعه کنید.

نحوه استقرار به این بستگی دارد که APEX ازقبل در دستگاه وجود داشته باشد یا نه:

  • اگر APEX ازقبل نصب شده باشد، می‌توانید تغییراتتان را مستقیماً از ASfP مستقر کنید.
  • اگر APEX جدید است، ابتدا باید ایمیج سیستم را بازسازی و مجدداً راه‌اندازی کنید، یا از ایمیج سیستمی استفاده کنید که شامل کلید استفاده‌شده برای امضای APEX باشد. پس‌از آن، می‌توانید از ASfP مستقر کنید.

برای استقرار APEX دسته سرویس، این مراحل را دنبال کنید:

  1. دستگاه SDV را با افزونه Cuttlefish راه‌اندازی کنید. برای اطلاعات بیشتر، اجرای دستگاه‌های SDV در Cuttlefish را ببینید.
  2. فایل apex/Android.bp دسته سرویس را باز کنید و روی نماد اجرا در حاشیه کنار بلوک apex { کلیک کنید.
  3. در منویی که باز می‌شود، اجرای «استقرار APEX_NAME» را انتخاب کنید. همچنین می‌توانید APEX را بدون استقرار آن بسازید یا پیکربندی اجرا را از همان منو تغییر دهید.

اجرای دستگاه‌های SDV در Cuttlefish

ASfP شامل افزونه Cuttlefish است که دستگاه‌های Cuttlefish محلی را ایجاد و اجرا می‌کند. این افزونه به هماهنگ‌ساز میزبان Cuttlefish نیاز دارد. اگر هماهنگ‌ساز میزبان دردسترس نباشد، ASfP دستورالعمل‌های راه‌اندازی آن را نشان می‌دهد.

برای ایجاد دستگاه SDV، این مراحل را دنبال کنید:

  1. Tools (ابزارها) > Device Manager (مدیر دستگاه) را انتخاب کنید، روی + کلیک کنید، و Create Cuttlefish Device (ایجاد دستگاه Cuttlefish) را انتخاب کنید.
  2. برای ایجاد راه‌اندازی چند ماشین مجازی، از پیکربندی متعارف را انتخاب کنید و پیکربندی‌ای برای راه‌اندازی‌تان ایجاد یا وارد کنید، مثلاً SDV Core با SDV IVI، یا SDV Media با SDV IVI برای «ایمنی نمایشگر». برای ایجاد یک ماشین مجازی، درعوض از بررسی درخت منبع Android محلی را انتخاب کنید.

برای مشاهده همه نمایشگرهای VM در یک صفحه و دسترسی به گزینه‌های بیشتر دستگاه، از پنجره ابزار Cuttlefish استفاده کنید. برای باز کردن آن، نماد ... را در پانل کناری انتخاب کنید و Cuttlefish را انتخاب کنید، یا Cuttlefish را در راهنما > یافتن کنش جستجو کنید. همچنین می‌توانید نمایشگرهای تکی را در دستگاه‌های درحال اجرا مشاهده کنید. چون SDV Core بدون نمایشگر اجرا می‌شود، از Logcat و پایانه برای بازرسی آن استفاده کنید.

اشکال‌زدایی و آزمایش

‫ASfP شامل یک اشکال‌زدای LLDB داخلی برای کد C++‎ و Rust است. برای اطلاعات بیشتر درباره اشکال‌زدایی و آزمایش در ASfP، به اشکال‌زدایی کد پلاتفرم، اشکال‌زدایی کد Rust، آزمایش کد پلاتفرم با atest، و اشکال‌زدایی هدف‌های cc_test و rust_test تحت LLDB مراجعه کنید.

وقتی اشکال‌زدا را به دسته سرویس پیوست می‌کنید، به فرایندی که آن را میزبانی می‌کند پیوست کنید. نام‌های فرایند از قالب <bundle_name>:<instance_name> استفاده می‌کنند، مثل OrchestratorSampleRustServiceBundle:sample-main-no-conditions. فرمان زیر فرایندهای منطبق و شناسه فرایند آن‌ها را فهرست می‌کند:

adb shell ps -A | grep <bundle_name>

برای اطلاعات بیشتر درباره گردش‌های کاری اشکال‌زدایی SDV، مثل متصل شدن به چند دستگاه و مشاهده گزارش‌ها، اشکال‌زدایی SDV را ببینید.

ویرایش فایل‌های VSIDL

ASfP شامل سرور زبان VSIDL (vsidl-lsp) است. برای اطلاعات بیشتر درباره نحوه راه‌اندازی کاتالوگ برای سرور زبان، به به‌روزرسانی‌های خودکار کاتالوگ و ادغام LSP مراجعه کنید. وقتی کاتالوگ شما شامل فایل CATALOG_UPDATE باشد، ویرایشگر ویژگی‌های زیر را برای فایل‌های .vsidl ارائه می‌دهد:

  • اعتبارسنجی زنده: ویرایشگر کلیدواژه‌های VSIDL را برجسته می‌کند و خطاهای نحوی، انواع حل‌نشده، و خطاهای اعتبارسنجی VSIDLC را در پنجره مشکلات نشان می‌دهد. برای اطلاعات بیشتر درباره قوانین اعتبارسنجی و کدهای خطای آن‌ها، مشخصات زبان VSIDL را ببینید.
  • تکمیل خودکار و مستندات: می‌توانید Ctrl+Space را برای پیشنهادهای کلیدواژه، پیام، سرویس، موضوع، و کانال فشار دهید، و Ctrl+Q را برای مشاهده نظرات مستندات فشار دهید.
  • پیمایش و قالب‌بندی: می‌توانید Ctrl+B را فشار دهید تا به تعاریف .vsidl یا .proto بروید، Alt+Shift+F7 را فشار دهید تا مراجع را پیدا کنید، Ctrl+F12 را فشار دهید تا ساختار فایل را مشاهده کنید، و Ctrl+Alt+L را فشار دهید تا فایل را قالب‌بندی کنید.

افزودن بافت خودروی نرم‌افزارمحور برای دستیارهای هوش مصنوعی

‫ASfP شامل هوش مصنوعی در «استودیو Android» و یک عامل داخلی با ابزارهای ساخت Soong و atest است. چون فایل‌های AGENTS.md در کنار کد منبع شما در کنترل نسخه قرار دارند، می‌توانید همان قوانین SDV را در سراسر عامل داخلی ASfP و عامل‌های کدنویسی مبتنی بر محفظه یا خط فرمان که AGENTS.md را می‌خوانند هم‌رسانی کنید. وقتی پیام‌واره‌ای را با فایلی که در ASfP باز است ارسال می‌کنید، نماینده فایل‌های AGENTS.md را از دایرکتوری آن فایل و دایرکتوری‌های والد آن بار می‌کند (مگر اینکه فایل GEMINI.md در همان دایرکتوری اولویت داشته باشد)، و می‌توانید فایل‌های فعال را در کشوی بافت پانل گپ در بخش فایل‌های AGENTS.md تأیید کنید. برای اطلاعات بیشتر، به آشنایی با «استودیو Android» برای پلاتفرم و سفارشی‌سازی عامل بااستفاده از فایل‌های AGENTS.md مراجعه کنید.

الگوهای زیر نقاط شروعی برای گردش‌های کار در ایجاد پروژه SDV ارائه می‌دهند.

دسته‌های سرویس SDV

این فایل AGENTS.md را در فهرست راهنمای دسته موجود در .asfp-project که پوشه‌های catalog/، services/، و apex/ شما را دربرمی‌گیرد قرار دهید. برای اطلاعات بیشتر، به تولید میان‌افزار، ساخت و استقرار بسته‌های سرویس، نوشتن فایل نگاشت 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 Gateway در SDV IVI

این فایل AGENTS.md را در فهرست راهنمای ماژول مشتری IVI یا system/software_defined_vehicle/sdv_gateway/ قرار دهید. برای اطلاعات بیشتر، استفاده از «دروازه خودروی نرم‌افزارمحور» در سیستم سرگرمی-اطلاعاتی درون‌خودرو را ببینید.

# 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