CMake未为共享库中Q_NAMESPACE运行moc致链接错误

核心原因 #

CMake与qmake对Qt元对象宏的处理逻辑存在差异：qmake会自动扫描所有包含Qt元对象相关宏的头文件，而CMake的自动moc扫描仅针对带有Q_OBJECT、Q_GADGET等类级宏的文件。Q_NAMESPACE属于命名空间级宏，默认不会被CMake的自动扫描识别，因此无法生成对应的moc文件，最终导致staticMetaObject未定义的链接错误。

解决方法 #

1. 显式触发moc生成 #

针对包含Q_NAMESPACE的头文件，使用CMake提供的Qt moc命令强制生成moc代码：

Qt5 配置：

# 为目标头文件生成moc代码
qt_wrap_cpp(MOC_GENERATED enum_namespace.h)
# 将生成的moc文件加入共享库编译源
add_library(your_shared_lib SHARED ${PROJECT_SOURCES} ${MOC_GENERATED})

Qt6 配置：

# Qt6使用qt_add_moc替代qt_wrap_cpp
qt_add_moc(MOC_GENERATED enum_namespace.h)
add_library(your_shared_lib SHARED ${PROJECT_SOURCES} ${MOC_GENERATED})

2. 确保头文件在CMake扫描范围内 #

将包含Q_NAMESPACE的头文件所在目录添加到库的包含路径中，避免moc工具无法解析头文件：

target_include_directories(your_shared_lib
    PUBLIC
        ${CMAKE_CURRENT_SOURCE_DIR}/include
)

3. 验证Qt模块依赖配置 #

确保CMakeLists.txt中正确引入了Qt Core模块（处理元对象系统的核心依赖），并链接到共享库：

# Qt5
find_package(Qt5 REQUIRED COMPONENTS Core Qml)
target_link_libraries(your_shared_lib PUBLIC Qt5::Core Qt5::Qml)

# Qt6
find_package(Qt6 REQUIRED COMPONENTS Core Qml)
target_link_libraries(your_shared_lib PUBLIC Qt6::Core Qt6::Qml)

4. 清理构建缓存重新编译 #

旧的构建缓存可能导致moc生成异常，完全删除构建目录后，重新执行cmake配置和编译命令，排除缓存干扰。

5. 检查头文件宏使用正确性 #

确认头文件中Q_NAMESPACE的使用符合Qt规范，必须包含QObject头文件，且宏位置正确：

#include <QObject>

namespace EnumNamespace {
Q_NAMESPACE
enum class MyEnum { Option1, Option2 };
Q_ENUM_NS(MyEnum) // 若需向QML注册枚举则添加此宏
}

内容的提问来源于stack exchange，提问作者Adri C.S.