cmake_lvgl8.1从PC模拟到ARM开发板的LVGL移植避坑指南

简介：面向嵌入式Linux与ARM平台开发者的LVGL移植实践文档，聚焦在开发板上搭建轻量图形界面时遇到的交叉编译链配置、源码目录调整、库文件裁剪与程序入口适配等问题，适合具备Linux运维基础、正在从PC模拟转向嵌入式硬件部署的初中级开发者参考，也可用于智能终端、工业HMI等带屏设备的方案预研。压缩包仅含1个docx文件，约449KB，以文字说明和配置要点为主，体积轻便，便于在工程实践中快速检索与对照。已有3381人学习，反映出嵌入式GUI落地场景的较高关注度。内容围绕移植流程、CMake构建配置、屏幕参数调整，以及驱动兼容、内存管理和性能优化等常见难点展开，并给出问题排查思路，可帮助读者建立从源码准备到板端运行的完整认知，减少编译错误、资源占用与显示适配方面的试错成本。

1. 从 PC 模拟到 arm 开发板：cmake_lvgl8.1 这套打包件到底能不能直接用

cmake_lvgl8.1 打包件是把 LVGL 图形库、一份界面设计器导出的 UI 代码和一套 CMake 构建入口拼在一起的工程，目的很直接：先在 PC 上把界面跑通，再交叉编译成嵌入式 Linux 开发板能执行的 arm 程序。它省掉的是移植里最磨人的那一段——目录结构、编译入口、UI 初始化代码都已经搭好，剩下的是改工具链、归位两个文件夹、接上自己的显示驱动。适合手上有板子、能进串口、会写一点 C 的嵌入式硬件从业者；连 /dev/fb0 都没摸过的，建议先补这一课。反直觉的地方在于：这套包在 PC 上一路绿灯，直接改交叉编译器上板，十有八九是链接报错或者屏幕全黑，坑全藏在默认配置和几个只服务桌面模拟的库里。

2. 拆包与目录归位：custom、generated 两个文件夹放哪儿才不报头文件缺失

移植失败的第一现场往往不是编译错误，而是找不到头文件。原因不复杂：设计器导出的是两个独立文件夹，而工程默认只把src挂进 include 路径，两者的从属关系没建立起来，gui_guider.h、events_init.h就成了幽灵文件。这一章把目录这一步做干净，后面改工具链才有意义。

2.1 先摸清包内结构再动手

解压后别急着cmake，先花两分钟把结构看清楚。这类工程通常顶层一个CMakeLists.txt负责add_subdirectory，src下面放 LVGL 本体、驱动对接层和你自己的业务代码，而custom、generated是另外两个平级文件夹。先跑一遍目录树，确认哪一层是 include 根，哪一层是源码根。

# 解压到独立目录，别和别的工程混在一起，后面删 build 才不误伤 unzip cmake_lvgl8.1.zip -d ~/lvgl_port cd ~/lvgl_port # 看三层以内的目录骨架，重点确认 src 与 custom/generated 的相对位置 find . -maxdepth 3 -type d | sort # 把所有 CMakeLists.txt 列出来，心里有数这一版有几层子工程 find . -name CMakeLists.txt | sort

-maxdepth 3是刻意压小的，嵌入式工程目录树动辄七八层，全展开反而看不出主干。find . -name CMakeLists.txt的输出决定了后面第 3 章你要逐个过几遍工具链配置——这一条命令的结果直接对应「每个 CMakeLists.txt 都要改」这句话的工作量。

如果find的输出里src下已经带了lvgl、lv_drivers，说明 LVGL 本体是以源码形式内置的，不需要额外装库；如果是空的或者只有一个main.c，那就得把 LVGL 源码补进去，这种情况先回打包件里确认有没有单独的lvgl目录。

2.2 复制、软链、子目录挂载三种挂法的取舍

把custom和generated归到src下，有几种做法，长期维护的代价完全不同。

