Yocto平台下Catkin工作空间构建失败：_setup_util.py生成空Shebang

问题现象 #

在基于Yocto的镜像上运行ROS 1 Noetic，创建空Catkin工作空间执行catkin_init_workspace后运行catkin_make，配置阶段报错：

/home/root/catkin_ws/devel/_setup_util.py: line 40: import: command not found
/home/root/catkin_ws/devel/_setup_util.py: line 49: syntax error near unexpected token '('

检查发现生成的devel/_setup_util.py仅包含无效Shebang：

#!
# -*- coding: utf-8 -*-

而非预期的#!/usr/bin/env python3，导致setup.sh用sh执行该Python脚本，引发语法错误。

已确认环境信息 #

• /usr/bin/python3存在且可用，版本3.10.15
• CMakeCache.txt中PYTHON_EXECUTABLE已正确设置为/usr/bin/python3
• /usr/bin/env存在且功能正常
• 该问题仅出现在Yocto镜像，Ubuntu环境下可正常生成正确Shebang

已尝试的无效操作 #

• 验证/usr/bin/python3存在且可用
• 确认CMakeCache.txt中PYTHON_EXECUTABLE配置正确
• 验证/usr/bin/env正常工作
• 手动修改_setup_util.py添加正确Shebang可临时解决，但catkin_make会覆盖
• 手动修改devel/setup.sh指定Python执行，同样会被catkin_make覆盖
• 执行catkin_make -DPYTHON_EXECUTABLE=/usr/bin/python3仍无法解决

问题根源 #

核心原因是Yocto环境下，meta-ros层提供的catkin包在生成_setup_util.py时，模板中的Shebang变量未被正确替换。catkin通过CMake模板setup_util.py.in生成该文件，原模板中的@PYTHON_EXECUTABLE@变量在Yocto交叉编译或目标环境执行时，未被正确填充为有效的Python解释器路径，最终生成了空的#!行。

修复方案 #

1. 临时修复（单次构建有效） #

两种快速解决方式，任选其一：

# 方法1：直接给_setup_util.py补上正确Shebang
echo -e "#!/usr/bin/env python3\n$(cat /home/root/catkin_ws/devel/_setup_util.py)" > /home/root/catkin_ws/devel/_setup_util.py
chmod +x /home/root/catkin_ws/devel/_setup_util.py

# 方法2：修改setup.sh，强制用Python3执行脚本
sed -i 's/_setup_util.py/python3 &/' /home/root/catkin_ws/devel/setup.sh

2. 永久修复（修改Yocto层配置） #

方案A：给catkin包打补丁

1. 找到meta-ros1-noetic层中catkin的recipe（路径通常为recipes-ros/catkin/catkin_*.bb）
2. 创建补丁文件catkin-fix-setup-util-shebang.patch，修改模板文件的Shebang：

diff --git a/cmake/templates/setup_util.py.in b/cmake/templates/setup_util.py.in
index abc123..def456 100644
--- a/cmake/templates/setup_util.py.in
+++ b/cmake/templates/setup_util.py.in
@@ -1,4 +1,4 @@
-#!@PYTHON_EXECUTABLE@
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
 @copyright Copyright (c) 2011, Willow Garage, Inc.

3. 在catkin的recipe中添加补丁引用：

SRC_URI += "file://catkin-fix-setup-util-shebang.patch"

方案B：强制设置catkin的CMake变量

在Yocto的local.conf或catkin的recipe中添加：

EXTRA_OECMAKE:append = " -DPYTHON_EXECUTABLE=/usr/bin/env python3"

确保catkin在构建和运行时都使用正确的Python解释器路径。

方案C：确认meta-ros层的Python版本配置

检查meta-ros1-noetic层的layer.conf，确保已设置Python3为默认版本：

PYTHON_PREFERRED_VERSION = "3.10"
ROS_PYTHON_VERSION = "3"

验证方法 #

修复后重新构建Yocto镜像，部署到目标设备后执行以下步骤：

mkdir -p ~/catkin_ws/src && cd ~/catkin_ws/src
catkin_init_workspace
cd .. && catkin_make
source devel/setup.bash

检查devel/_setup_util.py的开头是否为#!/usr/bin/env python3，且构建过程无语法错误。

内容的提问来源于stack exchange，提问作者Amin Sobhani