合宙ESP32系列|自定义固件|在线云编译|本地编译|Windows|luat_conf_bsp.h|（2）、CORE-ESP32S3编译

该文档提供了ESP32系列芯片（如ESP32C3,ESP32C2,ESP32,ESP32S3）使用LuatOS编译固件的详细步骤，包括环境准备、源码获取、目录结构、编译过程和错误排查。用户需注意idf5版本和luat_conf_bsp.h的配置，以及在启用某些功能时可能出现的编译错误。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

源文档见：ESP32系列编译文档 - LuatOS 文档

LuatOS-SoC通用固件格式soc介绍

定制固件里的库

PS:luat_conf_bsp.h问题汇总

源文档见：ESP32系列编译文档 - LuatOS 文档

本文档适合以下芯片:

esp32c3
esp32c2
esp32
esp32s3

使用本文档前,请确认以下信息:

你大概率不需要这份文档，这是用于自行扩展固件的高级文档。
我们提供的固件包就包含编译好的固件
如果你只是想将已有的库添加到固件中，可以使用我们提供的在线云编译生成自定义固件。
如果你是在找刷机/编译lua脚本之类的应用型文档，那么这份文档不是你需要查看的内容。

视频教程链接: B站每日喝粥

本地编译详细步骤

准备环境

windows 10 x64, 其他版本自行解决idf安装问题, 需要idf5, 最新idf5!! 低版本编译不了!!
所有步骤均使用 CMD, 非 PowerShell, 若不知道这些是什么, 请先百度学习一下
起码2G的磁盘空间, 用于存放代码和中间文件

准备项目

建一个文件夹,用于存放编译所需要的全部文件

推荐使用 D:\github , 最低要求是不能有空格,中文,特殊字符串, 且尽量短

获取源码

源码要2份, LuatOS主库及luatos-soc-idf5, 这是两个不同的仓库, 两个都需要!!

获取方式: 推荐git, 注册后下载zip也可以

必须按以下目录结构进行摆放, 以G:\bsp\ESP32\ 为例

D:\

github\

LuatOS\

lua\

luat\

components\

其他目录

luatos-soc-idf5\

luatos\

检查点, 路径正确的情况下, 以下文件路径必存在, 找不到就肯定是命名问题, 手动添加是徒劳的

G:\bsp\ESP32\LuatOS\lua\src\lgc.c
G:\bsp\ESP32\luatos-soc-idf5\luatos\include\luat_conf_bsp.h

LuatOS luatos-soc-idf5 都是固定目录名称, 都不可以改, 例如 LuatOS-master 就是错误的命名, 必须要改回 LuatOS

如果实在不方便把主库存放在 D:\github\LuatOS, 修改luatos-soc-idf5\luatos\CMakeLists.txt里面的LUATOS_ROOT值. 例如, 存放在 E:/abc/LuatOS, 则修改为

set(LUATOS_ROOT "E://abc/LuatOS/")

编译前的最后准备

安装 idf5

访问地址 https://dl.espressif.cn/dl/esp-idf/
下载idf5离线安装包 ESP-IDF v5.0 - Offline Installer
下载后双击启动, 按提示安装
安装完成后, 开始菜单会有idf5的快捷方式

编译

使用开始菜单或快捷方式, 进入idf5的CMD

g:

cd G:\bsp\ESP32\luatos-soc-idf5\luatos

idf.py fullclean

idf.py set-target esp32s3

idf.py build

（idf.py set-target 为设置要编译的芯片后面输入自己要编译的型号，不要无脑输入esp32c3）

当出现Project build complete.字样则表示编译成功, 会生成 .soc 后的文件(G:\bsp\ESP32\luatos-soc-idf5\luatos), 使用LuaTools刷机即可

LuatOS-SoC通用固件格式soc介绍

定制固件里的库

打开

G:\bsp\ESP32\luatos-soc-idf5\luatos\include \luat_conf_bsp.h，

按需注释或取消注释。注意，如果功能太大导致固件放不下，会编译失败。

PS:luat_conf_bsp.h问题汇总

1、以下宏取消注释进行编译报错，暂不支持，提issue。

// SDIO 仅支持TF/SD卡的挂载

// #define LUAT_USE_SDIO 1

// #define LUAT_USE_OTP 1

错误提示：