我的习惯是新项目先复制，把功能跑通，等界面定稿、导出频率降下来再换软链。软链在本地开发时很爽，但当你把整个工程打成 tar 包丢到编译服务器上做流水线时，链接目标一旦不在包内，cmake阶段就会报路径不存在，这类问题在服务器端排查起来很不直观。

# 方案一：复制，最保险，界面定稿前建议就用这个 cp -r ./custom ./src/ cp -r ./generated ./src/ # 方案二：软链，适合设计器频繁重新导出的阶段 # 注意相对路径的基准是链接所在目录，别写成绝对路径 ln -s ../../generated ./src/generated # 归位后立刻验证关键文件在不在 ls -l src/generated/gui_guider.h src/generated/events_init.h

ln -s的第一个参数是目标，第二个是链接名，写反了会得到一个指向空处的死链，症状是编译时说头文件不存在、但ls看着文件明明在。归位之后那条ls -l不要省，它会同时告诉你文件存在性和链接是否有效。

2.3 头文件搜索路径与 include 顺序

main里写的是#include "src/generated/gui_guider.h"，这个写法隐含了一个前提：编译器的 include 根目录是工程根，不是src。PC 上能编过，是因为顶层 CMake 恰好把工程根加进去了；换了交叉编译环境、或者子工程的相对路径变了，同样的代码就会报找不到文件。

# 顶层 CMakeLists.txt 里，把三个 include 根都显式声明，别依赖默认值 target_include_directories(${PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR} # 支持 "src/generated/xxx.h" 这种写法 ${CMAKE_CURRENT_SOURCE_DIR}/src # 支持 "generated/xxx.h" ${CMAKE_CURRENT_SOURCE_DIR}/src/generated ${CMAKE_CURRENT_SOURCE_DIR}/src/custom )

顺序有意义：CMake 会按声明顺序查找，同名头文件出现在两个目录时，排前面的赢。工程里如果有旧的lv_conf.h和设计器生成的配置并存，这一条就是玄学问题的来源——改了配置不生效，八成是另一份同名文件被先命中了。

PRIVATE表示这些路径只对当前目标可见。如果generated要被打成静态库给别的目标用，就得改成PUBLIC，否则下游链接时依然找不到符号声明。这一步改错的典型症状是：库编出来了，链接主程序时报undefined reference，而符号明明在库里——声明没传下去。

3. 交叉编译链：每一个 CMakeLists.txt 都要过一遍

工具链配错是移植里返工率最高的一环，而且它的失败形式很迷惑：有时候编出来的程序在板子上直接Illegal instruction，有时候是链接期报file format not recognized，还有时候编译一路顺利、上板发现调的是本机库。根源基本都是同一件事——工程里有多处写死了编译器路径，你只改了看得见的那一处。

3.1 用 toolchain 文件集中管，别散着改

能不逐个文件改就不逐个改。CMake 提供了 toolchain 机制，把编译器、sysroot、查找规则收在一个文件里，命令行用-DCMAKE_TOOLCHAIN_FILE引进去。这样即使子工程里写了set(CMAKE_C_COMPILER ...)，你也能通过 grep 快速定位并删掉。

# toolchain-arm-linux.cmake set(CMAKE_SYSTEM_NAME Linux) # 告诉 CMake 这是交叉编译，不设会走本机规则 set(CMAKE_SYSTEM_PROCESSOR arm) # 只影响部分库的架构判断，不影响实际编译器 set(CROSS_COMPILE /opt/toolchain/bin/arm-linux-gnueabihf-) set(CMAKE_C_COMPILER ${CROSS_COMPILE}gcc) set(CMAKE_CXX_COMPILER ${CROSS_COMPILE}g++) # sysroot 指向目标板的根文件系统副本，头文件和库都从这里找 set(CMAKE_SYSROOT /opt/toolchain/arm-linux-gnueabihf/sysroot) set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT}) # 关键三行：程序在本机找，库和头文件只在 sysroot 里找 set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

CMAKE_SYSROOT是最容易被忽略的一行。不设它，CMake 依然会用交叉编译器，但find_package、find_library会在本机的/usr/lib里翻，最后链上一个 x86 的.so，症状是链接期报格式不匹配，或者侥幸链上了、运行期加载失败。

CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER的意思是查找可执行程序时不去 sysroot 里找。交叉编译过程中要跑一些构建期工具（代码生成器之类），这些必须是本机能执行的，设成ONLY会直接卡在配置阶段。

路径这部分没有通用答案，用下面两条命令确认自己环境里的真实位置，别照抄示例。

# 确认交叉编译器在哪，输出应该是 /xxx/arm-xxx-gcc which arm-linux-gnueabihf-gcc # 确认 sysroot 位置，通常在工具链安装目录下，或从编译器自带的搜索路径里看 arm-linux-gnueabihf-gcc -print-sysroot

-print-sysroot返回空字符串说明这个工具链没配 sysroot，那就得手动指向板子的根文件系统副本。这一步省不得，后面所有关于库版本的疑惑都从这里来。

3.2 把写死工具链的地方全揪出来

拿到一个别人打包的工程，第一件事不是编译，是搜。打包件在原作者机器上能跑，很可能是因为他的工具链就在默认 PATH 里，CMake 顺手找到了，代码里那句写死的路径一直没暴露问题。

# 找出所有直接写死编译器/系统名的地方，这些都要么删掉、要么改成用 toolchain 变量 grep -rn --include=CMakeLists.txt \ -E "CMAKE_C_COMPILER|CMAKE_CXX_COMPILER|CMAKE_SYSTEM_NAME|CMAKE_SYSTEM_PROCESSOR" . # 看谁在 add_subdirectory，确认子工程不会自己重设工具链 grep -rn --include=CMakeLists.txt "add_subdirectory" . # 顺带查一下有没有硬编码的本机路径，这种在别人机器上必然失败 grep -rn --include=CMakeLists.txt -E "/home/|/usr/local/" .

第一条命令的输出就是你的修改清单。处理原则很简单：顶层CMakeLists.txt里的set(CMAKE_C_COMPILER ...)全部删掉，交给 toolchain 文件；子目录里的同样处理。留着也不是不能用，但它的执行时机在 toolchain 之后，会覆盖掉你精心写的配置，而报错信息不会告诉你「被覆盖了」，只会告诉你「编译失败」。

第三条命令查硬编码路径，这在打包件里很常见——原作者把某个第三方库的路径写成了自己家目录。这类行必须改成相对路径或find_library，否则换台机器就崩。

改完重新配置时，务必清干净缓存：

cd ~/lvgl_port rm -rf build # CMakeCache.txt 会记住上次的编译器，不清会沿用旧值 mkdir build && cd build cmake .. -DCMAKE_TOOLCHAIN_FILE=../toolchain-arm-linux.cmake make -j$(nproc)

rm -rf build这一步在原始流程里就有，不是多余动作。CMakeCache.txt里的CMAKE_C_COMPILER一旦写入就不会被新的-D参数改掉，很多人改了工具链却「没生效」，就是被这个缓存坑的。-j$(nproc)比写死-j12更稳，虚拟机只有 4 核的时候-j12会把内存打满，链接阶段直接被 OOM killer 干掉，报错信息还特别像代码问题。

3.3 产物校验：file、readelf、ldd 三件套

编译通过不等于产物正确。上板之前，用三条命令把产物验一遍，比在板子上抓瞎强得多。

# 看架构，期望输出里出现 ARM、32-bit 或 64-bit AArch64 file build/bin/your_app # 看 ELF 头，Machine 一行是权威答案 readelf -h build/bin/your_app | grep -E "Class|Machine|Type" # 看动态依赖，确认链的是目标板的库，不是本机的 readelf -d build/bin/your_app | grep NEEDED

file输出x86-64说明工具链根本没生效，回头查第 3.2 节的 grep 结果。readelf -h里Machine: ARM或AArch64才是对的，Class: ELF32对应 32 位工具链，和板子上的内核位数必须一致——32 位用户态程序能跑在 64 位内核上，反过来不行。

