JerryScript 项目从1.0到2.0版本的迁移指南

JerryScript 项目从1.0到2.0版本的迁移指南

jerryscript Ultra-lightweight JavaScript engine for the Internet of Things. 项目地址: https://gitcode.com/gh_mirrors/je/jerryscript

JerryScript 是一个轻量级的 JavaScript 引擎，专为资源受限的设备设计。随着项目从1.0版本升级到2.0版本，API 发生了一些重大变化。本文将详细介绍这些变更，并提供迁移建议，帮助开发者顺利过渡到新版本。

一、主要变更概览

1.1 头文件变更

• 移除的头文件：jerry-internal.h
• 重命名的头文件：
  • jerry-api.h → jerryscript.h
  • jerry-port.h → jerryscript-port.h

1.2 类型变更

• 移除了 jerry_char_ptr_t 类型，改用 jerry_char_t *
• 将 jerry_object_free_callback_t 替换为 jerry_object_native_free_callback_t

1.3 配置宏变更

所有配置宏前缀从 CONFIG_ 改为 JERRY_，例如：

• CONFIG_MEM_STACK_LIMIT → JERRY_MEM_STACK_LIMIT

二、错误处理API变更

2.1 错误标志处理

2.0版本对错误处理进行了重构，引入了更清晰的API：

| 1.0版本函数 | 2.0版本替代函数 | |------------|----------------| | jerry_value_set_abort_flag | jerry_create_abort_from_value | | jerry_value_has_abort_flag | jerry_value_is_abort | | jerry_value_set_error_flag | jerry_create_error_from_value | | jerry_value_has_error_flag | jerry_value_is_error | | jerry_value_clear_error_flag | 合并到 jerry_get_value_from_error | | jerry_get_value_without_error_flag | 合并到 jerry_get_value_from_error |

迁移示例：

// 1.0版本
jerry_value_set_error_flag(&value);

// 2.0版本
jerry_value_t error = jerry_create_error_from_value(value, true);

2.2 错误值提取

新版本合并了两个功能相似的函数，提供了更统一的接口：

// 2.0版本推荐写法
jerry_value_t real_value = jerry_get_value_from_error(error, true);

三、快照生成API变更

3.1 全局快照生成

jerry_parse_and_save_snapshot 被 jerry_generate_snapshot 取代，新API提供了更好的错误处理：

jerry_value_t generate_result = jerry_generate_snapshot(
    NULL, 0, 
    code_to_snapshot_p, 
    strlen((const char *)code_to_snapshot_p),
    snapshot_buffer, 
    buffer_size);

if (jerry_value_is_error(generate_result)) {
    // 错误处理
} else {
    size_t snapshot_size = (size_t)jerry_get_number_value(generate_result);
}

3.2 函数快照生成

类似地，函数快照生成API也进行了更新：

jerry_value_t generate_result = jerry_generate_function_snapshot(
    NULL, 0,
    src_p, strlen((const char *)src_p),
    args_p, strlen((const char *)args_p),
    0, func_snapshot_buffer, buffer_size);

四、垃圾回收改进

4.1 垃圾回收压力控制

jerry_gc 函数现在支持指定回收压力级别：

// 低压力模式
jerry_gc(JERRY_GC_PRESSURE_LOW);

// 高压力模式
jerry_gc(JERRY_GC_PRESSURE_HIGH);

五、本地指针管理改进

2.0版本改进了本地指针管理，支持多个本地信息注册：

5.1 类型定义变更

// 2.0版本使用jerry_object_native_info_t
static const jerry_object_native_info_t my_info_type_info = {
    .free_cb = handler_construct_freecb
};

5.2 API使用示例

// 设置本地指针
jerry_set_object_native_pointer(
    this_val, 
    info, 
    &my_info_type_info);

// 获取本地指针
void *ptr = NULL;
bool has_p = jerry_get_object_native_pointer(
    this_val, 
    &ptr, 
    &my_info_type_info);

六、时区处理改进

时区处理API进行了重大改进，提供了更精确的时区偏移计算：

// 2.0版本时区处理
double jerry_port_get_local_time_zone_adjustment(
    double unix_ms, 
    bool is_utc) {
    // 实现细节...
}

七、总结

JerryScript 2.0版本的API变更主要集中在以下几个方面：

1. 错误处理更加清晰和一致
2. 快照生成API提供了更好的错误反馈
3. 垃圾回收支持压力控制
4. 本地指针管理更加灵活
5. 时区处理更加精确

迁移时需要注意：

• 仔细检查所有错误处理相关的代码
• 更新快照生成逻辑
• 考虑垃圾回收压力级别的选择
• 重构本地指针管理代码

通过遵循本指南，开发者可以顺利将项目从JerryScript 1.0迁移到2.0版本，并利用新版本提供的改进功能。

jerryscript Ultra-lightweight JavaScript engine for the Internet of Things. 项目地址: https://gitcode.com/gh_mirrors/je/jerryscript