试用 LVGL Pro,一套完整的工具包,助您高效构建、测试、分享和交付 UI!
LVGL
公告

50 行代码上手 LVGL v9.6

LVGL v9.6 如何在 CMake 构建时自动查找并拉取可选依赖,以及背后的 lv_conf.h 预处理机制。

安德烈·科斯塔安德烈·科斯塔7 分钟阅读
50 行代码上手 LVGL v9.6

LVGL 核心本身没有任何外部依赖,但不少可选功能需要链接系统库:桌面模拟器需要 SDL2,JPEG 解码需要 libjpeg-turbo, Linux DRM 显示输出需要 libdrm,等等。 在此之前,这意味着你要自己安装每一个库,确保 LVGL 能找到它们,并让这些配置和 lv_conf.h 中启用的功能保持一致。 这样做当然可行,但仅仅为了跑起来就要花不少功夫。

从 v9.6 开始,只要配合 CMake 使用,LVGL 就能替你管理全部外部依赖。它会自动在系统中定位所需依赖,找不到时则从源码拉取并构建。 举例来说,如果你使用 SDL2 模拟器,构建前不需要单独安装 SDL2。

我们先把一个项目跑起来,再看它是如何工作的。

两分钟上手#

下面是一个最小项目,使用 SDL2 后端让 LVGL 跑在桌面上,无需手动安装 SDL2。

1. 创建项目结构

lvgl_demo
  • CMakeLists.txt
  • lv_conf.h
    • main.c

2. 在 lv_conf.h 中启用 SDL

lv_conf.h
#ifndef LV_CONF_H
#define LV_CONF_H
#define LV_USE_SDL 1
#endif
c

3. 在 src/main.c 中初始化 SDL 驱动并创建界面

src/main.c
#include <lvgl.h>
#include <stdlib.h>
#include <time.h>
 
int main(void)
{
    lv_init();
 
    lv_display_t * disp = lv_sdl_window_create(800, 600);
    if(!disp) {
        return EXIT_FAILURE;
    }
    lv_sdl_mouse_create();
 
    lv_obj_t * button = lv_button_create(lv_screen_active());
    lv_obj_t * label  = lv_label_create(button);
    lv_label_set_text_static(label, "Click Me!");
    lv_obj_center(button);
 
    while(1) {
        lv_timer_handler();
        lv_sleep_ms(5);
    }
 
    return EXIT_SUCCESS;
}
c

4. 添加 CMakeLists.txt

CMakeLists.txt
cmake_minimum_required(VERSION 3.18)
project(lvgl_demo_dependency_fetching)
 
include(FetchContent)
 
set(LV_BUILD_SET_CONFIG_OPTS ON CACHE BOOL "" FORCE)
 
