# oh_ability_lite_debug

**Repository Path**: baiduowang/oh_ability_lite_debug

## Basic Information

- **Project Name**: oh_ability_lite_debug
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-19
- **Last Updated**: 2025-11-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于 CLion 的 OpenHarmony `ability_ability_lite` 完整调试工程（Windows 版）

提供 **可直接导入 CLion 并编译调试** 的完整工程，包含 `ability_ability_lite` 核心源码、Windows 模拟层（替代 LiteOS 内核）、JerryScript 模拟依赖及测试入口，解决所有跨平台适配问题（如 `jerry_length_t` 未定义、LiteOS 接口缺失等）。

## 一、工程结构
先在本地创建如下目录（建议路径：`D:\oh_ability_lite_debug`），后续所有文件按此结构放置：
```
oh_ability_lite_debug/
├─ main.c                    # 1. 调试入口层
├─ app_list.txt              # 调试入口层：应用配置
├─ CMakeLists.txt            # 工程编译配置
├─ ability_ability_lite/     # 2. 核心业务层
│  ├─ lite_ams/
│  │  ├─ lite_ams.c
│  │  └─ lite_ams.h
│  ├─ slite_ability_loader/
│  │  ├─ slite_ability_loader.c
│  │  └─ slite_ability_loader.h
│  └─ js_ability_thread/
│     ├─ js_ability_thread.cpp
│     └─ js_ability_thread.h
├─ kernel_liteos_m/          # 3. kernel_liteos_m 适配层
│  └─ include/
│     ├─ los_typedef.h
│     └─ los_task.h
├─ sim_adapter/              # 4. 模拟适配层
│  └─ los_task_adapter.c
└─ 3rd_party/                # 5. 基础依赖层
   └─ jerryscript/
      ├─ include/
      │  └─ jerryscript.h    # 简化版JS引擎头文件
      ├─ lib/
      │  └─ libjerry.a       # JerryScript 模拟静态库（MinGW 版）
      └─ src/
         └─ jerry_impl.c     # 上述实现文件
```

参考鸿蒙开源仓代码： https://gitee.com/openharmony/ability_ability_lite

## 二、工程架构总览
本项目采用**五层分层架构**，在 Windows 系统的 CLion 中构建 OpenHarmony ability_ability_lite 的调试环境。核心设计思路是通过“底层模拟真实环境、上层保留核心逻辑”，实现跨平台适配与高效调试，各层自上而下依赖，职责边界清晰，整体架构如下：

```
┌─────────────────────────────────────────────────────────────┐
│ 1. 调试入口层（第五层）                                      │
│    main.c + CMakeLists.txt + app_list.txt                   │
├─────────────────────────────────────────────────────────────┤
│ 2. 核心业务层（第四层）                                      │
│    lite_ams + slite_ability_loader + js_ability_thread      │
├─────────────────────────────────────────────────────────────┤
│ 3. kernel_liteos_m 适配层（第三层）                          │
│    抽象原生 LiteOS-M 接口（task/sem/mutex），无具体实现       │
├─────────────────────────────────────────────────────────────┤
│ 4. 模拟适配层（第二层）                                      │
│    Windows 环境下的 LiteOS-M 接口实现（los_task_adapter等）  │
├─────────────────────────────────────────────────────────────┤
│ 5. 基础依赖层（第一层）                                      │
│    jerryscript（静态库+头文件） + Windows API 依赖           │
└─────────────────────────────────────────────────────────────┘
```

### 架构核心逻辑（后序需要更新）
1. 基础模拟层与第三方依赖层共同构成“模拟运行环境”，替代真实设备的 LiteOS 内核与 JerryScript 引擎，解决 Windows 与 OpenHarmony 底层环境的兼容性问题。
2. 核心业务层直接复用 OpenHarmony ability_ability_lite 源码，不修改核心逻辑，仅通过“接口映射”调用模拟层能力，确保调试结果与真实设备一致。
3. 调试入口层为 CLion 提供编译配置与测试触发点，支持一键导入、编译、调试，降低开发门槛。


## 三、分层架构详情与组件说明
按从底层到上层的顺序，详细说明各层的核心组件、功能及关键文件作用。

