3. 顶层目录结构解析：src、Marlin、build、config 等核心目录的功能划分
拿到一份 Marlin 源码，第一眼看到那一堆文件夹，很多人会懵。我刚开始接触的时候也一样，对着根目录发了好一会儿呆。其实 Marlin 的顶层目录划分非常清晰，每个文件夹各司其职。今天我就带你把这些「地盘」挨个走一遍。
3.1 src/ —— 真正的「发动机舱」
src/ 是 Marlin 的核心源码所在。说白了，所有控制逻辑、运动规划、温度管理、G-code 解析，全塞在这里面。我个人习惯把 src/ 比作汽车的发动机舱——你平时不用打开它，但所有动力都从这儿来。
打开 src/，你会看到一堆子目录：
- inc/：全局头文件，各种宏定义、条件编译开关。嗯，这里要注意，很多新手改配置时找不到定义，其实都在
inc/里。 - core/：核心数据结构，比如
Marlin.h、hal/（硬件抽象层）。 - module/：功能模块，像
stepper.cpp（步进电机）、temperature.cpp（温度控制）、endstops.cpp（限位开关）。 - gcode/：G-code 解析器，每个 G/M 指令对应一个处理函数。
- feature/：可选功能，比如
babystep、filament_sensor、bltouch。
避坑指南： 我曾经在移植 Marlin 到一块新主控板时，死活编译不过。查了两天，最后发现是 src/core/ 下的 boards.h 里没有定义我的板子型号。所以，如果你要添加新主板，第一件事就是去 src/core/boards.h 注册一个宏。
3.2 Marlin/ —— 主逻辑与配置的「指挥中心」
这个目录名字和顶层目录重名，容易搞混。顶层 Marlin/ 是整个项目根，而这里的 Marlin/ 子目录存放的是主程序入口和配置文件模板。
里面最重要的两个文件：
Marlin.cpp：主循环loop()所在，负责调度所有模块。你想想看，打印机每毫秒该干什么，全由这个文件决定。Configuration.h和Configuration_adv.h：这两个是配置文件的「本体」。很多人以为配置在config/里，其实那只是示例。真正生效的是Marlin/下的这两个文件。
我的习惯： 每次拿到新固件，我会先把 config/examples/ 里对应机型的配置复制到 Marlin/ 目录下，覆盖默认文件。这样能省掉 80% 的配置时间。
3.3 build/ —— 编译的「工地」
build/ 是编译过程中生成的临时文件存放地。包括 .o 目标文件、.elf 可执行文件、.hex 烧录文件等。
这个目录有几个特点：
- 自动生成：你不需要手动创建它，PlatformIO 或 Make 会自动生成。
- 可以删除：如果编译遇到奇怪的问题，比如改了代码但没生效，我建议你删掉
build/目录，重新编译。这叫「清洁构建」，能解决 90% 的玄学问题。 - 不要提交到 Git：这个目录应该写在
.gitignore里。
注意： 有些新手把 build/ 里的 .hex 文件直接发给别人用，这是有风险的。因为 build/ 里的固件是基于你当前配置生成的，换一块板子可能就 brick 了。正确的做法是分享源码和配置，而不是编译产物。
3.4 config/ —— 官方配置「样板间」
config/ 目录下存放的是 Marlin 官方为各种机型预置的配置文件。结构如下：
| 子目录 | 内容 |
|---|---|
examples/ |
按厂商/机型分类的配置示例，比如 Creality/Ender-3、Prusa/i3 |
default/ |
通用默认配置，适合从头开始定制 |
releases/ |
每个发布版本的快照配置 |
我个人建议：不要直接修改 config/examples/ 里的文件。正确的做法是复制一份到 Marlin/ 目录下再改。这样万一改坏了，还能从 config/ 里找回原始版本。
3.5 lib/ —— 第三方库的「仓库」
lib/ 存放的是 Marlin 依赖的第三方库和硬件抽象层（HAL）代码。比如：
- LiquidCrystal：LCD 屏幕驱动库
- U8glib：图形化屏幕库
- HAL 文件夹：针对不同 MCU 平台的底层实现，比如
HAL_STM32、HAL_AVR、HAL_LPC1768
这里有个关键点：lib/ 里的代码通常不需要你修改。但如果遇到硬件兼容性问题，比如换了一个不常见的屏幕，你可能需要去 lib/ 里找对应的驱动文件，看看有没有需要调整的时序参数。
3.6 platformio.ini —— 构建系统的「总开关」
这个文件不在任何子目录里，就在根目录下。它是 PlatformIO 的配置文件，定义了：
- 目标开发板（
board） - 编译环境（
env） - 串口波特率、烧录方式等
举个例子，一段典型的 platformio.ini 配置：
[env:mega2560]
platform = atmelavr
board = mega2560
framework = arduino
monitor_speed = 250000
build_flags = -DMOTHERBOARD=BOARD_RAMPS_14_EFB这里 build_flags 里的 -DMOTHERBOARD 就是告诉编译器用哪块主板定义。你想想看，如果没有这个文件，编译器连用哪个芯片都不知道。
避坑指南： 我曾经帮一个朋友调试，他编译总是报错说找不到某个 HAL 函数。我一看，他的 platformio.ini 里 board 写的是 mega2560，但实际用的是 STM32 板子。所以，platformio.ini 是第一个要检查的文件，别让它背锅。
3.7 其他目录与文件
除了上面几个核心目录，根目录下还有一些辅助文件：
ini/：存放 PlatformIO 的扩展配置，比如不同环境的预定义。docs/：文档目录，不过内容通常比较简略。.github/：GitHub Actions 的 CI/CD 配置，用于自动化测试。Makefile：如果你不用 PlatformIO，也可以用 Make 编译。不过现在用 PlatformIO 是主流。
嗯，到这里，Marlin 的顶层目录结构你应该心里有数了。每个目录都有自己的职责，互不干扰。下次你拿到一份 Marlin 源码，至少知道该去哪个文件夹找什么东西。这就像你熟悉了家里的布局，找东西自然快得多。