summaryrefslogtreecommitdiffstats
path: root/Help/manual/cmake-qt.7.rst
blob: 038279462690c918ecf2512e60dab6b5b78a9757 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
.. cmake-manual-description: CMake Qt Features Reference

cmake-qt(7)
***********

.. only:: html

   .. contents::

Introduction
============

CMake can find and use Qt 4 and Qt 5 libraries.  The Qt 4 libraries are found
by the :module:`FindQt4` find-module shipped with CMake, whereas the
Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See
:manual:`cmake-packages(7)` for more information about CMake packages, and
see `the Qt cmake manual <http://qt-project.org/doc/qt-5/cmake-manual.html>`_
for your Qt version.

Qt 4 and Qt 5 may be used together in the same
:manual:`CMake buildsystem <cmake-buildsystem(7)>`:

.. code-block:: cmake

  cmake_minimum_required(VERSION 3.8.0 FATAL_ERROR)

  project(Qt4And5)

  set(CMAKE_AUTOMOC ON)

  find_package(Qt5 COMPONENTS Widgets DBus REQUIRED)
  add_executable(publisher publisher.cpp)
  target_link_libraries(publisher Qt5::Widgets Qt5::DBus)

  find_package(Qt4 REQUIRED)
  add_executable(subscriber subscriber.cpp)
  target_link_libraries(subscriber Qt4::QtGui Qt4::QtDBus)

A CMake target may not link to both Qt 4 and Qt 5.  A diagnostic is issued if
this is attempted or results from transitive target dependency evaluation.

Qt Build Tools
==============

Qt relies on some bundled tools for code generation, such as ``moc`` for
meta-object code generation, ``uic`` for widget layout and population,
and ``rcc`` for virtual file system content generation.  These tools may be
automatically invoked by :manual:`cmake(1)` if the appropriate conditions
are met.  The automatic tool invocation may be used with both Qt 4 and Qt 5.

AUTOMOC
^^^^^^^

The :prop_tgt:`AUTOMOC` target property controls whether :manual:`cmake(1)`
inspects the C++ files in the target to determine if they require ``moc`` to
be run, and to create rules to execute ``moc`` at the appropriate time.

If a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is found in a header file,
``moc`` will be run on the file.  The result will be put into a file named
according to ``moc_<basename>.cpp``.
If the macro is found in a C++ implementation
file, the moc output will be put into a file named according to
``<basename>.moc``, following the Qt conventions.  The ``<basename>.moc`` must
be included by the user in the C++ implementation file with a preprocessor
``#include``.

Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the
``<AUTOGEN_BUILD_DIR>/include`` directory which is
automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.

* This differs from CMake 3.7 and below; see their documentation for details.

* For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`,
  the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``.

* See :prop_tgt:`AUTOGEN_BUILD_DIR`.

Not included ``moc_<basename>.cpp`` files will be generated in custom
folders to avoid name collisions and included in a separate
``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` file which is compiled
into the target.

* See :prop_tgt:`AUTOGEN_BUILD_DIR`.

The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and
:prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being
invoked for, and for the appropriate build configuration.

The :prop_tgt:`AUTOMOC` target property may be pre-set for all
following targets by setting the :variable:`CMAKE_AUTOMOC` variable.  The
:prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set
options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS`
variable may be populated to pre-set the options for all following targets.

Additional macro names to search for can be added to
:prop_tgt:`AUTOMOC_MACRO_NAMES`.

Additional ``moc`` dependency file names can be extracted from source code
by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`.

Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by
enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`.

.. _`Qt AUTOUIC`:

AUTOUIC
^^^^^^^

The :prop_tgt:`AUTOUIC` target property controls whether :manual:`cmake(1)`
inspects the C++ files in the target to determine if they require ``uic`` to
be run, and to create rules to execute ``uic`` at the appropriate time.

If a preprocessor ``#include`` directive is found which matches
``<path>ui_<basename>.h``, and a ``<basename>.ui`` file exists,
then ``uic`` will be executed to generate the appropriate file.
The ``<basename>.ui`` file is searched for in the following places

1. ``<source_dir>/<basename>.ui``
2. ``<source_dir>/<path><basename>.ui``
3. ``<AUTOUIC_SEARCH_PATHS>/<basename>.ui``
4. ``<AUTOUIC_SEARCH_PATHS>/<path><basename>.ui``

where ``<source_dir>`` is the directory of the C++ file and
:prop_tgt:`AUTOUIC_SEARCH_PATHS` is a list of additional search paths.

The generated generated ``ui_*.h`` files are placed in the
``<AUTOGEN_BUILD_DIR>/include`` directory which is
automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.

* This differs from CMake 3.7 and below; see their documentation for details.

* For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`,
  the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``.