readelf -d的NEEDED列表要逐个看：出现libc.so.6是正常的，出现带版本号且板子上没有的库（比如libpng16.so.16）就得把对应功能裁掉，或者把库一起拷进板子的/usr/lib。这一条在板子上表现为error while loading shared libraries，很多人第一反应是编译参数问题，其实是依赖没对齐。

4. main 函数接线与屏幕参数：三行 UI 初始化代码的位置有讲究

setup_ui、events_init这两行的内容原样照抄没问题，位置放错就是灾难。它们依赖 LVGL 内核已经初始化、显示驱动已经注册，顺序一乱，轻则界面不显示，重则setup_ui里对空指针解引用直接段错误，而 core dump 里的调用栈会指向设计器生成的代码，让你误以为是导出的代码有 bug。

4.1 setup_ui、events_init 与 lv_init 的先后

一个能跑起来的最小main长这样，注释里标的是不可调换的原因。

#include "lvgl/lvgl.h" #include "src/generated/gui_guider.h" #include "src/generated/events_init.h" /* 全局变量，不要放栈上：UI 控件树的生命周期覆盖整个进程， 放栈上函数一返回指针就悬空，症状是随机崩溃 */ lv_ui guider_ui; int main(void) { lv_init(); /* 必须最先，任何 lv_* 调用都依赖它建好的内部状态 */ lv_port_disp_init(); /* 你的 framebuffer 对接层，注册 lv_disp_drv_t */ lv_port_indev_init(); /* 有触摸屏才需要，没有就删掉这行 */ setup_ui(&guider_ui); /* 建控件树，必须在 lv_init 和 disp_init 之后 */ events_init(&guider_ui); /* 绑事件回调，必须在 setup_ui 之后，否则回调找不到控件 */ while (1) { lv_timer_handler(); /* LVGL 的主心跳，内部处理动画、刷新、输入 */ usleep(5000); /* 5ms 一次，按 CPU 余量调，太短白烧 CPU，太长界面卡顿 */ } return 0; }

setup_ui和events_init传的是同一个guider_ui的地址，这两个函数内部会往结构体里填控件指针，之后你的业务代码也通过这个全局变量访问控件（比如guider_ui.screen_btn_1）。所以它必须是全局或静态的，这一点设计器生成的代码默认就按全局写，别自作主张改成局部变量。

events_init放在setup_ui之后是硬约束。事件绑定需要拿到控件对象，而控件是setup_ui里创建的。顺序反了不会立刻报错，但回调全部静默失效，你会以为是触摸驱动没工作——这个坑我见过不止一次，排查方向整个跑偏。

4.2 屏幕像素、色彩格式与 flush 回调的对齐

「修改屏幕像素」这句话在原始步骤里只有一行，实际涉及三个必须一致的值：分辨率、位深、像素格式。任何一个对不上，表现都是黑屏或者花屏，而且不报错。

上板之前先在板子上把 framebuffer 的真实参数读出来，别信设计器里的设置。

# 分辨率与虚拟分辨率 cat /sys/class/graphics/fb0/virtual_size # 每像素位数，常见 16 / 24 / 32 cat /sys/class/graphics/fb0/bits_per_pixel # 也可以用 fbset 看完整参数，注意没有这个命令时用上面两个文件代替 fbset -i 2>/dev/null | head -20

拿到参数后，对齐三处配置：

lv_conf.h里的LV_COLOR_DEPTH和 framebuffer 的位深必须一致。板子是 32 位 ARGB 而你按 16 位 RGB565 配，界面上每个像素的高低字节会被拆开解释，出来的效果就是大面积色块乱窜。这个错误最难往配置上想，因为编译期毫无提示。

flush 回调是对接层里唯一必须自己写的部分，逻辑就是把 LVGL 画好的缓冲区刷到/dev/fb0映射出来的内存上。