FetchContent_Declare(
  lvgl
  GIT_REPOSITORY https://github.com/lvgl/lvgl.git
  GIT_TAG eaeed76889bd35cf9c0d9cca192bce90ed647bf3
  GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(lvgl)
 
add_executable(main src/main.c)
target_link_libraries(main lvgl)
cmake

这里的关键是 LV_BUILD_SET_CONFIG_OPTS。设置之后,LVGL 会在配置阶段读取你的 lv_conf.h, 发现 LV_USE_SDL 已启用,然后自行完成 SDL2 的查找或拉取。 你自己的 CMake 文件中不需要写 find_package(SDL2) 或 pkg_check_modules。

5. 构建并运行

cmake -B build
cmake --build build -j$(nproc)
./build/main
bash

就是这样。如果系统里已经装了 SDL2,它会被自动找到;如果没有,LVGL 会在配置阶段拉取源码并构建它。

本文接下来会讲清楚配置阶段究竟发生了什么,以及在你需要时如何重新掌控它。

LVGL 如何读取你的配置#

这一切的前提是 CMake 能够看到 lv_conf.h 里的内容。这部分能力早在 LVGL v9.3.0 就已经引入:通过 CMake 自动预处理 lv_conf.h。 启用后,lv_conf.h 会在配置阶段经过 C 预处理器,转换成一个 .cmake 文件,让 CMake 可以直接读取你的配置, 无需在 lv_conf.h 和 CMakeLists.txt 之间手动同步。

这带来了两个很实用的能力:

  • 根据 lv_conf.h 中启用的选项,有条件地包含或排除源文件
  • 只查找并链接真正需要的依赖

启用方式是设置 CMake 变量 LV_BUILD_SET_CONFIG_OPTS(就像上面的项目那样),并确保系统中有 python3, 以及 python3-venv 或 pcpp 其中之一。 如果使用 Kconfig 作为配置系统,这项功能会自动启用。

依赖解析的过程#

一旦 CMake 知道启用了哪些功能,它也就知道构建需要哪些库。对每一个可选依赖,LVGL 会依次尝试三种策略:

  1. find_package,CMake 的标准机制
  2. pkg-config,适用于提供 .pc 文件的库
  3. 从源码拉取,即在构建过程中克隆并编译该依赖
警告

并非所有依赖都支持源码拉取。

关闭自动解析#

如果你更愿意自己管理某个依赖,上述每一种策略都可以单独关闭。

针对单个依赖关闭:

cmake -B build \
  -DLV_USE_FIND_PACKAGE_SDL2=OFF \ # 不对 sdl2 使用 cmake 的 find_package
  -DLV_USE_PKG_CONFIG_SDL2=OFF \   # 不对 sdl2 使用 pkg-config
  -DLV_FETCH_SDL2=OFF              # 不为 sdl2 拉取源码
bash

或者全局关闭:

cmake -B build \
  -DLV_USE_FIND_PACKAGE=OFF \ # 不使用 cmake 的 find_package
  -DLV_USE_PKG_CONFIG=OFF \   # 不使用 pkg-config
  -DLV_FETCH_DEPENDENCIES=OFF # 不从源码拉取
bash

起点:Linux 移植版#

lvgl/lv_port_linux

LVGL configured to work on Linux (Wayland, DRM, EGL, OpenGL, fbdev, X11 etc)

C474265

这些能力并不是先出现在 LVGL 自己的仓库里的。lv_port_linux 是率先探索这一方式的移植版本, 它引入了模块化构建:只有在对应的配置选项被启用时,相关依赖才会被引入。下面是 DRM 支持的例子:

CMakeLists.txt
if(CONFIG_LV_USE_LINUX_DRM)
  message("Including DRM support")
  find_package(PkgConfig REQUIRED)
  pkg_check_modules(LIBDRM REQUIRED libdrm)
  list(APPEND PKG_CONFIG_LIB ${LIBDRM_LIBRARIES})
  list(APPEND PKG_CONFIG_INC ${LIBDRM_INCLUDE_DIRS})
  list(APPEND LV_LINUX_BACKEND_SRC src/lib/display_backends/drm.c)
endif()
cmake

如果启用了 LV_USE_LINUX_DRM,这段代码会尝试通过 pkg-config 找到 libdrm,并把它链接进最终的可执行文件。

如果配置中没有启用它,整段代码就是空操作,构建机器上也不需要安装 libdrm。

这套做法效果不错,因此在 v9.6 中它被搬进了 LVGL 自身,并在此基础上加入了源码拉取。 这样每个项目都能直接受益,不必再手写上面那样的代码块。

小结#

欢迎试用。如果遇到任何问题,请在 github.com/lvgl/lvgl/issues 提交 issue 告诉我们。

这是「在 Linux 上构建与分发 LVGL」系列的第一篇。下一篇:既然 LVGL 已经清楚自己链接了哪些库, 它就可以把这些信息交给你项目中已经在用的工具。

在 Linux 上构建与分发 LVGL第 1 部分,共 4 部分

常见问题#

关于作者

安德烈·科斯塔
安德烈·科斯塔

LVGL Open 团队负责人

LVGL Open 团队负责人,推动开源嵌入式图形库的开发和应用。

认识博客背后的作者们

了解那些分享 LVGL 知识的优秀作者们

查看作者

订阅我们的通讯 不错过任何关于 LVGL 的新闻。我们每月最多发送 2 封邮件。

LVGL

LVGL 是最受欢迎的免费开源嵌入式图形库,支持任何 MCU、MPU 和显示类型,助您构建精美的用户界面。

我们还提供 UI 设计、实现和咨询等服务。

© 2026 LVGL。保留所有权利。
YouTubeGitHubLinkedIn