G:/bsp/ESP32/LuatOS/components/romfs/luat_vfs_romfs.c:271:32: note: expected 'char *' but argument is of type 'romfs_file_t *' {aka 'struct romfs_file *'}
[1589/1592] Linking CXX executable luatos.elfFAILED: luatos.elf elf_src_esp32s3.c.obj
cmd.exe /C "cd . && G:\bsp\Espressif\tools\xtensa-esp32s3-elf\esp-2022r1-11.2.0\xtensa-esp32s3-elf\bin\xtensa-esp32s3-elf-g++.exe -mlongcalls  @CMakeFiles\luatos.elf.rsp -o luatos.elf  && cd ."
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_otp.c.obj):(.literal.l_otp_lock+0x0): undefined reference to `luat_otp_lock'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_otp.c.obj):(.literal.l_otp_erase+0x0): undefined reference to `luat_otp_erase'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_otp.c.obj):(.literal.l_otp_write+0x0): undefined reference to `luat_otp_write'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_otp.c.obj):(.literal.l_otp_read+0x0): undefined reference to `luat_otp_read'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_otp.c.obj): in function `l_otp_lock':
G:/bsp/ESP32/LuatOS/luat/modules/luat_lib_otp.c:117: undefined reference to `luat_otp_lock'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_otp.c.obj): in function `l_otp_erase':
G:/bsp/ESP32/LuatOS/luat/modules/luat_lib_otp.c:106: undefined reference to `luat_otp_erase'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_otp.c.obj): in function `l_otp_write':
G:/bsp/ESP32/LuatOS/luat/modules/luat_lib_otp.c:86: undefined reference to `luat_otp_write'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_otp.c.obj): in function `l_otp_read':
G:/bsp/ESP32/LuatOS/luat/modules/luat_lib_otp.c:52: undefined reference to `luat_otp_read'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj):(.literal.l_sdio_sd_format+0x4): undefined reference to `luat_sdio_sd_format'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj):(.literal.l_sdio_sd_umount+0x0): undefined reference to `luat_sdio_sd_unmount'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj):(.literal.l_sdio_sd_mount+0x4): undefined reference to `luat_sdio_sd_mount'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj):(.literal.l_sdio_write+0x0): undefined reference to `luat_sdio_sd_write'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj):(.literal.l_sdio_read+0x0): undefined reference to `luat_sdio_sd_read'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj):(.literal.l_sdio_init+0x0): undefined reference to `luat_sdio_init'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj): in function `l_sdio_sd_format':
G:/bsp/ESP32/LuatOS/luat/modules/luat_lib_sdio.c:136: undefined reference to `luat_sdio_sd_format'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj): in function `l_sdio_sd_umount':
G:/bsp/ESP32/LuatOS/luat/modules/luat_lib_sdio.c:122: undefined reference to `luat_sdio_sd_unmount'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj): in function `l_sdio_sd_mount':
G:/bsp/ESP32/LuatOS/luat/modules/luat_lib_sdio.c:106: undefined reference to `luat_sdio_sd_mount'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj): in function `l_sdio_write':
G:/bsp/ESP32/LuatOS/luat/modules/luat_lib_sdio.c:85: undefined reference to `luat_sdio_sd_write'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj): in function `l_sdio_read':
G:/bsp/ESP32/LuatOS/luat/modules/luat_lib_sdio.c:54: undefined reference to `luat_sdio_sd_read'
g:/bsp/espressif/tools/xtensa-esp32s3-elf/esp-2022r1-11.2.0/xtensa-esp32s3-elf/bin/../lib/gcc/xtensa-esp32s3-elf/11.2.0/../../../../xtensa-esp32s3-elf/bin/ld.exe: esp-idf/luat/libluat.a(luat_lib_sdio.c.obj): in function `l_sdio_init':
G:/bsp/ESP32/LuatOS/luat/modules/luat_lib_sdio.c:60: undefined reference to `luat_sdio_init'
collect2.exe: error: ld returned 1 exit status
ninja: build stopped: subcommand failed.
ninja failed with exit code 1, output of the command is in the g:\bsp\esp32\luatos-soc-idf5\luatos\build\log\idf_py_stderr_output_9004 and g:\bsp\esp32\luatos-soc-idf5\luatos\build\log\idf_py_stdout_output_9004

output文件： g:\bsp\esp32\luatos-soc-idf5\luatos\build\log\idf_py_stdout_output_9004，cmd命令行关闭后可以查询错误的内容。