从零开始在 Linux 上编译运行 lvgljs 图形界面项目

项目简介lvgljs 是一个用 JavaScript/React 语法操作 LVGL轻量级通用图形库的开源项目。它将 LVGL 的 C 语言 UI 组件封装成了类似 React 的组件化接口开发者可以用 JSX 编写嵌入式 UI渲染到 SDL2 模拟器或真实的嵌入式设备上。技术栈JavaScript 运行时txiki.js基于 QuickJS libuv curl图形引擎LVGL嵌入式 GUI 库前端框架自定义 React Reconcilervirtual DOM → LVGL C 调用构建工具CMakenative 层 esbuildJS 层一、环境准备1.1 安装系统依赖sudoaptupdatesudoaptinstall-y\git\cmake\nodejs\npm\libsdl2-dev\libcurl4-openssl-dev\libffi-dev\libtool\autoconf\automake\texinfo各依赖说明包名用途git克隆代码、拉取 git 子模块cmakeCMake 3.16构建 native 层nodejs/npm运行 esbuild、打包 JS bundlelibsdl2-devSDL2 模拟器显示驱动libcurl4-openssl-devtxiki.js HTTP 客户端依赖libffi-dev外部 FFI 库解决 CMake 4.x 兼容问题libtool autoconf automake texinfolibffi 源码构建工具链1.2 克隆代码并初始化子模块gitclone https://github.com/lvgl/lv_binding_js.gitcdlv_binding_jsgitsubmodule update--recursive--init这一步会拉取三个关键子模块deps/lvgl— LVGL 图形库deps/lv_drivers— LVGL 输入/显示驱动deps/txiki— JavaScript 运行时二、修改构建配置关键步骤项目的 Makefile 设计时针对标准 CMake 版本在Ubuntu26.04系统上CMake 4.x 环境下需要做两处修改。打开项目根目录的Makefile找到simulator目标将 cmake 命令修改为simulator: mkdir -p $(BUILD_SIM) cmake -B $(BUILD_SIM) -DCMAKE_BUILD_TYPESimulator -DCMAKE_POLICY_VERSION_MINIMUM3.5 -DUSE_EXTERNAL_FFION -DCMAKE_C_FLAGS-Wno-errordiscarded-qualifiers -Wno-errorunterminated-string-initialization cmake --build $(BUILD_SIM) -j修改说明参数原因-DUSE_EXTERNAL_FFIONCMake 4.x 与 libffi 的 autotools 构建系统不兼容使用系统已安装的 libffi-Wno-errordiscarded-qualifierstxiki 依赖的 quickjs 代码中有const限定符警告被-Werror拦截-Wno-errorunterminated-string-initialization同上quickjs 中字符串初始化警告被当作错误三、编译并运行3.1 一键编译模拟器makesimulator这一步骤会创建build/目录运行 CMake 配置Simulator 模式会自动链接 SDL2编译 txiki.js、LVGL、lv_drivers 和项目自身的 C 绑定层编译产物为build/lvgljs可执行文件。3.2 打包 JS Bundlenpminstall# 安装前端依赖首次运行一次即可npmrun bundle# 用 esbuild 将 .jsx/.tsx 打包成 .jsbuild.js会扫描demo/*/index.jsx和test/*/index.jsx将所有 JSX/TSX 文件打包为可被 txiki.js 执行的纯 JavaScript 文件。3.3 运行 Demo# 默认运行 widgets 示例makedemo# 运行其他 demomakedemoPROJECThello_worldmakedemoPROJECTcalculator也可以手动指定路径./build/lvgljs run demo/widgets/index.js3.4 热重载开发模式同时打开两个终端窗口# 终端 1监视 JSX 文件变化自动重新打包npmrun bundle:watch# 终端 2监视编译产物变化自动重新运行npmrun sim:watch -- demo/widgets/index.js四、项目结构一览lvgljs/ ├── CMakeLists.txt # C 构建配置 ├── Makefile # 便捷构建入口 ├── build.js # esbuild JS 打包脚本 ├── package.json # npm 依赖配置 │ ├── src/ │ ├── engine/ # C 应用入口 │ │ ├── engine.cpp # main()初始化 txiki.js 暴露 lvgljs 对象 │ │ └── hal/ │ │ ├── simulator/ # SDL2 模拟器 HAL │ │ └── device/ # 嵌入式 framebuffer HAL │ │ │ └── render/ │ ├── native/ # C LVGL 绑定层 │ │ ├── bootstrap/ # 初始化所有组件/事件绑定 │ │ └── components/ # 各个 LVGL 组件的 C 包装 │ └── react/ # JavaScript UI 框架 │ ├── core/ # Reconciler、样式、动画、主题 │ └── components/ # Button、Text、View 等 React 组件 │ ├── deps/ │ ├── lvgl/ # LVGL 图形库子模块 │ ├── lv_drivers/ # LVGL 驱动子模块 │ └── txiki/ # txiki.js 运行时子模块 │ ├── demo/ │ ├── widgets/ # 组件展示 demo │ ├── hello_world/ # 入门 hello world │ └── calculator/ # 计算器 demo │ └── doc/ # 详细文档 ├── build/ # 构建指南 ├── component/ # 各组件 API 文档 └── style/ # CSS 样式文档五、编写自己的 UI项目提供了类似 React 的组件化接口。使用前确保npm run bundle已执行过或者开bundle:watch然后编写 JSX 文件import { Button, Render, Text, View } from lvgljs-ui; import React from react; function App() { return ( View style{{ background-color: #1a1a2e, flex-direction: column, align-items: center, justify-content: center }} Text style{{ color: #ffffff, font-size: 24 }} Hello lvgljs! /Text Button style{{ margin-top: 20, background-color: #e94560 }} TextClick Me/Text /Button /View ); } Render.render(App /);将文件放到demo/myapp/index.jsx运行npmrun bundle ./build/lvgljs run demo/myapp/index.js六、可能遇到的问题问题解决方案Could NOT find CURLsudo apt install libcurl4-openssl-devCould NOT find SDL2sudo apt install libsdl2-devLIBTOOL is undefinedsudo apt install libtool autoconf automakemakeinfo: command not foundsudo apt install texinfoquickjs ... discarded-qualifiersMakefile cmake 命令加-DCMAKE_C_FLAGS-Wno-errordiscarded-qualifiersunterminated-string-initialization同上加-Wno-errorunterminated-string-initializationlibffi configure failedcmake 命令加-DUSE_EXTERNAL_FFIONsudo apt install libffi-dev七、总结整个流程可以归纳为 4 条命令# 1. 安装依赖一次性sudoaptinstallgitcmake nodejsnpmlibsdl2-dev libcurl4-openssl-dev\libffi-dev libtool autoconf automake texinfo# 2. 拉取代码和子模块网络不好的话自己想办法gitclone https://github.com/lvgl/lv_binding_js.gitcdlv_binding_jsgitsubmodule update--recursive--init# 3. 安装 JS 依赖npminstall# 4. 编译 打包 运行makesimulatornpmrun bundlemakedemo修改 Makefile 这一步只在 CMake 4.x Ubuntu 最新版系统上需要。如果是较老版本的 CMake3.16~3.28项目原生的 Makefile 应该是可以直接使用的make setup make simulator即可成功编译。