3、获取LVGL源码：从GitHub下载LVGL、了解LVGL的目录结构、选择正确的Release版本
好，咱们正式开始动手。这一章要解决一个最基础的问题——源码从哪来、怎么选、拿到手之后长什么样。
你可能觉得这步没什么技术含量，不就是点个下载按钮嘛。但我见过太多人在这一步翻车：下载了最新的开发分支，结果编译一堆报错；或者随便找了个旧版本，发现缺了一堆关键API。嗯，这里确实有讲究。
3.1 从GitHub获取LVGL源码
LVGL的官方仓库在GitHub上，地址是 https://github.com/lvgl/lvgl。我个人习惯直接走Git克隆，因为后续更新方便，但如果你只是快速评估，下载ZIP包也行。
两种方式对比
| 方式 | 命令/操作 | 适用场景 |
|---|---|---|
| Git克隆 | git clone https://github.com/lvgl/lvgl.git |
长期开发、需要跟踪更新 |
| 下载ZIP | GitHub页面 → Code → Download ZIP | 快速评估、一次性使用 |
如果你用Git克隆，记得加上 --recursive 参数拉取子模块。LVGL依赖一些第三方库（比如 lv_drivers），不拉子模块后面编译会缺文件。
git clone --recursive https://github.com/lvgl/lvgl.git我的习惯：克隆完成后，先切到一个干净的tag再开始工作。这样能保证你手里的代码和文档、教程完全对应，不会因为master分支的频繁变动而出问题。
3.2 选择正确的Release版本
LVGL的版本号遵循语义化版本规则：主版本.次版本.补丁。比如 v8.3.11，8是主版本，3是次版本，11是补丁号。
为什么版本选择这么重要？我曾经接手过一个项目，对方用了v7.11的代码，但参考的是v8的文档，结果API对不上，折腾了两天才发现是版本不匹配。说白了，LVGL每个大版本之间API变化很大，尤其是v7到v8、v8到v9，很多函数名和结构体都改了。
我的建议：
- 新项目：选最新的稳定Release。写这篇文章时，推荐
v8.3.x或v9.0.x（取决于你的硬件资源）。v8生态成熟，资料多；v9性能更好，但部分驱动需要自己适配。 - 老项目维护：保持原有大版本，只升级补丁号。比如从v8.3.0升到v8.3.11，修复bug但不改API。
- 学习阶段：选v8.3.x，文档最全，社区案例最多。
避坑指南：千万不要直接下载master分支的最新commit。那个是开发中的代码，可能今天能编译，明天就报错。我曾经在master上踩过坑，一个结构体字段名被改了，但文档还没更新，排查了整整一个下午。
3.3 了解LVGL的目录结构
下载完源码，咱们来看看里面都有什么。你打开 lvgl 文件夹，会看到这样的结构：
lvgl/
├── docs/ # 文档（HTML格式，可本地打开）
├── examples/ # 示例代码，快速上手用
├── scripts/ # 构建脚本、代码生成工具
├── src/ # 核心源码，最重要的目录
│ ├── core/ # 核心对象、事件、动画等
│ ├── draw/ # 绘图引擎、渲染器
│ ├── fonts/ # 字体引擎和内置字体
│ ├── hal/ # 硬件抽象层（显示、触摸、时钟）
│ ├── layouts/ # 布局引擎（Flex、Grid）
│ ├── libs/ # 第三方库（如png解码、freetype）
│ ├── misc/ # 杂项工具（日志、内存、数学）
│ ├── themes/ # 默认主题
│ └── widgets/ # 所有控件（按钮、标签、滑块等）
├── tests/ # 单元测试
├── library.json # 用于PlatformIO的配置文件
├── lv_conf_template.h # 配置文件模板（必须复制并改名）
└── lvgl.h # 主头文件，包含所有API你不需要记住每个文件夹，但有几个关键点必须清楚：
src/：所有核心代码都在这里。移植时你主要跟hal/和misc/打交道。lv_conf_template.h：这是配置文件的模板。你需要把它复制到项目根目录，改名为lv_conf.h，然后根据硬件配置开关。lvgl.h：你的应用程序只需要包含这一个头文件，它会自动引入所有需要的模块。
一个小技巧：我习惯把 lv_conf.h 放在项目根目录，而不是放在lvgl源码目录里。这样升级lvgl版本时，配置文件不会被覆盖，只需要重新检查新增的配置项。
3.4 核心目录关系图
下面这张图展示了LVGL源码中几个核心模块之间的关系。你看完就能明白，移植时到底要动哪些地方。
从这张图你能看到，你的应用程序通过 lvgl.h 进入LVGL世界，lv_conf.h 控制哪些功能开启或关闭，而真正干活的是 src/ 下的各个模块。移植时你主要跟 hal/ 打交道——它负责把LVGL和你的硬件连接起来。
3.5 快速验证：确认你拿到的源码是完整的
下载完成后，我建议你做一次快速验证，确保源码没有损坏或遗漏：
- 检查
lvgl.h是否存在，这是主入口文件。 - 检查
src/hal/目录下是否有lv_hal_disp.h、lv_hal_indev.h、lv_hal_tick.h这三个文件。它们是移植的核心。 - 检查
lv_conf_template.h是否存在。如果没有这个文件，你后面没法配置LVGL。 - 如果你用Git克隆，执行
git tag --list看看是否有版本标签。如果没有，说明你克隆的可能不是完整仓库。
我曾经遇到的情况：有一次从GitHub下载ZIP包，网络中断导致文件不完整，编译时报了一堆莫名其妙的“未定义引用”。排查了半天，最后发现是 src/draw/ 目录下少了一个文件。所以下载完成后，最好对比一下文件数量和官方仓库是否一致。
3.6 本章小结
这一章我们做了三件事：从GitHub获取源码、选择正确的Release版本、了解目录结构。说白了，就是让你拿到一份干净、可用、版本匹配的源码，并且知道每个文件夹是干什么的。