3. 源码获取与结构分析：从GitHub克隆Marlin，解读核心目录与文件结构
好，咱们正式开始动手。上一章我们把环境搭好了，现在该去拿真正的源码了。我个人习惯，不管做什么移植，第一件事就是先把官方仓库的脉络摸清楚。你想想看，连代码怎么组织的都不知道，后面改起来肯定抓瞎。
3.1 从GitHub获取Marlin源码
Marlin的官方仓库在GitHub上，地址是：https://github.com/MarlinFirmware/Marlin。我建议你直接用git clone，别下载zip包。为什么？因为后续你要跟踪官方更新、切分支、做补丁，git操作会方便得多。
git clone https://github.com/MarlinFirmware/Marlin.git
cd Marlin
git checkout bugfix-2.1.x # 我推荐用这个分支，修复比较及时克隆完之后，你会看到这样的目录结构（我截取了最核心的部分）：
Marlin/
├── Marlin/ # 核心固件代码
│ ├── src/ # 源代码主目录
│ ├── Configuration.h # 主配置文件
│ ├── Configuration_adv.h # 高级配置文件
│ └── ...
├── buildroot/ # 构建系统相关
├── platformio.ini # PlatformIO项目配置
└── ...3.2 核心目录结构解读
嗯，这里要注意，Marlin的目录结构经过多次重构，现在已经很清晰了。我刚开始接触的时候还是老版本，所有代码堆在一起，找个头文件都要翻半天。现在的结构好多了。
3.2.1 Marlin/src/ — 灵魂所在
这是整个固件的核心，所有C++源文件都在这里。我把它分成几个关键子目录：
| 子目录 | 作用 | 我重点关注什么 |
|---|---|---|
core/ |
核心数据类型、宏定义、串口通信 | Marlin.h、serial.h — 几乎每个文件都会引用 |
module/ |
运动控制、温度控制、限位开关等模块 | planner.cpp、stepper.cpp、temperature.cpp — 移植时经常要改 |
HAL/ |
硬件抽象层，不同平台的底层实现 | 这是移植工作的主战场！ |
feature/ |
高级功能，如ABL、WiFi、RGB灯效 | 按需启用，不用的别编译进去 |
lcd/ |
屏幕驱动和UI逻辑 | 如果你的板子有特殊屏幕，这里要动 |
HAL/ 目录下。其他目录尽量不动，保持与官方同步。
3.2.2 Marlin/Configuration.h 与 Configuration_adv.h
这两个文件是Marlin的「开关面板」。说白了，你不需要改底层代码就能控制大部分行为。比如：
- 定义主板型号：
#define MOTHERBOARD BOARD_RAMPS_14_EFB - 设置热床温度上限：
#define BED_MAXTEMP 120 - 启用自动调平：
#define AUTO_BED_LEVELING_BILINEAR
我曾经遇到一个坑：有人把配置改得乱七八糟，结果编译报错几百行。其实大部分错误都是宏定义冲突。我的建议是：第一次先保持默认配置，能编译通过再一项一项改。
3.2.3 buildroot/ 与 platformio.ini
这两个是构建系统的配置。如果你用PlatformIO（我强烈推荐），主要看platformio.ini。里面定义了：
- 目标平台（如
env:mega2560） - 编译选项
- 串口监视器设置
举个例子，你要为STM32F407VE编译，就在platformio.ini里加上：
[env:STM32F407VE]
platform = ststm32
board = genericSTM32F407VE
framework = arduino
build_flags = -DMOTHERBOARD=BOARD_STM32F407VEplatformio.ini。我习惯复制一份，比如platformio_custom.ini，然后用pio run -e my_env指定。这样官方更新时不会冲突。
3.3 核心逻辑框架图
下面这张图是我自己画的，帮你理解Marlin的代码是怎么「转起来」的。从硬件中断到G-code解析，再到运动规划，每一步都有对应的模块。
这张图你看懂了吗？数据流是从下往上的：硬件中断触发 → 核心模块处理 → G-code解析 → 应用层响应。移植的时候，你只需要动最下面那层HAL，上面的逻辑基本不用碰。
3.4 文件结构速查表
为了方便你快速定位，我整理了一份速查表。遇到问题直接查这个表，比翻文档快多了。
| 文件/目录 | 路径 | 什么时候需要改 |
|---|---|---|
| 主配置 | Marlin/Configuration.h |
每次移植必改，定义板型和功能 |
| 高级配置 | Marlin/Configuration_adv.h |
需要高级功能时改，如线性调平 |
| HAL实现 | Marlin/src/HAL/你的平台/ |
移植新平台的核心工作区 |
| 引脚定义 | Marlin/src/pins/你的板子.h |
板子引脚布局不同时改 |
| 构建配置 | platformio.ini |
添加新编译环境时改 |
Configuration.h 和 pins/ 下的文件。能编译通过、能点亮屏幕，就算成功了一半。别一上来就动HAL，那是后面优化的事。
3.5 避坑指南
最后分享几个我踩过的坑：
- 分支选错： 我曾经在
bugfix-2.0.x上改了三天，结果发现官方已经切到2.1了。现在我一直用bugfix-2.1.x，修复及时，社区活跃。 - 配置文件遗漏： 有些人只改了
Configuration.h，忘了Configuration_adv.h里还有一堆开关。结果编译通过，但功能不正常。我的习惯是：两个文件都过一遍，把不需要的关掉。 - HAL目录结构不熟： 刚开始我以为HAL就一个文件夹，后来发现每个平台还有自己的子目录。比如
HAL/STM32下面还有HAL/STM32/F4、HAL/STM32/F1。别找错地方。
嗯，源码结构就讲到这里。你只要把上面这些目录和文件的关系理清楚，后面移植的时候就不会迷路。记住：HAL是核心，配置是开关，其他模块尽量不动。