MacOS下Mamba环境Qt头文件与系统Qt冲突致ROS2 Humble编译失败

问题现象 #

在MacOS的Mamba环境（基于Robostack安装ROS2 Humble）编译mapviz包时，出现以下编译错误：

CMake Warning at CMakeLists.txt:167 (add_executable):
  Cannot generate a safe runtime search path for target mapviz because files
  in some directories may conflict with libraries in implicit directories:

    runtime library [libboost_date_time.dylib] in /Users/username/miniforge3/envs/ros_env/lib may be hidden by files in:
      /opt/homebrew/lib
    runtime library [libboost_system.dylib] in /Users/username/miniforge3/envs/ros_env/lib may be hidden by files in:
      /opt/homebrew/lib
    runtime library [libboost_filesystem.dylib] in /Users/username/miniforge3/envs/ros_env/lib may be hidden by files in:
      /opt/homebrew/lib
    runtime library [libproj.dylib] in /Users/username/miniforge3/envs/ros_env/lib may be hidden by files in:
      /opt/homebrew/lib
    runtime library [libyaml.dylib] in /Users/username/miniforge3/envs/ros_env/lib may be hidden by files in:
      /opt/homebrew/lib
    runtime library [libboost_atomic.dylib] in /Users/username/miniforge3/envs/ros_env/lib may be hidden by files in:
      /opt/homebrew/lib

  Some of these libraries may not be found correctly.


In file included from /Users/username/ros2_ws/src/mapviz/mapviz/src/mapviz_main.cpp:30:
In file included from /Users/username/ros2_ws/src/mapviz/mapviz/include/mapviz/mapviz.hpp:36:
In file included from /Users/username/miniforge3/envs/ros_env/include/qt/QtWidgets/QMenu:1:
/Users/username/miniforge3/envs/ros_env/include/qt/QtWidgets/qmenu.h:238:31: error: non-virtual member function marked 'override' hides virtual member function
  238 |     void enterEvent(QEvent *) override;
      |                               ^
/opt/homebrew/include/QtWidgets/qwidget.h:673:18: note: hidden overloaded virtual function 'QWidget::enterEvent' declared here: type mismatch at 1st parameter ('QEnterEvent *' vs 'QEvent *')
  673 |     virtual void enterEvent(QEnterEvent *event);
      |                  ^
In file included from /Users/username/ros2_ws/src/mapviz/mapviz/src/mapviz_main.cpp:30:
In file included from /Users/username/ros2_ws/src/mapviz/mapviz/include/mapviz/mapviz.hpp:36:
In file included from /Users/username/miniforge3/envs/ros_env/include/qt/QtWidgets/QMenu:1:
/Users/username/miniforge3/envs/ros_env/include/qt/QtWidgets/qmenu.h:275:8: error: an attribute list cannot appear here
  275 | inline QT_DEPRECATED void qt_mac_set_dock_menu(QMenu *menu) { menu->setAsDockMenu(); }
      |        ^~~~~~~~~~~~~
/opt/homebrew/include/QtCore/qtdeprecationmarkers.h:25:25: note: expanded from macro 'QT_DEPRECATED'
   25 | #  define QT_DEPRECATED Q_DECL_DEPRECATED
      |                         ^~~~~~~~~~~~~~~~~
/opt/homebrew/include/QtCore/qcompilerdetection.h:999:29: note: expanded from macro 'Q_DECL_DEPRECATED'
  999 | #  define Q_DECL_DEPRECATED [[deprecated]]
      |                             ^~~~~~~~~~~~~~

核心问题是Qt头文件同时来自/opt/homebrew/include/和/Users/username/miniforge3/envs/ros_env/include，出现路径冲突导致编译失败。此前尝试设置Qt5_DIR和CMAKE_PREFIX_PATH未解决问题。

解决方案 #

1. 临时隔离Homebrew环境变量 #

编译前执行以下命令，移除Homebrew的路径影响，避免CMake误找到Homebrew的Qt：

export PATH=$(echo $PATH | tr ':' '\n' | grep -v '/opt/homebrew' | tr '\n' ':')
export CPATH=$(echo $CPATH | tr ':' '\n' | grep -v '/opt/homebrew/include' | tr '\n' ':')
export LIBRARY_PATH=$(echo $LIBRARY_PATH | tr ':' '\n' | grep -v '/opt/homebrew/lib' | tr '\n' ':')

2. 修改mapviz的CMakeLists.txt #

在mapviz包的CMakeLists.txt开头添加以下配置，强制CMake仅使用Mamba环境内的Qt：

# 清空Qt相关缓存路径，避免残留配置
unset(Qt5_DIR CACHE)
unset(Qt6_DIR CACHE)

# 指定Mamba环境的Qt配置路径
set(Qt5_DIR "${CONDA_PREFIX}/lib/cmake/Qt5")

# 限制CMake仅从指定路径查找依赖
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

# 添加Mamba环境的头文件和库路径优先级
include_directories(SYSTEM "${CONDA_PREFIX}/include")
link_directories("${CONDA_PREFIX}/lib")

3. 清理编译缓存并重新编译 #

删除旧的编译产物和缓存，确保新配置生效：

cd ~/ros2_ws
rm -rf build/mapviz install/mapviz log
colcon build --packages-select mapviz --cmake-clean-cache

4. 验证环境（可选） #

编译前确认Qt工具路径指向Mamba环境：

echo $(which qmake)
# 预期输出：/Users/username/miniforge3/envs/ros_env/bin/qmake

内容的提问来源于stack exchange，提问作者Ali Habiban