JerryScript 迁移指南:从 1.0 到 2.0/3.0 的 API 升级实战
JerryScript 迁移指南:从 1.0 到 2.0/3.0 的 API 升级实战
本篇指南以 JerryScript 官方迁移文档(docs/16.MIGRATION-GUIDE.md)为主体,完整梳理从 1.0 到 2.0 版本间的 API 变更,包括被删除/重命名的头文件、类型、函数与配置宏,并为每一项变更提供 Before(1.0 写法) 与 After(2.0 写法) 的可直接编译对照代码。读者完成后将能够:识别并修复旧代码中的全部破坏性 API 调用、正确使用新的错误处理与原生指针(Native Pointer)机制、迁移快照生成与 GC 调用方式,并了解 2.x 到 3.x 的 API 大规模重命名背景。所有新 API 的完整签名可对照 docs/02.API-REFERENCE.md 查阅。
1. 迁移背景与总体思路
JerryScript 1.0 与 2.0 之间的主要变化集中在 API 函数的移除与签名调整 上。开发团队在设计 2.0 时遵循了一个重要原则:尽量最小化 API 函数与类型的变动。因此,绝大多数变更都是"一对一"的替换关系,每个被移除或修改的 API 方法都可以在本指南中找到对应的 before/after 代码示例,迁移成本被控制在可接受的范围内。
迁移工作的总思路可以概括为三步:
- 对照速查表:先使用第 2 节的"短列表"快速定位项目中用到了哪些已删除/已重命名的符号;
- 逐项替换:对每个符号按第 3~6 节的 before/after 示例进行替换;
- 处理新 API 与 Port API:根据需要补充实现新版本引入的功能(如 Promise、TypedArray、多原生指针),并更新移植层(Port API)的时区函数。
2. 删除/重命名清单速查
2.1 头文件变更
被删除的头文件:
jerry-internal.h—— 该内部头文件在 2.0 中不再对外暴露,相关内部实现被收纳进核心源码目录。
被重命名的头文件:
| 旧名称(1.0) | 新名称(2.0) |
|---|---|
jerry-api.h |
jerryscript.h |
jerry-port.h |
jerryscript-port.h |
在 2.0 中,主头文件为 jerry-core/include/jerryscript.h,它聚合了 jerryscript-core.h(核心 API)、jerryscript-snapshot.h(快照 API)等子头文件;移植层头文件为 jerryscript-port.h。
2.2 删除的 API 类型
| 旧类型(1.0) | 替换方案(2.0) |
|---|---|
jerry_char_ptr_t |
直接使用 jerry_char_t * |
jerry_object_free_callback_t |
jerry_object_native_info_t(结构化原生信息描述) |
jerry_char_t 在 jerryscript-types.h 中定义为 uint8_t,其指针形式 jerry_char_t * 即取代了 1.0 中冗余的 jerry_char_ptr_t 别名。
2.3 删除的 API 方法(及替换目标)
| 被删除方法(1.0) | 替换方法(2.0) |
|---|---|
jerry_get_memory_limits |
移除,内存信息获取方式改为通过上下文/配置管理 |
jerry_get_object_native_handle |
jerry_get_object_native_pointer |
jerry_set_object_native_handle |
jerry_set_object_native_pointer |
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 |
jerry_parse_and_save_snapshot |
jerry_generate_snapshot |
jerry_parse_and_save_function_snapshot |
jerry_generate_function_snapshot |
2.4 删除的配置宏
以下配置宏在 2.0 中被移除:
CONFIG_MEM_DATA_LIMIT_MINUS_HEAP_SIZECONFIG_MEM_STACK_LIMITCONFIG_VM_STACK_FRAME_INLINED_VALUES_NUMBERCONFIG_ECMA_GLOBAL_ENVIRONMENT_DECLARATIVE
同时,所有 CONFIG_.. 系列宏统一改名为 JERRY_ 前缀格式。当前版本的完整可配置宏清单可以在 jerry-core/config.h 中查看,例如内存上限 JERRY_MEM_HEAP_LIMIT、特性开关 JERRY_ESNEXT、JERRY_DEBUGGER 等。在 3.0 中这些宏进一步演进为 JERRY_BUILTIN_*、JERRY_GC_* 等细分命名。迁移时,凡是代码中出现的 CONFIG_ 前缀宏都需要改为对应的 JERRY_ 前缀形式。
3. 错误处理函数的迁移(重点)
错误处理是 1.0 → 2.0 中 最重要的 API 变更区域。1.0 时代通过"修改标志位"的方式在 jerry_value_t 上就地打上/清除错误与 abort 标记;2.0 改为显式构造错误/abort 值,返回值所有权语义更清晰。
3.1 jerry_value_set_abort_flag → jerry_create_abort_from_value
新函数 jerry_create_abort_from_value 的第二个参数(bool take_ownership)控制调用后第一个参数 value 是否仍然可用:
- 传
true:调用后原value的所有权转移给新的 abort 值,原变量不得再使用,只需释放 abort; - 传
false:调用后abort与value都可用,两者都需要单独释放。
Before(1.0):
{
jerry_value_t value;
// create or acquire value
// ...
jerry_value_set_abort_flag (&value);
jerry_release_value (value);
}
After(2.0,转移所有权):
{
jerry_value_t value;
// create or acquire value
// ...
jerry_value_t abort = jerry_create_abort_from_value (value, true);
// using the 'value' variable after release is invalid
jerry_release_value (abort);
}
After(2.0,保留原值):
{
jerry_value_t value;
... // create or acquire value
jerry_value_t abort = jerry_create_abort_from_value (value, false);
// both 'abort' and 'value' can be used and must be released when they are no longer needed
jerry_release_value (abort);
jerry_release_value (value);
}
3.2 jerry_value_has_abort_flag → jerry_value_is_abort
仅改名为 jerry_value_is_abort,参数与返回值语义不变。该函数在 jerryscript-core.h 中声明为 bool jerry_value_is_abort (const jerry_value_t value);。
Before:
{
jerry_value_t value;
// create or acquire value
// ...
if (jerry_value_has_abort_flag (value))
{
// ...
}
jerry_release_value (value);
}
After:
{
jerry_value_t value;
// create or acquire value
// ...
if (jerry_value_is_abort (value))
{
// ...
}
jerry_release_value (value);
}
3.3 jerry_value_set_error_flag → jerry_create_error_from_value
替换逻辑与 jerry_create_abort_from_value 完全对称,第二个参数同样控制 value 的所有权转移。文档中该函数参考 API Reference。
Before:
{
jerry_value_t value;
// create or acquire value
// ...
jerry_value_set_error_flag (&value);
jerry_release_value (value);
}
After(转移所有权):
{
jerry_value_t value;
// create or acquire value
// ...
jerry_value_t error = jerry_create_error_from_value (value, true);
// using the 'value' variable after release is invalid
jerry_release_value (error);
}
After(保留原值):
{
jerry_value_t value;
// create or acquire value
// ...
jerry_value_t error = jerry_create_error_from_value (value, false);
// both 'error' and 'value' can be used and must be released when they are no longer needed
jerry_release_value (error);
jerry_release_value (value);
}
3.4 jerry_value_has_error_flag → jerry_value_is_error
同名替换,声明见 jerryscript-core.h:bool jerry_value_is_error (const jerry_value_t value);。
Before:
{
jerry_value_t value;
// create or acquire value
// ...
if (jerry_value_has_error_flag (value))
{
// ...
}
jerry_release_value (value);
}
After:
{
jerry_value_t value;
// create or acquire value
// ...
if (jerry_value_is_error (value))
{
// ...
}
jerry_release_value (value);
}
3.5 jerry_value_clear_error_flag 与 jerry_get_value_without_error_flag → jerry_get_value_from_error
这两个 1.0 函数在 2.0 中被合并为单一的 jerry_get_value_from_error。注意其第二个参数:控制是否在取出真实值的同时释放传入的错误值。
Before:
{
jerry_value_t value;
// create or acquire value
// ...
jerry_value_set_error_flag (&value);
jerry_value_clear_error_flag (&value);
// or
jerry_value_t real_value = jerry_get_value_without_error_flag (value);
jerry_release_value (value);
jerry_release_value (real_value);
}
After:
{
jerry_value_t value;
// create or acquire value
// ...
jerry_value_t error = jerry_create_error_from_value (value, true);
jerry_value_t real_value = jerry_get_value_from_error (error, true);
jerry_release_value (real_value);
}
所有权小结:2.0 的错误处理 API 围绕
jerry_value_t的所有权转移设计了统一的二参数模式。迁移时最容易出错的地方是"第二个参数传错导致双重释放或内存泄漏",建议在替换时逐条核对:true表示调用方不再持有原值,false表示双方都需要释放。
4. 其他被修改的函数
4.1 jerry_register_magic_strings:类型从 jerry_char_ptr_t 改为 jerry_char_t *
该函数用于注册"魔法字符串"(magic strings,即在源码中高频出现、被静态化存储以节省内存的字符串常量)。变更点是第一个参数的基础类型由 jerry_char_ptr_t 改为 jerry_char_t *。当前仓库中的声明为 jerryscript-core.h:
void jerry_register_magic_strings (const jerry_char_t *const *ext_strings_p,
uint32_t count,
const jerry_length_t *lengths_p);
注意两个前提条件(两个版本通用):
- 数组必须是
static的,因为该函数不会复制字符串内容; - 字符串条目必须先按长度升序排序,再按字典序排序。
Before:
{
// must be static, because 'jerry_register_magic_strings' does not copy
// the items must be sorted by size at first, then lexicographically
static const jerry_char_ptr_t magic_string_items[] = {
(const jerry_char_ptr_t) "magicstring1",
(const jerry_char_ptr_t) "magicstring2",
(const jerry_char_ptr_t) "magicstring3"
};
uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t));
// must be static, because 'jerry_register_magic_strings' does not copy
static const jerry_length_t magic_string_lengths[] = { 12, 12, 12 };
jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
}
After:
{
// must be static, because 'jerry_register_magic_strings' does not copy
// the items must be sorted by size at first, then lexicographically
static const jerry_char_t *magic_string_items[] = {
(const jerry_char_t *) "magicstring1",
(const jerry_char_t *) "magicstring2",
(const jerry_char_t *) "magicstring3"
};
uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_t *));
// must be static, because 'jerry_register_magic_strings' does not copy
static const jerry_length_t magic_string_lengths[] = { 12, 12, 12 };
jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
}
4.2 jerry_parse_and_save_snapshot → jerry_generate_snapshot
快照(Snapshot)是 JerryScript 的核心特性之一:将源码预先编译为字节码缓冲,运行时直接加载,省去解析时间,非常适合物联网场景。2.0 的新函数 以返回值报告生成结果:若生成过程中出现问题(如语法错误)则返回错误对象;若成功则返回一个数字值,其数值即快照的字节数。底层实现在 jerry-snapshot.c 的 jerry_generate_snapshot 中,完整签名见 jerryscript-snapshot.h。
Before:
{
static uint32_t global_mode_snapshot_buffer[256];
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
size_t global_mode_snapshot_size =
jerry_parse_and_save_snapshot (code_to_snapshot_p,
strlen ((const char *) code_to_snapshot_p),
true,
false,
global_mode_snapshot_buffer,
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
// use "global_mode_snapshot_buffer"
}
After:
{
static uint32_t global_mode_snapshot_buffer[256];
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
jerry_value_t generate_result;
generate_result = jerry_generate_snapshot (NULL,
0,
code_to_snapshot_p,
strlen ((const char *) code_to_snapshot_p),
global_mode_snapshot_buffer,
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
if (jerry_value_is_error (generate_result))
{
// There was a problem during snapshot generation, for example there is a SyntaxError.
// Use the "generate_result" to check the error.
}
else
{
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
// use "global_mode_snapshot_buffer"
}
jerry_release_value (generate_result);
}
新签名在开头多出的两个参数(NULL, 0)分别对应"预编译的代码值"与"生成选项",直接传 NULL, 0 表示传入的是原始源码而非预编译结果。
4.3 jerry_parse_and_save_function_snapshot → jerry_generate_function_snapshot
函数快照用于将单个函数(含参数列表)预编译为快照。与上一个函数相同的错误返回约定:错误对象表示失败,数字值表示快照字节数。
Before:
{
static uint32_t func_snapshot_buffer[1024];
const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
size_t func_snapshot_size =
jerry_parse_and_save_function_snapshot (src_p,
strlen ((const char *) src_p),
args_p,
strlen ((const char *) args_p),
false,
func_snapshot_buffer,
sizeof (func_snapshot_buffer) / sizeof (uint32_t));
// check "function_snapshot_size" and use "func_snapshot_buffer"
}
After:
{
static uint32_t func_snapshot_buffer[1024];
const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
jerry_value_t generate_result;
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,
sizeof (func_snapshot_buffer) / sizeof (uint32_t));
if (jerry_value_is_error (generate_result))
{
// There was a problem during snapshot generation, for example there is a SyntaxError.
// Use the "generate_result" to check the error.
}
else
{
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
// use "func_snapshot_buffer"
}
jerry_release_value (generate_result)
}
4.4 jerry_gc:新增压力参数 jerry_gc_mode_t
jerry_gc 被修改为接收一个表示 GC 压力(pressure) 的参数。当前仓库中该接口已演进为 jerryscript-core.h 的 void jerry_heap_gc (jerry_gc_mode_t mode);,压力枚举 jerry_gc_mode_t 定义在 jerryscript-types.h:
typedef enum
{
JERRY_GC_PRESSURE_LOW, /**< free unused objects, but keep memory */
JERRY_GC_PRESSURE_HIGH /**< free as much memory as possible */
} jerry_gc_mode_t;
JERRY_GC_PRESSURE_LOW:仅释放不再使用的对象,尽量保留内存以备复用(适合常规时机调用);JERRY_GC_PRESSURE_HIGH:尽可能多地释放内存(适合内存告急时调用)。
Before:
{
jerry_gc ();
}
After:
{
jerry_gc (JERRY_GC_PRESSURE_LOW);
}
说明:
jerry_gc_mode_t的两个取值在 3.0 中被重命名为JERRY_GC_PRESSURE_LOW/HIGH的细分枚举(即上文 jerryscript-types.h 中展示的形式),2.0 时期对应为JERRY_GC_PRESSURE_NONE与JERRY_GC_PRESSURE_HIGH等命名,迁移时以当前头文件为准。
4.5 jerry_eval:第三个参数从 bool 改为 jerry_parse_opts_t
jerry_eval 的第三个参数由布尔值改为解析选项位掩码 jerry_parse_opts_t,以支持更丰富的解析行为(如 JERRY_PARSE_STRICT_MODE、JERRY_PARSE_MODULE 等)。当前声明为 jerryscript-core.h:
jerry_value_t jerry_eval (const jerry_char_t *source_p, size_t source_size, uint32_t flags);
其中 JERRY_PARSE_NO_OPTS = 0(无任何选项)定义在 jerryscript-types.h。
Before:
const jerry_char_t *str_to_eval = (const jerry_char_t *) "1 + 1";
jerry_value_t ret_val = jerry_eval (str_to_eval,
strlen ((const char *) str_to_eval),
false);
After:
const jerry_char_t *str_to_eval = (const jerry_char_t *) "1 + 1";
jerry_value_t ret_val = jerry_eval (str_to_eval,
strlen ((const char *) str_to_eval),
JERRY_PARSE_NO_OPTS);
原 false 对应的就是 JERRY_PARSE_NO_OPTS;若原来传 true(严格模式),则改为 JERRY_PARSE_STRICT_MODE。
5. Port API 迁移:时区处理
5.1 jerry_port_get_time_zone → jerry_port_get_local_time_zone_adjustment
1.0 的移植层时区接口存在设计缺陷:即使宿主系统具备完善的时区能力,旧接口也无法正确处理时区(问题背景见 JerryScript 官方 issue #1661)。2.0 将接口改为基于 Unix 毫秒时间戳计算本地时区偏移的新形式,新函数为 jerry_port_get_local_time_zone_adjustment,完整描述见 docs/05.PORT-API.md。当前仓库的 Unix 移植实现位于 jerry-port/unix/jerry-port-unix-date.c,Windows 实现位于 jerry-port/win/jerry-port-win-date.c。
下面是两个版本的默认实现对照:
Before(1.0):
bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p)
{
struct timeval tv;
struct timezone tz;
/* gettimeofday may not fill tz, so zero-initializing */
tz.tz_minuteswest = 0;
tz.tz_dsttime = 0;
if (gettimeofday (&tv, &tz) != 0)
{
return false;
}
tz_p->offset = tz.tz_minuteswest;
tz_p->daylight_saving_time = tz.tz_dsttime > 0 ? 1 : 0;
return true;
} /* jerry_port_get_time_zone */
After(2.0):
double jerry_port_get_local_time_zone_adjustment (double unix_ms,
bool is_utc)
{
struct tm tm;
time_t now = (time_t) (unix_ms / 1000);
localtime_r (&now, &tm);
if (!is_utc)
{
now -= tm.tm_gmtoff;
localtime_r (&now, &tm);
}
return ((double) tm.tm_gmtoff) * 1000;
} /* jerry_port_get_local_time_zone_adjustment */
新函数签名中:
unix_ms:Unix 毫秒时间戳;is_utc:指示当前处理的日期时间是否以 UTC 表示,用于决定是否需要在计算前把本地时间先"还原"为 UTC 再求偏移;- 返回值:本地时区相对 UTC 的偏移量,单位为毫秒。
6. 原生指针(Native Pointer)机制迁移
1.0 中每个 jerry_value_t 对象只能关联一个原生句柄(native handle),且回调类型为简单的 jerry_object_free_callback_t。2.0 中该机制被重新设计:允许为同一个 JS 对象注册多个原生信息(native info),每个原生信息通过 jerry_object_native_info_t 结构体描述,并作为后续读写操作的"类型标签"进行区分。
涉及的三处替换:
| 旧(1.0) | 新(2.0) |
|---|---|
jerry_object_free_callback_t 回调类型 |
jerry_object_native_info_t 结构体(含 free_cb 成员) |
jerry_get_object_native_handle |
jerry_get_object_native_pointer |
jerry_set_object_native_handle |
jerry_set_object_native_pointer |
当前仓库中 jerry_object_native_info_t 及相关操作(jerry_object_get_native_ptr、jerry_object_has_native_ptr、jerry_object_delete_native_ptr)声明见 jerryscript-core.h。
Before(1.0):
struct
{
int data;
} my_info;
static void
handler_construct_freecb (uintptr_t native_p)
{
// Invoked when the JS object is released and the
// native data should be freed.
struct my_info *info = (struct my_info *) native_p;
free (info);
}
void
demo (void)
{
jerry_value_t this_val;
// create or acquire this_val
// ...
struct my_info *info = (struct my_info *) malloc (sizeof (struct my_info));
info->data = 11;
// setting the native handle
jerry_set_object_native_handle (this_val,
(uintptr_t) info,
handler_construct_freecb);
// ...
// reading back the native handle
uintptr_t ptr = (uintptr_t) NULL;
bool is_ok = jerry_get_object_native_handle (this_val, &ptr);
if (is_ok)
{
struct my_info *obj_info = (struct my_info *) ptr;
// use "obj_info"
}
}
After(2.0):
struct
{
int data;
} my_info;
static void
handler_construct_freecb (void *native_p)
{
// Invoked when the JS object is released and the
// native data should be freed.
struct my_info *info = (struct my_info *) native_p;
free (info);
}
static const jerry_object_native_info_t my_info_type_info =
{
.free_cb = handler_construct_freecb
};
void
demo (void)
{
jerry_value_t this_val;
// create or acquire this_val
// ...
struct my_info *info = (struct my_info *) malloc (sizeof (struct my_info));
info->data = 11;
// setting the native handle
jerry_set_object_native_pointer (this_val,
info,
&my_info_type_info);
// ...
// reading back the native handle pointed by the "my_info_type_info" variable
void *ptr = NULL;
bool has_p = jerry_get_object_native_pointer (this_val, &ptr, &my_info_type_info);
if (has_p)
{
struct my_info *obj_info = (struct my_info *) ptr;
// use "obj_info"
}
}
迁移要点:
- 回调签名:
uintptr_t native_p改为void *native_p,不再需要整数与指针之间的强制转换; - 类型信息:原来的裸回调改为
static const jerry_object_native_info_t结构体({ .free_cb = ... }),该结构体同时充当该原生数据的"身份标识"; - 读写参数:
set/get都新增一个&my_info_type_info参数用于指定操作哪个原生信息,从而支持同一对象挂载多份不同类型原生数据。
7. 2.0 新增的 API 函数清单
2.0 同时引入了一批新 API,覆盖新的内置对象与能力。以下是迁移文档中的完整清单(各函数详细签名见 docs/02.API-REFERENCE.md 对应小节)。
7.1 内置对象相关
ArrayBuffer:
jerry_create_arraybufferjerry_create_arraybuffer_external(基于外部内存创建 ArrayBuffer,适合零拷贝场景)jerry_get_arraybuffer_pointer
DataView:
jerry_create_dataviewjerry_value_is_dataviewjerry_get_dataview_buffer
JSON:
jerry_json_parsejerry_json_stringify
Number:
jerry_create_number_infinityjerry_create_number_nan
Promise:
jerry_run_all_enqueued_jobs(驱动 Promise 微任务队列,需在事件循环中调用)jerry_create_promisejerry_resolve_or_reject_promisejerry_value_is_promise
RegExp:
jerry_create_regexpjerry_create_regexp_sz
String(UTF-8 相关):
jerry_substring_to_utf8_char_bufferjerry_get_utf8_string_sizejerry_get_utf8_string_lengthjerry_create_string_from_utf8jerry_create_string_sz_from_utf8
Symbol:
jerry_create_symboljerry_get_symbol_descriptive_stringjerry_value_is_symbol
TypedArray:
jerry_create_typedarrayjerry_create_typedarray_for_arraybufferjerry_create_typedarray_for_arraybuffer_szjerry_get_typedarray_typejerry_get_typedarray_lengthjerry_get_typedarray_bufferjerry_value_is_typedarray
7.2 实例与内存管理
JerryScript 实例:
jerry_create_context(创建独立上下文,支持多实例隔离)jerry_get_context_data(获取上下文私有数据)
内存管理:
jerry_heap_allocjerry_heap_free
多实例能力是 2.0 的重要架构升级:
jerry_create_context允许在一个进程内创建多个相互隔离的引擎实例。当前仓库的上下文实现可参考 jerry-core/jcontext/jcontext.c 与 jerry-core/jcontext/jcontext.h。
7.3 JavaScript 值操作
二元运算:
jerry_binary_operation
错误处理:
jerry_get_error_typejerry_get_backtrace(获取当前错误/异常的调用栈回溯)
原生指针:
jerry_delete_object_native_pointer(删除对象上某个原生信息)jerry_objects_foreach_by_native_info(遍历所有挂载了指定原生信息的对象)
属性操作:
jerry_delete_property_by_indexjerry_objects_foreach(遍历堆上所有对象)
7.4 调试器(Debugger)API
jerry_debugger_is_connectedjerry_debugger_stopjerry_debugger_continuejerry_debugger_stop_at_breakpointjerry_debugger_wait_for_client_sourcejerry_debugger_send_outputjerry_debugger_send_log
这些函数需要开启 JERRY_DEBUGGER 特性并配合调试器客户端使用,协议说明见 docs/07.DEBUGGER.md,客户端参考实现位于 jerry-debugger/ 目录(如 jerry_client_main.py)。
7.5 其他新函数
jerry_is_feature_enabled(运行时查询某特性是否编译启用,可配合 docs/01.CONFIGURATION.md 中的特性开关使用)jerry_parse_and_save_literals(保存解析过程中收集的字符串字面量,供魔法字符串注册使用)jerry_set_vm_exec_stop_callback(设置 VM 执行停止回调,用于实现执行超时/中断控制)
7.6 新增 Port API 函数
jerry_port_normalize_pathjerry_port_read_sourcejerry_port_release_sourcejerry_port_print_charjerry_port_get_current_contextjerry_port_fataljerry_port_sleepjerry_port_print_byte
这些函数的默认实现分布在 jerry-port/common/(如 jerry-port-io.c、jerry-port-process.c、jerry-port-fs.c)与各平台目录(jerry-port/unix/、jerry-port/win/),详见 docs/05.PORT-API.md。
8. 从 2.x 迁移到 3.x 的补充说明
JerryScript 3.0 最显著的变化是一次更大规模的 API 重命名:绝大多数 API 函数在 3.0 中被改名,以统一命名风格(例如 jerry_get_global_object 等 2.x 函数在 3.0 中改名,原 2.x 名称仅在旧版本中有效)。API Reference 中为每个此类函数都标注了 "Renamed in version 3.0, it was previously known as xxx in earlier versions" 形式的迁移提示。
如果你同时需要从 1.0 迁移到 3.x,建议采用两步迁移策略:
- 先按本文第 2~6 节完成 1.0 → 2.0 的破坏性变更替换(错误处理、原生指针、快照、GC、eval、时区 Port API);
- 再对照 docs/02.API-REFERENCE.md 中的 "Renamed in version 3.0" 提示,将函数名批量更新到 3.x 命名。
这样每次只处理一类变更,出错时更容易定位。另外,由于配置宏在 1.0 → 2.0 经历了 CONFIG_ → JERRY_ 前缀统一,3.0 又对特性宏做了细分(如 JERRY_BUILTIN_* 系列),在迁移构建系统时请以 jerry-core/config.h 中的当前宏定义与默认值为准。
9. 迁移自检清单
完成迁移后,建议按以下清单逐项验证:
- [ ] 头文件已更新为
#include "jerryscript.h"与#include "jerryscript-port.h",不再引用jerry-api.h、jerry-port.h、jerry-internal.h; - [ ] 源码中不存在
jerry_char_ptr_t、jerry_object_free_callback_t等旧类型; - [ ] 错误处理统一使用
jerry_create_abort_from_value/jerry_create_error_from_value/jerry_get_value_from_error,并核对每个调用的take_ownership参数; - [ ] 所有
CONFIG_前缀宏已改为JERRY_前缀; - [ ] 快照生成调用已切换到
jerry_generate_snapshot/jerry_generate_function_snapshot,并检查返回值是否为错误对象; - [ ]
jerry_gc已传入JERRY_GC_PRESSURE_LOW(或 HIGH)参数; - [ ]
jerry_eval的第三参数已由bool改为jerry_parse_opts_t枚举; - [ ] 移植层已实现
jerry_port_get_local_time_zone_adjustment,并删除旧jerry_port_get_time_zone; - [ ] 原生数据读写已改用
jerry_object_native_info_t与jerry_(get|set)_object_native_pointer三参数形式; - ] 编译通过且通过
tools/run-tests.py运行单元测试([tests/unit-core/)验证引擎行为无回归。
完成以上步骤后,你的代码即与 2.0 及以上版本的 JerryScript API 兼容。若需要了解每个新 API 的完整参数与返回值语义,请继续阅读 docs/02.API-REFERENCE.md(API 参考)、docs/05.PORT-API.md(移植层参考)与 docs/04.INTERNALS.md(内部实现原理)。