### 1. 基础模拟层（第一层）：模拟 LiteOS 内核环境
#### 层定位
替代真实设备中的 LiteOS 内核，提供核心内核接口的 Windows 兼容实现，让上层核心源码无需修改即可调用“内核级接口”。

#### 核心组件与文件说明
| 文件名 | 所在路径 | 核心功能 |
|--------|----------|----------|
| liteos_win_sim.c | sim_layer/ | 1. 实现 LiteOS 核心接口的模拟逻辑，如线程创建（SIM_LOS_ThreadCreate）、信号量操作（SIM_sem_wait）、互斥锁（SIM_mutex_lock）；<br>2. 适配 Windows 线程模型（如使用 CreateThread 实现线程创建），确保线程调度逻辑与 LiteOS 行为一致。 |
| liteos_win_sim.h | sim_layer/ | 1. 声明模拟的 LiteOS 接口，与 LiteOS 原生头文件（los_thread.h、los_sem.h 等）接口名对齐（前缀加 SIM_ 区分）；<br>2. 定义 Windows 环境下的适配数据类型（如用 HANDLE 替代 LiteOS 的线程 ID 类型）。 |

#### 依赖关系
- 无下层依赖，直接调用 Windows API（如 CreateThread、WaitForSingleObject）。
- 为上层核心业务层（如 js_ability_thread）提供线程、同步相关接口支持。


### 2. 第三方依赖层（第二层）：模拟 JerryScript 引擎
#### 层定位
替代 OpenHarmony 中的 JerryScript 引擎（用于解析执行 JS 类型 Ability），提供引擎核心接口的模拟实现，解决跨平台编译时“依赖缺失”问题（如 jerry_length_t 未定义）。

#### 核心组件与文件说明
| 文件名 | 所在路径 | 核心功能 |
|--------|----------|----------|
| jerryscript.h | 3rd_party/jerryscript/include/jerryscript/ | 1. 声明 JerryScript 核心接口，如 JS 上下文创建（jerryx_context_create）、JS 值转换（jerry_value_to_string）；<br>2. 定义模拟的数据类型（如 jerry_length_t 映射为 Windows 下的 size_t），避免编译报错。 |
| libjerry.a | 3rd_party/jerryscript/lib/ | 1. JerryScript 模拟接口的静态库（MinGW 编译），包含 jerryscript.h 中声明接口的实现逻辑；<br>2. 为上层 JS 能力模块（js_ability_thread）提供 JS 引擎调用支持，无需在 Windows 上编译完整 JerryScript 源码。 |

#### 依赖关系
- 无下层依赖，静态库直接编译为 Windows 兼容格式。
- 为上层核心业务层的 js_ability_thread 模块提供 JS 解析、执行相关接口支持。


### 3. 核心业务层（第三层）：Ability 框架核心逻辑
#### 层定位
OpenHarmony ability_ability_lite 的核心源码，承载 Ability 的管理、加载、线程调度等核心业务逻辑，是调试的主要对象。

#### 核心组件与文件说明
##### （1）lite_ams：Ability 管理服务
| 文件名 | 所在路径 | 核心功能 |
|--------|----------|----------|
| lite_ams.c | ability/ability/lite/lite_ams/ | 1. 实现 Ability 的生命周期管理，包括启动（LiteAmsStartAbility）、销毁（LiteAmsTerminateAbility）；<br>2. 维护 Ability 实例列表，记录当前运行的 Ability 状态（如前台/后台）；<br>3. 协调 slite_ability_loader 完成 Ability 的加载与初始化。 |
| lite_ams.h | ability/ability/lite/lite_ams/ | 1. 声明 AMS 服务的核心接口（如 LiteAmsStartAbility）；<br>2. 定义 Ability 状态枚举（如 LITE_ABILITY_STATE_FOREGROUND）、Ability 信息结构体（如 LiteAbilityInfo）。 |

##### （2）slite_ability_loader：Ability 加载器
| 文件名 | 所在路径 | 核心功能 |
|--------|----------|----------|
| slite_ability_loader.c | ability/ability/lite/slite_ability_loader/ | 1. 负责从配置（如 app_list.txt）中读取 Ability 信息，加载 Ability 实例；<br>2. 调用 JS 引擎接口（如 jerryx_context_create）初始化 JS 类型 Ability；<br>3. 为 AMS 提供 Ability 实例的创建与销毁支持。 |
| slite_ability_loader.h | ability/ability/lite/slite_ability_loader/ | 1. 声明 Ability 加载接口（如 SliteAbilityLoaderLoad）；<br>2. 定义 Ability 加载配置结构体（如 SliteAbilityLoadInfo）。 |

