1. 在 Windows 上跑 SITL 仿真:先解决终端和路径这两件事
在 Windows 上搭一套能跑 SITL 仿真的代码开发工具链,最容易翻车的不是代码本身,而是终端和路径。很多人拿到一套 Linux 风格的仿真代码,第一反应是打开资源管理器找到 .exe,或者用 Windows 命令行敲 cd D:\...,结果连代码根目录都进不去。这套代码依赖的是 Cygwin 提供的 Linux 风格终端、git 子模块递归拉取,以及 waf 构建脚本的配置检查。三件事里任何一件没做对,后面的编译都会以看似不相干的方式报错。这篇按实际动手顺序走一遍:先让终端认得你的代码目录,再把子模块拉全,最后用 waf-light configure --board=sitl 生成仿真板配置,中间把几个血泪经验的坑标出来。适合已经在 Windows 上克隆了代码、但卡在环境准备这一步的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具的入口:Cygwin 终端与 /cygdrive/ 盘符映射
2.1 Cygwin 终端不是 Windows 命令行:/cygdrive/ 从哪来
Cygwin 提供的是一套 Linux 风格的命令行界面,它有自己的根目录结构,不会直接把 C:\、D:\ 暴露成 /。Windows 的磁盘在 Cygwin 里被挂载到 /cygdrive/ 下面,盘符作为下一级目录出现。材料里给了一个很具体的例子:D:\ardupilot 在 Cygwin 中就是 /cygdrive/d/ardupilot。这里有两个细节:盘符要小写,路径分隔符要从反斜杠换成斜杠。
这个映射不是可选项,而是 Cygwin 的路径规则。你在 Windows 命令行里习惯的 D:\code\demo,在 Cygwin 里写成 D:/code/demo 也不一定稳,推荐直接写 /cygdrive/d/code/demo。原因很简单:Cygwin 的很多工具链脚本会把 /cygdrive/ 当成真实根路径的一部分去拼接,混用 Windows 风格路径时,脚本可能把盘符当成普通目录名,最后找错位置。
先确认终端类型。打开 Cygwin64 Terminal,提示符通常是 $ 结尾,和 Windows 的 C:\> 明显不同。不要在这个终端里敲 dir 去替代 ls,虽然部分命令能用,但脚本里依赖的是 Unix 风格命令和路径。环境准备阶段,统一用 Cygwin 终端,不要一会儿 Windows 命令行、一会儿 Cygwin,否则路径写法会来回打架。
还有一点容易被忽略:Cygwin 的当前目录是你启动终端时的目录,不是代码目录。很多人打开终端就直接跑 git submodule,结果报 fatal: not a git repository,以为代码坏了,其实是站错了位置。下一步先把 cd 做对。
2.2 用 cd 进入代码目录:盘符、大小写与分隔符
假设代码已经克隆到 Windows 的 D:\sim-demo,对应 Cygwin 路径是 /cygdrive/d/sim-demo。进入目录的命令只有一行,但参数写法要固定:
bash复制# 进入代码根目录;d 是盘符,sim-demo 是实际目录名,按你的环境替换
cd /cygdrive/d/sim-demo
这条命令里,/cygdrive/ 是固定前缀,d 对应 Windows 的 D 盘,sim-demo 是代码目录名。不要把 D: 写进去,也不要写成 \cygdrive\d\sim-demo。如果目录名里有空格,需要用引号包起来,例如 cd "/cygdrive/d/sim demo";但更稳的做法是把代码放在纯英文、无空格的路径下,构建脚本对空格路径的处理并不总是可靠。
进入之后,用 pwd 确认当前位置,用 ls 看目录内容:
bash复制# 打印当前工作目录,确认不是用户主目录
pwd
# 列出当前目录内容,确认能看到代码树里的模块目录
ls
pwd 的输出应该类似 /cygdrive/d/sim-demo。如果输出是 /home/你的用户名,说明 cd 没生效,或者路径写错了。ls 的输出里应该能看到代码根目录下的模块文件夹,材料里提到的 modules/waf/waf-light 就位于代码树的 modules 目录下。看不到 modules,先别往下走,回到上一步检查路径。
这里有一个实操习惯:在 Cygwin 里输入路径时多用 Tab 补全。敲 cd /cygdrive/d/ 后按 Tab,终端会列出可选的目录名,比手敲安全。Tab 补全还能提前暴露大小写问题:Windows 文件系统不区分大小写,Cygwin 的某些工具却区分,目录名写错一个字母,补全列表里就不会出现你要的那个。
2.3 路径确认的三个动作:pwd、ls、再 cd
在拉子模块和跑 configure 之前,建议固定做三个动作。第一个是 pwd,确认自己在代码根目录,而不是某个子目录。第二个是 ls,确认 modules 目录存在,因为后面的 waf 脚本就在这个目录下。第三个是再执行一次 cd,把路径切到绝对路径,避免相对路径叠加导致位置漂移。
bash复制# 动作一:确认当前位置
pwd
# 动作二:确认代码树关键目录存在
ls
# 动作三:用绝对路径重新进入,避免相对路径叠加
cd /cygdrive/d/sim-demo
为什么强调绝对路径?因为后面执行 ./modules/waf/waf-light 时,./ 是相对于当前目录的。如果你从代码根目录 cd 到了 modules 里面,再执行 ./modules/waf/waf-light,终端会去找 modules/modules/waf/waf-light,报 No such file or directory。这个报错看起来像文件丢了,实际是当前位置不对。固定用绝对路径重新 cd 一次,能把这个玄学问题压到最低。
另外,Cygwin 终端里不要用 cd D:\sim-demo 这种 Windows 写法。反斜杠在 Unix 风格 shell 里是转义符,D:\sim-demo 可能被解释成别的意思,最常见的结果是提示目录不存在。路径规则统一成 /cygdrive/盘符/目录,后面所有命令都按这个规则来。
3. 子模块拉不全,后面全白搭:git submodule 递归初始化
3.1 为什么先 cd 到代码根目录再拉子模块
git submodule 命令依赖当前目录里的 .git 和 .gitmodules。如果你在代码根目录之外执行,git 会直接告诉你这不是一个 git 仓库。材料里明确写了,更新子模块这一步是必须的,因为这套仿真代码依赖很多子项目。子模块不是普通目录,它们是独立仓库的引用,主仓库里只记录每个子模块应该停在哪个提交上。
正确的顺序是:先进入代码根目录,再执行子模块更新。不要在主目录外面执行,也不要在某个子模块目录里面执行。子模块目录里面有自己的 .git 文件,你在那里执行 git submodule update,操作的是子模块自己的仓库,不是主仓库的子模块列表。
bash复制# 先回到代码根目录,确保 .gitmodules 在当前目录可见
cd /cygdrive/d/sim-demo
# 初始化并递归拉取所有子模块
git submodule update --init --recursive
这条命令里的 --init 和 --recursive 是两个不同的事情,下一节拆开说。先记住执行位置:必须在代码根目录。判断方法很简单,执行 ls -a 能看到 .gitmodules 文件,说明位置对了。看不到就继续往上找,直到看见这个文件为止。
3.2 --init 与 --recursive 分别解决什么问题
git submodule update --init --recursive 可以拆成三层理解。第一层是 git submodule update,它让每个子模块检出主仓库记录的那个提交,而不是子模块仓库的最新提交。第二层是 --init,它把 .gitmodules 里登记的子模块配置写进 .git/config,相当于先注册再拉取。没有 --init,git 知道有子模块,但不会主动去初始化它们。第三层是 --recursive,它让子模块内部如果还有子模块,也继续往下拉,一层一层递归。
这套仿真代码的子项目比较多,材料里说“依赖很多子项目”,实际表现就是子模块可能还有自己的子模块。只执行 git submodule update --init,外层子模块能拉下来,但里层可能还是空目录,后面 configure 检查编译环境时就会报缺少某个模块或头文件。加上 --recursive,才能把整棵树拉全。
bash复制# 完整写法:初始化 + 递归拉取
git submodule update --init --recursive
执行时终端会逐个输出子模块的拉取进度,类似 Submodule path 'xxx': checked out '...'。如果中间出现 fatal: unable to access 或 Could not resolve host,说明网络在某个子模块上断了。处理方法是重新执行同一条命令,git 会跳过已经拉好的部分,继续补没拉完的。不要因为一次失败就删掉整个代码目录重来,那样反而会把已经完成的进度丢掉。
还有一个常见误解:以为 git pull 会把子模块一起更新。普通 git pull 只更新主仓库记录的子模块指针,不会自动把子模块内容拉下来。拉完主仓库后,仍然需要执行一次 git submodule update --init --recursive,否则子模块目录可能停在旧提交,甚至还是空的。
3.3 拉取完成后的自检:子模块目录不能是空的
命令跑完不等于拉全了。最直接的自检是看子模块状态:
bash复制# 查看子模块状态;行首为 '-' 通常表示该子模块尚未初始化
git submodule status
输出里每一行对应一个子模块,前面带一个状态字符。如果某些行以 - 开头,说明对应的子模块还没有初始化,需要回到上一步重新执行 git submodule update --init --recursive。如果所有行都以提交哈希开头,没有 - 前缀,说明子模块已经检出到主仓库记录的提交。
再进一步,可以进到关键子模块目录里看一眼:
bash复制# 进入 waf 所在目录,确认脚本文件存在
ls modules/waf
# 确认 waf-light 文件存在且不是空文件
ls -l modules/waf/waf-light
ls -l 的输出里会显示文件权限和大小。如果 waf-light 不存在,后面的 configure 一定跑不起来;如果文件大小为 0,说明子模块拉取不完整。这个检查比直接跑 configure 更早暴露问题,能省掉一轮看报错的时间。
材料里那句“这一步是必须的”不是客套。跳过子模块直接 configure,最常见的现象是 configure 输出里出现某个 missing 或者找不到头文件,但你顺着报错去找,发现文件明明在代码树里。原因就是那个文件属于某个子模块,而子模块目录还是空的。先把子模块拉全,再谈配置。
4. 代码开发工具的构建入口:waf-light configure 与 --board=sitl
4.1 waf-light 为什么用 ./ 开头调用
waf-light 是这套代码使用的构建脚本入口,位于 modules/waf/ 目录下。材料里给的调用方式是 ./modules/waf/waf-light configure --board=sitl。前面的 ./ 表示“当前目录下的相对路径”。在 Unix 风格 shell 里,如果一个可执行文件不在 PATH 环境变量里,直接敲文件名是找不到的,必须用路径指明位置。./ 就是最明确的写法。
bash复制# 在代码根目录执行;./ 表示从当前目录开始找 modules/waf/waf-light
./modules/waf/waf-light configure --board=sitl
这条命令可以拆成四段:./ 是路径前缀,modules/waf/waf-light 是脚本位置,configure 是子命令,--board=sitl 是传给 configure 的参数。执行时当前目录必须是代码根目录,否则 ./modules/... 会找错位置。如果你不确定,先 pwd 看一眼,输出不是代码根目录就重新 cd。
另一个细节是执行权限。Cygwin 下从 Windows 文件系统继承的权限有时不包含可执行位,直接运行可能报 Permission denied。遇到这种情况,常见做法是先给脚本加执行权限再跑:
bash复制# 如果提示 Permission denied,先补执行权限
chmod +x modules/waf/waf-light
# 再执行 configure
./modules/waf/waf-light configure --board=sitl
chmod +x 只改 waf-light 这一个文件的权限,不影响其他文件。不要图省事对整棵代码树递归加权限,那样会把不该执行的脚本也变成可执行,后面排查问题时反而多一层干扰。
4.2 configure 子命令与 --board=sitl 参数
configure 是 waf 的配置阶段。材料里说得很清楚:这个命令会检查你的编译环境,并生成针对 SITL 仿真板的配置。也就是说,它至少做两件事:第一,探测当前环境里的编译器、工具链和路径是否满足构建要求;第二,把目标板相关的配置写下来,供后续构建使用。
--board=sitl 里的 sitl 是目标板名称,代表软件在环仿真。这个参数决定了 configure 按哪套板级配置去检查环境。不加这个参数,waf 可能不知道要配哪个目标,或者落到默认配置上,后面构建出来的东西和你要跑的仿真对不上。参数写法是等号连接,--board=sitl,中间不要加空格写成 --board = sitl,waf 的参数解析对空格比较敏感。
bash复制# 标准配置命令:目标板为 sitl
./modules/waf/waf-light configure --board=sitl
执行后终端会输出一系列检查信息。成功的标志是看到 Configuration done 之类的提示。材料里原话是“看到 ‘Configuration done’ 之类的提示就成功了”。注意“之类”两个字,不同版本的输出措辞可能略有差异,但核心是 configure 正常结束、没有停在错误上。不要只扫一眼最后一行就继续,往上翻几屏,确认没有 error 或 missing 关键字。
configure 阶段检查的是环境,不是业务代码。它报错时,优先看第一个错误,不要被后面一堆连锁输出带偏。比如它先说找不到某个编译器,后面又会说某个模块无法配置,根因还是第一个。把第一个错误解决掉,再重新跑 configure,比逐条追后面的报错效率高得多。
4.3 看到 Configuration done 之后做什么
configure 通过后,当前代码树里已经生成了针对 SITL 的构建配置。此时不要急着改代码,也不要重复执行 configure 多次。重复执行本身不一定报错,但如果两次之间环境变量或路径变了,配置结果可能不一致,后面构建出问题时会很难判断是哪一次配置生效。
比较稳的做法是:configure 成功后,先把这次输出末尾的关键行记下来,确认目标板是 sitl,确认没有警告级别的路径问题。然后再进入构建阶段。构建命令由项目脚本决定,材料里没有展开,这里不替它编一条命令。能确定的是,构建入口仍然是同一个 waf-light,只是子命令从 configure 换成构建动作。
如果你改了代码目录位置,或者换了 Cygwin 终端重新打开,建议重新跑一次 configure。因为 configure 生成的配置里可能包含绝对路径,目录一变,旧配置就失效了。判断是否需要重跑,看一个信号:构建时报找不到某个本应存在的文件,而文件实际在代码树里,大概率是配置里的路径过期了。重新 configure 一次,比手动改配置文件可靠。
5. 避坑与排查:四个翻车现场
5.1 现象:cd D:\sim-demo 提示 No such file or directory
现象很直接:在 Cygwin 终端里敲 cd D:\sim-demo,终端回一句 No such file or directory,但资源管理器里这个目录明明存在。原因不是目录没了,而是 Cygwin 不按 Windows 盘符规则解析路径,反斜杠还会被 shell 当成转义符。解决方法是换成 /cygdrive/ 写法:cd /cygdrive/d/sim-demo。盘符小写,分隔符用斜杠。如果目录名有空格,加引号;更稳的是把代码放到无空格、纯英文的路径下。
5.2 现象:configure 报找不到某个模块或头文件
现象是 configure 输出里出现 missing、not found 或者某个头文件路径不存在,但你顺着路径去找,文件其实在代码树里。原因大概率是子模块没拉全,那个文件属于某个子模块,而子模块目录还是空的。解决方法是回到代码根目录,执行 git submodule update --init --recursive,然后用 git submodule status 确认没有以 - 开头的行,再重新跑 configure。不要先去改编译器的 include 路径,那是治标不治本。
5.3 现象:./modules/waf/waf-light: Permission denied
现象是命令路径是对的,文件也存在,但终端提示权限不足。原因是 Cygwin 从 Windows 文件系统继承的权限里没有可执行位。解决方法是给脚本补执行权限:chmod +x modules/waf/waf-light,然后再执行 configure。只给这一个文件加权限,不要递归改整棵代码树。如果补了权限还是不行,检查文件是不是 0 字节,0 字节说明子模块没拉完整,回到 5.2 处理。
5.4 现象:命令跑完没看到 Configuration done,后面构建全错
现象是 configure 命令执行完了,终端也回到了提示符,但输出里没有 Configuration done,或者中间夹着 error。很多人只看了最后一行,以为命令结束就是成功,结果后面构建报一堆错。原因是 configure 没有真正通过,环境检查在某一步失败了。解决方法是重新执行 configure,从输出第一处 error 开始看,解决后再跑,直到明确看到 Configuration done。不要用“命令没卡住”来判断成功,退出码和关键字才是依据。
6. 把配置结果固化成检查清单:每次改环境后先跑一遍
环境准备这件事,最怕的是“上次能跑,这次不能跑”。代码没改、命令没改,但换了终端、换了目录、或者中途拉过一次代码,配置就可能失效。我的习惯是把前面几步压缩成一个检查清单,每次动完环境先跑一遍,确认三件事:位置对、子模块全、configure 通过。
bash复制#!/usr/bin/env bash
# 环境自检清单:在 Cygwin 终端里按顺序执行
# 1. 确认当前目录是代码根目录,输出应为 /cygdrive/盘符/目录
pwd
# 2. 确认子模块已递归拉取,行首不应有 '-' 前缀
git submodule status
# 3. 重新跑一次配置,确认输出包含 Configuration done
./modules/waf/waf-light configure --board=sitl
这三步的顺序不要颠倒。先 pwd,是因为后面两条命令都依赖当前目录;先 git submodule status,是因为子模块不全时 configure 的报错会很有迷惑性;最后才跑 configure,是因为它最耗时,放在最后能避免白跑。清单里的 pwd 输出如果不是 /cygdrive/ 开头,直接停下来重新 cd,不要继续往下执行。
还有一个验证技巧:把 configure 的输出重定向到文件,出问题时直接搜关键字,比在终端里往上翻屏可靠。
bash复制# 把 configure 输出同时写到终端和日志文件,方便回看第一处错误
./modules/waf/waf-light configure --board=sitl 2>&1 | tee configure.log
# 在日志里找错误关键字;没有输出说明没匹配到
grep -n -i "error\|missing\|not found" configure.log
2>&1 把标准错误也并入标准输出,tee 让内容既显示在终端又写进 configure.log。grep -n 会带行号输出匹配行,-i 忽略大小写。如果 grep 没有任何输出,再确认日志末尾有没有 Configuration done。这个习惯帮我省过很多次“明明刚才还能跑”的排查时间。
从那以后我每次换终端、换代码目录,或者拉完新代码,都强制先走一遍 pwd、git submodule status、configure 这三步,确认输出里该有的关键字都在,再开始构建。环境准备不是一次性动作,而是一个可以重复执行的检查流程。希望帮到你。
