在 ESP32 上运行 JerryScript:基于 ESP-IDF 的构建、烧录与串口验证全指南

原创2026-09-27 13:19:261,623 阅读
文章标签:编程语言语言运行时解释器嵌入式物联网标准库

在 ESP32 上运行 JerryScript:基于 ESP-IDF 的构建、烧录与串口验证全指南

JerryScript 作为面向物联网的超轻量级 JavaScript 引擎,官方仓库在 targets/baremetal-sdk/espressif 目录中提供了完整的 ESP32 移植工程:本文以 esp-idf 构建指南 为骨架,逐步讲解如何在 Ubuntu 上搭建 ESP-IDF(release/v4.4)开发环境、编译出 jerryscript.bin 固件、烧录到 ESP32 开发板,并通过串口监视器验证 Hello, World! 脚本的执行结果。读完本文,你将掌握 JerryScript 在 ESP32 上从零构建到上板运行的完整链路,并理解其背后基于 CMake/tools/build.py 的交叉编译机制与 Port 层适配方式。

一、目标与适用环境

该目标目录用于在乐鑫 ESP32 芯片上运行 JerryScript,开发框架为 ESP-IDF(Espressif IoT Development Framework)。根据文档说明:

  • 文档在 Ubuntu 20.04 操作系统上完成验证;
  • 经验证可用的 ESP-IDF 版本为 release/v4.4 分支;
  • 编译需要 Xtensa 架构的交叉工具链(xtensa-esp32-elf-gcc8_4_0-esp-2021r2)。

工程所在的仓库目录结构如下:

targets/baremetal-sdk/espressif
  + esp-idf/            # 面向 ESP32 + ESP-IDF 的构建说明与 CI 脚本
  + esp8266-rtos-sdk/   # 面向 ESP8266 + ESP8266 RTOS SDK 的姊妹目标
  + main/               # 固件入口与 Port 层实现(CMakeLists.txt、jerry-main.c、jerry-port.c)
  + CMakeLists.txt      # ESP-IDF 项目级 CMake 文件
  + README.md           # 双目标总览

其中 espressif/README.md 明确指出,ESP32(ESP-IDF)与 ESP8266(ESP8266 RTOS SDK)两个目标共用同一套基于 ESP-IDF 风格的构建系统与目录结构,因此本文的构建原理对两个目标均适用。

二、第一步:搭建构建环境

2.1 克隆必要项目

在任意位置创建一个工作目录 jerry-esp,依次克隆 JerryScript 与 ESP-IDF,并下载 Xtensa 工具链:

# Create a base folder for all the projects.
mkdir jerry-esp && cd jerry-esp

git clone https://github.com/jerryscript-project/jerryscript.git
git clone https://github.com/espressif/esp-idf.git -b release/v4.4

# SDK requires Xtensa toolchain.
wget https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-amd64.tar.gz

克隆完成后应得到如下目录结构:

jerry-esp
  + jerryscript
  |  + targets
  |      + baremetal-sdk
  |          + espressif
  |
  + esp-idf
  + xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-amd64.tar.gz

注:ESP-IDF 固定检出到 release/v4.4 分支,这是文档中声明的最新验证可用版本;主分支或更新版本未被该文档验证过。

2.2 安装双方依赖并解压工具链

# Assuming you are in jerry-esp folder.
jerryscript/tools/apt-get-install-deps.sh

# Install dependencies of esp-idf.
python -m pip install --user -r esp-idf/requirements.txt

# Extract the downloaded toolchain.
tar -xvf xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-amd64.tar.gz
  • jerryscript/tools/apt-get-install-deps.sh 是仓库自带的依赖安装脚本,负责补齐 JerryScript 构建所需的系统级软件包;
  • ESP-IDF 的 Python 依赖通过 requirements.txt 安装(以 --user 方式避免污染系统环境);
  • 工具链解压后会生成 xtensa-esp32-elf/bin 目录,其中包含 xtensa-esp32-elf-gcc 等交叉编译工具,后续构建与监视命令均需将其加入 PATH。

三、第二步:构建固件(ESP-IDF + JerryScript)

3.1 idf.py 构建命令

在 jerry-esp 目录下执行:

# Assuming you are in jerry-esp folder.
PATH=${PWD}/xtensa-esp32-elf/bin:$PATH esp-idf/tools/idf.py \
  --project-dir jerryscript/targets/baremetal-sdk/espressif \
  --build-dir jerryscript/build/esp-idf \
  set-target esp32 \
  all

各参数含义:

参数 作用
--project-dir 指定 ESP-IDF 工程目录,即仓库内的 targets/baremetal-sdk/espressif
--build-dir 指定构建输出目录,最终产物落在 jerryscript/build/esp-idf 下
set-target esp32 设置芯片目标为 ESP32(SDK 会据此选择正确的 Xtensa 工具链与链接脚本)
all 构建全部目标(bootloader、partition table、应用固件)
前置的 PATH=... 将解压出的 Xtensa 工具链目录临时加入搜索路径,供 idf.py 调用

构建成功后,生成的固件为 jerryscript/build/esp-idf/jerryscript.bin,同时该目录下还会有 bootloader/bootloader.bin、partition_table/partition-table.bin 与 jerryscript.elf,分别用于烧录与调试。

3.2 构建背后的原理:CMake 与 build.py 的联动

该 ESP-IDF 工程并不手写交叉编译规则,而是在 espressif/CMakeLists.txt 中通过 include($ENV{IDF_PATH}/tools/cmake/project.cmake) 接入 ESP-IDF 的标准构建框架,并声明 project(jerryscript);其中还包含一个细节:用 file(TOUCH ${SDKCONFIG}) 预先在构建目录生成空的 sdkconfig,以避免配置漂移。

真正的 JerryScript 内核编译发生在 main/CMakeLists.txt 中,它通过 execute_process 调用仓库根目录的 tools/build.py 完成一次独立的子构建:

set(JERRY_ROOT_DIR ${PROJECT_DIR}/../../..)
set(JERRY_BUILD_DIR ${JERRY_ROOT_DIR}/build/jerry)
set(JERRY_HEAP_SIZE 20)

execute_process(COMMAND ${JERRY_ROOT_DIR}/tools/build.py
                            --clean
                            --builddir=${JERRY_BUILD_DIR}
                            --lto=OFF
                            --jerry-cmdline=OFF
                            --jerry-math=OFF
                            --amalgam=ON
                            --mem-heap=${JERRY_HEAP_SIZE}
                            --profile=es.next
                            --compile-flag=${COMPILE_FLAGS}
                            --toolchain=${CMAKE_TOOLCHAIN_FILE})

对照 tools/build.py 的参数定义,可以解读出该配置的实际含义:

  • --mem-heap=20:将 JerryScript 的全局内存堆设置为 20 KB(对应 CMake 变量 JERRY_GLOBAL_HEAP_SIZE),这是面向 ESP32 片上 SRAM 的典型紧凑配置;
  • --profile=es.next:使用 es.next.profile 特性集,该文件内容为「所有特性默认全开」(# All features are enabled by default.),即启用完整 ES.next 语法与内建对象;
  • --amalgam=ON:启用合并编译(amalgamated build),将多个源文件合并后一次性编译,可显著减小代码体积与编译开销,非常适合资源受限的嵌入式目标;
  • --lto=OFF:关闭链接期优化,避免与 ESP-IDF 工具链的兼容性问题;
  • --jerry-cmdline=OFF / --jerry-math=OFF:不构建桌面命令行工具与自带的 jerry-math 数学库,进一步瘦身;
  • --toolchain=${CMAKE_TOOLCHAIN_FILE}:把 ESP-IDF 传入的 Xtensa 交叉工具链文件原样传递给 JerryScript 子构建,保证两套 CMake 使用同一套交叉编译环境;
  • --compile-flag=${COMPILE_FLAGS}:将上层收集到的编译选项(由 COMPILE_OPTIONS 与 C_COMPILE_OPTIONS 拼接而成)透传给内核编译。

子构建产物为 build/jerry/lib/ 下的三个静态库 libjerry-core.a、libjerry-ext.a、libjerry-port.a,随后 main/CMakeLists.txt 通过 add_library(... STATIC IMPORTED) 与 target_link_libraries 将它们链接进 ESP-IDF 组件:

idf_component_register(SRCS "jerry-main.c" "jerry-port.c" INCLUDE_DIRS ${JERRY_INCLUDE_DIRS})
add_library(jerry-core STATIC IMPORTED)
add_library(jerry-ext STATIC IMPORTED)
add_library(jerry-port STATIC IMPORTED)
set_target_properties(jerry-core PROPERTIES IMPORTED_LOCATION "${JERRY_BUILD_DIR}/lib/libjerry-core.a")
set_target_properties(jerry-ext PROPERTIES IMPORTED_LOCATION "${JERRY_BUILD_DIR}/lib/libjerry-ext.a")
set_target_properties(jerry-port PROPERTIES IMPORTED_LOCATION "${JERRY_BUILD_DIR}/lib/libjerry-port.a")
target_link_libraries(${COMPONENT_LIB} INTERFACE jerry-core jerry-ext jerry-port)

其中 jerry-port 库的 Port 层实现(jerry-port.c)与主程序(jerry-main.c)直接作为 ESP-IDF 组件源码参与编译,实现了「JerryScript 内核预编译 + 板级适配源码就地编译」的混合构建模式。

四、第三步:烧录到 ESP32 开发板

将开发板通过 Micro-USB 连接(同时供电与烧录),设备通常显示为 /dev/ttyUSB0。使用 ESP-IDF 自带的 esptool 烧写三份镜像:

# Assuming you are in jerry-esp folder.
sudo python esp-idf/components/esptool_py/esptool/esptool.py \
  --chip esp32 \
  --port /dev/ttyUSB0 \
  --baud 460800 \
  --before default_reset \
  --after hard_reset \
  write_flash \
  --flash_mode dio \
  --flash_size detect \
  --flash_freq 40m \
  0x1000 jerryscript/build/esp-idf/bootloader/bootloader.bin \
  0x8000 jerryscript/build/esp-idf/partition_table/partition-table.bin \
  0x10000 jerryscript/build/esp-idf/jerryscript.bin

各烧录参数与地址的含义:

参数/地址 说明
--chip esp32 指定目标芯片型号
--port /dev/ttyUSB0 串口设备节点(如插拔后编号变化,以 ls /dev/ttyUSB* 实际输出为准)
--baud 460800 烧录波特率,远高于调试波特率,可加快写入
--before default_reset / --after hard_reset 烧录前自动复位进入下载模式,烧录完成后硬复位启动固件
--flash_mode dio 双线 I/O 模式(与启动日志中的 flash io: dio 对应)
--flash_size detect 自动探测 Flash 容量
--flash_freq 40m Flash 工作频率 40 MHz
0x1000 引导加载器 bootloader.bin 的烧录地址
0x8000 分区表 partition-table.bin 的烧录地址
0x10000 应用固件 jerryscript.bin 的烧录地址

五、第四步:连接串口监视器并验证输出

ESP-IDF 提供了 Python 编写的串口监视脚本 idf_monitor.py,也可使用 minicom、picocom 等第三方工具。关键信息:

  • 设备节点:/dev/ttyUSB0
  • 串口波特率:115200
  • 退出监视器:按 CTRL + ALT + ]