##### （3）js_ability_thread：JS Ability 线程管理
| 文件名 | 所在路径 | 核心功能 |
|--------|----------|----------|
| js_ability_thread.cpp | ability/ability/lite/js_ability_thread/ | 1. 为 JS 类型 Ability 创建独立线程，避免阻塞主线程；<br>2. 调用基础模拟层的线程接口（SIM_LOS_ThreadCreate）创建线程，调度 JS 代码执行；<br>3. 处理 JS 线程的同步与销毁逻辑，确保线程安全。 |
| js_ability_thread.h | ability/ability/lite/js_ability_thread/ | 1. 声明 JS 线程管理接口（如 JsAbilityThreadCreate）；<br>2. 定义 JS 线程上下文结构体（如 JsAbilityThreadCtx），存储线程 ID、JS 上下文等信息。 |

#### 依赖关系
- 依赖基础模拟层：调用 sim_layer 提供的线程、同步接口（如 SIM_LOS_ThreadCreate）。
- 依赖第三方依赖层：js_ability_thread 调用 jerryscript 提供的 JS 引擎接口。
- 为上层调试入口层提供 Ability 框架的核心调用入口（如 main.c 调用 LiteAmsStartAbility）。


### 4. 调试入口层（第四层）：CLion 编译与测试入口
#### 层定位
为 CLion 提供工程配置、测试触发点与应用配置，支持一键导入编译、模拟设备启动流程，是调试的“入口与控制层”。

#### 核心组件与文件说明
| 文件名 | 所在路径 | 核心功能 |
|--------|----------|----------|
| main.c | 根目录 | 1. 模拟设备开机流程：初始化基础模拟层、第三方依赖层；<br>2. 模拟 Launcher 行为：调用 AMS 接口（LiteAmsStartAbility）触发 Ability 启动；<br>3. 提供调试断点入口，可在 Ability 启动、加载等关键流程处设置断点。 |
| CMakeLists.txt | 根目录 | 1. 定义 CLion 编译规则：指定源文件（如 lite_ams.c、js_ability_thread.cpp）、依赖库（如 libjerry.a）；<br>2. 配置编译选项（如 -O0 -g3 开启调试符号），确保断点能命中核心代码；<br>3. 支持一键编译生成可执行文件，直接在 CLion 中启动调试。 |
| app_list.txt | 根目录 | 1. 替代真实设备中 Flash 存储的 app_list.cfg，配置待调试的应用与 Ability 信息；<br>2. 内容格式示例：`app_name=demo_ability;ability_name=DemoAbility`，供 slite_ability_loader 读取加载。 |

#### 依赖关系
- 依赖核心业务层：main.c 直接调用 lite_ams、slite_ability_loader 的核心接口。
- 依赖第三方依赖层与基础模拟层：CMakeLists.txt 配置 libjerry.a 与 sim_layer 源文件的编译依赖。


## 四、核心业务流程示例
以“JS 类型 Ability 启动”为例，说明各层协同工作流程，帮助理解架构逻辑：
1. **调试入口层触发**：main.c 调用 `LiteAmsStartAbility`（AMS 接口），传入待启动的 Ability 名称（从 app_list.txt 读取）。
2. **核心业务层调度**：
   - lite_ams.c 接收请求，调用 `SliteAbilityLoaderLoad`（加载器接口），请求加载 Ability 实例。
   - slite_ability_loader.c 读取 app_list.txt 配置，调用 JerryScript 接口（`jerryx_context_create`）初始化 JS 上下文，创建 Ability 实例。
3. **依赖层提供支持**：
   - 第三方依赖层：libjerry.a 执行 JS 上下文初始化逻辑，返回有效上下文句柄。
   - 基础模拟层：js_ability_thread.cpp 调用 `SIM_LOS_ThreadCreate`，创建独立线程用于执行 JS 代码。
4. **流程完成**：JS 线程启动，执行 Ability 的 onCreate、onStart 生命周期方法，调试者可在 CLion 中查看断点、跟踪流程。