* See :prop_tgt:`AUTOGEN_BUILD_DIR`.

The :prop_tgt:`AUTOUIC` target property may be pre-set for all following
targets by setting the :variable:`CMAKE_AUTOUIC` variable.  The
:prop_tgt:`AUTOUIC_OPTIONS` target property may be populated to set options
to pass to ``uic``.  The :variable:`CMAKE_AUTOUIC_OPTIONS` variable may be
populated to pre-set the options for all following targets.  The
:prop_sf:`AUTOUIC_OPTIONS` source file property may be set on the
``<basename>.ui`` file to set particular options for the file.  This
overrides options from the :prop_tgt:`AUTOUIC_OPTIONS` target property.

A target may populate the :prop_tgt:`INTERFACE_AUTOUIC_OPTIONS` target
property with options that should be used when invoking ``uic``.  This must be
consistent with the :prop_tgt:`AUTOUIC_OPTIONS` target property content of the
depender target.  The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may
be used to track the origin target of such
:prop_tgt:`INTERFACE_AUTOUIC_OPTIONS`.  This means that a library which
provides an alternative translation system for Qt may specify options which
should be used when running ``uic``:

.. code-block:: cmake

  add_library(KI18n klocalizedstring.cpp)
  target_link_libraries(KI18n Qt5::Core)

  # KI18n uses the tr2i18n() function instead of tr().  That function is
  # declared in the klocalizedstring.h header.
  set(autouic_options
    -tr tr2i18n
    -include klocalizedstring.h
  )

  set_property(TARGET KI18n APPEND PROPERTY
    INTERFACE_AUTOUIC_OPTIONS ${autouic_options}
  )

A consuming project linking to the target exported from upstream automatically
uses appropriate options when ``uic`` is run by :prop_tgt:`AUTOUIC`, as a
result of linking with the :prop_tgt:`IMPORTED` target:

.. code-block:: cmake

  set(CMAKE_AUTOUIC ON)
  # Uses a libwidget.ui file:
  add_library(LibWidget libwidget.cpp)
  target_link_libraries(LibWidget
    KF5::KI18n
    Qt5::Widgets
  )

Source files can be excluded from :prop_tgt:`AUTOUIC` processing by
enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`.

.. _`Qt AUTORCC`:

AUTORCC
^^^^^^^

The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)`
creates rules to execute ``rcc`` at the appropriate time on source files
which have the suffix ``.qrc``.

.. code-block:: cmake

  add_executable(myexe main.cpp resource_file.qrc)

The :prop_tgt:`AUTORCC` target property may be pre-set for all following targets
by setting the :variable:`CMAKE_AUTORCC` variable.  The
:prop_tgt:`AUTORCC_OPTIONS` target property may be populated to set options
to pass to ``rcc``.  The :variable:`CMAKE_AUTORCC_OPTIONS` variable may be
populated to pre-set the options for all following targets.  The
:prop_sf:`AUTORCC_OPTIONS` source file property may be set on the
``<name>.qrc`` file to set particular options for the file.  This
overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property.

Source files can be excluded from :prop_tgt:`AUTORCC` processing by
enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`.

The ``<ORIGIN>_autogen`` target
===============================

The ``moc`` and ``uic`` tools are executed as part of a synthesized
``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by
CMake.  By default that ``<ORIGIN>_autogen`` target inherits the dependencies
of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`).
Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding
them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property.

Visual Studio Generators
========================

When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake
generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>`
instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>`
(for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`).
This isn't always possible though and
an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used,
when either

- the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't
  excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by
  :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN`
  or :policy:`CMP0071`
- :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file

qtmain.lib on Windows
=====================

The Qt 4 and 5 :prop_tgt:`IMPORTED` targets for the QtGui libraries specify
that the qtmain.lib static library shipped with Qt will be linked by all
dependent executables which have the :prop_tgt:`WIN32_EXECUTABLE` enabled.

To disable this behavior, enable the ``Qt5_NO_LINK_QTMAIN`` target property for
Qt 5 based targets or ``QT4_NO_LINK_QTMAIN`` target property for Qt 4 based
targets.

.. code-block:: cmake

  add_executable(myexe WIN32 main.cpp)
  target_link_libraries(myexe Qt4::QtGui)

  add_executable(myexe_no_qtmain WIN32 main_no_qtmain.cpp)
  set_property(TARGET main_no_qtmain PROPERTY QT4_NO_LINK_QTMAIN ON)
  target_link_libraries(main_no_qtmain Qt4::QtGui)