启动监视命令:

# Assuming you are in jerry-esp folder.
PATH=${PWD}/xtensa-esp32-elf/bin:$PATH esp-idf/tools/idf_monitor.py \
  --port /dev/ttyUSB0 \
  --baud 115200 \
  --toolchain-prefix=xtensa-esp32-elf- \
  jerryscript/build/esp-idf/jerryscript.elf

其中 --toolchain-prefix 用于让监视器能够调用 addr2line 等工具解析崩溃回溯;传入 jerryscript.elf(而非 .bin)是为了在日志中附带符号信息。

设备复位后,应捕获到如下输出:

I (0) cpu_start: App cpu up.
I (326) cpu_start: Pro cpu start user code
I (326) cpu_start: cpu freq: 160000000
I (326) cpu_start: Application information:
I (331) cpu_start: Project name:     jerryscript
I (336) cpu_start: App version:      v2.4.0-278-ge815e540-dirty
I (342) cpu_start: Compile time:     Jan 21 2022 11:38:44
I (349) cpu_start: ELF file SHA256:  2e874acb5a45c0cb...
I (355) cpu_start: ESP-IDF:          v4.4-beta1-284-gd83021a6e8-dirt
I (362) heap_init: Initializing. RAM available for dynamic allocation:
I (369) heap_init: At 3FFAE6E0 len 00001920 (6 KiB): DRAM
I (375) heap_init: At 3FFB8510 len 00027AF0 (158 KiB): DRAM
I (381) heap_init: At 3FFE0440 len 00003AE0 (14 KiB): D/IRAM
I (387) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
I (394) heap_init: At 4008B3E8 len 00014C18 (83 KiB): IRAM
I (401) spi_flash: detected chip: generic
I (405) spi_flash: flash io: dio
I (410) cpu_start: Starting scheduler on PRO CPU.
I (0) cpu_start: Starting scheduler on APP CPU.
I (420) JS: This test run the following script code:
I (430) JS: print ('Hello, World!');
Hello, World!

判定成功的两个标志:

  1. 日志中出现带 JS 标签(来自 ESP-IDF 日志组件)的两条信息,说明 JerryScript 已初始化并开始解析脚本;
  2. 末尾直接打印出 Hello, World!,证明 JS 引擎在 ESP32 上完成了「解析 → 执行 → 调用 print 输出」的完整闭环。

六、固件入口与 Port 层实现解读

6.1 应用入口 app_main

