在 ESP32 上运行 JerryScript:基于 ESP-IDF 的构建、烧录与串口验证全指南
在 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!
判定成功的两个标志:
- 日志中出现带
JS标签(来自 ESP-IDF 日志组件)的两条信息,说明 JerryScript 已初始化并开始解析脚本; - 末尾直接打印出
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 应用固件。