/* 简化版 flush，假设 fb 已 mmap 到 fb_mem，且 LV_COLOR_DEPTH 与 fb 位深一致 */ static void disp_flush(lv_disp_drv_t *drv, const lv_area_t *area, lv_color_t *color_p) { int32_t w = area->x2 - area->x1 + 1; int32_t h = area->y2 - area->y1 + 1; /* 逐行拷贝：framebuffer 一行有固定跨度，不能整块 memcpy */ for (int32_t y = 0; y < h; y++) { uint32_t *dst = fb_mem + (area->y1 + y) * fb_width + area->x1; memcpy(dst, color_p + y * w, w * sizeof(uint32_t)); } /* 必须调用，否则 LVGL 认为刷新没完成，不会再送下一帧 */ lv_disp_flush_ready(drv); }

逐行拷贝是因为 framebuffer 的行跨度由line_length决定，通常等于width * 字节数，但虚拟分辨率大于可见分辨率时就不是了，整块memcpy会错行。lv_disp_flush_ready漏掉的表现是界面只画了第一帧就再也不动，看起来像程序卡死，实际是 LVGL 在等确认。

4.3 剪掉只在 PC 模拟时用的库

打包件为了能在桌面直接跑，通常会链一批桌面专用的库：窗口后端、输入事件后端、甚至音频库。交叉编译时这些库在 sysroot 里根本不存在，find_package失败，配置阶段就卡住。

# 顶层 CMakeLists.txt，把桌面模拟相关的段落整块注释掉 # find_package(SDL2 REQUIRED) # target_link_libraries(${PROJECT_NAME} PRIVATE SDL2::SDL2) # 只保留目标板真正需要的：显示走 framebuffer，输入走 evdev，都不需要额外链库 target_link_libraries(${PROJECT_NAME} PRIVATE m # LVGL 内部用 pow/sqrt 之类的数学函数 pthread # lv_timer_handler 里如果启用了多线程渲染才需要 )

注释而不是删除，是为了保留随时回 PC 模拟的能力。切换时用 CMake 选项控制比手工改文件干净：

option(BUILD_FOR_PC "build with desktop simulator backend" OFF) if(BUILD_FOR_PC) find_package(SDL2 REQUIRED) target_link_libraries(${PROJECT_NAME} PRIVATE SDL2::SDL2) endif()

option的默认值设成OFF，交叉编译时什么都不用加；想跑模拟就cmake .. -DBUILD_FOR_PC=ON。这样同一份源码在两个环境之间来回切，不用 git stash 也不用担心把改好的工具链配置覆盖掉。

顺手把不需要的组件也关掉，能省不少体积：

/* lv_conf.h，按板子资源裁剪，关掉用不上的组件和字体 */ #define LV_USE_CHART 0 /* 没有图表需求就关，省几 KB */ #define LV_USE_ANIMIMG 0 #define LV_FONT_MONTSERRAT_24 1 /* 只留实际用到的那几号字 */ #define LV_FONT_MONTSERRAT_20 0

字体是体积大户，一份 24 号字库动辄几十 KB。全开会把可执行文件顶到好几 MB，而嵌入式板子的 rootfs 分区可能就给了 64MB。关掉时注意别把界面里真在用的字号关了，症状是编译通过、运行到那个控件时段错误或者不显示文字。

5. 避坑排查：编过、跑过、还是黑屏的五条记录

下面五条都是实际踩过的，按发生频率排序。每条都给出可验证的判断依据，别靠猜。

第一条：链接期报undefined reference to lv_...。现象是 LVGL 的库文件明明编出来了，主程序链接时却找不到符号。原因九成是target_link_libraries里漏了 LVGL 目标，或者lv_conf.h里的LV_USE_XXX宏没打开导致对应源文件根本没参与编译。解决方式是先确认lvgl目标的编译产物在不在，再回去核对宏开关；带LV_USE_前缀的符号缺失，优先查配置而不是查链接顺序。

第二条：板子上执行报cannot execute binary file或Illegal instruction。现象很直接，程序传上去一跑就被内核拒绝。原因是用本机 gcc 编出了 x86 产物，或者工具链的浮点 ABI 和板子不匹配（硬浮点程序跑在软浮点系统上）。解决方式是先用file和readelf -h确认架构，再确认工具链的 ABI 后缀（gnueabihf和gnueabi不能混用）；两者都对了还报错，就看内核位数与 ELF Class 是否一致。