## 五、JS Ability 启动流程时序图（含各层调用关系）
下面时序图基于项目四层架构，详细拆解“JS 类型 Ability 启动”的完整调用链路，标注了各层组件的交互顺序与核心接口，可直观理解从调试入口触发到 JS 代码执行的全流程。

```mermaid
sequenceDiagram
    participant 调试入口层（main.c）
    participant 核心业务层-AMS（lite_ams.c）
    participant 核心业务层-加载器（slite_ability_loader.c）
    participant 核心业务层-JS线程（js_ability_thread.cpp）
    participant 第三方依赖层（jerryscript）
    participant 基础模拟层（liteos_win_sim.c）
    
    %% 1. 调试入口层触发启动请求
    调试入口层（main.c）->>核心业务层-AMS（lite_ams.c）: 调用 LiteAmsStartAbility()
     Note over 调试入口层（main.c）: 从 app_list.txt 读取<br>待启动Ability名称
    
    %% 2. AMS 调度加载器加载Ability
    核心业务层-AMS（lite_ams.c）->>核心业务层-加载器（slite_ability_loader.c）: 调用 SliteAbilityLoaderLoad()
     Note over 核心业务层-AMS（lite_ams.c）: 检查Ability状态<br>协调加载流程
    
    %% 3. 加载器读取配置并初始化JS环境
    核心业务层-加载器（slite_ability_loader.c）->>核心业务层-加载器（slite_ability_loader.c）: 读取 app_list.txt 配置
    核心业务层-加载器（slite_ability_loader.c）->>第三方依赖层（jerryscript）: 调用 jerryx_context_create()
    第三方依赖层（jerryscript）-->>核心业务层-加载器（slite_ability_loader.c）: 返回 JS 上下文句柄
     Note over 第三方依赖层（jerryscript）: 模拟JS引擎初始化<br>创建独立上下文
    
    %% 4. 加载器请求创建JS线程
    核心业务层-加载器（slite_ability_loader.c）->>核心业务层-JS线程（js_ability_thread.cpp）: 调用 JsAbilityThreadCreate()
     Note over 核心业务层-加载器（slite_ability_loader.c）: 传入JS上下文句柄<br>请求独立线程执行JS
    
    %% 5. JS线程模块调用模拟层创建线程
    核心业务层-JS线程（js_ability_thread.cpp）->>基础模拟层（liteos_win_sim.c）: 调用 SIM_LOS_ThreadCreate()
    基础模拟层（liteos_win_sim.c）->>基础模拟层（liteos_win_sim.c）: 调用 Windows API CreateThread()
    基础模拟层（liteos_win_sim.c）-->>核心业务层-JS线程（js_ability_thread.cpp）: 返回模拟线程ID
     Note over 基础模拟层（liteos_win_sim.c）: 适配Windows线程模型<br>封装LiteOS接口格式
    
    %% 6. JS线程执行Ability生命周期
    核心业务层-JS线程（js_ability_thread.cpp）->>第三方依赖层（jerryscript）: 调用 jerry_eval() 执行JS代码
    第三方依赖层（jerryscript）-->>核心业务层-JS线程（js_ability_thread.cpp）: 返回JS代码执行结果
    核心业务层-JS线程（js_ability_thread.cpp）->>核心业务层-AMS（lite_ams.c）: 回调 OnAbilityStarted() 通知启动完成
     Note over 核心业务层-JS线程（js_ability_thread.cpp）: 执行Ability的onCreate/onStart<br>生命周期方法
```

### 时序图核心说明
1. **分层调用逻辑**：流程严格遵循“上层调用下层”规则，调试入口层仅调用核心业务层，核心业务层按需调用依赖层，无跨层直接调用（如 main.c 不直接调用 jerryscript），确保架构分层清晰。
2. **依赖层价值体现**：第三方依赖层（jerryscript）解决 JS 引擎适配问题，基础模拟层（liteos_win_sim）解决内核接口适配问题，二者共同支撑核心业务层在 Windows 环境运行。
3. **调试关键节点**：时序图中标记的接口（如 `LiteAmsStartAbility`、`SIM_LOS_ThreadCreate`、`jerry_eval`）均为调试高频断点位置，可在 CLion 中针对这些接口设置断点，跟踪 Ability 启动全流程。

