Building with CMake | Qt 5.12

- Qt 5.12
- Building with CMake
- Qt 5.12.10 Reference Documentation

# Building with CMake

`CMake` is a tool that helps simplify the build process for development projects across different platforms. `CMake` automates the generation of buildsystems such as Makefiles and Visual Studio project files.

`CMake` is a 3rd party tool with its own documentation. The rest of this topic details the specifics of how to use Qt 5 with `CMake`. The minimum version required to use Qt5 is `CMake` 3.1.0.

## Getting Started

The first requirement when using `CMake` is to use `find_package` to locate the libraries and header files shipped with Qt. These libraries and header files can then be used to build libraries and applications based on Qt.

The recommended way to use Qt libraries and headers with `CMake` is to use the `target_link_libraries` command. This command automatically adds appropriate include directories, compile definitions, the position-independent-code flag, and links to the qtmain.lib library on Windows.

To build a helloworld GUI executable, typical usage would be:

     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)

In order for `find_package` to be successful, Qt 5 must be found below the CMAKE_PREFIX_PATH, or the `Qt5_DIR` must be set in the `CMake` cache to the location of the `Qt5Config.cmake` file. The easiest way to use `CMake` is to set the CMAKE_PREFIX_PATH environment variable to the install prefix of Qt 5.

The CMAKE_AUTOMOC setting runs moc automatically when required. For more on this feature see the CMake AUTOMOC documentation

### Imported targets

Imported targets are created for each Qt module. Imported target names should be preferred instead of using a variable like Qt5<Module>_LIBRARIES in CMake commands such as `target_link_libraries`. The actual path to the library can be obtained using the LOCATION property:

     find_package(Qt5 COMPONENTS Core REQUIRED)

     get_target_property(QtCore_location Qt5::Core LOCATION)

Note however that it is rare to require the full location to the library in `CMake` code. Most `CMake` APIs are aware of imported targets and can automatically use them instead of the full path.

Each module in Qt 5 has a library target with the naming convention Qt5::<Module> which can be used for this purpose.

Imported targets are created with the configurations Qt was configured with. That is, if Qt was configured with the -debug switch, an imported target with the configuration DEBUG will be created. If Qt was configured with the -release switch an imported target with the configuration RELEASE will be created. If Qt was configured with the -debug-and-release switch (the default on windows), then imported targets will be created with both RELEASE and DEBUG configurations.

If your project has custom CMake build configurations, it may be necessary to set a mapping from your custom configuration to either the debug or 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")

Plugins are also available as `IMPORTED` targets in CMake. The Qt Network, Qt SQL, Qt GUI, and Qt Widgets modules have plugins associated. They provide a list of plugins in the `Qt5`<Module>`_PLUGINS` variable.

     foreach(plugin ${Qt5Network_PLUGINS})
       get_target_property(_loc ${plugin} LOCATION)
       message("Plugin ${plugin} is at location ${_loc}")
     endforeach()

## Variable Reference

### Module variables

The result of a `find_package` call is that imported targets will be created for use with `target_link_libraries`, some variables will be populated with information required to configure the build, and macros will be made available for use. The name of the imported target for each module matches the name of the module with a prefix of 'Qt5::', for example Qt5::Widgets. All of the package-specific variables have a consistent name with a prefix of the name of the package. For example, `find_package(Qt5 COMPONENTS Widgets)` will make the following variables available if successfully found:

- Qt5Widgets_VERSION String describing the version of the module.
- Qt5Widgets_LIBRARIES List of libraries for use with the target_link_libraries command.
- Qt5Widgets_INCLUDE_DIRS List of directories for use with the include_directories command.
- Qt5Widgets_DEFINITIONS List of definitions for use with add_definitions.
- Qt5Widgets_COMPILE_DEFINITIONS List of definitions for use with the COMPILE_DEFINITIONS target property.
- Qt5Widgets_FOUND Boolean describing whether the module was found successfully.
- Qt5Widgets_EXECUTABLE_COMPILE_FLAGS String of flags to be used when building executables.

Equivalents of those variables will be available for all packages found with a `find_package` call. Note that the variables are case-sensitive.

### Installation variables

Additionally, several other variables are available which do not relate to a particular package, but to the Qt installation itself.

- QT_VISIBILITY_AVAILABLE Boolean describing whether Qt was built with hidden visibility.
- QT_LIBINFIX String containing the infix used in library names.

## Command Reference

### Qt5::Core

qt5_add_big_resources | Compiles big binary resources into object code
qt5_add_binary_resources | Creates an RCC file from a list of Qt resource files
qt5_add_resources | Compiles binary resources into source code
qt5_generate_moc | Calls moc on an input file
qt5_wrap_cpp | Creates .moc files from sources

### Qt5::Widgets

qt5_wrap_ui | Creates sources for .ui files

### Qt5::DBus

qt5_add_dbus_adaptor | Generates an adaptor class for a D-Bus interface
qt5_add_dbus_interface | Generates C++ sources implementing an interface for a D-Bus interface description file
qt5_add_dbus_interfaces | Generates C++ sources implementing interfaces for D-Bus interface description files
qt5_generate_dbus_interface | Generates a D-Bus interface from a header file

### Qt5::LinguistTools

qt5_add_translation | Compiles Qt Linguist .ts files into .qm files
qt5_create_translation | Sets up the Qt Linguist translation toolchain