第三条：程序正常启动、串口无报错，屏幕全黑。这是最耗时间的一种。原因是 framebuffer 的参数和配置对不上，或者 flush 回调里漏了lv_disp_flush_ready。排查顺序是：先cat /sys/class/graphics/fb0/bits_per_pixel确认位深，再往/dev/fb0里dd一段纯色数据看屏幕有没有反应——这一步能把「驱动问题」和「LVGL 配置问题」彻底分开，屏幕有反应说明驱动没问题，问题在 LVGL 侧。

第四条：运行几秒到几十秒后段错误，core dump 指向设计器生成的代码。原因是lv_ui guider_ui被写成了局部变量，或者lv_timer_handler没在主线程里调、却开了多线程渲染。解决方式是把guider_ui改成全局，并检查lv_conf.h里LV_USE_OS的设置是否和你的线程模型一致；单线程裸跑就把 OS 支持关掉，别半开半关。

第五条：中文显示成方块，英文正常。原因是字库里只有 ASCII 字形，或者LV_FONT_...对应的中文字库没启用。设计器导出的界面如果用了中文，字体文件必须一起带过来，并且在lv_conf.h里打开对应字号。解决方式是把中文字库的.c文件加进编译，确认lv_font_t结构体被正确引用；体积允许的话用子集化工具只保留用到的字，能省掉大半体积。

这五条的共同点是：编译期都不会报错。所以从make成功到程序真正跑起来，中间必须有一段主动验证——上板前验产物架构，上板后先验 framebuffer，再验 UI。跳过验证直接跑，遇到问题时你连是「没编对」还是「跑不对」都分不清。

6. 上板验证与调优：从 build/bin 到长时间稳定跑

编译产物在build/bin下，传到板子上的方式按你手头的通道选，串口sz、SSH 的scp、或者挂载 NFS 都行。我一般用scp，因为改一版传一版最快。

# 传到板子的临时目录，先别覆盖正式程序 scp build/bin/your_app root@<board-ip>:/tmp/ # 上板后先给执行权限，再前台跑一次，把日志直接看在串口上 ssh root@<board-ip> "chmod +x /tmp/your_app && /tmp/your_app"

第一次跑一定放前台，不要直接丢后台。前台的崩溃信息、printf输出、内核 Oops 都会打到同一个终端上，这是最省事的调试姿态。等确认稳定了再考虑做成开机自启。

调优有几项性价比很高，按投入产出排：

strip前后体积差常常有一半以上，但一定要留一份带符号的原始产物，否则现场崩溃只能靠猜。这个习惯值不值得养成，等你第一次在客户现场拿到一个没有符号表的 core dump 就知道了。

最后一件事是时钟源。LVGL 的动画、超时都依赖 tick，默认实现如果用的是clock()或者精度很低的接口，动画会一抖一抖。板子上有clock_gettime(CLOCK_MONOTONIC)就用它，这是单调时钟，不受系统时间调整影响。

/* lv_tick 的自定义实现，注册到 lv_tick_set_cb 或直接覆盖弱符号 */ uint32_t my_tick_get(void) { struct timespec ts; clock_gettime(CLOCK_MONOTONIC, &ts); /* 毫秒精度足够，LVGL 内部按 32 位回绕处理，不用担心溢出 */ return (uint32_t)(ts.tv_sec * 1000 + ts.tv_nsec / 1000000); }

用CLOCK_REALTIME也能跑，但设备一旦对时，时间跳变会让所有定时器瞬间失效或者集体触发，界面表现是突然卡住再猛跳一下。这类问题在现场极难复现，因为要刚好卡在对时那一刻。

从那以后，我每次移植完都会强制走一遍固定动作：file验架构、readelf -d验依赖、上板后先dd一段纯色验 framebuffer、最后才跑 UI。这四步花不了五分钟，能省掉大半天在「到底是没编对还是没跑对」之间反复横跳的时间。希望帮到你。

本文还有配套的精品资源，点击获取