烧录进 ESP32 的固件入口是 main/jerry-main.c 中的 app_main,其执行流程对应了 JerryScript 的标准生命周期:

jerry_init (JERRY_INIT_EMPTY);                       /* 1. 初始化引擎 */
jerry_log_set_level (JERRY_LOG_LEVEL_DEBUG);
jerryx_register_global ("print", jerryx_handler_print); /* 2. 注册 print 全局函数 */
ret_value = jerry_parse (script, sizeof (script) - 1, NULL); /* 3. 解析源码 */
ret_value = jerry_run (ret_value);                   /* 4. 执行 */
jerry_value_free (ret_value);                        /* 5. 释放返回值 */
jerry_cleanup ();                                    /* 6. 清理引擎 */

其中:

  • print 函数来自 jerry-ext 扩展库(jerryx_handler_print,声明于 jerryscript-ext/handlers.h),通过 jerryx_register_global 注册到全局对象上,这正是日志中 print ('Hello, World!'); 能被识别执行的原因;
  • 解析失败或执行异常时,jerry_value_is_exception 分支会输出 Script error... 调试日志,便于排查板端脚本问题。

6.2 板级 Port 层适配

JerryScript 通过 Port 层与宿主环境解耦,main/jerry-port.c 给出了 ESP32 上的典型实现:

  • jerry_port_log:将引擎日志转发到 ESP-IDF 日志系统(ESP_LOGI,标签 JS),这就是启动日志中 I (420) JS: ... 的来源;
  • jerry_port_fatal:致命错误时输出 Fatal error: %d,先挂起当前 FreeRTOS 任务再 abort(),避免错误后继续运行导致不可预期行为;
  • jerry_port_local_tza / jerry_port_current_time:基于 localtime_r 与 gettimeofday 实现本地时区偏移与毫秒级当前时间,供 Date 等 ECMAScript 内建对象使用。

Port 层 API 的完整契约可参考 docs/05.PORT-API.md,在自有硬件上移植 JerryScript 时,只需按同样签名补齐这些函数。

七、配套与延伸

7.1 ESP8266 姊妹目标

同一 espressif 目录下还提供了 ESP8266 + ESP8266 RTOS SDK(release/v3.4)的构建说明,见 esp8266-rtos-sdk/README.md。其流程与本文完全同构,差异点在于:

  • 工具链为 xtensa-lx106-elf-gcc8_4_0-esp-2020r3;
  • 烧录起始地址为 0x0(无独立 bootloader 分区起点偏移);
  • 串口调试波特率为 74880;
  • 启动日志显示 ESP-IDF v3.4,Flash 为 2MB / QIO 40MHz。

两者共用 main/ 目录下的组件源码与构建脚本,进一步印证了「ESP-IDF 风格统一构建」的设计。

7.2 CI 验证脚本

仓库在 esp-idf/Makefile.travis 中沉淀了自动化验证流程,其 script 目标与手动命令一一对应:

script:
	PATH=/tmp/xtensa-esp32-elf/bin:$(PATH) \
	python /tmp/esp-idf/tools/idf.py \
		--project-dir ./targets/baremetal-sdk/espressif \
		--build-dir ./build/esp-idf \
		set-target esp32 \
		all

它同时展示了 install-xtensa-esp32-gcc、install-esp-idf 等依赖准备步骤的自动化写法,本地复现构建时可直接参考其命令序列。

八、关键注意事项小结

  • 版本锁定:ESP-IDF 务必使用 release/v4.4(文档声明的最新验证版本),ESP8266 目标对应 release/v3.4,更换版本可能遇到工具链或 API 不兼容;
  • 系统环境:文档在 Ubuntu 20.04 上验证,依赖安装脚本与 Python 依赖安装步骤均针对该环境编写;
  • 内存预算:JerryScript 全局堆固定为 20 KB(JERRY_HEAP_SIZE,见 main/CMakeLists.txt),调整脚本复杂度时需留意堆上限,必要时可修改该值重新构建;
  • 串口权限:烧录命令使用了 sudo,监视命令在 ESP32 目标下未强制要求,但若设备节点无读写权限需以 sudo 运行;
  • 产物位置:固件 jerryscript.bin 生成于 jerryscript/build/esp-idf/ 目录,符号文件 jerryscript.elf 供监视器与调试器使用。

按照上述步骤,即可在 ESP32 上获得一个完整的、可交互的 JerryScript 运行环境;在此基础上,将 main/jerry-main.c 中的测试脚本替换为实际业务逻辑,并注册自定义原生函数,即可快速开发面向物联网场景的 JavaScript 应用固件。

登录后查看全文
jerryscript