4. 编译环境配置（一）：安装Python依赖库、配置ArduPilot的Python工具链、验证环境

好，咱们进入正题。编译环境配置这块，说白了就是给电脑装上能“听懂”ArduPilot代码的工具。很多新手卡在这一步，不是装错版本，就是漏了某个包。我当年第一次编译Pixhawk固件时，就因为少装了一个future库，折腾了整整一个下午。嗯，咱们今天就把这事彻底搞定。

4.1 为什么需要Python依赖库？

ArduPilot的构建系统（也就是编译脚本）是用Python写的。你想想看，C++代码的编译过程，需要解析参数、生成头文件、处理MAVLink消息……这些脏活累活，都靠Python脚本在背后调度。

具体来说，这几个库各司其职：

• future：让Python 2和Python 3的代码能互相兼容。虽然现在主流是Python 3，但ArduPilot有些老模块还留着Python 2的写法。装上它，编译时就不会报“语法错误”。
• pyserial：串口通信库。烧录固件时，电脑通过USB转串口跟飞控板通信，全靠它。
• empy：模板引擎。编译过程中，它会根据模板生成一堆C++头文件。比如AP_Param的参数定义，就是empy生成的。
• 其他常用库：numpy、pyparsing、setuptools等，视具体功能而定。

4.2 安装Python依赖库（实操）

打开终端，咱们一步步来。我假设你已经装好了Python 3.6以上版本（推荐3.8或3.10）。

4.2.1 更新pip和setuptools

python3 -m pip install --upgrade pip setuptools wheel

这一步很重要。老版本的pip有时候会装错依赖版本。我曾经遇到过pip 9.0装empy时卡死，升级到21.0后就秒过。

4.2.2 安装核心依赖

python3 -m pip install --user future pyserial empy

加上--user参数，意思是只给当前用户装，不影响系统其他用户。我个人习惯用这个，万一装坏了，删掉~/.local目录下的对应文件夹就行，不用重装系统。

4.2.3 安装其他常用依赖（可选但推荐）

python3 -m pip install --user numpy pyparsing lxml

这些库在编译某些板子（比如CubeOrange）时会用到。不装的话，编译到一半会报错，然后你又要回头装。嗯，一次性搞定省心。

4.3 配置ArduPilot的Python工具链

依赖装好了，接下来要告诉系统“ArduPilot的Python脚本在哪里”。说白了就是设置环境变量和路径。

4.3.1 克隆ArduPilot仓库（如果还没做）

git clone https://github.com/ArduPilot/ardupilot.git
cd ardupilot

注意：不要用--depth=1浅克隆，因为后面编译时需要完整的git历史来生成版本号。我吃过这个亏，编译出来的固件版本号全是unknown。

4.3.2 安装子模块和Python工具链

git submodule update --init --recursive
python3 -m pip install --user -r requirements.txt

requirements.txt文件里列出了所有必需的Python包。运行上面这条命令，它会自动检查并安装缺失的库。我个人建议先手动装future、pyserial、empy这三个，再跑requirements.txt，这样能避免某些依赖冲突。

4.3.3 验证工具链路径

ArduPilot的编译脚本会调用Tools/autotest/目录下的Python脚本。确保你的终端能直接运行这些脚本：

export PATH=$PATH:~/ardupilot/Tools/autotest
echo $PATH

如果你不想每次打开终端都设置一遍，可以把上面这行加到~/.bashrc或~/.zshrc里。我习惯在.bashrc里加一行注释，方便以后查找。

4.4 验证环境是否配置成功

光装完不算完，得跑个测试确认一下。我一般用三步验证法：

4.4.1 验证Python库是否可导入

python3 -c "import future; print('future OK')"
python3 -c "import serial; print('pyserial OK')"
python3 -c "import empy; print('empy OK')"

如果每个都打印出“OK”，说明库装好了。如果报ModuleNotFoundError，那就是没装上，或者装到了别的Python版本里。检查一下python3 --version和pip3 --version是否对应。

4.4.2 验证ArduPilot的Python工具链

cd ardupilot
python3 Tools/autotest/param_metadata/param_parse.py --help

这个脚本是用来解析参数元数据的。如果它能正常打印帮助信息，说明工具链路径没问题。如果报错No module named 'future'，那就是future没装对，重新装一遍。

4.4.3 快速编译测试（可选）

如果你时间充裕，可以跑一个最简单的编译测试：

./waf configure --board sitl
./waf build --target tests

这个命令会编译SITL（软件在环仿真）的测试目标。编译过程大概需要5-10分钟。如果顺利通过，说明整个环境完全OK。我第一次配置成功时，看到终端里刷出Build commands: 0 failed，心里那叫一个踏实。

4.5 知识体系图

下面这张图帮你理清整个配置流程的逻辑关系：

这张图展示了从Python基础环境到最终验证的完整链路。你跟着箭头走，每一步都验证通过，就不会出问题。

4.6 常见问题与避坑

我整理了几个新手最容易踩的坑：

问题现象	原因	解决方法
import serial 报错	pyserial没装，或者装到了Python 2里	用python3 -m pip install pyserial重装
empy报语法错误	empy版本太旧（< 3.3）	pip install --upgrade empy
waf configure 找不到Python	系统默认Python是2.7	设置export PYTHON=python3
编译时提示缺少lxml	requirements.txt没装全	重新跑pip install -r requirements.txt

好了，环境配置的第一步就到这里。你按照上面的步骤走，应该不会出大问题。如果卡住了，回头检查一下pip版本和Python版本是否匹配。嗯，这些基础打牢了，后面编译固件就是水到渠成的事。

---

公众号:蓝海资料掘金营，微信deep3321