Help/manual/cmake-qt.7.rst

   1 .. cmake-manual-description: CMake Qt Features Reference
   2
   3 cmake-qt(7)
   4 ***********
   5
   6 .. only:: html
   7
   8    .. contents::
   9
  10 Introduction
  11 ============
  12
  13 CMake can find and use Qt 4 and Qt 5 libraries.  The Qt 4 libraries are found
  14 by the :module:`FindQt4` find-module shipped with CMake, whereas the
  15 Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See
  16 :manual:`cmake-packages(7)` for more information about CMake packages, and
  17 see `the Qt cmake manual <https://contribute.qt-project.org/doc/qt-5/cmake-manual.html>`_
  18 for your Qt version.
  19
  20 Qt 4 and Qt 5 may be used together in the same
  21 :manual:`CMake buildsystem <cmake-buildsystem(7)>`:
  22
  23 .. code-block:: cmake
  24
  25   cmake_minimum_required(VERSION 3.8.0 FATAL_ERROR)
  26
  27   project(Qt4And5)
  28
  29   set(CMAKE_AUTOMOC ON)
  30
  31   find_package(Qt5 COMPONENTS Widgets DBus REQUIRED)
  32   add_executable(publisher publisher.cpp)
  33   target_link_libraries(publisher Qt5::Widgets Qt5::DBus)
  34
  35   find_package(Qt4 REQUIRED)
  36   add_executable(subscriber subscriber.cpp)
  37   target_link_libraries(subscriber Qt4::QtGui Qt4::QtDBus)
  38
  39 A CMake target may not link to both Qt 4 and Qt 5.  A diagnostic is issued if
  40 this is attempted or results from transitive target dependency evaluation.
  41
  42 Qt Build Tools
  43 ==============
  44
  45 Qt relies on some bundled tools for code generation, such as ``moc`` for
  46 meta-object code generation, ``uic`` for widget layout and population,
  47 and ``rcc`` for virtual file system content generation.  These tools may be
  48 automatically invoked by :manual:`cmake(1)` if the appropriate conditions
  49 are met.  The automatic tool invocation may be used with both Qt 4 and Qt 5.
  50
  51 .. _`Qt AUTOMOC`:
  52
  53 AUTOMOC
  54 ^^^^^^^
  55
  56 The :prop_tgt:`AUTOMOC` target property controls whether :manual:`cmake(1)`
  57 inspects the C++ files in the target to determine if they require ``moc`` to
  58 be run, and to create rules to execute ``moc`` at the appropriate time.
  59
  60 If a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is found in a header file,
  61 ``moc`` will be run on the file.  The result will be put into a file named
  62 according to ``moc_<basename>.cpp``.
  63 If the macro is found in a C++ implementation
  64 file, the moc output will be put into a file named according to
  65 ``<basename>.moc``, following the Qt conventions.  The ``<basename>.moc`` must
  66 be included by the user in the C++ implementation file with a preprocessor
  67 ``#include``.
  68
  69 Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the
  70 ``<AUTOGEN_BUILD_DIR>/include`` directory which is
  71 automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
  72
  73 * This differs from CMake 3.7 and below; see their documentation for details.
  74
  75 * For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`,
  76   the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``.
  77
  78 * See :prop_tgt:`AUTOGEN_BUILD_DIR`.
  79
  80 Not included ``moc_<basename>.cpp`` files will be generated in custom
  81 folders to avoid name collisions and included in a separate
  82 file which is compiled into the target, named either
  83 ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` or
  84 ``<AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.cpp``.
  85
  86 * See :prop_tgt:`AUTOGEN_BUILD_DIR`.
  87
  88 The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and
  89 :prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being
  90 invoked for, and for the appropriate build configuration.
  91
  92 The :prop_tgt:`AUTOMOC` target property may be pre-set for all
  93 following targets by setting the :variable:`CMAKE_AUTOMOC` variable.  The
  94 :prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set
  95 options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS`
  96 variable may be populated to pre-set the options for all following targets.
  97
  98 Additional macro names to search for can be added to
  99 :prop_tgt:`AUTOMOC_MACRO_NAMES`.
 100
 101 Additional ``moc`` dependency file names can be extracted from source code
 102 by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`.
 103
 104 Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by
 105 enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`.
 106
 107 .. _`Qt AUTOUIC`:
 108
 109 AUTOUIC
 110 ^^^^^^^
 111
 112 The :prop_tgt:`AUTOUIC` target property controls whether :manual:`cmake(1)`
 113 inspects the C++ files in the target to determine if they require ``uic`` to
 114 be run, and to create rules to execute ``uic`` at the appropriate time.
 115
 116 If a preprocessor ``#include`` directive is found which matches
 117 ``<path>ui_<basename>.h``, and a ``<basename>.ui`` file exists,
 118 then ``uic`` will be executed to generate the appropriate file.
 119 The ``<basename>.ui`` file is searched for in the following places
 120
 121 1. ``<source_dir>/<basename>.ui``
 122 2. ``<source_dir>/<path><basename>.ui``
 123 3. ``<AUTOUIC_SEARCH_PATHS>/<basename>.ui``
 124 4. ``<AUTOUIC_SEARCH_PATHS>/<path><basename>.ui``
 125
 126 where ``<source_dir>`` is the directory of the C++ file and
 127 :prop_tgt:`AUTOUIC_SEARCH_PATHS` is a list of additional search paths.
 128
 129 The generated generated ``ui_*.h`` files are placed in the
 130 ``<AUTOGEN_BUILD_DIR>/include`` directory which is
 131 automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
 132
 133 * This differs from CMake 3.7 and below; see their documentation for details.
 134
 135 * For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`,
 136   the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``.
 137
 138 * See :prop_tgt:`AUTOGEN_BUILD_DIR`.
 139
 140 The :prop_tgt:`AUTOUIC` target property may be pre-set for all following
 141 targets by setting the :variable:`CMAKE_AUTOUIC` variable.  The
 142 :prop_tgt:`AUTOUIC_OPTIONS` target property may be populated to set options
 143 to pass to ``uic``.  The :variable:`CMAKE_AUTOUIC_OPTIONS` variable may be
 144 populated to pre-set the options for all following targets.  The
 145 :prop_sf:`AUTOUIC_OPTIONS` source file property may be set on the
 146 ``<basename>.ui`` file to set particular options for the file.  This
 147 overrides options from the :prop_tgt:`AUTOUIC_OPTIONS` target property.
 148
 149 A target may populate the :prop_tgt:`INTERFACE_AUTOUIC_OPTIONS` target
 150 property with options that should be used when invoking ``uic``.  This must be
 151 consistent with the :prop_tgt:`AUTOUIC_OPTIONS` target property content of the
 152 depender target.  The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may
 153 be used to track the origin target of such
 154 :prop_tgt:`INTERFACE_AUTOUIC_OPTIONS`.  This means that a library which
 155 provides an alternative translation system for Qt may specify options which
 156 should be used when running ``uic``:
 157
 158 .. code-block:: cmake
 159
 160   add_library(KI18n klocalizedstring.cpp)
 161   target_link_libraries(KI18n Qt5::Core)
 162
 163   # KI18n uses the tr2i18n() function instead of tr().  That function is
 164   # declared in the klocalizedstring.h header.
 165   set(autouic_options
 166     -tr tr2i18n
 167     -include klocalizedstring.h
 168   )
 169
 170   set_property(TARGET KI18n APPEND PROPERTY
 171     INTERFACE_AUTOUIC_OPTIONS ${autouic_options}
 172   )
 173
 174 A consuming project linking to the target exported from upstream automatically
 175 uses appropriate options when ``uic`` is run by :prop_tgt:`AUTOUIC`, as a
 176 result of linking with the :prop_tgt:`IMPORTED` target:
 177
 178 .. code-block:: cmake
 179
 180   set(CMAKE_AUTOUIC ON)
 181   # Uses a libwidget.ui file:
 182   add_library(LibWidget libwidget.cpp)
 183   target_link_libraries(LibWidget
 184     KF5::KI18n
 185     Qt5::Widgets
 186   )
 187
 188 Source files can be excluded from :prop_tgt:`AUTOUIC` processing by
 189 enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`.
 190
 191 .. _`Qt AUTORCC`:
 192
 193 AUTORCC
 194 ^^^^^^^
 195
 196 The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)`
 197 creates rules to execute ``rcc`` at the appropriate time on source files
 198 which have the suffix ``.qrc``.
 199
 200 .. code-block:: cmake
 201
 202   add_executable(myexe main.cpp resource_file.qrc)
 203
 204 The :prop_tgt:`AUTORCC` target property may be pre-set for all following targets
 205 by setting the :variable:`CMAKE_AUTORCC` variable.  The
 206 :prop_tgt:`AUTORCC_OPTIONS` target property may be populated to set options
 207 to pass to ``rcc``.  The :variable:`CMAKE_AUTORCC_OPTIONS` variable may be
 208 populated to pre-set the options for all following targets.  The
 209 :prop_sf:`AUTORCC_OPTIONS` source file property may be set on the
 210 ``<name>.qrc`` file to set particular options for the file.  This
 211 overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property.
 212
 213 Source files can be excluded from :prop_tgt:`AUTORCC` processing by
 214 enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`.
 215
 216 The ``<ORIGIN>_autogen`` target
 217 ===============================
 218
 219 The ``moc`` and ``uic`` tools are executed as part of a synthesized
 220 ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by
 221 CMake.  By default that ``<ORIGIN>_autogen`` target inherits the dependencies
 222 of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`).
 223 Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding
 224 them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property.
 225
 226 Visual Studio Generators
 227 ========================
 228
 229 When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake
 230 generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>`
 231 instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>`
 232 (for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`).
 233 This isn't always possible though and
 234 an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used,
 235 when either
 236
 237 - the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't
 238   excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by
 239   :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN`
 240   or :policy:`CMP0071`
 241 - :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file
 242 - :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is enabled
 243
 244 qtmain.lib on Windows
 245 =====================
 246
 247 The Qt 4 and 5 :prop_tgt:`IMPORTED` targets for the QtGui libraries specify
 248 that the qtmain.lib static library shipped with Qt will be linked by all
 249 dependent executables which have the :prop_tgt:`WIN32_EXECUTABLE` enabled.
 250
 251 To disable this behavior, enable the ``Qt5_NO_LINK_QTMAIN`` target property for
 252 Qt 5 based targets or ``QT4_NO_LINK_QTMAIN`` target property for Qt 4 based
 253 targets.
 254
 255 .. code-block:: cmake
 256
 257   add_executable(myexe WIN32 main.cpp)
 258   target_link_libraries(myexe Qt4::QtGui)
 259
 260   add_executable(myexe_no_qtmain WIN32 main_no_qtmain.cpp)
 261   set_property(TARGET main_no_qtmain PROPERTY QT4_NO_LINK_QTMAIN ON)
 262   target_link_libraries(main_no_qtmain Qt4::QtGui)