```
sequenceDiagram
    participant 调试入口层（main.c）
    participant 核心业务层-AMS（lite_ams.c）
    participant 核心业务层-加载器（slite_ability_loader.c）
    participant 核心业务层-JS线程（js_ability_thread.c）
    participant 第三方依赖层（jerryscript: libjerry.a）
    participant 基础模拟层（liteos_win_sim.c）
    
    %% 1. 工程启动：初始化基础环境与JS引擎
    调试入口层（main.c）->>基础模拟层（liteos_win_sim.c）: 调用 SIM_LiteOS_Init()
    基础模拟层（liteos_win_sim.c）-->>调试入口层（main.c）: 返回LOS_OK
    调试入口层（main.c）->>核心业务层-JS线程（js_ability_thread.c）: 调用 JsAbilityEngineInit()
    核心业务层-JS线程（js_ability_thread.c）->>第三方依赖层（jerryscript）: 调用 jerry_init(JERRY_INIT_EMPTY)
    第三方依赖层（jerryscript）-->>核心业务层-JS线程（js_ability_thread.c）: 返回引擎初始化结果
    Note over 核心业务层-JS线程（js_ability_thread.c）: 源码中通过jerry_init初始化JS引擎，为后续执行做准备
    
    %% 2. 触发Ability启动：AMS调度加载
    调试入口层（main.c）->>核心业务层-AMS（lite_ams.c）: 调用 LiteAmsStartAbility("DemoAbility")
    核心业务层-AMS（lite_ams.c）->>核心业务层-加载器（slite_ability_loader.c）: 调用 SliteAbilityLoaderLoad()
    核心业务层-加载器（slite_ability_loader.c）-->>核心业务层-AMS（lite_ams.c）: 返回SliteAbility实例
    核心业务层-AMS（lite_ams.c）->>核心业务层-JS线程（js_ability_thread.c）: 调用 JsAbilityThreadCreate(实例)
    
    %% 3. 创建JS线程：初始化同步资源
    核心业务层-JS线程（js_ability_thread.c）->>基础模拟层（liteos_win_sim.c）: 调用 SIM_sem_init()
    基础模拟层（liteos_win_sim.c）-->>核心业务层-JS线程（js_ability_thread.c）: 返回信号量初始化结果
    核心业务层-JS线程（js_ability_thread.c）->>基础模拟层（liteos_win_sim.c）: 调用 SIM_LOS_ThreadCreate(JsAbilityThreadMain)
    基础模拟层（liteos_win_sim.c）-->>核心业务层-JS线程（js_ability_thread.c）: 返回模拟线程ID
    
    %% 4. 线程执行：注册JS回调+执行代码（源码核心逻辑）
    核心业务层-JS线程（js_ability_thread.c）->>核心业务层-JS线程（js_ability_thread.c）: 执行JsAbilityThreadMain()
    核心业务层-JS线程（js_ability_thread.c）->>第三方依赖层（jerryscript）: 调用 jerryx_handler_register()
    Note over 核心业务层-JS线程（js_ability_thread.c）: 源码中注册JS回调（如Ability生命周期回调），关联C层逻辑
    第三方依赖层（jerryscript）-->>核心业务层-JS线程（js_ability_thread.c）: 返回回调注册结果
    
    核心业务层-JS线程（js_ability_thread.c）->>核心业务层-JS线程（js_ability_thread.c）: 读取JS文件（如main.js）
    核心业务层-JS线程（js_ability_thread.c）->>第三方依赖层（jerryscript）: 调用 jerry_eval(js_code, len, JERRY_PARSE_NO_OPTS)
    Note over 核心业务层-JS线程（js_ability_thread.c）: 源码中通过jerry_eval执行JS代码，是JS能力核心执行步骤
    第三方依赖层（jerryscript）-->>核心业务层-JS线程（js_ability_thread.c）: 返回js_value_t执行结果
    
    %% 5. 执行结果处理：通知AMS启动完成
    核心业务层-JS线程（js_ability_thread.c）->>核心业务层-AMS（lite_ams.c）: 调用 OnAbilityStarted()
    核心业务层-AMS（lite_ams.c）-->>调试入口层（main.c）: 返回Ability启动成功
```