JerryScript 1.0 到 2.0 版本迁移指南

JerryScript 1.0 到 2.0 版本迁移指南

jerryscript 项目地址: https://gitcode.com/gh_mirrors/jer/jerryscript

本文详细介绍了 JerryScript 从 1.0 版本升级到 2.0 版本时需要注意的主要变更点，并提供了具体的代码迁移示例。JerryScript 是一个轻量级的 JavaScript 引擎，专为资源受限的嵌入式设备设计。

一、主要变更概览

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_DATA_LIMIT_MINUS_HEAP_SIZE → JERRY_MEM_DATA_LIMIT_MINUS_HEAP_SIZE

二、错误处理机制变更

2.0 版本对错误处理机制进行了重大重构，引入了更清晰的 API 设计。

2.1 错误标志相关函数

| 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 | 仅函数名变更 |

迁移示例：

// 1.0 版本
jerry_value_set_error_flag(&value);

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

2.2 错误值提取

jerry_value_clear_error_flag 和 jerry_get_value_without_error_flag 合并为 jerry_get_value_from_error。

迁移示例：

// 2.0 版本
jerry_value_t real_value = jerry_get_value_from_error(error, true);

三、原生指针处理变更

2.0 版本改进了原生指针的管理方式，支持为单个对象注册多个原生信息。

3.1 主要变更点

• 使用 jerry_object_native_info_t 结构体替代回调函数
• 新增原生信息类型标识
• 支持多个原生指针关联

迁移示例：

// 2.0 版本原生指针设置
static const jerry_object_native_info_t my_info_type_info = {
    .free_cb = handler_construct_freecb
};

jerry_set_object_native_pointer(
    this_val, 
    info, 
    &my_info_type_info
);

四、快照生成 API 变更

快照生成相关 API 进行了重构，提供了更好的错误处理机制。

4.1 主要变更

• jerry_parse_and_save_snapshot → jerry_generate_snapshot
• jerry_parse_and_save_function_snapshot → jerry_generate_function_snapshot
• 新增返回值错误检查机制

迁移示例：

// 2.0 版本快照生成
jerry_value_t generate_result = jerry_generate_snapshot(
    NULL, 0, 
    code_to_snapshot_p, 
    strlen(code_str),
    snapshot_buffer, 
    buffer_size
);

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

五、其他重要变更

5.1 垃圾回收

jerry_gc 函数新增压力模式参数：

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

5.2 时区处理

时区处理接口完全重构，新的端口 API 函数：

double jerry_port_get_local_time_zone_adjustment(
    double unix_ms, 
    bool is_utc
);

5.3 魔术字符串注册

jerry_char_ptr_t 类型替换为 jerry_char_t*：

static const jerry_char_t *magic_string_items[] = {
    (const jerry_char_t *)"string1",
    (const jerry_char_t *)"string2"
};

六、总结

JerryScript 2.0 版本通过重构错误处理机制、改进原生指针管理、增强快照生成功能等，提供了更强大、更灵活的 API 接口。迁移时需要注意：

1. 所有错误处理相关 API 都已重构，需要按照新范式重写
2. 原生指针管理支持多信息关联，功能更强大
3. 快照生成提供更好的错误反馈机制
4. 配置宏前缀统一变更为 JERRY_

建议开发者在迁移前充分测试修改后的代码，特别是错误处理相关逻辑，确保系统行为符合预期。

jerryscript 项目地址: https://gitcode.com/gh_mirrors/jer/jerryscript