3、PX4源码下载与结构：Git clone、子模块更新、源码目录解析

好，咱们正式开始动手了。这一章我带你把PX4源码从GitHub上拉下来，再把目录结构捋一遍。说实话，很多新手卡在这一步——不是下载失败，就是编译报错，最后发现是子模块没更新。嗯，咱们一步步来。

3.1 准备工作：环境确认

在敲命令之前，先确认你的机器上已经装好了Git。我个人习惯用终端操作，Windows用户建议用Git Bash或者WSL。如果你用的是Ubuntu，直接终端就行。

💡 我的小建议： 别用Windows自带的cmd去搞Git操作，编码问题会让你怀疑人生。我踩过这个坑，后来老老实实换了Git Bash。

确认Git版本：

git --version

输出类似 git version 2.25.1 就说明没问题。如果没装，去官网下一个，或者Ubuntu下跑一句：

sudo apt install git

3.2 Git clone：把源码拉下来

PX4官方仓库地址是 https://github.com/PX4/PX4-Autopilot.git。我建议你克隆的时候加上 --recursive 参数，这样会把子模块一起拉下来。不过说实话，我更喜欢分两步走——先克隆主仓库，再单独更新子模块。为什么？因为网络不好的时候，一次性拉完容易超时，分开搞反而更稳。

先克隆主仓库：

git clone https://github.com/PX4/PX4-Autopilot.git

这个过程取决于你的网速。我当年在学校实验室拉这个仓库，用了将近半小时。现在网络好多了，一般几分钟搞定。

⚠️ 注意： 如果你在公司内网或者有代理的环境，记得先配好Git代理。我曾经因为没配代理，卡在克隆阶段整整一下午，最后发现是防火墙把Git的端口封了。

克隆完成后，你会看到一个 PX4-Autopilot 文件夹。进去看看：

cd PX4-Autopilot
ls -la

3.3 子模块更新：这一步不能省

PX4依赖很多第三方库，比如 mavlink、uavcan、eigen 等等。这些库以子模块（submodule）的形式挂在主仓库下面。如果你克隆的时候没加 --recursive，那这些子模块的目录是空的。

更新子模块的命令：

git submodule update --init --recursive

解释一下这三个参数：

  • --init：初始化子模块配置文件
  • --recursive：递归更新嵌套的子模块

这个过程同样需要联网。你可能会看到类似这样的输出：

Submodule 'Tools/jMAVSim' (https://github.com/px4/jMAVSim.git) registered for path 'Tools/jMAVSim'
Cloning into '/home/user/PX4-Autopilot/Tools/jMAVSim'...
Submodule path 'Tools/jMAVSim': checked out 'abc123...'
🔑 关键点： 子模块更新完成后，每个子模块都处于 detached HEAD 状态。这是正常的，不要慌。你不需要在子模块里做任何修改，除非你要调试仿真器或者底层驱动。

我遇到过一种情况：子模块更新到一半网络断了，再跑一次 git submodule update 会报错。解决办法是先把子模块目录删掉，重新来一遍：

rm -rf Tools/jMAVSim
git submodule update --init --recursive

3.4 源码目录解析：别被文件夹吓到

好，现在源码已经完整地躺在你硬盘上了。我第一次打开PX4目录的时候，说实话有点懵——文件夹太多了。但别怕，核心目录其实就那么几个。我带你捋一遍。

目录/文件 作用 我的备注
src/ 核心源代码，包括飞控逻辑、驱动、模块 你改代码主要在这里
boards/ 各种硬件板级的配置文件 换飞控板时重点关注
cmake/ 编译系统的配置文件 加新功能时可能要改这里
ROMFS/ 文件系统镜像，存放启动脚本和参数 改启动参数时用
Tools/ 仿真工具、地面站、调试脚本 jMAVSim和Gazebo在这里
msg/ uORB消息定义文件 自定义话题时必看
mavlink/include/mavlink/v2.0 MAVLink协议定义 一般不动，除非改协议
Makefile 顶层编译入口 编译命令都通过它

3.5 深入 src/ 目录

src/ 是核心中的核心。咱们再往下挖一层：

src/
├── drivers/       # 各种传感器、执行器驱动
├── modules/       # 功能模块（姿态估计、位置控制、导航等）
├── lib/           # 通用库函数
├── systemcmds/    # 系统命令（如param、top、listener）
├── examples/      # 示例代码，新手入门的好东西
└── platforms/     # 平台相关代码（POSIX、NuttX等）

我个人觉得，modules/ 是你要花最多时间的地方。比如：

  • modules/ekf2/：扩展卡尔曼滤波器，负责姿态和位置估计
  • modules/mc_pos_control/：多旋翼位置控制
  • modules/mc_att_control/：多旋翼姿态控制
💡 实战经验： 如果你想自定义飞控行为，比如加一个自定义的飞行模式，那就在 modules/ 下新建一个文件夹，按照其他模块的套路写代码。我当年第一次加自定义模块时，就是照着 mc_pos_control 的代码结构抄了一遍，然后改逻辑。

3.6 版本选择：用稳定版还是最新版？

PX4的master分支是开发版，每天都在变。我建议初学者用稳定版（release版本）。怎么看版本？

git tag -l

你会看到一堆标签，比如 v1.12.3、v1.13.2。切换到稳定版：

git checkout v1.13.2
⚠️ 警告： 切换版本后，记得重新更新子模块！因为不同版本依赖的子模块版本可能不一样。我吃过这个亏——切到v1.12后没更新子模块，编译报了一堆莫名其妙的错，排查了半天才发现是子模块版本不匹配。 
git submodule update --init --recursive

3.7 验证源码完整性

下载完成后，我习惯跑一个简单的编译测试，确认源码没问题。比如编译一个仿真目标：

make px4_sitl_default gazebo

这个命令会编译PX4的仿真版本，并启动Gazebo。第一次编译会比较慢，因为要下载依赖库、编译工具链。如果顺利通过，说明你的源码下载和子模块更新都没问题。

🎯 总结一下： 源码下载就三步——clone主仓库、更新子模块、切到稳定版。目录结构记住 src/modules/ 和 boards/ 这两个核心目录就行。其他的用到再查，不用一次性全记住。

好，这一章就到这里。下一章咱们开始配置编译环境，然后真正动手编译第一个固件。到时候你会发现，前面这些准备工作做得越扎实，后面就越顺。

← 上一章 📖 返回目录 下一章 →