Get started with CMake

Start with find_package to locate the libraries and header files shipped with Qt. Then, you can use these libraries and header files with the target_link_libraries command to build Qt-based libraries and applications. This command automatically adds the appropriate include directories, compile definitions, the position-independent-code flag, and links to the qtmain.lib library on Windows, for example.

Build a GUI executable

To build a helloworld GUI executable, you need the following:

 cmake_minimum_required(VERSION 3.1.0)

 project(helloworld)

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

 if(CMAKE_VERSION VERSION_LESS "3.7.0")
     set(CMAKE_INCLUDE_CURRENT_DIR ON)
 endif()

 find_package(Qt5 COMPONENTS Widgets REQUIRED)

 add_executable(helloworld
     mainwindow.ui
     mainwindow.cpp
     main.cpp
     resources.qrc
 )

 target_link_libraries(helloworld Qt5::Widgets)

For find_package to be successful, CMake must find the Qt installation in one of the following ways:

1. Set your CMAKE_PREFIX_PATH environment variable to the Qt 5 installation prefix. This is the recommended way.
2. Set the Qt5_DIR in the CMake cache to the location of the Qt5Config.cmake file.

The CMAKE_AUTOMOC setting runs moc automatically when required. For more details, see CMake AUTOMOC documentation.

Imported library targets

Each Qt module that is loaded defines a CMake library target. The target names start with Qt5::, followed by the module name. For example: Qt5::Core, Qt5::Gui. Pass the name of the library target to target_link_libraries to use the respective library.

Note: Since Qt 5.15, the CMake targets are also available as Qt::Core, Qt::Gui, and so on. This eases writing CMake code that can work with both Qt 5 and Qt 6.

Imported targets are created with the same configurations as when Qt was configured. That is:

• If Qt was configured with the -debug switch, an imported target with the DEBUG configuration is created.
• If Qt was configured with the -release switch, an imported target with the RELEASE configuration is created.
• If Qt was configured with the -debug-and-release switch, then imported targets are created with both RELEASE and DEBUG configurations.

If your project has custom CMake build configurations, you have to map your custom configuration to either the debug or the release Qt configuration.

 find_package(Qt5 COMPONENTS Core REQUIRED)

 set(CMAKE_CXX_FLAGS_COVERAGE "${CMAKE_CXX_FLAGS_RELEASE} -fprofile-arcs -ftest-coverage")

 # set up a mapping so that the Release configuration for the Qt imported target is
 # used in the COVERAGE CMake configuration.
 set_target_properties(Qt5::Core PROPERTIES MAP_IMPORTED_CONFIG_COVERAGE "RELEASE")