1. 代码开发工具先跑通:catkin 工作空间到底解决什么问题
代码开发工具这件事,最容易被跳过的一步是搭好编译和查找包的链路,往往不是写代码本身。很多人拿到一份 ROS 工程,直接在源码目录里敲编译,结果 CMakeLists 找不到、包名对不上、换个终端又全部失效。catkin 工作空间就是用来解决这些混乱的:它把源码包、编译产物和环境脚本分到固定位置,让 catkin_make 有明确的扫描范围,也让 ROS 能稳定找到你新写的包。这一篇只讲一件事——从空目录开始,把 catkin 工作空间建起来、编译通过、source 生效,再把建包和排错串成一条能照着走的线。适合刚接触 ROS 构建、或者被环境变量折腾过几轮的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具的第一层:catkin 工作空间的目录、编译与 source 链路
catkin 工作空间看起来只是几个文件夹,但它把「源码在哪、编译产物在哪、环境变量怎么来」这三件事固定下来。不按这个约定走,后面的包管理、消息生成、跨包依赖都会变成玄学问题。
2.1 catkin 为什么要求先有工作空间,而不是直接写 CMakeLists
catkin 本质上是构建系统这一层对 CMake 的扩展:它仍然调用 CMake 和 make,但额外接管了包的发现、包间依赖解析和环境脚本生成。裸 CMake 项目各自维护一份构建配置,A 库依赖 B 库时,路径、编译选项、链接顺序都得手工写死;包一多,改一个依赖就要动好几处。
工作空间把这件事收敛成固定的目录约定。src 是源码空间,所有包按目录平铺在里面,每个包有各自的 package.xml 和 CMakeLists.txt;build 放 CMake 缓存和中间产物;devel 放开发期生成的东西,其中就包括 setup.sh 系列环境脚本。catkin_make 在根目录执行时,先扫描 src 下所有包,再统一进 build 调 CMake,最后把每个包的环境拼成 devel/setup.bash。
这里有个容易被忽略的点:工作空间是空的也能编译。src 里哪怕只有一个指向顶层 CMakeLists 的链接文件,catkin_make 依然会跑完,并生成 build 和 devel 两个文件夹。这说明编译的入口是工作空间根目录,而不是某个具体包的源码。理解了这一点,后面「为什么不能在 src 里编译」「为什么新包要重新跑一次 catkin_make」就都顺了。
选 catkin 而不是自己写一套 Makefile 的理由也很实际:包多了以后,你真正想维护的是每个包的依赖声明和源码结构,不想维护一堆绝对路径。catkin 把这部分重复劳动收走,代价是你必须接受它的目录约定——而这个约定,正是新手最容易踩空的地方。
2.2 建目录与首次编译:几条命令背后的路径约定
第一步不是写代码,是把工作空间的骨架建出来。下面这组命令,每一行都在履行一个约定。
bash复制# 1. 创建工作空间根目录,以及它下面的源码空间 src
mkdir -p ~/catkin_test/src
# 2. 回到工作空间根目录,catkin_make 必须在这一层执行
cd ~/catkin_test
# 3. 首次编译,空工作空间也会生成 build/ 和 devel/
catkin_make
mkdir -p 的 -p 不是可有可无的装饰:父目录不存在时它会一路建上去,目录已存在时也不报错,所以重复执行是安全的。目录名 catkin_test 可以换成你习惯的名字,但 src 这一级名字是约定,不能省也不能改,catkin_make 就是靠它找源码的。
第二步的 cd 是整组命令里最容易被跳过的一步。catkin_make 的扫描起点是当前目录,当前目录里没有 src,它就没有源码可扫;当前目录在 src 里面,它又会把每个包的源码当成工作空间根来处理。这两种情况的表现不一样,但都编不出你要的结果。
第三步执行完,在当前目录下应该能看到 build 和 devel 两个文件夹。build 里是 CMake 的缓存和中间文件,devel 里是编译出来的库、可执行文件以及几个 setup.sh。判断首次编译是否成功,看这两个目录有没有生成就够了,不用急着看有没有输出二进制——空工作空间本来就没有可执行文件。
| 命令 | 作用 | 失败时先看什么 |
|---|---|---|
mkdir -p ~/catkin_test/src |
建根目录和源码空间 | ls ~/catkin_test 是否只有 src |
cd ~/catkin_test |
进入工作空间根目录 | pwd 输出是否以工作空间名结尾 |
catkin_make |
扫描 src 并编译 | 根目录下是否生成了 build 与 devel |
2.3 source 与 ROS_PACKAGE_PATH:确认工作空间在环境最顶层
编译成功不等于能用。新开的终端并不知道你刚建的工作空间在哪,需要把 devel 下的环境脚本加载进来。
bash复制# 让当前终端加载这个工作空间的环境
source devel/setup.bash
# 检查 ROS 查找包的路径,自己工作空间的路径应排在前面
echo $ROS_PACKAGE_PATH
source 的执行位置有讲究:这里用的是相对路径 devel/setup.bash,所以必须先 cd 到工作空间根目录。如果人在别的目录里敲同一行,要么报文件不存在,要么更糟——source 到了另一个工作空间的同名脚本,你以为加载的是自己的环境,实际是别人的。
devel 下不止一个 setup 脚本,source 其中任何一个都能把当前工作空间设置到 ROS 工作环境的最顶层。所谓「最顶层」,落到可观测的行为上就是查找优先级:ROS_PACKAGE_PATH 里这个工作空间排在前面,同名包会优先命中它。这也是后面多个工作空间叠加时最容易出问题的地方。
echo $ROS_PACKAGE_PATH 的输出应该包含你工作空间的 src 目录。如果没有,说明 source 没生效或者 source 错了文件;如果排在已有路径的后面,说明有别的环境先加载了,需要检查加载顺序。
还有一个容易被忽略的验证点:source 只对当前这个终端会话有效。关掉窗口、新开标签页,环境就回到初始状态。这不是 bug,是 shell 的进程隔离,后面讲持久化时会专门处理它。
3. 代码开发工具的第二层:用 catkin_create_pkg 建包与依赖声明
工作空间只是容器,真正承载代码的是包。建包这一步决定了后面编译能不能找到依赖、别人拿到你的工程能不能一次编过。
3.1 catkin_create_pkg 的参数顺序与依赖声明
建包命令的位置参数是有语义的:第一个是包名,后面全部是依赖。
bash复制# 先进入源码空间,包必须建在 src 下
cd ~/catkin_test/src
# 包名 + 依赖列表:std_msgs、rospy、roscpp
catkin_create_pkg beginner_tutorials std_msgs rospy roscpp
beginner_tutorials 是包名,同时也是目录名,命名上我一般坚持小写加下划线,避免大小写混用在跨平台时出岔子。后面的 std_msgs、rospy、roscpp 是三个依赖:std_msgs 提供标准消息类型,roscpp 是 C++ 客户端库,rospy 是 Python 客户端库。这三个是绝大多数入门包的常见组合,用不上 Python 的话,rospy 可以不加,依赖越少编译越快,也越不容易在换环境时缺东西。
命令执行后,catkin 会把依赖写进两个地方:package.xml 里的依赖声明,以及 CMakeLists.txt 里的 find_package 和 catkin_package。很多人只记住了「建包」这个动作,却不知道依赖是被写进这两个文件的,后面手工加依赖时找不到位置,或者只改了 package.xml 忘了改 CMakeLists.txt,编译时就报找不到头文件。
包的建立位置必须是 src 下。建在 src 外面,catkin_make 扫描不到,表现就是「明明建了包,编译日志里却没有它」。这类问题不看日志很难定位,因为命令本身是成功的,目录也真实存在。
3.2 建包之后立刻检查的三个位置
包建完不要急着写代码,先花一分钟确认骨架是对的。我一般按下面三个位置依次看。
| 位置 | 看什么 | 常见问题 |
|---|---|---|
package.xml |
依赖声明是否齐全 | 后面手加依赖时漏写,编译找不到头文件 |
CMakeLists.txt |
find_package 与 catkin_package 是否包含同一批依赖 |
两处不一致,链接阶段才报错 |
| 包内源码目录 | 节点源码放在约定位置 | 放错层级,编译目标里找不到源文件 |
package.xml 是包的身份证,名字、版本、依赖、导出信息都在里面。建包命令只会写入你当时给出的依赖,后面代码里用了新的消息类型或者新的库,这个文件要同步补。
CMakeLists.txt 里最需要关注的是 find_package 和 catkin_package 两处。前者告诉构建系统去哪里找依赖,后者声明这个包对外导出什么。两处依赖对不上时,症状往往不是编译报错,而是链接阶段才冒出未定义符号,排查成本高得多。
第三个位置是源码目录。catkin 包的源码通常放在包内的 src 下,和构建目标对应。这个层级如果放错,CMakeLists.txt 里配置的可执行目标就找不到源文件,报错信息会指向一个你确认过确实存在的文件名——这种「文件明明在,编译器说没有」的情况,九成是相对路径的起点不对。
3.3 改完包之后重新编译的顺序
新增包或者改了依赖声明,都要回到工作空间根目录重新编译。
bash复制# 回到工作空间根目录再编译,不要在 src 里编译
cd ~/catkin_test
# 重新扫描 src 下的所有包并编译
catkin_make
顺序不能反:先 cd 到根目录,再 catkin_make。在 src 里执行同一条命令,扫描起点就变成了源码空间,结果是每个包被当成独立工作空间处理,轻则报找不到 src,重则生成一批位置错误的构建目录,把原本干净的工作空间弄乱。
新增包之后必须重跑一次 catkin_make,因为包的发现发生在扫描阶段,不重扫就不会被纳入构建。只改源码文件时,catkin_make 做的是增量编译,速度很快,可以放心反复执行。改了 package.xml 的依赖或者 CMakeLists.txt 的构建目标,同样需要重跑,让配置阶段重新读取。
编译成功的判断标准也要说清楚:日志末尾没有报错只是第一步,还要确认 devel 下确实生成了对应的产物。只看日志很容易漏掉「编译通过但目标没生成」的情况,那通常是 CMakeLists.txt 里目标配置被注释掉了或者写错了条件。
4. 代码开发工具避坑:五类翻车现场与排查顺序
这一节记录的是我在搭工作空间时反复见到的五类问题,每一条都按「现象、原因、解决」写,照着顺序查,比盲目重装环境快得多。
4.1 目录名前后不一致,cd 直接报错
现象:建目录时用的是 ~/catkin_test/src,后面编译却敲了 cd ~/catkin_ws/,终端直接返回 No such file or directory。如果这个错误被忽略继续往下执行,后面的 catkin_make 会在错误的目录里跑,生成一堆和预期无关的文件。
原因:工作空间的绝对路径在几条命令之间没有统一。这类错误常见于照抄别人的命令片段,片段里的目录名和你实际建的不一样,命令本身没错,路径对不上。
解决:先把实际路径确认下来,再往下走。
bash复制# 确认工作空间真实存在,并看清它的名字
ls ~
# 进入确认过的工作空间根目录
cd ~/catkin_test
# 打印当前路径,确认终点就是工作空间根目录
pwd
ls ~ 用于确认目录名,pwd 用于确认当前所在层。养成执行 catkin_make 前先看一眼 pwd 的习惯,能省掉大量「命令没报错但结果不对」的排查时间。
4.2 在 src 里执行 catkin_make,扫描起点错了
现象:catkin_make 报找不到 src 目录,或者提示当前路径下的 CMakeLists 不属于任何工作空间。有时命令能跑完,但 build 和 devel 生成在了 src 里面,整个目录结构变得很乱。
原因:catkin_make 以当前目录为工作空间根,去找它下面的 src。人已经在 src 里,再往下找自然找不到;它也可能把 src 里的顶层 CMakeLists 当根配置处理,于是产物落在了错误层级。
解决:先退到工作空间根目录,再编译。
bash复制# 从 src 退回上一级,也就是工作空间根目录
cd ..
# 确认当前目录下确实有 src
ls
# 再执行编译
catkin_make
如果 src 里已经生成了 build 或 devel,先确认里面没有你要保留的东西再删掉,然后回到根目录重编。构建目录混在源码空间里,后续每次扫描都会把它当成内容处理,越拖越难清理。
4.3 新开终端不认包,环境没加载
现象:上一个终端里一切正常,新开一个终端执行编译或者运行节点,提示找不到包,或者行为像是工作空间根本不存在。
原因:source devel/setup.bash 只对执行它的那个 shell 进程有效。新开的终端是一个新进程,不会继承上一个终端的环境变量。这不是配置丢了,是环境变量本来就不跨会话。
解决:每个需要用到这个工作空间的终端,都先 source 一次。
bash复制# 进入工作空间根目录
cd ~/catkin_test
# 加载当前工作空间的环境
source devel/setup.bash
# 确认路径已经进到环境变量里
echo $ROS_PACKAGE_PATH
三条命令的顺序不能乱,尤其是 cd 必须在 source 之前,因为这里用的是相对路径。想让每个终端自动加载,就要写进 shell 的启动文件,具体做法和它的坑放在下一节。
4.4 把 source 写进 .bashrc,却写死了绝对路径
现象:换了一台机器或者换了一个用户之后,每次打开终端都报一行 No such file or directory,而且这行错误出现在所有命令之前,看着很吓人。
原因:启动文件里写的是带用户名的绝对路径,比如指向某个固定家目录下的 devel/setup.bash。路径本身在那个用户下是有效的,换用户、换机器、甚至改过目录名之后就失效了。
解决:用家目录展开代替写死的用户名,并在写入前确认文件真的存在。
bash复制# 打开当前用户的 shell 启动文件
sudo gedit ~/.bashrc
在文件末尾追加一行,用 $HOME 而不是具体用户名:
bash复制# 加载工作空间环境,$HOME 会展开成当前用户的家目录
source $HOME/catkin_test/devel/setup.bash
写之前先 ls 确认 $HOME/catkin_test/devel/setup.bash 存在。写完之后,新开终端验证,不要只在当前终端 source ~/.bashrc 就算完——当前终端里可能已经加载过旧路径,验证不出问题。用 sudo 编辑自己的家目录文件并不必要,gedit ~/.bashrc 就够了,权限用错反而可能让文件属主变化。
4.5 ROS_PACKAGE_PATH 顺序混乱,同名包命中错的版本
现象:明明改了自己工作空间里的包,运行起来却还是旧行为;或者两个工作空间里有同名包,每次命中的都不是你以为的那个。
原因:ROS_PACKAGE_PATH 是有顺序的,靠前的优先。多个工作空间叠加时,后 source 的会插到前面;反复 source 也可能让同一路径出现多次。顺序一变,同名包的解析结果就变了。
解决:用 echo 把路径打出来,逐个核对顺序和重复项,再决定加载哪一个。
bash复制# 查看当前终端的包查找路径,注意顺序和重复
echo $ROS_PACKAGE_PATH
排查时优先怀疑顺序而不是内容:路径都存在,但排在前面的不是你想用的那个,表现就和「代码没生效」一模一样。最省事的做法是新开一个终端,只 source 需要的那一个工作空间,再复现问题。如果新终端里正常,基本可以确定是旧终端里环境叠加导致的。
5. 把验证做在交付前:三个检查点和一条习惯
环境问题最麻烦的地方在于它不报错,只是让结果和预期不一样。所以我现在不把「编译通过」当作完成标志,而是固定跑一遍下面三个检查点。
| 检查点 | 命令 | 期望结果 |
|---|---|---|
| 目录结构 | ls ~/catkin_test |
能看到 src、build、devel |
| 环境脚本 | ls devel/setup.bash |
文件存在,不是空文件 |
| 查找路径 | echo $ROS_PACKAGE_PATH |
包含本工作空间的 src,且排在前面 |
这三条合起来,一个刚打开的终端就能跑完:
bash复制# 进入工作空间根目录
cd ~/catkin_test
# 加载环境,注意必须在根目录执行
source devel/setup.bash
# 确认环境脚本存在、路径已生效
ls devel/setup.bash
echo $ROS_PACKAGE_PATH
source 和 ls 的顺序可以互换,但都要在 cd 之后。ls 那一步不是多余:如果构建中途失败,devel/setup.bash 可能根本没生成,此时 source 会报文件不存在,而这个报错很容易被后面一连串输出淹没。先 ls 确认文件在,再 source,问题的边界就清楚了。
还有一个我踩过的坑:只在当前终端验证,然后把工程交给别人。对方新开终端,第一步就卡住,因为 .bashrc 里那行路径是按我的目录名写的。从那以后,我每次交付前都强制走一遍「关掉所有终端、新开一个、从零 source、再 echo 路径」的流程,确认工程不依赖任何我这边残留的环境。这个习惯花不了一分钟,但能把「在我这能跑」这句话变成可验证的事实。工作空间这层地基打稳了,后面加包、改依赖、换机器才不会变成一次次重来。希望帮到你。
