Comprehensive Guide to Integrating Qt Projects with CMake: The Correct Approach to Automatic MOC / UIC / RCC

When writing C++ projects with Qt, many people’s first reaction is to directly use Qt Creator to create a .pro project, compile, and run, which goes smoothly. However, once the project needs to interface with an existing CMake build system or needs to be built in a cross-platform CI environment, the .pro file becomes inflexible, making the switch to CMake a necessary choice.

The first hurdle in migrating a Qt project to CMake is the automatic generation steps for MOC / UIC / RCC. If the configuration is incorrect, you may encounter strange issues such as signal-slot failures, UI files not compiling, and missing resource files. Below, I will summarize my approach to integrating Qt with CMake and discuss the principles behind these mechanisms.

📚 The C++ Knowledge Base is now live on ima! The current content covered by the knowledge base is shown in the image below:👇👇👇

📌 Students interested in the knowledge base can add the assistant vx (cppmiao24) with the note 【Knowledge Base】 or click 👉 C++ Knowledge Base (tap to jump) to view the complete introduction to the knowledge base～

1. The Roles of the Three Tools

When building a Qt project with CMake, these three tasks must be handled properly:

Tool	Function	Input	Output
MOC (Meta-Object Compiler)	Processes the `<span>Q_OBJECT</span>` macro and generates meta-object code	`<span>.h</span>`	`<span>moc_xxx.cpp</span>`
UIC (User Interface Compiler)	Converts `<span>.ui</span>` XML to C++ code	`<span>.ui</span>`	`<span>ui_xxx.h</span>`
RCC (Resource Compiler)	Packs `<span>.qrc</span>` resource files into C++ source code	`<span>.qrc</span>`	`<span>qrc_xxx.cpp</span>`

In a .pro project, these steps are handled by Qt itself; in CMake, you need to explicitly tell it to execute these steps and include the generated files in the build link.

2. Letting CMake Handle MOC / UIC / RCC Automatically

The good news is that starting from CMake 3.10, all three tasks can be automatically completed using built-in switches. The core configuration is as follows:

cmake_minimum_required(VERSION 3.10)
project(MyQtApp LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Widgets)

# Key: Enable automatic generation
set(CMAKE_AUTOMOC ON)   # Automatically run MOC
set(CMAKE_AUTOUIC ON)   # Automatically run UIC
set(CMAKE_AUTORCC ON)   # Automatically run RCC

add_executable(MyQtApp
    main.cpp
    mainwindow.cpp
    mainwindow.h
    mainwindow.ui      # Triggers UIC
    resources.qrc      # Triggers RCC
)

target_link_libraries(MyQtApp PRIVATE Qt6::Widgets)

These ON switches tell CMake:

To scan .h, .cpp, .ui, and .qrc files before compilation
If it finds a Q_OBJECT macro, it automatically calls moc
If there are .ui files, it uses uic to convert them to .h
If there are .qrc files, it uses rcc to convert them to .cpp

This essentially allows for “just add files to compile” without the need to manually manage generated files.

3. The Storage Path for Automatically Generated Files

By default, CMake will place moc_*.cpp, ui_*.h, and qrc_*.cpp in the build directory. If you don’t see these files in your IDE (like CLion), don’t be surprised; they are in the build directory, not the source directory.

If you want to see the generated code during debugging, you can directly look in the build/ directory, for example:

build/CMakeFiles/MyQtApp_autogen

Sometimes I add:

set(CMAKE_INCLUDE_CURRENT_DIR ON)

This allows both the current directory and the automatically generated directory to be included in the include path, eliminating the need for manual include_directories.

4. Manually Specifying MOC/UIC/RCC (Special Cases)

Although the automatic mode is convenient, there are cases where you need to add them manually, such as:

A header file is not in the project directory and cannot be scanned automatically
The generated ui_*.h needs to be placed in a specific path

In this case, you can use:

qt6_wrap_cpp(MOC_SOURCES myclass.h)
qt6_wrap_ui(UI_SOURCES mainwindow.ui)
qt6_add_resources(RCC_SOURCES resources.qrc)

add_executable(MyQtApp
    main.cpp
    ${MOC_SOURCES}
    ${UI_SOURCES}
    ${RCC_SOURCES}
)

However, in manual mode, you have to manage the generated files yourself, which is less convenient than automatic mode.

5. Differences Between Qt5 and Qt6

find_package(Qt6 ...) replaces find_package(Qt5 ...)
Qt6 recommends using qt_add_executable() and qt_add_resources()
The automatic MOC/UIC/RCC mechanisms for Qt5/6 are basically the same, with differences mainly in the API prefix

If you are still using a Qt5 project, you can replace Qt6::Widgets with Qt5::Widgets, keeping everything else unchanged.

6. Common Pitfalls

Forgetting to enable automatic switches Forgetting to set set(CMAKE_AUTOMOC ON) will lead to signal-slot failures, and during compilation, you may encounter “undefined reference to vtable” errors.
.ui files not added to target.ui must appear in the source file list of add_executable() or add_library(), otherwise UIC will not be triggered.
.qrc not in the build link.qrc also needs to be explicitly added.
Mixing Qt versionsfind_package(Qt5) paths found mixed with Qt6::Widgets will cause compilation to fail.

7. Conclusion

If you are integrating a Qt project with CMake and want to avoid pitfalls, it is recommended to directly enable:

set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTORCC ON)

Then, simply place the .ui and .qrc files directly in the target’s source file list, allowing CMake to automatically call the corresponding tools. This results in a clear build link, high portability, and easy integration with CI systems and cross-platform builds.

My personal experience is that once a project is switched to CMake, it is best to maintain the principle of letting CMake take over all generation steps, avoiding mixing in .pro files or external scripts. This will make future maintenance and migration much easier.