Qt Project Structure & CMake

Qt Project Layout

A typical Qt 6 CMake project looks like this:

MyApp/
├── CMakeLists.txt          # Top-level build script
├── main.cpp                # Entry point
├── mainwindow.h            # Main window header
├── mainwindow.cpp          # Main window implementation
├── mainwindow.ui           # Qt Designer UI file (optional)
├── resources.qrc           # Qt resource file (optional)
└── build/                  # Out-of-source build directory

For larger projects, split into subdirectories:

MyApp/
├── CMakeLists.txt
├── src/
│   ├── CMakeLists.txt
│   ├── main.cpp
│   └── core/
│       ├── engine.h
│       └── engine.cpp
├── ui/
│   └── mainwindow.ui
└── resources/
    ├── resources.qrc
    └── icons/

CMakeLists.txt — Full Qt6 Example

cmake_minimum_required(VERSION 3.16)

project(MyApp
    VERSION 1.0.0
    DESCRIPTION "My Qt Application"
    LANGUAGES CXX
)

# Require C++17
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Qt auto-tools — must be set before find_package
set(CMAKE_AUTOMOC ON)   # Meta-Object Compiler
set(CMAKE_AUTORCC ON)   # Resource Compiler
set(CMAKE_AUTOUIC ON)   # UI Compiler

# Find Qt6 components
find_package(Qt6 REQUIRED COMPONENTS
    Core
    Widgets
    Network
    Quick
)

qt_standard_project_setup()

# Collect sources
set(SOURCES
    src/main.cpp
    src/mainwindow.cpp
)

set(HEADERS
    src/mainwindow.h
)

set(UI_FILES
    ui/mainwindow.ui
)

set(RESOURCES
    resources/resources.qrc
)

# Create executable
qt_add_executable(MyApp
    ${SOURCES}
    ${HEADERS}
    ${UI_FILES}
    ${RESOURCES}
)

# Link Qt modules
target_link_libraries(MyApp PRIVATE
    Qt6::Core
    Qt6::Widgets
    Qt6::Network
)

# Include dirs
target_include_directories(MyApp PRIVATE src/)

qmake vs CMake

Qt 6 recommends CMake for all new projects. qmake is still supported but considered legacy.

Feature	CMake	qmake
Qt recommendation	Preferred (Qt 6+)	Legacy
IDE support	Qt Creator, CLion, VS	Qt Creator
Cross-platform	Excellent	Good
Ecosystem	Broad (vcpkg, Conan)	Qt-only
Syntax	Verbose but powerful	Simpler

The Qt Auto-Tools (MOC, UIC, RCC)

Qt relies on three code-generation tools:

MOC — Meta-Object Compiler

Processes header files with Q_OBJECT macro and generates meta-object code for signals/slots and reflection.

set(CMAKE_AUTOMOC ON)  # handled automatically by CMake

UIC — UI Compiler

Converts .ui files (Qt Designer) into C++ header files (ui_mainwindow.h).

set(CMAKE_AUTOUIC ON)

RCC — Resource Compiler

Embeds binary resources (images, QML files) into the executable.

set(CMAKE_AUTORCC ON)

Build Configurations

# Configure (Debug)
cmake -B build -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_PREFIX_PATH=/path/to/Qt/6.x/gcc_64

# Configure (Release)
cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_PREFIX_PATH=/path/to/Qt/6.x/gcc_64

# Build
cmake --build build --parallel $(nproc)

# Run
./build/MyApp

Qt Resource System (.qrc)

Embed files into your binary so they’re always available:

<!-- resources/resources.qrc -->
<RCC>
  <qresource prefix="/icons">
    <file>icons/app.png</file>
    <file>icons/logo.svg</file>
  </qresource>
  <qresource prefix="/qml">
    <file>qml/Main.qml</file>
  </qresource>
</RCC>

Access in C++:

QIcon icon(":/icons/app.png");
QFile file(":/qml/Main.qml");

Summary

Concept	Purpose
`CMAKE_AUTOMOC`	Auto-run MOC for Q_OBJECT classes
`CMAKE_AUTOUIC`	Auto-compile .ui files
`CMAKE_AUTORCC`	Auto-embed .qrc resources
`qt_add_executable`	Qt-aware executable target
`find_package(Qt6)`	Locate installed Qt modules

Next tutorial → Signals & Slots