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
|
/****************************************************************************
**
** Copyright (C) 2012 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Stephen Kelly <stephen.kelly@kdab.com>
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page cmake-manual.html
\target CMake Manual
\title Building with CMake
\c {CMake} is a tool that helps simplify the build process for
development projects across different platforms. \c{CMake}
automates the generation of buildsystems such as Makefiles and Visual Studio project
files.
\c{CMake} is a 3rd party tool with its own \l{CMake Documentation}{documentation}.
The rest of this topic details the specifics of how to use Qt 5 with \c{CMake}.
The minimum version required to use Qt5 is \c{CMake} 3.1.0.
\section1 Getting Started
The first requirement when using \c{CMake} is to use \c{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 \c{CMake} is to use
the \c{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:
\snippet snippets/cmake/CMakeLists.pro 0
In order for \c{find_package} to be successful, Qt 5 must be found below the CMAKE_PREFIX_PATH,
or the \c{Qt5_DIR} must be set in the \c{CMake} cache to the location of the
\c{Qt5Config.cmake} file. The easiest way to use \c{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 \l{CMake AUTOMOC documentation}
\section2 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 \c{target_link_libraries}.
The actual path to the library can be obtained using the \l{CMake LOCATION Documentation}{LOCATION property}:
\snippet snippets/cmake/CMakeLists.pro 1
Note however that it is rare to require the full location to the library in \c{CMake} code. Most
\c{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.
\snippet snippets/cmake/CMakeLists.pro 2
Plugins are also available as \c IMPORTED targets in CMake. The \l{Qt
Network}, \l{Qt SQL}, \l{Qt GUI}, and \l{Qt Widgets} modules have plugins
associated. They provide a list of plugins in the
\c{Qt5}\e{<Module>}\c{_PLUGINS} variable.
\snippet snippets/cmake/CMakeLists.pro 5
\section1 Variable Reference
\section2 Module variables
The result of a \c{find_package} call is that imported targets will be created for
use with \c{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,
\c{find_package(Qt5 COMPONENTS Widgets)} will make the following variables available
if successfully found:
\list
\li Qt5Widgets_VERSION String describing the version of the module.
\li Qt5Widgets_LIBRARIES List of libraries for use with the target_link_libraries command.
\li Qt5Widgets_INCLUDE_DIRS List of directories for use with the include_directories command.
\li Qt5Widgets_DEFINITIONS List of definitions for use with add_definitions.
\li Qt5Widgets_COMPILE_DEFINITIONS List of definitions for use with the COMPILE_DEFINITIONS target property.
\li Qt5Widgets_FOUND Boolean describing whether the module was found successfully.
\li Qt5Widgets_EXECUTABLE_COMPILE_FLAGS String of flags to be used when building executables.
\endlist
Equivalents of those variables will be available for all packages found with a \c{find_package} call. Note
that the variables are case-sensitive.
\section2 Installation variables
Additionally, several other variables are available which do not relate to a particular package, but to the
Qt installation itself.
\list
\li QT_VISIBILITY_AVAILABLE Boolean describing whether Qt was built with hidden visibility.
\li QT_LIBINFIX String containing the infix used in library names.
\endlist
\section1 Macro Reference
\section2 Qt5Core macros
Macros available when Qt5Core is found.
\table
\header \li Macro \li Description
\row \li qt5_wrap_cpp(outfiles inputfile ... OPTIONS ...)
\li Create moc code from a list of files containing Qt class with
the Q_OBJECT declaration. Per-directory preprocessor definitions
are also added. Options may be given to moc, such as those found
when executing "moc -help".
\row \li qt5_add_resources(outfiles inputfile ... OPTIONS ...)
\li Create code from a list of Qt resource files.
Options may be given to rcc, such as those found
when executing "rcc -help".
\row \li qt5_add_binary_resources(target inputfile ... OPTIONS ... DESTINATION ...)
\li Create an RCC file from a list of Qt resource files.
Options may be given to rcc, such as those found
when executing "rcc -help".
A destination may be given to use a different filename
or path for the RCC file.
\row \li qt5_generate_moc(inputfile outputfile )
\li Creates a rule to run moc on infile and create outfile.
Use this if for some reason QT5_WRAP_CPP() isn't appropriate, e.g.
because you need a custom filename for the moc file or something similar.
\row \li qt5_use_modules(target [LINK_PUBLIC|LINK_PRIVATE] module ... )
\li Indicates that the target uses the named Qt 5 modules. The target
will be linked to the specified modules, use the include directories
installed by those modules, use the COMPILE_DEFINITIONS set by those
modules, and use the COMPILE_FLAGS set by the modules. The LINK_PRIVATE
or LINK_PUBLIC specifiers can optionally be specified. If LINK_PRIVATE is specified
then the modules are not made part of the link interface of the target.
See the documentation for
\l{CMake target_link_libraries Documentation}{target_link_libraries}
for more information.
Note that this macro is only available if using \c{CMake} 2.8.9 or later.
This macro is obsolete. Use target_link_libraries with IMPORTED targets instead.
\endtable
\section2 Qt5Widgets macros
Macros available when Qt5Widgets is found.
\table
\header \li Macro \li Description
\row \li qt5_wrap_ui(outfiles inputfile ... OPTIONS ...)
\li Create code from a list of Qt designer ui files.
Options may be given to uic, such as those found
when executing "uic -help"
\endtable
\section2 Qt5DBus macros
Macros available when Qt5DBus is found.
\table
\header \li Macro \li Description
\row \li qt5_add_dbus_interface(outfiles interface basename)
\li Create the interface header and implementation files with the
given basename from the given interface xml file and add it to
the list of sources
\row \li qt5_add_dbus_interfaces(outfiles inputfile ... )
\li Create the interface header and implementation files
for all listed interface xml files
the name will be automatically determined from the name of the xml file
\row \li qt5_add_dbus_adaptor(outfiles xmlfile parentheader parentclassname [basename] [classname])
\li Create a dbus adaptor (header and implementation file) from the xml file
describing the interface, and add it to the list of sources. The adaptor
forwards the calls to a parent class, defined in parentheader and named
parentclassname. The name of the generated files will be
<basename>adaptor.{cpp,h} where basename defaults to the basename of the xml file.
If <classname> is provided, then it will be used as the classname of the
adaptor itself.
\row \li qt5_generate_dbus_interface( header [interfacename] OPTIONS ...)
\li Generate the xml interface file from the given header.
If the optional argument interfacename is omitted, the name of the
interface file is constructed from the basename of the header with
the suffix .xml appended.
Options may be given to qdbuscpp2xml, such as those found when executing "qdbuscpp2xml --help"
\endtable
\section2 Qt5LinguistTools macros
Macros available when Qt5LinguistTools is found.
\table
\header \li Macro \li Description
\row \li qt5_create_translation( qm_files directories ... sources ...
ts_files ... OPTIONS ...)
\li Out: qm_files
In: Directories sources ts_files
Options: flags to pass to lupdate, such as -extensions to specify
Extensions for a directory scan.
Generates commands to create .ts (via lupdate) and .qm
(via lrelease) - files from directories and/or sources. The ts files are
created and/or updated in the source tree (unless given with full paths).
The qm files are generated in the build tree.
Updating the translations can be done by adding the qm_files
to the source list of your library/executable, so they are
always updated, or by adding a custom target to control when
they get updated/generated.
\row \li qt5_add_translation( qm_files ts_files ... )
\li Out: qm_files
In: ts_files
Generates commands to create .qm from .ts - files. The generated
filenames can be found in qm_files. The ts_files
must exist and are not updated in any way.
\endtable
*/
|
