Debian Codegraph @

qmake/doc/src/qmake-manual.qdoc

raw
1 // Copyright (C) 2019 The Qt Company Ltd.
2 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4 /*!
5 \page qmake-manual.html
6 \title qmake Manual
7 \startpage index.html
8 \nextpage Overview
9
10 \ingroup qttools
11 \keyword qmake
12
13 The qmake tool helps simplify the build process for development projects
14 across different platforms. It automates the generation of Makefiles so that
15 only a few lines of information are needed to create each Makefile.
16 You can use qmake for any software project, whether it is written with Qt or
17 not.
18
19 qmake generates a Makefile based on the information in a
20 project file. Project files are created by the developer, and are usually
21 simple, but more sophisticated project files can be created for complex
22 projects.
23
24 qmake contains additional features to support development
25 with Qt, automatically including build rules for \l{moc.html}{moc}
26 and \l{uic.html}{uic}.
27
28 qmake can also generate projects for Microsoft Visual studio
29 without requiring the developer to change the project file.
30
31 \section1 Table of Contents
32
33 \list
34 \li \l{Overview}
35 \li \l{Getting Started with qmake}
36 \li \l{Creating Project Files}
37 \li \l{Building Common Project Types}
38 \li \l{Running qmake}
39 \li \l{Platform Notes}
40 \li \l{qmake Language}
41 \li \l{Advanced Usage}
42 \li \l{Using Third-Party Libraries}
43 \li \l{Using Precompiled Headers}
44 \li \l{Configuring qmake}
45 \li \l{Reference}
46 \list
47 \li \l{Variables}
48 \li \l{Replace Functions}
49 \list
50 \li \l{Built-in Replace Functions}
51 \endlist
52 \li \l{Test Functions}
53 \list
54 \li \l{Built-in Test Functions}
55 \li \l{Test Function Library}
56 \endlist
57 \endlist
58 \endlist
59 */
60
61 /*!
62 \page qmake-overview.html
63 \title Overview
64 \previouspage qmake Manual
65 \nextpage Getting Started with qmake
66
67 The qmake tool provides you with a project-oriented system for managing the
68 build process for applications, libraries, and other components.
69 This approach gives you control over the source files used, and
70 allows each of the steps in the process to be described concisely,
71 typically within a single file. qmake expands
72 the information in each project file to a Makefile that executes the necessary
73 commands for compiling and linking.
74
75 \section1 Describing a project
76
77 Projects are described by the contents of project (\c .pro) files. qmake
78 uses the information within the files to generate Makefiles that contain
79 all the commands that are needed to build each project.
80 Project files typically contain a list of source and header files,
81 general configuration information, and any application-specific details,
82 such as a list of extra libraries to link against, or a list of extra
83 include paths to use.
84
85 Project files can contain a number of different elements, including
86 comments, variable declarations, built-in functions, and some simple
87 control structures. In most simple projects, it is only necessary
88 to declare the source and header files that are used to build the
89 project with some basic configuration options. For more information about
90 how to create a simple project file, see \l{Getting Started with qmake}.
91
92 You can create more sophisticated project files for complex projects. For an
93 overview of project files, see \l{Creating Project Files}. For detailed
94 information about the variables and functions that you can use in project
95 files, see \l{Reference}.
96
97 You can use application or library project templates to specify specialized
98 configuration options to fine tune the build process. For more information,
99 see \l{Building Common Project Types}.
100
101 You can use the \l{Qt Creator: Creating Projects}{Qt Creator new project wizard} to create the project file.
102 You choose the project template, and Qt Creator creates a project file with
103 default values that enable you to build and run the project. You can modify
104 the project file to suit your purposes.
105
106 You can also use qmake to generate project files. For a full description of
107 qmake command line options, see \l{Running qmake}.
108
109 The basic configuration features of qmake can handle most cross-platform
110 projects. However, it might be useful, or even necessary, to use some
111 platform-specific variables. For more information, see \l{Platform Notes}.
112
113 \section1 Building a project
114
115 For simple projects, you only need to run qmake in the top level directory
116 of your project to generate a Makefile. You can then run your platform's
117 \c make tool to build the project according to the Makefile.
118
119 For more information about the environment variables that qmake uses when
120 configuring the build process, see \l{Configuring qmake}.
121
122 \note Add your project build directory to the list of excluded directories
123 of any anti-virus application that runs on your system.
124
125 \section1 Adding third-party libraries
126
127 The guide to \l{Using Third-Party Libraries} shows you how to use simple third
128 party libraries in your Qt project.
129
130 \section1 Precompiling headers
131
132 In large projects, it is possible to take advantage of precompiled
133 header files to speed up the build process. For more information, see
134 \l{Using Precompiled Headers}.
135 */
136
137 /*!
138 \page qmake-project-files.html
139 \title Creating Project Files
140 \previouspage Getting Started with qmake
141 \nextpage Building Common Project Types
142
143 Project files contain all the information required by qmake to build your
144 application, library, or plugin. Generally, you use a series of declarations
145 to specify the resources in the project, but support for simple programming
146 constructs enables you to describe different build processes for different
147 platforms and environments.
148
149 \section1 Project File Elements
150
151 The project file format used by qmake can be
152 used to support both simple and fairly complex build systems.
153 Simple project files use a straightforward declarative style,
154 defining standard variables to indicate the source and header files
155 that are used in the project. Complex projects may use control flow
156 structures to fine-tune the build process.
157
158 The following sections describe the different types of elements used
159 in project files.
160
161 \section2 Variables
162
163 In a project file, variables are used to hold lists of strings. In the
164 simplest projects, these variables inform qmake
165 about the configuration options to use, or supply filenames and paths to
166 use in the build process.
167
168 qmake looks for certain variables in each
169 project file, and it uses the contents of these to determine what it
170 should write to a Makefile. For example, the lists of values in the
171 \l{HEADERS} and \l{SOURCES} variables are used to tell qmake about header
172 and source files in the same directory as the project file.
173
174 Variables can also be used internally to store temporary lists of values,
175 and existing lists of values can be overwritten or extended with new
176 values.
177
178 The following snippet illustrates how lists of values are assigned to
179 variables:
180
181 \snippet qmake/variables.pro 0
182
183 The list of values in a variable is extended in the following way:
184
185 \snippet qmake/variables.pro 1
186
187 \note The first assignment only includes values that are specified on
188 the same line as the \c HEADERS variable. The second assignment splits
189 the values in the \c SOURCES variable across lines by using a backslash
190 (\\).
191
192 The \l{CONFIG} variable is another special variable that qmake uses when
193 generating a Makefile. It is discussed in \l{General Configuration}.
194 In the snippet above, \c console is added to the list of existing values
195 contained in \c CONFIG.
196
197 The following table lists some frequently used variables and describes their
198 contents. For a full list of variables and their descriptions,
199 see \l{Variables}.
200
201 \table
202 \header \li Variable \li Contents
203 \row \li \l{CONFIG} \li General project configuration options.
204 \row \li \l{DESTDIR} \li The directory in which the executable or binary file will
205 be placed.
206 \row \li \l{FORMS} \li A list of UI files to be processed by the
207 \l{uic}{user interface compiler (uic)}.
208 \row \li \l{HEADERS} \li A list of filenames of header (.h) files used when
209 building the project.
210 \row \li \l{Variables#QT}{QT} \li A list of Qt modules used in the project.
211 \row \li \l{RESOURCES} \li A list of resource (.qrc) files to be included in the
212 final project. See the \l{The Qt Resource System} for
213 more information about these files.
214 \row \li \l{SOURCES} \li A list of source code files to be used when building
215 the project.
216 \row \li \l{TEMPLATE} \li The template to use for the project. This determines
217 whether the output of the build process will be an
218 application, a library, or a plugin.
219 \endtable
220
221 The contents of a variable can be read by prepending the variable name with
222 \c $$. This can be used to assign the contents of one variable to another:
223
224 \snippet qmake/dereferencing.pro 0
225
226 The \c $$ operator is used extensively with built-in functions that operate
227 on strings and lists of values. For more information, see
228 \l{qmake Language}.
229
230 \section3 Whitespace
231
232 Usually, whitespace separates values in variable assignments. To specify
233 values that contain spaces, you must enclose the values in double quotes:
234
235 \snippet qmake/quoting.pro 0
236
237 The quoted text is treated as a single item in the list of values held by
238 the variable. A similar approach is used to deal with paths that contain
239 spaces, particularly when defining the
240 \l{INCLUDEPATH} and \l{LIBS} variables for the Windows platform:
241
242 \snippet qmake/spaces.pro quoting include paths with spaces
243
244 \section2 Comments
245
246 You can add comments to project files. Comments begin with the \c
247 # character and continue to the end of the same line. For example:
248
249 \snippet qmake/comments.pro 0
250
251 To include the \c # character in variable assignments, it is necessary
252 to use the contents of the built-in \l{LITERAL_HASH} variable.
253
254 \section2 Built-in Functions and Control Flow
255
256 qmake provides a number of built-in functions to enable the contents of
257 variables to be processed. The most commonly used function in simple
258 project files is the \l{include(filename)}{include()} function which takes a
259 filename as an
260 argument. The contents of the given file are included in the project
261 file at the place where the \c include function is used.
262 The \c include function is most commonly used to include other project
263 files:
264
265 \snippet qmake/include.pro 0
266
267 Support for conditional structures is made available via
268 \l{Scopes}{scopes} that behave like \c if statements in programming languages:
269
270 \snippet qmake/scopes.pro 0
271
272 The assignments inside the braces are only made if the condition is
273 true. In this case, the \c win32 \l{CONFIG} option must be set. This
274 happens automatically on Windows. The opening brace must stand on the same
275 line as the condition.
276
277 More complex operations on variables that would usually require loops
278 are provided by built-in functions such as \l{find(variablename, substr)}
279 {find()}, \l{unique(variablename)}{unique()}, and
280 \l{count(variablename, number)}{count()}.
281 These functions, and many others are provided to manipulate
282 strings and paths, support user input, and call external tools. For more
283 information about using the functions, see \l{qmake Language}. For lists
284 of all functions and their descriptions, see \l{Replace Functions} and
285 \l{Test Functions}.
286
287 \section1 Project Templates
288
289 The \l{TEMPLATE} variable is used to define the type of project that will
290 be built. If this is not declared in the project file,
291 qmake assumes that an application should be
292 built, and will generate an appropriate Makefile (or equivalent file)
293 for the purpose.
294
295 The following table summarizes the types of projects available and describes
296 the files that qmake will generate for each of them:
297
298 \table
299 \header \li Template \li qmake Output
300 \row \li app (default) \li Makefile to build an application.
301 \row \li lib \li Makefile to build a library.
302 \row \li aux \li Makefile to build nothing. Use this if no compiler needs to
303 be invoked to create the target, for instance because your
304 project is written in an interpreted language.
305 \note This template type is only available for Makefile-based
306 generators. In particular, it will not work with the vcxproj and
307 Xcode generators.
308 \row \li subdirs \li Makefile containing rules for the
309 subdirectories specified using the \l{SUBDIRS}
310 variable. Each subdirectory must contain its own project file.
311 \row \li vcapp \li Visual Studio Project file to build
312 an application.
313 \row \li vclib \li Visual Studio Project file to build a library.
314 \row \li vcsubdirs \li Visual Studio Solution file to build
315 projects in sub-directories.
316 \endtable
317
318 See \l{Building Common Project Types} for advice on writing project files for
319 projects that use the \c app and \c lib templates.
320
321 When the \c subdirs template is used, qmake
322 generates a Makefile to examine each specified subdirectory,
323 process any project file it finds there, and run the platform's
324 \c make tool on the newly-created Makefile.
325 The \c SUBDIRS variable is used to
326 contain a list of all the subdirectories to be processed.
327
328 \section1 General Configuration
329
330 The \l{CONFIG} variable specifies the options and features that the project
331 should be configured with.
332
333 The project can be built in \e release mode or \e debug mode, or both.
334 If debug and release are both specified, the last one takes effect. If you
335 specify the \c debug_and_release option to build both the debug and release
336 versions of a project, the Makefile that qmake generates includes a rule
337 that builds both versions. This can be invoked in the following way:
338
339 \snippet code/doc_src_qmake-manual.pro 0
340
341 Adding the \c build_all option to the \c CONFIG variable makes this rule
342 the default when building the project.
343
344 \note Each of the options specified in the \c CONFIG variable can also be
345 used as a scope condition.
346 You can test for the presence of certain configuration options by using the
347 built-in \l{CONFIG(config)}{CONFIG()} function.
348 For example, the following lines show the function as the condition in a scope
349 to test whether only the \c opengl option is in use:
350
351 \snippet qmake/configscopes.pro 4
352 \snippet qmake/configscopes.pro 5
353
354 This enables different configurations to be defined for \c release and
355 \c debug builds. For more information, see \l{Scopes}{Using Scopes}.
356
357 The following options define the type of project to be built.
358
359 \note Some of these options only take effect when used on the relevant
360 platform.
361
362 \table
363 \header \li Option \li Description
364 \row \li qt \li The project is a Qt application and should link against the Qt
365 library. You can use the \c QT variable to control any additional
366 Qt modules that are required by your application.
367 This value is added by default, but you can remove it to
368 use qmake for a non-Qt project.
369 \row \li x11 \li The project is an X11 application or library.
370 This value is not needed if the target uses Qt.
371 \endtable
372
373 The \l{TEMPLATE}{application and library project templates} provide you with
374 more specialized configuration options to fine tune the build process. The
375 options are explained in detail in \l{Building Common Project Types}.
376
377 For example, if your application uses the Qt library and you want to
378 build it in \c debug mode, your project file will contain the following line:
379
380 \snippet code/doc_src_qmake-manual.pro 1
381
382 \note You must use "+=", not "=", or qmake
383 will not be able to use Qt's configuration to determine the settings
384 needed for your project.
385
386 \section1 Declaring Qt Libraries
387
388 If the \l{CONFIG} variable contains the \c qt value, qmake's support for Qt
389 applications is enabled. This makes it possible to fine-tune which of the
390 Qt modules are used by your application. This is achieved with the
391 \l{Variables#QT}{QT} variable which can be used to declare the required
392 extension modules.
393 For example, we can enable the XML and network modules in the following way:
394
395 \snippet code/doc_src_qmake-manual.pro 2
396
397 \note \c QT includes the \c core and \c gui modules by default, so the
398 above declaration \e adds the network and XML modules to this default list.
399 The following assignment \e omits the default modules, and will lead to
400 errors when the application's source code is being compiled:
401
402 \snippet code/doc_src_qmake-manual.pro 3
403
404 If you want to build a project \e without the \c gui module, you need to
405 exclude it with the "-=" operator. By default, \c QT contains both
406 \c core and \c gui, so the following line will result in a minimal
407 Qt project being built:
408
409 \snippet code/doc_src_qmake-manual.pro 4
410
411 For a list of Qt modules that you can add to the \c QT variable, see
412 \l{Variables#QT}{QT}.
413
414 \section1 Configuration Features
415
416 qmake can be set up with extra configuration
417 features that are specified in feature (.prf) files. These extra features
418 often provide support for custom tools that are used during the build
419 process. To add a feature to the build process, append the feature name
420 (the stem of the feature filename) to the \c CONFIG variable.
421
422 For example, qmake can configure the build
423 process to take advantage of external libraries that are supported by
424 \l{http://www.freedesktop.org/wiki/Software/pkg-config}{pkg-config},
425 such as the D-Bus and ogg libraries, with the following lines:
426
427 \snippet code/doc_src_qmake-manual.pro 5
428
429 For more information about adding features, see
430 \l{Adding New Configuration Features}.
431
432 \section1 Declaring Other Libraries
433
434 If you are using other libraries in your project in addition to those
435 supplied with Qt, you need to specify them in your project file.
436
437 The paths that qmake searches for libraries
438 and the specific libraries to link against can be added to the list of values in the
439 \l{LIBS} variable. You can specify the paths to the libraries or use the
440 Unix-style notation for specifying libraries and paths.
441
442 For example, the following lines show how a library can be specified:
443
444 \snippet code/doc_src_qmake-manual.pro 6
445
446 The paths containing header files can also be specified in a similar way
447 using the \l{INCLUDEPATH} variable.
448
449 For example, to add several paths to be searched for header files:
450
451 \snippet code/doc_src_qmake-manual.pro 7
452 */
453
454 /*!
455 \page qmake-running.html
456 \title Running qmake
457 \previouspage Building Common Project Types
458 \nextpage Platform Notes
459
460 The behavior of qmake can be customized when it
461 is run by specifying various options on the command line. These allow the
462 build process to be fine-tuned, provide useful diagnostic
463 information, and can be used to specify the target platform for
464 your project.
465
466 \section1 Command Syntax
467
468 The syntax used to run qmake takes the following simple form:
469
470 \snippet code/doc_src_qmake-manual.pro 8
471
472 \note If you installed Qt via a package manager, the binary
473 may be \c{qmake6}.
474
475 \section1 Operating Modes
476
477 qmake supports two different modes of operation. In the default mode, qmake
478 uses the information in a project file to generate a Makefile, but it is also
479 possible to use qmake to generate project files.
480 If you want to explicitly set the mode, you must specify it before all
481 other options. The \c mode can be either of the following two values:
482
483 \list
484 \li \c -makefile \BR
485 qmake output will be a Makefile.
486 \li \c -project \BR
487 qmake output will be a project file. \BR
488 \note It is likely that the created file will need to be edited. For example,
489 adding the \c QT variable to suit what modules are required for the project.
490 \endlist
491
492 You can use the \c options to specify both general and mode-specific
493 settings. Options that only apply to the Makefile mode are described in the
494 \l{Makefile Mode Options} section, whereas options that influence the
495 creation of project files are described in the
496 \l{Project Mode Options} section.
497
498 \section1 Files
499
500 The \c files argument represents a list of one or more project files, separated
501 by spaces.
502
503 \section1 General Options
504
505 A wide range of options can be specified on the command line to
506 qmake in order to customize the build process,
507 and to override default settings for your platform. The following basic
508 options provide help on using qmake, specify where qmake writes the output
509 file, and control the
510 level of debugging information that will be written to the console:
511
512 \list
513 \li \c -help \BR
514 qmake will go over these features and give some useful help.
515 \li \c {-o file} \BR
516 qmake output will be directed to \c file. If
517 this option is not specified, qmake will try
518 to use a suitable file name for its output, depending on the mode it is
519 running in.\BR
520 If '-' is specified, output is directed to stdout.
521 \li \c -d \BR
522 qmake will output debugging information. Adding \c -d more than once
523 increases verbosity.
524 \endlist
525
526 The template used for the project is usually specified by the \l{TEMPLATE}
527 variable in the project file. You can override or modify this by using the
528 following options:
529
530 \list
531 \li \c {-t tmpl} \BR
532 qmake will override any set \c TEMPLATE variables with \c tmpl, but only
533 \e after the .pro file has been processed.
534 \li \c {-tp prefix} \BR
535 qmake will add \c prefix to the \c TEMPLATE variable.
536 \endlist
537
538 The level of warning information can be fine-tuned to help you find problems in
539 your project file:
540
541 \list
542 \li \c -Wall \BR
543 qmake will report all known warnings.
544 \li \c -Wnone \BR
545 No warning information will be generated by qmake.
546 \li \c -Wparser \BR
547 qmake will only generate parser warnings.
548 This will alert you to common pitfalls and potential problems in the
549 parsing of your project files.
550 \li \c -Wlogic \BR
551 qmake will warn of common pitfalls and
552 potential problems in your project file. For example,
553 qmake will report multiple occurrences of files in lists and missing
554 files.
555 \endlist
556
557 \section1 Makefile Mode Options
558
559 \snippet code/doc_src_qmake-manual.pro 9
560
561 In Makefile mode, qmake will generate a Makefile
562 that is used to build the project. Additionally, the following options may
563 be used in this mode to influence the way the project file is generated:
564
565 \list
566 \li \c -after \BR
567 qmake will process assignments given on the
568 command line after the specified files.
569 \li \c -nocache \BR
570 qmake will ignore the \c{.qmake.cache} file.
571 \li \c -nodepend \BR
572 qmake will not generate any dependency
573 information.
574 \li \c {-cache file} \BR
575 qmake will use \c file as the cache file,
576 ignoring any other .qmake.cache files found.
577 \li \c {-spec spec} \BR
578 qmake will use \c spec as a path to platform and compiler information,
579 and ignore the value of \l{QMAKESPEC}.
580 \endlist
581
582 You may also pass qmake assignments on the command line. They are processed
583 before all of the files specified. For example, the following command
584 generates a Makefile from test.pro:
585
586 \snippet code/doc_src_qmake-manual.pro 10
587
588 However, some of the specified options can be omitted as they are default
589 values:
590
591 \snippet code/doc_src_qmake-manual.pro 11
592
593 If you are certain you want your variables processed after the
594 files specified, then you may pass the \c -after option. When this
595 is specified, all assignments on the command line after the \c -after
596 option will be postponed until after the specified files are parsed.
597
598 \section1 Project Mode Options
599
600 \snippet code/doc_src_qmake-manual.pro 12
601
602 In project mode, qmake will generate a project
603 file. Additionally, you may supply the following options in this mode:
604
605 \list
606 \li \c -r \BR
607 qmake will look through supplied directories recursively.
608 \li \c -nopwd \BR
609 qmake will not look in your current working directory for source code.
610 It will only use the specified \c files.
611 \endlist
612
613 In this mode, the \c files argument can be a list of files or directories.
614 If a directory is specified, it will be included in the \l{DEPENDPATH}
615 variable, and relevant code from there will be included in the generated
616 project file. If a file is given, it will be appended to the correct
617 variable, depending on its extension. For example, UI files are added
618 to \l{FORMS}, and C++ files are added to \l{SOURCES}.
619
620 You may also pass assignments on the command line in this mode. When doing
621 so, these assignments will be placed last in the generated project file.
622 */
623
624 /*!
625 \page qmake-platform-notes.html
626 \title Platform Notes
627 \previouspage Running qmake
628 \nextpage qmake Language
629
630 Many cross-platform projects can be handled by the basic qmake configuration
631 features. However, on some platforms, it is sometimes useful, or even
632 necessary, to take advantage of platform-specific features.
633 qmake knows about many of these features, which can be accessed via specific
634 variables that only take effect on the platforms where they are relevant.
635
636 \section1 \macos, iOS, tvOS, and watchOS
637
638 Features specific to these platforms include support for creating universal
639 binaries, frameworks and bundles.
640
641 \section2 Source and Binary Packages
642
643 The version of qmake supplied in source packages
644 is configured slightly differently to that supplied in binary packages in
645 that it uses a different feature specification. Where the source package
646 typically uses the \c macx-g++ specification, the binary package is
647 typically configured to use the \c macx-xcode specification.
648
649 Users of each package can override this configuration by invoking
650 qmake with the \c -spec option (see \l{Running qmake} for more information).
651 For example, to use qmake from a binary package to create a Makefile in a
652 project directory, invoke the following command:
653
654 \snippet code/doc_src_qmake-manual.pro 13
655
656 \section2 Using Frameworks
657
658 qmake is able to automatically generate build
659 rules for linking against frameworks in the standard framework directory on
660 \macos, located at \c{/Library/Frameworks/}.
661
662 Directories other than the standard framework directory need to be specified
663 to the build system, and this is achieved by appending linker options to the
664 \l{LIBS} variable, as shown in the following example:
665
666 \snippet code/doc_src_qmake-manual.pro 14
667
668 The framework itself is linked in by appending the \c{-framework} options and
669 the name of the framework to the \l{LIBS} variable:
670
671 \snippet code/doc_src_qmake-manual.pro 15
672
673 \section2 Creating Frameworks
674
675 Any given library project can be configured so that the resulting library
676 file is placed in a
677 \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html}
678 {framework}, ready for deployment. To do this, set up the project to use the
679 \l{TEMPLATE}{\c lib template} and add the \c lib_bundle option to the
680 \l{CONFIG} variable:
681
682 \snippet code/doc_src_qmake-manual.pro 16
683
684 The data associated with the library is specified using the
685 \l{QMAKE_BUNDLE_DATA}
686 variable. This holds items that will be installed with a library
687 bundle, and is often used to specify a collection of header files,
688 as in the following example:
689
690 \snippet code/doc_src_qmake-manual.pro 17
691
692 You use the \c FRAMEWORK_HEADERS variable to specify the headers required by
693 a particular framework.
694 Appending it to the \c QMAKE_BUNDLE_DATA variable ensures that
695 information about these headers is added to the collection of
696 resources that will be installed with the library bundle. Also, the
697 framework name and version are specified by the \l {QMAKE_FRAMEWORK_BUNDLE_NAME}
698 and \l{QMAKE_FRAMEWORK_VERSION} variables. By default, the values used for
699 these variables are obtained from the \l{TARGET} and \l{VERSION} variables.
700
701 See \l{Qt for macOS - Deployment} for more information about
702 deploying applications and libraries.
703
704 \section2 Creating and Moving Xcode Projects
705
706 On \macos, developers can generate Xcode project files from an existing qmake
707 project file. For example:
708
709 \snippet code/doc_src_qmake-manual.pro 19
710
711 \note If a project is later moved on the disk, qmake must be run again to
712 process the project file and create a new Xcode project file.
713
714 \section2 Supporting Two Build Targets Simultaneously
715
716 Implementing this is currently not feasible, because the Xcode
717 concept of Active Build Configurations is conceptually different
718 from the qmake idea of build targets.
719
720 The Xcode Active Build Configurations settings are for modifying
721 Xcode configurations, compiler flags and similar build
722 options. Unlike Visual Studio, Xcode does not allow for the
723 selection of specific library files based on whether debug or
724 release build configurations are selected. The qmake debug and
725 release settings control which library files are linked to the
726 executable.
727
728 It is currently not possible to set files in Xcode configuration
729 settings from the qmake generated Xcode project file. The way the
730 libraries are linked in the \e {Frameworks & Libraries} phase in the
731 Xcode build system.
732
733 Furthermore, the selected \e {Active Build Configuration} is stored
734 in a .pbxuser file, which is generated by Xcode on first load, not
735 created by qmake.
736
737 \section1 Windows
738
739 Features specific to this platform include support for Windows resource
740 files (provided or auto-generated), creating Visual Studio project files,
741 and handling manifest files when deploying Qt applications developed
742 using Visual Studio 2005, or later.
743
744 \section2 Adding Windows Resource Files
745
746 This section describes how to handle a Windows resource file with
747 qmake to have it linked to an application executable (EXE) or dynamic
748 link library (DLL). qmake can optionally auto-generate a suitably
749 filled Windows resource file.
750
751 A linked Windows resource file may contain many elements that can
752 be accessed by its EXE or DLL. However, the
753 \l{The Qt Resource System}{Qt resource system} should be used for
754 accessing linked-in resources in a platform-independent way. But
755 some standard elements of the linked Windows resource file are
756 accessed by Windows itself. For example, in Windows explorer the
757 version tab of the file properties is filled by resource elements.
758 In addition, the program icon of the EXE is read from these elements.
759 So it is good practice for a Qt created Windows EXE or DLL to use
760 both techniques at the same time: link platform-independent resources
761 via the \l{The Qt Resource System}{Qt resource system} and add Windows
762 specific resources via a Windows resource file.
763
764 Typically, a resource-definition script (.rc file) is compiled to a
765 Windows resource file. Within the Microsoft toolchain, the RC tool
766 generates a .res file, which can be linked with the Microsoft linker
767 to an EXE or DLL. The MinGW toolchain uses the windres tool to generate
768 an .o file that can be linked with the MinGW linker to an EXE or DLL.
769
770 The optional auto-generation of a suitably filled .rc file by qmake is
771 triggered by setting at least one of the system variables \l{VERSION}
772 and \l{RC_ICONS}. The generated .rc file is automatically compiled and
773 linked. Elements that are added to the .rc file are defined by the system
774 variables \l{QMAKE_TARGET_COMPANY}, \l{QMAKE_TARGET_DESCRIPTION},
775 \l{QMAKE_TARGET_COPYRIGHT}, \l{QMAKE_TARGET_PRODUCT},
776 \l{QMAKE_TARGET_ORIGINAL_FILENAME}, \l{QMAKE_TARGET_INTERNALNAME},
777 \l{QMAKE_TARGET_COMMENTS}, \l{QMAKE_TARGET_TRADEMARKS}, \l{QMAKE_MANIFEST},
778 \l{RC_CODEPAGE}, \l{RC_ICONS}, \l{RC_LANG} and \l{VERSION}.
779
780 If these elements are not sufficient, qmake has the two system variables
781 \l{RC_FILE} and \l{RES_FILE} that point directly to an externally created
782 .rc or .res file. By setting one of these variables, the specified file
783 is linked to the EXE or DLL.
784
785 \note The generation of the .rc file by qmake is blocked, if \l{RC_FILE}
786 or \l{RES_FILE} is set. In this case, no further changes are made to the
787 given .rc file or the .res or .o file by qmake; the variables pertaining
788 to .rc file generation have no effect.
789
790
791 \section2 Creating Visual Studio Project Files
792
793 This section describes how to import an existing
794 qmake project into Visual Studio.
795 qmake is able to take a project file and create
796 a Visual Studio project that contains all the necessary information
797 required by the development environment. This is achieved by setting the
798 qmake \l{TEMPLATE}{project template} to either \c vcapp
799 (for application projects) or \c vclib (for library projects).
800
801 This can also be set using a command line option, for example:
802
803 \snippet code/doc_src_qmake-manual.pro 20
804
805 It is possible to recursively generate \c{.vcproj} files in subdirectories
806 and a \c{.sln} file in the main directory, by typing:
807
808 \snippet code/doc_src_qmake-manual.pro 21
809
810 Each time you update the project file, you need to run
811 qmake to generate an updated Visual Studio
812 project.
813
814 \note If you are using the Visual Studio Add-in, select \gui Qt >
815 \gui{Import from .pro file} to import \c .pro files.
816
817 \section2 Visual Studio Manifest Files
818
819 When deploying Qt applications built using Visual Studio 2005, or later,
820 make sure that the manifest file that was created when the application
821 was linked is handled correctly. This is handled automatically for
822 projects that generate DLLs.
823
824 Removing manifest embedding for application executables can be done with
825 the following assignment to the \l{CONFIG} variable:
826
827 \snippet code/doc_src_qmake-manual.pro 22
828
829 Also, the manifest embedding for DLLs can be removed with the following
830 assignment to the \c CONFIG variable:
831
832 \snippet code/doc_src_qmake-manual.pro 23
833
834 This is discussed in more detail in the
835 \l{Qt for Windows - Deployment#Manifest files}
836 {deployment guide for Windows}.
837 */
838
839 /*!
840 \page qmake-reference.html
841 \title Reference
842 \previouspage Configuring qmake
843 \nextpage Variables
844
845 The reference sections describe in detail the variables and functions that
846 are available for use in qmake project files.
847
848 \section1 Variable Reference
849
850 \l{Variables} describes the variables that are recognized by qmake when
851 configuring the build process for projects.
852
853 \section1 Function Reference
854
855 There are two types of qmake functions: replace functions and test
856 functions. Replace functions return a value list, while test functions
857 return a boolean result. The functions are implemented in two places:
858 fundamental functionality is offered as built-in functions. More complex
859 functions are implemented in a library of feature files (.prf).
860
861 The functions are divided into categories according to their type:
862
863 \list
864 \li \l{Replace Functions}
865 \li \l{Test Functions}
866 \endlist
867 */
868
869 /*!
870 \page qmake-variable-reference.html
871 \title Variables
872 \previouspage Reference
873 \nextpage Replace Functions
874 \keyword qmake Variable Reference
875
876 The fundamental behavior of qmake is influenced by variable declarations that
877 define the build process of each project. Some of these declare resources,
878 such as headers and source files, that are common to each platform. Others
879 are used to customize the behavior of compilers and linkers on specific
880 platforms.
881
882 Platform-specific variables follow the naming pattern of the
883 variables which they extend or modify, but include the name of the relevant
884 platform in their name. For example, a makespec may use \c QMAKE_LIBS
885 to specify a list of libraries that each project needs to link against,
886 and \c QMAKE_LIBS_X11 would be used to extend this list.
887
888 \section1 ANDROID_ABIS
889
890 \note This variable applies only to Android targets.
891
892 Specifies a list of Android target ABIs. Valid values are: armeabi-v7a,
893 arm64-v8a, x86, x86_64.
894
895 You can provide the ABIs as a qmake argument:
896
897 \badcode
898 qmake ANDROID_ABIS="armeabi-v7a arm64-v8a"
899 \endcode
900
901 \note It is possible to use this variable inside the *.pro file, however,
902 it is not recommended since it will override any ABIs specified on the
903 \c qmake command line.
904
905 \section1 ANDROID_API_VERSION
906
907 \note This variable applies only to Android targets.
908
909 Specifies the Android API level number. For more information, see
910 \l{Android: Build Numbers}{Android Build Numbers}.
911
912 \section1 ANDROID_APPLICATION_ARGUMENTS
913
914 \note This variable applies only to Android targets.
915
916 Specifies extra command-line arguments to the Android app using the
917 \c AndroidManifest.xml with the tag "android.app.arguments". This takes
918 a string of arguments:
919
920 \badcode
921 ANDROID_APPLICATION_ARGUMENTS = "arg1 arg2 arg3"
922 \endcode
923
924 \section1 ANDROID_BUNDLED_JAR_DEPENDENCIES
925
926 \note This variable applies only to Android modules.
927
928 This is useful when writing a Qt module. It specifies a list of pre-bundled
929 dependencies used by the module in a \c .jar format, for example:
930
931 \badcode
932 ANDROID_BUNDLED_JAR_DEPENDENCIES += jar/Qt6Android.jar
933 \endcode
934
935 \section1 ANDROID_DEPLOYMENT_DEPENDENCIES
936
937 \note This variable applies only to Android targets.
938
939 By default, \l androiddeployqt will detect the dependencies of your
940 application. However, since run-time usage of plugins cannot be detected,
941 there could be false positives, as your application might depend on any
942 plugin that is a potential dependency. If you want to minimize the size of
943 your \c APK, it's possible to override the automatic detection using the
944 this variable. This should contain a list of all Qt files which need to be
945 included, with paths relative to the Qt install root.
946
947 \note Only the Qt files specified with this variable are included. Failing
948 to include all the correct files can result in crashes. It's also important
949 to make sure the files are listed in the correct loading order. This variable
950 provides a way to override the automatic detection entirely, so if a library
951 is listed before its dependencies, it will fail to load on some devices.
952
953 \section1 ANDROID_DEPLOYMENT_SETTINGS_FILE
954
955 \note This variable applies only to Android targets.
956
957 Specifies the path to the \c {android-deployment-settings.json} file needed
958 by \l androiddeployqt and \c androidtestrunner. This overrides the path to
959 the settings file generated by qmake, thus you have to make sure to provide
960 a valid settings file.
961
962 \section1 ANDROID_EXTRA_LIBS
963
964 \note This variable applies only to Android targets.
965
966 A list of external libraries that will be copied into your application's
967 \c libs folder and loaded on start-up. This can be used, for instance,
968 to enable OpenSSL in your application. For more information, see
969 \l{Adding OpenSSL Support for Android}.
970
971 To include external libraries for multiple ABIs, where each ABIs has its own
972 directory, use the following:
973
974 \badcode
975 for (abi, ANDROID_ABIS): ANDROID_EXTRA_LIBS += $$PWD/$${abi}/library_name.so
976 \endcode
977
978 Otherwise, if the ABI is included in the library name, use the following:
979
980 \badcode
981 for (abi, ANDROID_ABIS): ANDROID_EXTRA_LIBS += $$PWD/library_name_$${abi}.so
982 \endcode
983
984 \section1 ANDROID_EXTRA_PLUGINS
985
986 \note This variable applies only to Android targets.
987
988 Specifies a path to C++ plugins or resources that your application has to bundle
989 but that cannot be delivered through the assets system, such as QML plugins.
990 With this variable, \l androiddeployqt will make sure everything is packaged
991 and deployed properly.
992
993 \c ANDROID_EXTRA_PLUGINS must point to the directory where the extra plugin(s)
994 are built. In addition, the build directory structure must follow a naming
995 convention similar to Qt plugins, that is, \e {plugins/<plugin name>}.
996
997 The plugins libraries should have the name format \e {libplugins_<type>_<name>_<abi>.so}.
998 To achieve that the plugin pro file could be defined as follows:
999
1000 \badcode
1001 TEMPLATE = lib
1002 CONFIG += plugin
1003
1004 PLUGIN_TYPE = imageformats
1005 DESTDIR = $$top_builddir/plugins/myplugin
1006 TARGET = $$qt5LibraryTarget(myplugin, "plugins/$$PLUGIN_TYPE/")
1007 \endcode
1008
1009 with top_builddir defined in .qmake.conf as:
1010 \badcode
1011 top_builddir=$$shadowed($$PWD)
1012 \endcode
1013
1014 This will ensure that the correct name mangling is applied to the plugin
1015 library (\e plugins/myplugin/libplugins_imageformats_myplugin_armeabi-v7a.so).
1016
1017 Then, assuming an extra image format plugin \e myplugin is built as
1018 \e {$$DESTDIR/plugins/myplugin/}, the following ensures it is packaged correctly:
1019
1020 \badcode
1021 ANDROID_EXTRA_PLUGINS += $$top_builddir/plugins
1022 \endcode
1023
1024 \section1 ANDROID_FEATURES
1025
1026 \note This variable applies only to Android modules.
1027
1028 Specifies a module's features list:
1029
1030 \badcode
1031 ANDROID_FEATURES += android.hardware.location.gps
1032 \endcode
1033
1034 For more information, see \l{Android: <uses-feature>}{Android <uses-feature> Docs}.
1035
1036 \section1 ANDROID_LIB_DEPENDENCIES
1037
1038 \note This variable applies only to Android modules.
1039
1040 This is useful when writing a Qt module. It specifies a list of pre-built
1041 dependencies used by the module, for example:
1042
1043 \badcode
1044 ANDROID_LIB_DEPENDENCIES += \
1045 plugins/libplugins_platforms_qtforandroid.so
1046 \endcode
1047
1048 \section1 ANDROID_MIN_SDK_VERSION
1049
1050 \note This variable applies only to Android targets.
1051
1052 Specifies the minimum Android API level for the project. By default, this
1053 variable is set to API level 23.
1054
1055 \section1 ANDROID_PACKAGE_SOURCE_DIR
1056
1057 \note This variable applies only to Android targets.
1058
1059 Specifies the path for a custom Android package template. The Android package
1060 template contains:
1061 \list
1062 \li AndroidManifest.xml file
1063 \li build.gradle file and other Gradle scripts
1064 \li res/values/libs.xml file
1065 \endlist
1066
1067 The path specified by this variable can contain custom Java classes under
1068 \c src directory. By default, the \l androiddeployqt tool copies the
1069 application template from the \Q4A installation path into your
1070 project's build directory, then it copies the contents of the path specified
1071 by this variable on top of that, overwriting any existing files. For
1072 instance, you can make a custom \c {AndroidManifest.xml} for your application,
1073 then place this directly into the directory specified by this variable.
1074
1075 \section1 ANDROID_PERMISSIONS
1076
1077 \note This variable applies only to Android modules.
1078
1079 Specifies a module's permissions list:
1080
1081 \badcode
1082 ANDROID_PERMISSIONS += android.permission.ACCESS_FINE_LOCATION
1083 \endcode
1084
1085 For more information, see \l{Android: <uses-permission>}{Android <uses-permission> Docs}.
1086
1087 \section1 ANDROID_TARGET_SDK_VERSION
1088
1089 \note This variable applies only to Android targets.
1090
1091 Specifies the target Android API level for the project. By default, this
1092 variable is set to API level 36.
1093
1094 \section1 ANDROID_VERSION_CODE
1095
1096 \note This variable applies only to Android targets.
1097
1098 Specifies the application's version number. For more information, see
1099 \l{Android: App Versioning}{Android App Versioning}.
1100
1101 \section1 ANDROID_VERSION_NAME
1102
1103 \note This variable applies only to Android targets.
1104
1105 Specifies the application's version in as a human readable string. For more
1106 information, see \l{Android: App Versioning}{Android App Versioning}.
1107
1108 \section1 CONFIG
1109
1110 Specifies project configuration and compiler options. The values are
1111 recognized internally by qmake and have special meaning.
1112
1113 \note The values are case-sensitive.
1114
1115 The following \c CONFIG values control compiler and linker flags:
1116
1117 \table
1118 \header \li Option \li Description
1119 \row \li release \li The project is to be built in release mode.
1120 If \c debug is also specified, the last one takes effect.
1121 \row \li debug \li The project is to be built in debug mode.
1122 \row \li debug_and_release \li The project is prepared to be built in
1123 \e both debug and release modes.
1124 \row \li debug_and_release_target \li This option is set by default. If
1125 \c debug_and_release is also set, the debug and release builds
1126 end up in separate debug and release directories.
1127 \row \li build_all \li If \c debug_and_release is specified, the project is
1128 built in both debug and release modes by default.
1129 \row \li autogen_precompile_source \li Automatically generates a \c .cpp
1130 file that includes the precompiled header file specified in the .pro
1131 file.
1132 \row \li ordered \li When using the \c subdirs template, this option
1133 specifies that the directories listed should be processed in the
1134 order in which they are given. \note The use of this option is discouraged.
1135 Specify dependencies as described in the \l{#SUBDIRS}{SUBDIRS}
1136 variable documentation.
1137 \row \li precompile_header \li Enables support for the use of
1138 \l{Using Precompiled Headers}{precompiled headers} in projects.
1139 \row \li precompile_header_c (MSVC only) \li Enables support for the use of
1140 \l{Using Precompiled Headers}{precompiled headers} for C files.
1141 \row \li warn_on \li The compiler should output as many warnings as possible.
1142 If \c warn_off is also specified, the last one takes effect.
1143 \row \li warn_off \li The compiler should output as few warnings as possible.
1144 \row \li exceptions \li Exception support is enabled. Set by default.
1145 \row \li exceptions_off \li Exception support is disabled.
1146 \row \li ltcg \li Link time code generation is enabled.
1147 This option is off by default.
1148 \row \li rtti \li RTTI support is enabled. By default, the compiler
1149 default is used.
1150 \row \li rtti_off \li RTTI support is disabled. By default, the compiler
1151 default is used.
1152 \row \li stl \li STL support is enabled. By default, the compiler
1153 default is used.
1154 \row \li stl_off \li STL support is disabled. By default, the compiler
1155 default is used.
1156 \row \li thread \li Thread support is enabled. This is enabled when CONFIG
1157 includes \c qt, which is the default.
1158 \row \li no_utf8_source \li Specifies that the project's source files does not use
1159 the UTF-8 encoding. Instead, the compiler default is used.
1160 \row \li hide_symbols \li Set the default visibility of symbols in the binary
1161 to hidden. By default, the compiler default is used.
1162 \row \li c99 \li C99 support is enabled. This option has no effect if
1163 the compiler does not support C99, or can't select the C standard.
1164 By default, the compiler default is used.
1165 \row \li c11 \li C11 support is enabled. This option has no effect if
1166 the compiler does not support C11, or can't select the C standard.
1167 By default, the compiler default is used.
1168 \row \li c17 \li C17, also known as C18, support is enabled.
1169 This option has no effect if the compiler does not support C17, or
1170 can't select the C standard.
1171 By default, the compiler default is used.
1172 \row \li c18 \li This is an alias for the \c{c17} value.
1173 \row \li strict_c \li Disables support for C compiler extensions.
1174 By default, they are enabled.
1175 \row \li c++11 \li C++11 support is enabled. This option has no effect if
1176 the compiler does not support C++11, or can't select the C++ standard.
1177 By default, support is enabled.
1178 \row \li c++14 \li C++14 support is enabled. This option has no effect if
1179 the compiler does not support C++14, or can't select the C++ standard.
1180 By default, support is enabled.
1181 \row \li c++17 \li C++17 support is enabled. This option has no effect if
1182 the compiler does not support C++17, or can't select the C++ standard.
1183 By default, support is enabled.
1184 \row \li c++1z \li Obsolete alias for c++17.
1185 \row \li c++20 \li C++20 support is enabled. This option has no effect if
1186 the compiler does not support C++20, or can't select the C++ standard.
1187 By default, support is disabled.
1188 \row \li c++2a \li Obsolete alias for c++20.
1189 \row \li c++latest \li Support for the latest C++ language standard is
1190 enabled. This option is mostly useful for MSVC that supports a
1191 \c{/std:c++latest} compiler argument. For other toolchains, this
1192 option enables the latest C++ standard that is known to Qt. By
1193 default, this option is disabled.
1194 \row \li strict_c++ \li Disables support for C++ compiler extensions.
1195 By default, they are enabled.
1196 \row \li depend_includepath \li Appending the value of INCLUDEPATH to
1197 DEPENDPATH is enabled. Set by default.
1198 \row \li lrelease \li Run \c lrelease for all files listed in
1199 \l TRANSLATIONS and \l EXTRA_TRANSLATIONS. If \c embed_translations
1200 is not set, install the generated .qm files into
1201 QM_FILES_INSTALL_PATH. Use QMAKE_LRELEASE_FLAGS to add options to
1202 the lrelease call. Not set by default.
1203 \row \li embed_translations \li Embed the generated translations from
1204 \c lrelease in the executable, under \l{QM_FILES_RESOURCE_PREFIX}.
1205 Requires \c lrelease to be set, too. Not set by default.
1206 \row \li create_libtool \li Create a libtool .la file for the currently
1207 built library.
1208 \row \li create_pc \li Create a pkg-config .pc file for the currently built
1209 library.
1210 \row \li no_batch \li NMake only: Turn off generation of NMake batch rules
1211 or inference rules.
1212 \row \li skip_target_version_ext \li Suppress the automatic version number
1213 appended to the DLL file name on Windows.
1214 \row \li suppress_vcproj_warnings \li Suppress warnings of the VS project
1215 generator.
1216 \row \li windeployqt \li Automatically invoke windeployqt after linking,
1217 and add the output as deployment items.
1218 \row \li dont_recurse \li Suppress qmake recursion for the current
1219 subproject.
1220 \row \li no_include_pwd \li Do not add the current directory to
1221 INCLUDEPATHS.
1222 \row \li compile_included_sources \li By default, qmake does not
1223 compile source files that are included in other source files. This
1224 option disables this behavior.
1225 \endtable
1226
1227 When you use the \c debug_and_release option (which is the default under
1228 Windows), the project will be processed three times: one time to produce
1229 a "meta" Makefile, and two more times to produce a Makefile.Debug and a
1230 Makefile.Release.
1231
1232 During the latter passes, \c build_pass and the respective \c debug or
1233 \c release option is appended to \c CONFIG. This makes it possible to
1234 perform build-specific tasks. For example:
1235
1236 \snippet code/doc_src_qmake-manual.pro 25
1237
1238 As an alternative to manually writing build type conditionals, some
1239 variables offer build-specific variants, for example
1240 \l{#QMAKE_LFLAGS_RELEASE}{QMAKE_LFLAGS_RELEASE} in addition to the general
1241 \l{#QMAKE_LFLAGS}{QMAKE_LFLAGS}. These should be used when available.
1242
1243 The meta Makefile makes the sub-builds invokable via the \c debug and
1244 \c release targets, and a combined build via the \c all target.
1245 When the \c build_all \c CONFIG option is used, the combined build is
1246 the default. Otherwise, the last specified \c CONFIG option from the set
1247 (\c debug, \c release) determines the default. In this case, you can
1248 explicitly invoke the \c all target to build both configurations at once:
1249
1250 \snippet code/doc_src_qmake-manual.pro 24
1251
1252 \note The details are slightly different when producing Visual Studio
1253 and Xcode projects.
1254
1255 When linking a library, qmake relies on the
1256 underlying platform to know what other libraries this library links
1257 against. However, if linking statically, qmake
1258 will not get this information unless we use the following \c CONFIG
1259 options:
1260
1261 \table
1262 \header \li Option \li Description
1263 \row \li create_prl \li This option enables
1264 qmake to track these dependencies. When this
1265 option is enabled, qmake will create a file
1266 with the extension \c .prl which will save meta-information about the library
1267 (see \l{Library Dependencies} for more info).
1268 \row \li link_prl \li When this option is enabled,
1269 qmake will process all libraries linked to
1270 by the application and find their meta-information (see
1271 \l{Library Dependencies} for more info).
1272 \row \li no_install_prl \li This option disables the generation of
1273 installation rules for generated .prl files.
1274 \endtable
1275
1276 \note The \c create_prl option is required when \e {building} a
1277 static library, while \c link_prl is required when \e {using} a
1278 static library.
1279
1280 The following options define the application or library type:
1281
1282 \table
1283 \header \li Option \li Description
1284 \row \li qt \li The target is a Qt application or library and requires the Qt
1285 library and header files. The proper include and library paths for the
1286 Qt library will automatically be added to the project. This is defined
1287 by default, and can be fine-tuned with the \l{#qt}{QT} variable.
1288 \row \li x11 \li The target is an X11 application or library. The proper
1289 include paths and libraries will automatically be added to the
1290 project.
1291 \row \li testcase \li The target is an automated test.
1292 \l{Building Common Project Types#building-a-testcase}{A check target} will be added
1293 to the generated Makefile to run the test. Only relevant when generating
1294 Makefiles.
1295 \row \li insignificant_test \li The exit code of the automated test will be ignored.
1296 Only relevant if \c testcase is also set.
1297 \row \li windows \li The target is a Win32 window application (app only). The
1298 proper include paths, compiler flags and libraries will
1299 automatically be added to the project.
1300 \row \li console \li The target is a Win32 console application (app only). The
1301 proper include paths, compiler flags and libraries will automatically be
1302 added to the project. Consider using the option \c{cmdline} for
1303 cross-platform applications.
1304 \row \li cmdline \li The target is a cross-platform command line application.
1305 On Windows, this implies \c{CONFIG += console}.
1306 On macOS, this implies \c{CONFIG -= app_bundle}.
1307 \row \li shared \li{1,2} The target is a shared object/DLL. The proper
1308 include paths, compiler flags and libraries will automatically be
1309 added to the project. Note that \c dll can also be used on all platforms;
1310 a shared library file with the appropriate suffix for the target platform
1311 (.dll or .so) will be created.
1312 \row \li dll
1313 \row \li static \li{1,2} The target is a static library (lib only). The proper
1314 compiler flags will automatically be added to the project.
1315 \row \li staticlib
1316 \row \li plugin \li The target is a plugin (lib only). This enables dll as well.
1317 \row \li designer \li The target is a plugin for \QD.
1318 \row \li no_lflags_merge \li Ensures that the list of libraries stored in the
1319 \c LIBS variable is not reduced to a list of unique values before it is used.
1320 \row \li metatypes \li Create a \c {<name>_metatypes.json} file for the
1321 current project. \c {<name>} is the all lowercase base name of
1322 \l TARGET.
1323 \row \li qmltypes \li Automatically register QML types defined in C++.
1324 For more information, see \l {Defining QML Types from C++}.
1325 Also, create a \c {<template>.qmltypes} file for the current
1326 project. \c <template> will be \c plugins (plural, for historical
1327 reasons) if \c plugin is set, or the value of \l TEMPLATE otherwise.
1328 \c qmltypes implies \c metatypes.
1329 \endtable
1330
1331 These options define specific features on Windows only:
1332
1333 \table
1334 \header \li Option \li Description
1335 \row \li flat \li When using the vcapp template this will put all the source
1336 files into the source group and the header files into the header group
1337 regardless of what directory they reside in. Turning this
1338 option off will group the files within the source/header group depending
1339 on the directory they reside. This is turned on by default.
1340 \row \li embed_manifest_dll \li Embeds a manifest file in the DLL created
1341 as part of a library project.
1342 \row \li embed_manifest_exe \li Embeds a manifest file in the EXE created
1343 as part of an application project.
1344 \endtable
1345
1346 See \l{Platform Notes#Visual Studio Manifest Files}{Platform Notes}
1347 for more information about the options for embedding manifest files.
1348
1349 The following options take an effect only on \macos:
1350
1351 \table
1352 \header \li Option \li Description
1353 \row \li app_bundle \li Puts the executable into a bundle (this is the default).
1354 \row \li lib_bundle \li Puts the library into a library bundle.
1355 \row \li plugin_bundle \li Puts the plugin into a plugin bundle. This value
1356 is not supported by the Xcode project generator.
1357 \endtable
1358
1359 The build process for bundles is also influenced by
1360 the contents of the \l{#QMAKE_BUNDLE_DATA}{QMAKE_BUNDLE_DATA} variable.
1361
1362 The following options take an effect only on Linux/Unix platforms:
1363
1364 \table
1365 \header \li Option \li Description
1366 \row \li largefile \li Includes support for large files.
1367 \row \li separate_debug_info \li Puts debugging information for libraries in
1368 separate files.
1369 \endtable
1370
1371 The \c CONFIG variable will also be checked when resolving scopes. You may
1372 assign anything to this variable.
1373
1374 For example:
1375
1376 \snippet code/doc_src_qmake-manual.pro 26
1377
1378 \section1 DEFINES
1379
1380 qmake adds the values of this variable as
1381 compiler C preprocessor macros (-D option).
1382
1383 For example:
1384
1385 \snippet code/doc_src_qmake-manual.pro 27
1386
1387 \section1 DEFINES_DEBUG
1388
1389 Specifies preprocessor defines for the debug configuration. The values of
1390 this variable get added to \l{DEFINES} after the project is loaded. This
1391 variable is typically set in \l{#QMAKESPEC}{qmake.conf} and rarely needs
1392 to be modified.
1393
1394 This variable was introduced in Qt 5.13.2.
1395
1396 \section1 DEFINES_RELEASE
1397
1398 Specifies preprocessor defines for the release configuration. The values of
1399 this variable get added to \l{DEFINES} after the project is loaded. This
1400 variable is typically set in \l{#QMAKESPEC}{qmake.conf} and rarely needs
1401 to be modified.
1402
1403 \note For MSVC mkspecs, this variable contains the value \c NDEBUG by
1404 default.
1405
1406 This variable was introduced in Qt 5.13.2.
1407
1408 \section1 DEF_FILE
1409
1410 \note This variable is used only on Windows when using the \c app template.
1411
1412 Specifies a \c .def file to be included in the project.
1413
1414 \section1 DEPENDPATH
1415
1416 Specifies a list of directories for qmake to scan, to resolve dependencies.
1417 This variable is used when qmake crawls through the header files that you
1418 \c{#include} in your source code.
1419
1420 \section1 DESTDIR
1421
1422 Specifies where to put the \l{#TARGET}{target} file.
1423
1424 For example:
1425
1426 \snippet code/doc_src_qmake-manual.pro 30
1427
1428 \note The list of supported characters can depend on
1429 the used build tool. In particular, parentheses do not
1430 work with \c{make}.
1431
1432 \section1 DISTFILES
1433
1434 Specifies a list of files to be included in the dist
1435 target. This feature is supported by UnixMake specs only.
1436
1437 For example:
1438
1439 \snippet code/doc_src_qmake-manual.pro 31
1440
1441 \section1 DLLDESTDIR
1442
1443 \note This variable applies only to Windows targets.
1444
1445 Specifies where to copy the \l{#TARGET}{target} dll.
1446
1447 \section1 EXTRA_TRANSLATIONS
1448
1449 Specifies a list of translation (.ts) files that contain
1450 translations of the user interface text into non-native languages.
1451
1452 In contrast to \l TRANSLATIONS, translation files in \c EXTRA_TRANSLATIONS
1453 will be processed only by \l{Using lrelease}{lrelease}, not
1454 \l{Using lupdate}{lupdate}.
1455
1456 You can use \l{CONFIG}{CONFIG += lrelease} to automatically compile the
1457 files during the build, and
1458 \l{CONFIG}{CONFIG += lrelease embed_translations} to make them available in
1459 \l{The Qt Resource System}.
1460
1461 See the \l{Qt Linguist Manual} for more information about
1462 internationalization (i18n) and localization (l10n) with Qt.
1463
1464 \section1 FORMS
1465
1466 Specifies the UI files (see \l{Qt Widgets Designer Manual}) to be processed
1467 by \c uic before compiling. All dependencies, headers and source files
1468 required to build these UI files will automatically be added to the
1469 project.
1470
1471 For example:
1472
1473 \snippet code/doc_src_qmake-manual.pro 32
1474
1475 \section1 GUID
1476
1477 Specifies the GUID that is set inside a \c{.vcproj} file. The GUID is
1478 usually randomly determined. However, should you require a fixed GUID,
1479 it can be set using this variable.
1480
1481 This variable is specific to \c{.vcproj} files only; it is ignored
1482 otherwise.
1483
1484 \section1 HEADERS
1485
1486 Defines the header files for the project.
1487
1488 qmake automatically detects whether \l{moc} is required by the classes in
1489 the headers, and adds the appropriate dependencies and files to the project
1490 for generating and linking the moc files.
1491
1492 For example:
1493
1494 \snippet code/doc_src_qmake-manual.pro 34
1495
1496 See also \l{#SOURCES}{SOURCES}.
1497
1498 \section1 ICON
1499
1500 This variable is used only on Mac OS to set the application icon.
1501 Please see \l{Setting the Application Icon}{the application icon documentation}
1502 for more information.
1503
1504 \section1 IDLSOURCES
1505
1506 This variable is used only on Windows for the Visual Studio project generation to
1507 put the specified files in the Generated Files folder.
1508
1509 \section1 INCLUDEPATH
1510
1511 Specifies the #include directories which should be
1512 searched when compiling the project.
1513
1514 For example:
1515
1516 \snippet code/doc_src_qmake-manual.pro 35
1517
1518 To specify a path containing spaces, quote the path using the technique
1519 described in \l{Whitespace}.
1520
1521 \snippet qmake/spaces.pro quoting include paths with spaces
1522
1523 \section1 INSTALLS
1524
1525 Specifies a list of resources that will be installed when
1526 \c{make install} or a similar installation procedure is executed. Each
1527 item in the list is typically defined with attributes that provide
1528 information about where it will be installed.
1529
1530 For example, the following \c{target.path} definition describes where the
1531 build target will be installed, and the \c INSTALLS assignment adds the
1532 build target to the list of existing resources to be installed:
1533
1534 \snippet code/doc_src_qmake-manual.pro 36
1535
1536 \c INSTALLS has a \c{.CONFIG} member that can take several values:
1537
1538 \table
1539 \header
1540 \li Value
1541 \li Description
1542 \row
1543 \li no_check_exist
1544 \li If not set, qmake looks to see if the files to install actually
1545 exist. If these files don't exist, qmake doesn’t create the
1546 install rule. Use this config value if you need to install
1547 files that are generated as part of your build process, like
1548 HTML files created by qdoc.
1549 \row
1550 \li nostrip
1551 \li If set, the typical Unix strip functionality is turned off and
1552 the debug information will remain in the binary.
1553 \row
1554 \li executable
1555 \li On Unix, this sets the executable flag.
1556 \row
1557 \li no_build
1558 \li When you do a \c{make install}, and you don't have a build of
1559 the project yet, the project is first built, and then installed.
1560 If you don't want this behavior, set this config value to ensure
1561 that the build target is not added as a dependency to the install
1562 target.
1563 \row
1564 \li no_default_install
1565 \li A project has a top-level project target where, when you do a
1566 \c{make install}, everything is installed. But, if you have an
1567 install target with this config value set, it's not installed by
1568 default. You then have to explicitly say \c{make install_<file>}.
1569 \endtable
1570
1571 For more information, see \l{Installing Files}.
1572
1573 This variable is also used to specify which additional files will be
1574 deployed to embedded devices.
1575
1576 \section1 JAVA_HOME
1577
1578 \note This variable is useful only to Android targets.
1579
1580 Specifies the JDK/OpenJDK installation path used for building the project.
1581
1582 \section1 LEXIMPLS
1583
1584 Specifies a list of Lex implementation files. The value
1585 of this variable is typically handled by qmake or
1586 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
1587
1588 \section1 LEXOBJECTS
1589
1590 Specifies the names of intermediate Lex object
1591 files. The value of this variable is typically handled by
1592 qmake and rarely needs to be modified.
1593
1594 \section1 LEXSOURCES
1595
1596 Specifies a list of Lex source files. All
1597 dependencies, headers and source files will automatically be added to
1598 the project for building these lex files.
1599
1600 For example:
1601
1602 \snippet code/doc_src_qmake-manual.pro 37
1603
1604 \section1 LIBS
1605
1606 Specifies a list of libraries to be linked into the project.
1607 If you use the Unix \c -l (library) and -L (library path) flags, qmake
1608 handles the libraries correctly on Windows (that is, passes the full path of
1609 the library to the linker). The library must exist for
1610 qmake to find the directory where a \c -l lib is located.
1611
1612 For example:
1613
1614 \snippet code/doc_src_qmake-manual.pro 38
1615
1616 To specify a path containing spaces, quote the path using the technique
1617 described in \l{Whitespace}.
1618
1619 \snippet qmake/spaces.pro quoting library paths with spaces
1620
1621 By default, the list of libraries stored in \c LIBS is reduced to a list of
1622 unique names before it is used. To change this behavior, add the
1623 \c no_lflags_merge option to the \l{CONFIG} variable:
1624
1625 \snippet code/doc_src_qmake-manual.pro 39
1626
1627 \section1 LIBS_PRIVATE
1628
1629 Specifies a list of libraries to be linked privately into the project.
1630 The behavior of this variable is identical to \l LIBS, except that
1631 shared library projects built for Unix do not expose these dependencies
1632 in their link interface.
1633
1634 The effect of this is that if project C depends on library B which
1635 depends on library A privately, but C also wants to use symbols from A
1636 directly, it needs to link to A explicitly. Put differently, libraries
1637 linked privately are not exposed transitively at build time.
1638
1639 \section1 LITERAL_HASH
1640
1641 This variable is used whenever a literal hash character (\c{#}) is needed in
1642 a variable declaration, perhaps as part of a file name or in a string passed
1643 to some external application.
1644
1645 For example:
1646
1647 \snippet qmake/comments.pro 1
1648
1649 By using \c LITERAL_HASH in this way, the \c # character can be used
1650 to construct a URL for the \c message() function to print to the console.
1651
1652 \section1 MAKEFILE
1653
1654 Specifies the name of the generated Makefile. The value of this variable is
1655 typically handled by qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to
1656 be modified.
1657
1658 \section1 MAKEFILE_GENERATOR
1659
1660 Specifies the name of the Makefile generator to use
1661 when generating a Makefile. The value of this variable is typically
1662 handled internally by qmake and rarely needs to
1663 be modified.
1664
1665 \section1 MSVCPROJ_*
1666
1667 These variables are handled internally by qmake and should not be modified
1668 or utilized.
1669
1670 \section1 MOC_DIR
1671
1672 Specifies the directory where all intermediate moc
1673 files should be placed.
1674
1675 For example:
1676
1677 \snippet code/doc_src_qmake-manual.pro 40
1678
1679 \section1 OBJECTIVE_HEADERS
1680
1681 Defines the Objective-C++ header files for the project.
1682
1683 qmake automatically detects whether \l{moc} is required by the classes in the
1684 headers, and adds the appropriate dependencies and files to the project for
1685 generating and linking the moc files.
1686
1687 This is similar to the HEADERS variable, but will let the generated moc
1688 files be compiled with the Objective-C++ compiler.
1689
1690 See also \l{#OBJECTIVE_SOURCES}{OBJECTIVE_SOURCES}.
1691
1692 \section1 OBJECTIVE_SOURCES
1693
1694 Specifies the names of all Objective-C/C++ source files in the project.
1695
1696 This variable is now obsolete, Objective-C/C++ files (.m and .mm) can be
1697 added to the \l{#SOURCES}{SOURCES} variable.
1698
1699 See also \l{#OBJECTIVE_HEADERS}{OBJECTIVE_HEADERS}.
1700
1701 \section1 OBJECTS
1702
1703 This variable is automatically populated from the \l{SOURCES} variable.
1704 The extension of each source file is replaced by .o (Unix) or .obj (Win32).
1705 You can add objects to the list.
1706
1707 \section1 OBJECTS_DIR
1708
1709 Specifies the directory where all intermediate
1710 objects should be placed.
1711
1712 For example:
1713
1714 \snippet code/doc_src_qmake-manual.pro 41
1715
1716 \section1 POST_TARGETDEPS
1717
1718 Lists the libraries that the \l{#TARGET}{target} depends on. Some backends,
1719 such as the generators for Visual Studio and Xcode project files, do not
1720 support this variable. Generally, this variable is supported internally by
1721 these build tools, and it is useful for explicitly listing dependent static
1722 libraries.
1723
1724 This list is placed after all builtin (and \link #PRE_TARGETDEPS
1725 $$PRE_TARGETDEPS \endlink) dependencies.
1726
1727 \section1 PRE_TARGETDEPS
1728
1729 Lists libraries that the \l{#TARGET}{target} depends on. Some backends,
1730 such as the generators for Visual Studio and Xcode project files, do not
1731 support this variable. Generally, this variable is supported internally by
1732 these build tools, and it is useful for explicitly listing dependent static
1733 libraries.
1734
1735 This list is placed before all builtin dependencies.
1736
1737 \section1 PRECOMPILED_HEADER
1738
1739 Indicates the header file for creating a precompiled
1740 header file, to increase the compilation speed of a project.
1741 Precompiled headers are currently only supported on some platforms
1742 (Windows - all MSVC project types, Apple - Xcode, Makefile,
1743 Unix - gcc 3.3 and up).
1744
1745 \section1 PWD
1746
1747 Specifies the full path leading to the directory
1748 containing the current file being parsed. This can be useful
1749 to refer to files within the source tree when writing project files to
1750 support shadow builds.
1751
1752 See also \l{#_PRO_FILE_PWD_}{_PRO_FILE_PWD_}.
1753
1754 \note Do not attempt to overwrite the value of this variable.
1755
1756 \section1 OUT_PWD
1757
1758 Specifies the full path leading to the directory where qmake places the
1759 generated Makefile.
1760
1761 \note Do not attempt to overwrite the value of this variable.
1762
1763 \section1 QM_FILES_RESOURCE_PREFIX
1764
1765 Specifies the directory in the resource system where \c .qm files will
1766 be made available by \l{CONFIG}{CONFIG += embed_translations}.
1767
1768 The default is \c{:/i18n/}.
1769
1770 \section1 QM_FILES_INSTALL_PATH
1771
1772 Specifies the target directory \c .qm files generated by
1773 \l{CONFIG}{CONFIG += lrelease} will be installed to. Does not have any
1774 effect if \l{CONFIG}{CONFIG += embed_translations} is set.
1775
1776 \section1 QML_IMPORT_PATH
1777
1778 This variable is only used by \l{\QC Documentation}{Qt Creator}. If you have
1779 an extra module that is kept outside of your Qt installation, you can
1780 specify its path here.
1781
1782 See \l{Qt Creator: Using QML Modules with Plugins} for details.
1783
1784 \section1 QMLPATHS
1785
1786 Expects a list of import paths that point to root directories of trees of
1787 QML modules. For example, if you have a custom location for your QML
1788 modules, you can specify it here.
1789
1790 \note The path entries for QMLPATHS point to root directories of trees of
1791 QML modules. This is the concept of import paths the QML engine understands.
1792 You can pass the same paths via the \c QML_IMPORT_PATH \e environment variable
1793 to your QML application, but they are \e different from the expected contents
1794 of the \l QML_IMPORT_PATH \e qmake variable. The latter expects paths to
1795 \e individual modules to be processed by Qt Creator only.
1796
1797 \note The contents of QMLPATHS are \e not automatically passed to your
1798 application. Rather, they are only used at build time. In particular,
1799 qmlimportscanner uses them to find any QML modules it may need to mark as
1800 imported by your application.
1801
1802 \sa QQmlEngine::addImportPath()
1803
1804 \section1 QMAKE
1805
1806 Specifies the name of the qmake program itself and is placed in generated
1807 Makefiles. The value of this variable is typically handled by qmake or
1808 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
1809
1810 \section1 QMAKESPEC
1811
1812 A system variable that contains the full path of the qmake configuration that is used
1813 when generating Makefiles. The value of this variable is automatically computed.
1814
1815 \note Do not attempt to overwrite the value of this variable.
1816
1817 \section1 QMAKE_APPLE_DEVICE_ARCHS
1818
1819 \note This variable is used on \macos only.
1820
1821 Specifies a list of architectures to build for. By default, a project is
1822 built for the development machine's architecture. This variable allows to
1823 override the default and build for a different architecture or to create
1824 multi-architecture binaries.
1825
1826 This variable is usually specified on the command line or in the project
1827 file.
1828
1829 See \l{Qt for macOS} for more information.
1830
1831 \section1 QMAKE_AR_CMD
1832
1833 \note This variable is used on Unix platforms only.
1834
1835 Specifies the command to execute when creating a shared library. The value of this variable
1836 is typically handled by qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
1837
1838 \section1 QMAKE_BUNDLE_DATA
1839
1840 \note This variable is used on \macos, iOS, tvOS, and watchOS only.
1841
1842 Specifies the data that will be installed with a library
1843 bundle, and is often used to specify a collection of header files.
1844
1845 For example, the following lines add \c path/to/header_one.h
1846 and \c path/to/header_two.h to a group containing information about the
1847 headers supplied with the framework:
1848
1849 \snippet code/doc_src_qmake-manual.pro 43
1850
1851 The last line adds the information about the headers to the collection of
1852 resources that will be installed with the library bundle.
1853
1854 Library bundles are created when the \c lib_bundle option is added to the
1855 \l{#CONFIG}{CONFIG} variable.
1856
1857 See \l{Platform Notes#Creating Frameworks}{Platform Notes} for
1858 more information about creating library bundles.
1859
1860 A project can also use this variable to bundle application translation
1861 files. The exact syntax depends on whether the project is using Xcode's
1862 legacy build system or its new build system.
1863
1864 For example when the following project snippet is built using the
1865 legacy build system:
1866
1867 \snippet code/doc_src_qmake-manual.pro 188
1868
1869 Xcode will ignore the original location of \c InfoPlist.strings
1870 and the file will placed into the bundle \c Resources directory
1871 under the provided \c translations_en.path path, so
1872 \c Resources/en.lproj/InfoPlist.strings
1873
1874 With the new build system, the relative location of the file is
1875 preserved, which means the file will incorrectly be placed under
1876 \c Resources/en.lproj/en.lproj/InfoPlist.strings
1877
1878 To ensure correct file placement, the project can either move
1879 the original file not to be in a sub-directory or it can choose
1880 not to specify the \c translations_en.path variable.
1881
1882 \snippet code/doc_src_qmake-manual.pro 189
1883
1884 See \qtbug QTBUG-98417 for more details on how the Xcode build
1885 system changed its behavior in bundling translation files.
1886
1887 \section1 QMAKE_BUNDLE_EXTENSION
1888
1889 \note This variable is used on \macos, iOS, tvOS, and watchOS only.
1890
1891 Specifies the extension to be used for library bundles.
1892 This allows frameworks to be created with custom extensions instead of the
1893 standard \c{.framework} directory name extension.
1894
1895 For example, the following definition will result in a framework with the
1896 \c{.myframework} extension:
1897
1898 \snippet code/doc_src_qmake-manual.pro 44
1899
1900 \section1 QMAKE_CC
1901
1902 Specifies the C compiler that will be used when building
1903 projects containing C source code. Only the file name of the compiler
1904 executable needs to be specified as long as it is on a path contained
1905 in the \c PATH variable when the Makefile is processed.
1906
1907 \section1 QMAKE_CFLAGS
1908
1909 Specifies the C compiler flags for building
1910 a project. The value of this variable is typically handled by
1911 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
1912 needs to be modified. The flags specific to debug and release modes can be
1913 adjusted by modifying the \c QMAKE_CFLAGS_DEBUG and
1914 \c QMAKE_CFLAGS_RELEASE variables, respectively.
1915
1916 \section1 QMAKE_CFLAGS_DEBUG
1917
1918 Specifies the C compiler flags for debug builds.
1919 The value of this variable is typically handled by qmake or \l{#QMAKESPEC}{qmake.conf} and
1920 rarely needs to be modified.
1921
1922 \section1 QMAKE_CFLAGS_RELEASE
1923
1924 Specifies the C compiler flags for release builds.
1925 The value of this variable is typically handled by qmake or \l{#QMAKESPEC}{qmake.conf}
1926 and rarely needs to be modified.
1927
1928 \section1 QMAKE_CFLAGS_RELEASE_WITH_DEBUGINFO
1929
1930 Specifies the C compiler flags for release builds where
1931 \c{force_debug_info} is set in \c{CONFIG}.
1932 The value of this variable is typically handled by
1933 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
1934
1935 \section1 QMAKE_CFLAGS_SHLIB
1936
1937 \note This variable is used on Unix platforms only.
1938
1939 Specifies the compiler flags for creating a shared
1940 library. The value of this variable is typically handled by
1941 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
1942 needs to be modified.
1943
1944 \section1 QMAKE_CFLAGS_THREAD
1945
1946 Specifies the compiler flags for creating a multi-threaded
1947 application. The value of this variable is typically handled by
1948 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
1949 needs to be modified.
1950
1951 \section1 QMAKE_CFLAGS_WARN_OFF
1952
1953 This variable is used only when the \c {warn_off} \l{#CONFIG}{CONFIG} option
1954 is set. The value of this variable is typically handled by qmake or
1955 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
1956
1957 \section1 QMAKE_CFLAGS_WARN_ON
1958
1959 This variable is used only when the \c {warn_on} \l{#CONFIG}{CONFIG} option
1960 is set. The value of this variable is typically handled by
1961 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
1962
1963 \section1 QMAKE_CLEAN
1964
1965 Specifies a list of generated files (by \l{moc} and \l{uic}, for example) and
1966 object files to be removed by \c {make clean}.
1967
1968 \section1 QMAKE_CXX
1969
1970 Specifies the C++ compiler that will be used when building
1971 projects containing C++ source code. Only the file name of the compiler
1972 executable needs to be specified as long as it is on a path contained
1973 in the \c PATH variable when the Makefile is processed.
1974
1975 \section1 QMAKE_CXXFLAGS
1976
1977 Specifies the C++ compiler flags for building
1978 a project. The value of this variable is typically handled by
1979 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
1980 needs to be modified. The flags specific to debug and release modes can be
1981 adjusted by modifying the \c QMAKE_CXXFLAGS_DEBUG and
1982 \c QMAKE_CXXFLAGS_RELEASE variables, respectively.
1983
1984 \section1 QMAKE_CXXFLAGS_DEBUG
1985
1986 Specifies the C++ compiler flags for debug builds.
1987 The value of this variable is typically handled by
1988 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
1989
1990 \section1 QMAKE_CXXFLAGS_RELEASE
1991
1992 Specifies the C++ compiler flags for release builds.
1993 The value of this variable is typically handled by
1994 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
1995
1996 \section1 QMAKE_CXXFLAGS_RELEASE_WITH_DEBUGINFO
1997
1998 Specifies the C++ compiler flags for release builds where
1999 \c{force_debug_info} is set in \c{CONFIG}.
2000 The value of this variable is typically handled by
2001 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2002
2003 \section1 QMAKE_CXXFLAGS_SHLIB
2004
2005 Specifies the C++ compiler flags for creating a shared library.
2006 The value of this variable is typically handled by
2007 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2008 needs to be modified.
2009
2010 \section1 QMAKE_CXXFLAGS_THREAD
2011
2012 Specifies the C++ compiler flags for creating a multi-threaded application.
2013 The value of this variable is typically handled by qmake or \l{#QMAKESPEC}
2014 {qmake.conf} and rarely needs to be modified.
2015
2016 \section1 QMAKE_CXXFLAGS_WARN_OFF
2017
2018 Specifies the C++ compiler flags for suppressing compiler
2019 warnings. The value of this variable is typically handled by
2020 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2021 needs to be modified.
2022
2023 \section1 QMAKE_CXXFLAGS_WARN_ON
2024
2025 Specifies C++ compiler flags for generating compiler warnings.
2026 The value of this variable is typically handled by
2027 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2028 needs to be modified.
2029
2030 \section1 QMAKE_DEVELOPMENT_TEAM
2031
2032 \note This variable is used on \macos, iOS, tvOS, and watchOS only.
2033
2034 The identifier of a development team to use for signing certificates
2035 and provisioning profiles.
2036
2037 \section1 QMAKE_DISTCLEAN
2038
2039 Specifies a list of files to be removed by \c{make distclean}.
2040
2041 \section1 QMAKE_EXTENSION_SHLIB
2042
2043 Contains the extension for shared libraries. The value of
2044 this variable is typically handled by qmake or
2045 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2046
2047 \note Platform-specific variables that change the extension override
2048 the contents of this variable.
2049
2050 \section1 QMAKE_EXTENSION_STATICLIB
2051
2052 Contains the extension for shared static libraries. The value of
2053 this variable is typically handled by qmake or
2054 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2055
2056 \section1 QMAKE_EXT_MOC
2057
2058 Contains the extension used on included moc files.
2059
2060 See also \l{Configuring qmake#File Extensions}{File Extensions}.
2061
2062 \section1 QMAKE_EXT_UI
2063
2064 Contains the extension used on \QD UI files.
2065
2066 See also \l{Configuring qmake#File Extensions}{File Extensions}.
2067
2068 \section1 QMAKE_EXT_PRL
2069
2070 Contains the extension used on created PRL files.
2071
2072 See also \l{Configuring qmake#File Extensions}{File Extensions},
2073 \l{Library Dependencies}.
2074
2075 \section1 QMAKE_EXT_LEX
2076
2077 Contains the extension used on files given to Lex.
2078
2079 See also \l{Configuring qmake#File Extensions}{File Extensions},
2080 \l{#LEXSOURCES}{LEXSOURCES}.
2081
2082 \section1 QMAKE_EXT_YACC
2083 Contains the extension used on files given to Yacc.
2084
2085 See also \l{Configuring qmake#File Extensions}{File Extensions},
2086 \l{#YACCSOURCES}{YACCSOURCES}.
2087
2088 \section1 QMAKE_EXT_OBJ
2089
2090 Contains the extension used on generated object files.
2091
2092 See also \l{Configuring qmake#File Extensions}{File Extensions}.
2093
2094 \section1 QMAKE_EXT_CPP
2095
2096 Contains suffixes for files that should be interpreted as C++ source code.
2097
2098 See also \l{Configuring qmake#File Extensions}{File Extensions}.
2099
2100 \section1 QMAKE_EXT_H
2101
2102 Contains suffixes for files which should be interpreted as C header files.
2103
2104 See also \l{Configuring qmake#File Extensions}{File Extensions}.
2105
2106 \section1 QMAKE_EXTRA_COMPILERS
2107
2108 Specifies a list of additional compilers or preprocessors.
2109
2110 See also \l{Adding Compilers}.
2111
2112 \section1 QMAKE_EXTRA_TARGETS
2113
2114 Specifies a list of additional qmake targets.
2115
2116 See also \l{Adding Custom Targets}.
2117
2118 \section1 QMAKE_FAILED_REQUIREMENTS
2119
2120 Contains the list of failed requirements.
2121 The value of this variable is set by qmake and cannot be modified.
2122
2123 See also \l{requires(condition)}{requires()} and \l{REQUIRES}.
2124
2125 \section1 QMAKE_FRAMEWORK_BUNDLE_NAME
2126
2127 \note This variable is used on \macos, iOS, tvOS, and watchOS only.
2128
2129 In a framework project, this variable contains the name to be used for the
2130 framework that is built.
2131
2132 By default, this variable contains the same value as the \l{#TARGET}{TARGET}
2133 variable.
2134
2135 See \l{Creating Frameworks} for
2136 more information about creating frameworks and library bundles.
2137
2138 \section1 QMAKE_FRAMEWORK_VERSION
2139
2140 \note This variable is used on \macos, iOS, tvOS, and watchOS only.
2141
2142 For projects where the build target is a \macos, iOS, tvOS, or watchOS
2143 framework, this variable is used to specify the version number that will be
2144 applied to the framework that is built.
2145
2146 By default, this variable contains the same value as the \l{#VERSION}{VERSION}
2147 variable.
2148
2149 See \l{Creating Frameworks} for more information about creating frameworks.
2150
2151 \section1 QMAKE_HOST
2152
2153 Provides information about the host machine running qmake.
2154 For example, you can retrieve the host machine architecture from
2155 \c{QMAKE_HOST.arch}.
2156
2157 \table
2158 \header \li Keys \li Values
2159 \row \li .arch \li Host architecture
2160 \row \li .os \li Host OS
2161 \row \li .cpu_count \li Number of available cpus
2162 \row \li .name \li Host computer name
2163 \row \li .version \li Host OS version number
2164 \row \li .version_string \li Host OS version string
2165 \endtable
2166
2167 \snippet code/doc_src_qmake-manual.pro 187
2168
2169 \section1 QMAKE_INCDIR
2170
2171 Specifies the list of system header paths that are appended to \l{INCLUDEPATH}.
2172 The value of this variable is typically handled by qmake or
2173 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2174
2175 \section1 QMAKE_INCDIR_EGL
2176
2177 Specifies the location of EGL header files to be added to
2178 \l{INCLUDEPATH} when building a target with OpenGL/ES or OpenVG support.
2179 The value of this variable is typically handled by
2180 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2181 needs to be modified.
2182
2183 \section1 QMAKE_INCDIR_OPENGL
2184
2185 Specifies the location of OpenGL header files to be added
2186 to \l{INCLUDEPATH} when building a target with OpenGL support. The
2187 value of this variable is typically handled by
2188 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2189 needs to be modified.
2190
2191 If the OpenGL implementation uses EGL (most OpenGL/ES systems),
2192 then QMAKE_INCDIR_EGL may also need to be set.
2193
2194 \section1 QMAKE_INCDIR_OPENGL_ES2
2195
2196 This variable specifies the location of OpenGL header files to be added
2197 to \l{INCLUDEPATH} when building a target with OpenGL ES 2 support.
2198
2199 The value of this variable is typically handled by qmake or
2200 \l{#QMAKESPEC}{qmake.conf} and rarely
2201 needs to be modified.
2202
2203 If the OpenGL implementation uses EGL (most OpenGL/ES systems),
2204 then QMAKE_INCDIR_EGL may also need to be set.
2205
2206 \section1 QMAKE_INCDIR_OPENVG
2207
2208 Specifies the location of OpenVG header files to be added
2209 to \l{INCLUDEPATH} when building a target with OpenVG support. The
2210 value of this variable is typically handled by
2211 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2212 needs to be modified.
2213
2214 If the OpenVG implementation uses EGL then QMAKE_INCDIR_EGL may also
2215 need to be set.
2216
2217 \section1 QMAKE_INCDIR_X11
2218
2219 \note This variable is used on Unix platforms only.
2220
2221 Specifies the location of X11 header file paths to be added
2222 to \l{INCLUDEPATH} when building an X11 target. The value of this variable
2223 is typically handled by qmake or
2224 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2225
2226 \section1 QMAKE_INFO_PLIST
2227
2228 \note This variable is used on \macos, iOS, tvOS, and watchOS platforms only.
2229
2230 Specifies the name of the property list file, \c{.plist}, you
2231 would like to include in your \macos, iOS, tvOS, and watchOS application bundle.
2232
2233 In the \c{.plist} file, you can define some variables which
2234 qmake will replace with the relevant values:
2235
2236 \table
2237 \header
2238 \li Placeholder(s)
2239 \li Effect
2240 \row
2241 \li \c ${PRODUCT_BUNDLE_IDENTIFIER}, \c @BUNDLEIDENTIFIER@
2242 \li Expands to the target bundle's bundle identifier string,
2243 for example: \c{com.example.myapp}. Determined by concatenating the
2244 values of \c QMAKE_TARGET_BUNDLE_PREFIX and \c QMAKE_BUNDLE, separated
2245 by a full stop (\c{.}). The value of \c QMAKE_BUNDLE is derived from
2246 \c QMAKE_APPLICATION_BUNDLE_NAME, \c QMAKE_PLUGIN_BUNDLE_NAME, or
2247 \c QMAKE_FRAMEWORK_BUNDLE_NAME. It should not be set directly by the
2248 project.
2249 \row
2250 \li \c ${EXECUTABLE_NAME}, \c @EXECUTABLE@, \c @LIBRARY@
2251 \li Equivalent to the value of QMAKE_APPLICATION_BUNDLE_NAME,
2252 QMAKE_PLUGIN_BUNDLE_NAME, or QMAKE_FRAMEWORK_BUNDLE_NAME
2253 (depending on the type of target being created),
2254 or TARGET if none of the previous values are set.
2255 \row
2256 \li \c ${ASSETCATALOG_COMPILER_APPICON_NAME}, \c @ICON@
2257 \li Expands to the value of ICON.
2258 \row
2259 \li \c ${QMAKE_PKGINFO_TYPEINFO}, \c @TYPEINFO@
2260 \li Expands to the value of QMAKE_PKGINFO_TYPEINFO.
2261 \row
2262 \li \c ${QMAKE_FULL_VERSION}, \c @FULL_VERSION@
2263 \li Expands to the value of VERSION expressed with three version components.
2264 \row
2265 \li \c ${QMAKE_SHORT_VERSION}, \c @SHORT_VERSION@
2266 \li Expands to the value of VERSION expressed with two version components.
2267 \row
2268 \li \c ${MACOSX_DEPLOYMENT_TARGET}
2269 \li Expands to the value of QMAKE_MACOSX_DEPLOYMENT_TARGET.
2270 \row
2271 \li \c ${IPHONEOS_DEPLOYMENT_TARGET}
2272 \li Expands to the value of QMAKE_IPHONEOS_DEPLOYMENT_TARGET.
2273 \row
2274 \li \c ${TVOS_DEPLOYMENT_TARGET}
2275 \li Expands to the value of QMAKE_TVOS_DEPLOYMENT_TARGET.
2276 \row
2277 \li \c ${WATCHOS_DEPLOYMENT_TARGET}
2278 \li Expands to the value of QMAKE_WATCHOS_DEPLOYMENT_TARGET.
2279 \row
2280 \li \c ${IOS_LAUNCH_SCREEN}
2281 \li Expands to the value of QMAKE_IOS_LAUNCH_SCREEN.
2282 \endtable
2283
2284 \note When using the Xcode generator, the above \c{${var}}-style
2285 placeholders are replaced directly by the Xcode build system and are not
2286 handled by qmake. The \c{@var@} style placeholders work only with the qmake
2287 Makefile generators and not with the Xcode generator.
2288
2289 If building for iOS, and the \c{.plist} file contains the key
2290 \c NSPhotoLibraryUsageDescription, qmake will include an additional plugin
2291 to the build that adds photo access support (to, e.g.,
2292 \l{QFileDialog::setDirectory()}{QFile/QFileDialog}). See Info.plist
2293 documentation from Apple for more information regarding this key.
2294
2295 \note Most of the time, the default \c{Info.plist} is good enough.
2296
2297 \section1 QMAKE_IOS_DEPLOYMENT_TARGET
2298
2299 \note This variable is used on the iOS platform only.
2300
2301 Specifies the hard minimum version of iOS that the application supports.
2302
2303 For more information, see \l {Expressing Supported iOS Versions}.
2304
2305 \section1 QMAKE_IOS_LAUNCH_SCREEN
2306
2307 \note This variable is used on the iOS platform only.
2308
2309 Specifies the launch screen that is used by the application. If this is not set
2310 then a default launch screen is used.
2311
2312 \section1 QMAKE_LFLAGS
2313
2314 Specifies a general set of flags that are passed to
2315 the linker. If you need to change the flags used for a particular
2316 platform or type of project, use one of the specialized variables
2317 for that purpose instead of this variable.
2318
2319 \section1 QMAKE_LFLAGS_CONSOLE
2320
2321 \note This variable is used on Windows only.
2322
2323 Specifies the linker flags for building console programs. The value
2324 of this variable is typically handled by qmake
2325 or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2326
2327 \section1 QMAKE_LFLAGS_DEBUG
2328
2329 Specifies the linker flags for debug builds.
2330 The value of this variable is typically handled by qmake or \l{#QMAKESPEC}{qmake.conf}
2331 and rarely needs to be modified.
2332
2333 \section1 QMAKE_LFLAGS_PLUGIN
2334
2335 Specifies the linker flags for building plugins. The value of this
2336 variable is typically handled by qmake or
2337 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2338
2339 \section1 QMAKE_LFLAGS_RPATH
2340
2341 \note This variable is used on Unix platforms only.
2342
2343 Specifies the linker flags needed to use the values from \l{QMAKE_RPATHDIR}.
2344
2345 The value of this variable is typically handled by
2346 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2347
2348 \section1 QMAKE_LFLAGS_REL_RPATH
2349
2350 Specifies the linker flags needed to enable relative paths in
2351 \l{QMAKE_RPATHDIR}.
2352
2353 The value of this variable is typically handled by
2354 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2355
2356 \section1 QMAKE_REL_RPATH_BASE
2357
2358 Specifies the string the dynamic linker understands to be the
2359 location of the referring executable or library.
2360
2361 The value of this variable is typically handled by
2362 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2363
2364 \section1 QMAKE_LFLAGS_RPATHLINK
2365
2366 Specifies the linker flags needed to use the values from
2367 \l{QMAKE_RPATHLINKDIR}.
2368
2369 The value of this variable is typically handled by
2370 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2371
2372 \section1 QMAKE_LFLAGS_RELEASE
2373
2374 Specifies the linker flags for release builds.
2375 The value of this variable is typically handled by
2376 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2377
2378 \section1 QMAKE_LFLAGS_RELEASE_WITH_DEBUGINFO
2379
2380 Specifies the linker flags for release builds where \c{force_debug_info} is
2381 set in \c{CONFIG}. The value of this variable is typically handled by
2382 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2383
2384 \section1 QMAKE_LFLAGS_APP
2385
2386 Specifies the linker flags for building applications.
2387 The value of this variable is typically handled by qmake or
2388 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2389
2390 \section1 QMAKE_LFLAGS_SHLIB
2391
2392 Specifies the linker flags used for building shared libraries.
2393 The value of this variable is typically handled by
2394 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2395 needs to be modified.
2396
2397 \section1 QMAKE_LFLAGS_SONAME
2398
2399 Specifies the linker flags for setting the name of shared objects,
2400 such as .so or .dll. The value of this variable is typically handled by
2401 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2402 needs to be modified.
2403
2404 \section1 QMAKE_LFLAGS_THREAD
2405
2406 Specifies the linker flags for building multi-threaded projects.
2407 The value of this variable is typically handled by
2408 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2409 needs to be modified.
2410
2411 \section1 QMAKE_LFLAGS_WINDOWS
2412
2413 \note This variable is used on Windows only.
2414
2415 Specifies the linker flags for building Windows GUI projects (that is,
2416 non-console applications). The value of this variable is typically handled
2417 by qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2418 needs to be modified.
2419
2420 \section1 QMAKE_LIBDIR
2421
2422 Specifies a list of library search paths for all projects.
2423 The value of this variable is typically handled by qmake
2424 or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2425
2426 To specify additional search paths in project files,
2427 use \l LIBS like that, instead:
2428 \badcode
2429 LIBS += -L/path/to/libraries
2430 \endcode
2431
2432 \section1 QMAKE_LIBDIR_POST
2433
2434 Specifies a list of system library search paths for all projects.
2435 The value of this variable is typically handled by qmake
2436 or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2437
2438 \section1 QMAKE_LIBDIR_FLAGS
2439
2440 \note This variable is used on Unix platforms only.
2441
2442 Specifies the location of all library directories with -L
2443 prefixed. The value of this variable is typically handled by
2444 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2445 needs to be modified.
2446
2447 \section1 QMAKE_LIBDIR_EGL
2448
2449 Specifies the location of the EGL library directory, when EGL
2450 is used with OpenGL/ES or OpenVG. The value of this variable is typically
2451 handled by qmake or \l{#QMAKESPEC}{qmake.conf}
2452 and rarely needs to be modified.
2453
2454 \section1 QMAKE_LIBDIR_OPENGL
2455
2456 Specifies the location of the OpenGL library directory. The
2457 value of this variable is typically handled by
2458 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2459 needs to be modified.
2460
2461 If the OpenGL implementation uses EGL (most OpenGL/ES systems),
2462 then QMAKE_LIBDIR_EGL may also need to be set.
2463
2464 \section1 QMAKE_LIBDIR_OPENVG
2465
2466 Specifies the location of the OpenVG library directory. The
2467 value of this variable is typically handled by
2468 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2469 needs to be modified.
2470
2471 If the OpenVG implementation uses EGL, then QMAKE_LIBDIR_EGL
2472 may also need to be set.
2473
2474 \section1 QMAKE_LIBDIR_X11
2475
2476 \note This variable is used on Unix platforms only.
2477
2478 Specifies the location of the X11 library directory. The value
2479 of this variable is typically handled by qmake
2480 or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2481
2482 \section1 QMAKE_LIBS
2483
2484 Specifies additional libraries each project needs to link against.
2485 The value of this variable is typically handled by qmake or
2486 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2487
2488 To specify libraries in a project file, use \l LIBS instead.
2489
2490 \section1 QMAKE_LIBS_PRIVATE
2491
2492 Specifies additional private libraries each project needs to
2493 link against.
2494 The value of this variable is typically handled by qmake or
2495 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2496
2497 To specify private libraries in a library project file,
2498 use \l LIBS_PRIVATE instead.
2499
2500 \section1 QMAKE_LIBS_EGL
2501
2502 Specifies all EGL libraries when building Qt with OpenGL/ES
2503 or OpenVG. The value of this variable is typically handled by
2504 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2505 needs to be modified. The usual value is \c{-lEGL}.
2506
2507 \section1 QMAKE_LIBS_OPENGL
2508
2509 Specifies all OpenGL libraries. The value of this variable
2510 is typically handled by qmake or
2511 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2512
2513 If the OpenGL implementation uses EGL (most OpenGL/ES systems),
2514 then QMAKE_LIBS_EGL may also need to be set.
2515
2516 \section1 QMAKE_LIBS_OPENGL_ES1, QMAKE_LIBS_OPENGL_ES2
2517
2518 These variables specify all the OpenGL libraries for OpenGL ES 1
2519 and OpenGL ES 2.
2520
2521 The value of these variables is typically handled by
2522 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2523 needs to be modified.
2524
2525 If the OpenGL implementation uses EGL (most OpenGL/ES systems),
2526 then QMAKE_LIBS_EGL may also need to be set.
2527
2528 \section1 QMAKE_LIBS_OPENVG
2529
2530 Specifies all OpenVG libraries. The value of this variable
2531 is typically handled by qmake or
2532 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. The usual
2533 value is \c{-lOpenVG}.
2534
2535 Some OpenVG engines are implemented on top of OpenGL. This will
2536 be detected at configure time and QMAKE_LIBS_OPENGL will be implicitly
2537 added to QMAKE_LIBS_OPENVG wherever the OpenVG libraries are linked.
2538
2539 If the OpenVG implementation uses EGL, then QMAKE_LIBS_EGL may also
2540 need to be set.
2541
2542 \section1 QMAKE_LIBS_THREAD
2543
2544 \note This variable is used on Unix platforms only.
2545
2546 Specifies all libraries that need to be linked against when
2547 building a multi-threaded target. The value of this variable is
2548 typically handled by qmake or
2549 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2550
2551 \section1 QMAKE_LIBS_X11
2552
2553 \note This variable is used on Unix platforms only.
2554
2555 Specifies all X11 libraries. The value of this variable is typically handled by qmake or
2556 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2557
2558 \section1 QMAKE_LIB_FLAG
2559
2560 This variable is not empty if the \c lib template is specified. The value
2561 of this variable is typically handled by qmake
2562 or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2563
2564 \section1 QMAKE_LINK
2565
2566 Specifies the linker that will be used when building
2567 application based projects. Only the file name of the linker
2568 executable needs to be specified as long as it is on a path
2569 contained in the \c PATH variable when the Makefile is processed.
2570 The value of this variable is typically handled by qmake or
2571 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2572
2573 \section1 QMAKE_LINK_SHLIB_CMD
2574
2575 Specifies the command to execute when creating a shared
2576 library. The value of this variable is typically handled by
2577 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2578 needs to be modified.
2579
2580 \section1 QMAKE_LN_SHLIB
2581
2582 Specifies the command to execute when creating a link to a shared library. The
2583 value of this variable is typically handled by qmake or
2584 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2585
2586 \section1 QMAKE_LRELEASE_FLAGS
2587
2588 List of additional options passed to \l{Using lrelease}{lrelease} when
2589 enabled through \l{CONFIG}{CONFIG += lrelease}.
2590
2591 \section1 QMAKE_OBJECTIVE_CFLAGS
2592
2593 Specifies the Objective C/C++ compiler flags for building
2594 a project. These flags are used in addition to QMAKE_CFLAGS and
2595 QMAKE_CXXFLAGS.
2596
2597 \section1 QMAKE_POST_LINK
2598
2599 Specifies the command to execute after linking the \l{TARGET}
2600 together. This variable is normally empty and therefore nothing is
2601 executed.
2602
2603 \note This variable takes no effect on Xcode projects.
2604
2605 \section1 QMAKE_PRE_LINK
2606
2607 Specifies the command to execute before linking the \l{TARGET}
2608 together. This variable is normally empty and therefore nothing is
2609 executed.
2610
2611 \warning This variable is not supported when using the Xcode
2612 generator and the new Xcode build system.
2613
2614 \section1 QMAKE_PROJECT_NAME
2615
2616 \note This variable is used for Visual Studio project files only.
2617
2618 Determines the name of the project when generating project
2619 files for IDEs. The default value is the target name. The value of this
2620 variable is typically handled by qmake and rarely needs to be modified.
2621
2622 \section1 QMAKE_PROVISIONING_PROFILE
2623
2624 \note This variable is used on \macos, iOS, tvOS, and watchOS only.
2625
2626 The UUID of a valid provisioning profile. Use in conjunction with
2627 \l{QMAKE_DEVELOPMENT_TEAM} to specify the provisioning profile.
2628
2629 \note Specifying the provisioning profile disables the automatically
2630 managed signing.
2631
2632 \section1 QMAKE_MAC_SDK
2633
2634 This variable is used on \macos when building universal binaries.
2635
2636 \section1 QMAKE_MACOSX_DEPLOYMENT_TARGET
2637
2638 \note This variable is used on the \macos platform only.
2639
2640 Specifies the hard minimum version of \macos that the application supports.
2641
2642 For more information, see \l{Qt for \macos#Supported Configurations}{\macos Supported Configurations}.
2643
2644 \section1 QMAKE_MAKEFILE
2645
2646 Specifies the name of the Makefile to create. The value of
2647 this variable is typically handled by qmake or
2648 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2649
2650 \section1 QMAKE_QMAKE
2651
2652 Contains the absolute path of the qmake executable.
2653
2654 \note Do not attempt to overwrite the value of this variable.
2655
2656 \section1 QMAKE_RESOURCE_FLAGS
2657
2658 This variable is used to customize the list of options passed to the
2659 \l{rcc}{Resource Compiler} in each of the build rules where it is used.
2660 For example, the following line ensures that the \c{-threshold} and
2661 \c{-compress} options are used with particular values each time that
2662 \c rcc is invoked:
2663
2664 \snippet code/doc_src_qmake-manual.pro 45
2665
2666 \section1 QMAKE_RPATHDIR
2667
2668 \note This variable is used on Unix platforms only.
2669
2670 Specifies a list of library paths that are added to the
2671 executable at link time so that the paths will be preferentially
2672 searched at runtime.
2673
2674 When relative paths are specified, qmake will mangle them into a form
2675 understood by the dynamic linker to be relative to the location of
2676 the referring executable or library.
2677 This is supported only by some platforms (currently Linux and
2678 Darwin-based ones) and is detectable by checking whether
2679 \l{QMAKE_REL_RPATH_BASE} is set.
2680
2681 \section1 QMAKE_RPATHLINKDIR
2682
2683 Specifies a list of library paths for the static linker to search for implicit
2684 dependencies of shared libraries. For more information, see the manual page
2685 for \c ld(1).
2686
2687 \section1 QMAKE_RUN_CC
2688
2689 Specifies the individual rule needed to build an object. The
2690 value of this variable is typically handled by
2691 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2692 needs to be modified.
2693
2694 \section1 QMAKE_RUN_CC_IMP
2695
2696 Specifies the individual rule needed to build an object. The
2697 value of this variable is typically handled by
2698 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2699 needs to be modified.
2700
2701 \section1 QMAKE_RUN_CXX
2702
2703 Specifies the individual rule needed to build an object. The
2704 value of this variable is typically handled by
2705 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2706 needs to be modified.
2707
2708 \section1 QMAKE_RUN_CXX_IMP
2709
2710 Specifies the individual rule needed to build an object. The
2711 value of this variable is typically handled by
2712 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2713 needs to be modified.
2714
2715 \section1 QMAKE_SONAME_PREFIX
2716
2717 If defined, the value of this variable is used as a path to be prepended to
2718 the built shared library's \c SONAME identifier. The \c SONAME is the
2719 identifier that the dynamic linker will later use to reference the library.
2720 In general, this reference may be a library name or full library path. On \macos,
2721 iOS, tvOS, and watchOS, the path may be specified relatively using the following
2722 placeholders:
2723
2724 \table
2725 \header \li Placeholder \li Effect
2726 \row \li @rpath
2727 \li Expands to paths defined by LC_RPATH mach-o commands in
2728 the current process executable or the referring libraries.
2729 \row \li @executable_path
2730 \li Expands to the current process executable location.
2731 \row \li @loader_path
2732 \li Expands to the referring executable or library location.
2733 \endtable
2734
2735 In most cases, using \c @rpath is sufficient and recommended:
2736
2737 \snippet code/doc_src_qmake-manual.pro 183
2738
2739 However, the prefix may be also specified using different placeholders, or
2740 an absolute path, such as one of the following:
2741
2742 \snippet code/doc_src_qmake-manual.pro 184
2743
2744 For more information, see
2745 \l{https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/dyld.1.html}{dyld}
2746 documentation on dynamic library install names.
2747
2748 \section1 QMAKE_TARGET
2749
2750 Specifies the name of the project target. The value of this
2751 variable is typically handled by qmake or
2752 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
2753
2754 \section1 QMAKE_TARGET_COMPANY
2755
2756 Windows only. Specifies the company for the project target; this is
2757 used where applicable for putting the company name in the application's
2758 properties. This is only utilized if the \l{VERSION} or \l{RC_ICONS}
2759 variable is set and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
2760
2761 \section1 QMAKE_TARGET_DESCRIPTION
2762
2763 Windows only. Specifies the description for the project target; this is
2764 used where applicable for putting the description in the application's
2765 properties. This is only utilized if the \l{VERSION} or \l{RC_ICONS}
2766 variable is set and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
2767
2768 \section1 QMAKE_TARGET_COPYRIGHT
2769
2770 Windows only. Specifies the copyright information for the project target;
2771 this is used where applicable for putting the copyright information in the
2772 application's properties. This is only utilized if the \l{VERSION} or
2773 \l{RC_ICONS} variable is set and the \l{RC_FILE} and \l{RES_FILE} variables
2774 are not set.
2775
2776 \section1 QMAKE_TARGET_PRODUCT
2777
2778 Windows only. Specifies the product for the project target; this is used
2779 where applicable for putting the product in the application's properties.
2780 This is only utilized if the \l{VERSION} or \l{RC_ICONS} variable is set
2781 and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
2782
2783 \section1 QMAKE_TARGET_ORIGINAL_FILENAME
2784
2785 Windows only. Specifies the original file name for the project target;
2786 this is used where applicable for putting the original file name in the
2787 application's properties. This is only utilized if the \l{VERSION} or
2788 \l{RC_ICONS} variable is set and the \l{RC_FILE} and \l{RES_FILE}
2789 variables are not set.
2790
2791 \section1 QMAKE_TARGET_INTERNALNAME
2792
2793 Windows only. Specifies the internal name for the project target; this is
2794 used where applicable for putting the internal name in the application's
2795 properties. This is only utilized if the \l{VERSION} or \l{RC_ICONS}
2796 variable is set and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
2797
2798 \section1 QMAKE_TARGET_COMMENTS
2799
2800 Windows only. Specifies the comments for the project target; this is
2801 used where applicable for putting the comments in the application's
2802 properties. This is only utilized if the \l{VERSION} or \l{RC_ICONS}
2803 variable is set and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
2804
2805 \section1 QMAKE_TARGET_TRADEMARKS
2806
2807 Windows only. Specifies the trademark information for the project target;
2808 this is used where applicable for putting the trademark information in the
2809 application's properties. This is only utilized if the \l{VERSION} or
2810 \l{RC_ICONS} variable is set and the \l{RC_FILE} and \l{RES_FILE} variables
2811 are not set.
2812
2813 \section1 QMAKE_MANIFEST
2814
2815 Windows only. Specifies the manifest file for the project target.
2816 This is only utilized if the \l{RC_FILE} and \l{RES_FILE} variables are not set.
2817 Don't forget to remove embed_manifest_exe and embed_manifest_dll from
2818 the CONFIG variable, otherwise it will conflict with the compiler generated one.
2819
2820 \section1 QMAKE_TVOS_DEPLOYMENT_TARGET
2821
2822 \note This variable is used on the tvOS platform only.
2823
2824 Specifies the hard minimum version of tvOS that the application supports.
2825
2826 For more information, see \l {Expressing Supported iOS Versions}.
2827
2828 \section1 QMAKE_UIC_FLAGS
2829
2830 This variable is used to customize the list of options passed to the
2831 \l{uic}{User Interface Compiler} in each of the build rules where it is
2832 used.
2833
2834 \section1 QMAKE_WATCHOS_DEPLOYMENT_TARGET
2835
2836 \note This variable is used on the watchOS platform only.
2837
2838 Specifies the hard minimum version of watchOS that the application supports.
2839
2840 For more information, see \l {Expressing Supported iOS Versions}.
2841
2842 \section1 QML_IMPORT_MAJOR_VERSION
2843
2844 Specifies the major version to be used for automatically generated QML type
2845 registrations. For more information, see \l {Defining QML Types from C++}.
2846
2847 \section1 QML_IMPORT_MINOR_VERSION
2848
2849 When automatically registering QML types defined in C++, register an
2850 additional version of the module using this minor version. Generally,
2851 minor versions to be registered are inferred from the meta objects.
2852
2853 You can use this variable if the meta objects have not changed and you
2854 still want to import a QML module with a newer minor version number. For
2855 example, \c MyModule metaobjects are at \c 1.1 level, but you want to import
2856 the module as \c 1.3.
2857
2858 \section1 QML_IMPORT_VERSION
2859
2860 Specifies \l QML_IMPORT_MAJOR_VERSION and \l QML_IMPORT_MINOR_VERSION as a
2861 \c {<major>.<minor>} version string.
2862
2863 \section1 QML_IMPORT_NAME
2864
2865 Specifies the module name to be used for automatically generated QML type
2866 registrations. For more information, see \l {Defining QML Types from C++}.
2867
2868 \section1 QML_FOREIGN_METATYPES
2869
2870 Specifies further JSON files with metatypes to be considered when generating
2871 qmltypes files. Use this when external libraries provide types that are
2872 exposed to QML, either directly or as base types or properties of other
2873 types. Qt types will automatically be considered and don't have to be added
2874 here.
2875
2876 \section1 QT
2877
2878 Specifies the \l{All Modules}{Qt modules} that are used by your project. For
2879 the value to add for each module, see the module documentation.
2880
2881 At the C++ implementation level, using a Qt module makes its headers
2882 available for inclusion and causes it to be linked to the binary.
2883
2884 By default, \c QT contains \c core and \c gui, ensuring that standard
2885 GUI applications can be built without further configuration.
2886
2887 If you want to build a project \e without the \l{Qt GUI} module, you need to
2888 exclude the \c gui value with the "-=" operator. The following line will
2889 result in a minimal Qt project being built:
2890
2891 \snippet code/doc_src_qmake-manual.pro 47
2892
2893 If your project is a \QD plugin, use the value \c uiplugin to specify that
2894 the project is to be built as a library, but with specific plugin support
2895 for \QD. For more information, see \l {Building and Installing the Plugin}.
2896
2897 \section1 QTPLUGIN
2898
2899 Specifies a list of names of static Qt plugins that are to be
2900 linked with an application so that they are available as built-in
2901 resources.
2902
2903 qmake automatically adds the plugins that are typically needed
2904 by the used Qt modules (see \c QT).
2905 The defaults are tuned towards an optimal out-of-the-box experience.
2906 See \l{Static Plugins} for a list of available plugins, and ways
2907 to override the automatic linking.
2908
2909 This variable currently has no effect when linking against a
2910 shared/dynamic build of Qt, or when linking libraries.
2911 It may be used for deployment of dynamic plugins at a later time.
2912
2913 \section1 QT_VERSION
2914
2915 Contains the current version of Qt.
2916
2917 \section1 QT_MAJOR_VERSION
2918
2919 Contains the current major version of Qt.
2920
2921 \section1 QT_MINOR_VERSION
2922
2923 Contains the current minor version of Qt.
2924
2925 \section1 QT_PATCH_VERSION
2926
2927 Contains the current patch version of Qt.
2928
2929 \section1 RC_FILE
2930
2931 Windows only. Specifies the name of the Windows resource file (.rc) for the
2932 target. See \l{Adding Windows Resource Files}.
2933
2934 \section1 RC_CODEPAGE
2935
2936 Windows only. Specifies the codepage that should be specified in a generated
2937 .rc file. This is only utilized if the \l{VERSION} or \l{RC_ICONS} variable
2938 is set and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
2939
2940 \section1 RC_DEFINES
2941
2942 Windows only. qmake adds the values of this variable as RC preprocessor macros
2943 (/d option). If this variable is not set, the \l{DEFINES} variable is used instead.
2944
2945 \snippet code/doc_src_qmake-manual.pro 186
2946
2947 \section1 RC_ICONS
2948
2949 Windows only. Specifies the icons that should be included into a generated
2950 .rc file. This is only utilized if the \l{RC_FILE} and \l{RES_FILE} variable
2951 are not set. More details about the generation of .rc files can be found in
2952 the \l{Platform Notes}.
2953
2954 \section1 RC_LANG
2955
2956 Windows only. Specifies the language that should be specified in a generated
2957 .rc file. This is only utilized if the \l{VERSION} or \l{RC_ICONS} variable
2958 is set and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
2959
2960 \section1 RC_INCLUDEPATH
2961
2962 Specifies include paths that are passed to the Windows Resource Compiler.
2963
2964 \section1 RCC_DIR
2965
2966 Specifies the directory for Qt Resource Compiler output files.
2967
2968 For example:
2969
2970 \snippet code/doc_src_qmake-manual.pro 48
2971
2972 \section1 REQUIRES
2973
2974 Specifies a list of values that are evaluated as conditions. If any of the conditions is false,
2975 qmake skips this project (and its \l{SUBDIRS}) when building.
2976
2977 \note We recommend using the \l{requires(condition)}{requires()} function
2978 instead if you want to skip projects or subprojects when building.
2979
2980 \section1 RESOURCES
2981
2982 Specifies the name of the resource collection files (qrc)
2983 for the target. For more information about the resource collection
2984 file, see \l{The Qt Resource System}.
2985
2986 \section1 RES_FILE
2987
2988 Windows only. Specifies the name of the Windows resource compiler's output
2989 file for this target. See \l{RC_FILE} and \l{Adding Windows Resource Files}.
2990
2991 The value of this variable is typically handled by
2992 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
2993 needs to be modified.
2994
2995 \section1 SOURCES
2996
2997 Specifies the names of all source files in the project.
2998
2999 For example:
3000
3001 \snippet code/doc_src_qmake-manual.pro 49
3002
3003 See also \l{#HEADERS}{HEADERS}.
3004
3005 \section1 SUBDIRS
3006
3007 This variable, when used with the \c subdirs \l{#TEMPLATE}{template}
3008 specifies the names of all subdirectories or project files that contain
3009 parts of the project that need to be built. Each subdirectory specified
3010 using this variable must contain its own project file.
3011
3012 It is recommended that the project file in each subdirectory has the same
3013 base name as the subdirectory itself, because that makes it possible to omit
3014 the file name. For example, if the subdirectory is called \c myapp, the
3015 project file in that directory should be called \c myapp.pro.
3016
3017 Alternatively, you can specify a relative path to a .pro file in any
3018 directory. It is strongly recommended that you specify only paths in the
3019 current project's parent directory or its subdirectories.
3020
3021 For example:
3022
3023 \snippet code/doc_src_qmake-manual.pro 50
3024
3025 If you need to ensure that the subdirectories are built in a particular
3026 order, use the \c .depends modifier on the relevant \c SUBDIRS elements.
3027
3028 For example:
3029
3030 \snippet code/doc_src_qmake-manual.pro 51
3031
3032 The configuration above ensures that \c{my_library} is built before
3033 \c{my_executable} and that \c{my_executable} is built before \c{tests}.
3034 However, \c{doc} can be built in parallel with the other subdirectories,
3035 thus speeding up the build process.
3036
3037 \note Multiple dependencies can be listed and they will all be built before
3038 the target that depends on them.
3039
3040 \note Using \l{#CONFIG}{CONFIG += ordered} is discouraged as it can slow down
3041 multi-core builds. Unlike the example shown above, all builds will happen
3042 sequentially even if they don't have dependencies.
3043
3044 Beside defining the build order, it is possible to modify the default behavior
3045 of \c SUBDIRS by giving additional modifiers to \c SUBDIRS elements.
3046 Supported modifiers are:
3047
3048 \table
3049 \header \li Modifier \li Effect
3050 \row \li .subdir \li Use the specified subdirectory instead of \c SUBDIRS value.
3051 \row \li .file \li Specify the subproject \c pro file explicitly. Cannot be
3052 used in conjunction with \c .subdir modifier.
3053 \row \li .depends \li This subproject depends on specified subproject(s).
3054 \row \li .makefile \li The makefile of subproject.
3055 Available only on platforms that use makefiles.
3056 \row \li .target \li Base string used for makefile targets related to this
3057 subproject.
3058 Available only on platforms that use makefiles.
3059 \endtable
3060
3061 For example, define two subdirectories, both of which reside in a different directory
3062 than the \c SUBDIRS value, and one of the subdirectories must be built before the other:
3063
3064 \snippet code/doc_src_qmake-manual.pro 149
3065
3066 \section1 TARGET
3067
3068 Specifies the name of the target file. Contains the base name of the project
3069 file by default.
3070
3071 For example:
3072
3073 \snippet code/doc_src_qmake-manual.pro 52
3074
3075 The project file above would produce an executable named \c myapp on
3076 unix and \c{myapp.exe} on Windows.
3077
3078 \section1 TARGET_EXT
3079
3080 Specifies the extension of \c TARGET. The value of this variable
3081 is typically handled by qmake or
3082 \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
3083
3084 \section1 TARGET_x
3085
3086 Specifies the extension of \c TARGET with a major version number.
3087 The value of this variable is typically handled by
3088 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
3089 needs to be modified.
3090
3091 \section1 TARGET_x.y.z
3092
3093 Specifies the extension of \c TARGET with a version number. The
3094 value of this variable is typically handled by
3095 qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
3096 needs to be modified.
3097
3098 \section1 TEMPLATE
3099
3100 Specifies the name of the template to use when generating the project. The
3101 allowed values are:
3102
3103 \table
3104 \header \li Option \li Description
3105 \row \li app \li Creates a Makefile for building applications
3106 (the default). See \l{Building an Application} for more information.
3107 \row \li lib \li Creates a Makefile for building libraries. See
3108 \l{Building a Library} for more information.
3109 \row \li subdirs \li Creates a Makefile for building targets in subdirectories.
3110 The subdirectories are specified using the \l{#SUBDIRS}{SUBDIRS}
3111 variable.
3112 \row \li aux \li Creates a Makefile for not building anything. Use this if no compiler
3113 needs to be invoked to create the target; for instance, because your
3114 project is written in an interpreted language.
3115 \note This template type is only available for Makefile-based
3116 generators. In particular, it will not work with the vcxproj and
3117 Xcode generators.
3118 \row \li vcapp \li Windows only. Creates an application project for
3119 Visual Studio. See \l{Creating Visual Studio Project Files} for more
3120 information.
3121 \row \li vclib \li Windows only. Creates a library project for Visual Studio.
3122 \endtable
3123
3124 For example:
3125
3126 \snippet code/doc_src_qmake-manual.pro 53
3127
3128 The template can be overridden by specifying a new template type with the
3129 \c -t command line option. This overrides the template type \e after the .pro
3130 file has been processed. With .pro files that use the template type to
3131 determine how the project is built, it is necessary to declare TEMPLATE on
3132 the command line rather than use the \c -t option.
3133
3134 \section1 TRANSLATIONS
3135
3136 Specifies a list of translation (.ts) files that contain
3137 translations of the user interface text into non-native languages.
3138
3139 Translation files in \c TRANSLATIONS will be processed by both
3140 \l{Using lrelease}{lrelease} and \l{Using lupdate} tools. Use
3141 \l EXTRA_TRANSLATIONS if you want only \c lrelease to process a file.
3142
3143 You can use \l{CONFIG}{CONFIG += lrelease} to automatically compile the
3144 files during the build, and
3145 \l{CONFIG}{CONFIG += lrelease embed_translations} to make them available in
3146 \l{The Qt Resource System}.
3147
3148 See the \l{Qt Linguist Manual} for more information about
3149 internationalization (i18n) and localization (l10n) with Qt.
3150
3151 \section1 TR_EXCLUDE
3152
3153 Specifies a list of paths (source files, subdirectories, and C++ include
3154 paths) to be excluded from handling in \c{lupdate}. The paths may contain
3155 wildcards. Relative paths are considered to be relative to
3156 \l{_PRO_FILE_PWD_}.
3157
3158 For example, to exclude source files:
3159
3160 \snippet code/doc_src_qmake-manual.pro TR_EXCLUDE sources
3161
3162 To exclude subdirectories of a \c SUBDIRS project:
3163
3164 \snippet code/doc_src_qmake-manual.pro TR_EXCLUDE SUBDIRS
3165
3166 To speed up lupdate's C++ parser, exclude include paths:
3167
3168 \snippet code/doc_src_qmake-manual.pro TR_EXCLUDE include paths
3169
3170 \section1 UI_DIR
3171
3172 Specifies the directory where all intermediate files from uic
3173 should be placed.
3174
3175 For example:
3176
3177 \snippet code/doc_src_qmake-manual.pro 54
3178
3179 \section1 VERSION
3180
3181 Specifies the version number of the application if the \c app
3182 \l{#TEMPLATE}{template} is specified or the version number of
3183 the library if the \c lib template is specified.
3184
3185 On Windows, triggers auto-generation of an .rc file if the \l{RC_FILE}
3186 and \l{RES_FILE} variables are not set. The generated .rc file will have
3187 the FILEVERSION and PRODUCTVERSION entries filled with major, minor, patch
3188 level, and build number. Each number must be in the range from 0 to 65535.
3189 More details about the generation of .rc files can be found in the
3190 \l{Platform Notes}.
3191
3192 For example:
3193
3194 \snippet code/doc_src_qmake-manual.pro 57
3195
3196 \section1 VERSION_PE_HEADER
3197
3198 Windows only. Specifies the version number, that the Windows linker
3199 puts into the header of the .exe or .dll file via the /VERSION option.
3200 Only a major and minor version may be specified.
3201 If VERSION_PE_HEADER is not set, it falls back to
3202 the major and minor version from \l{VERSION} (if set).
3203
3204 \snippet code/doc_src_qmake-manual.pro 185
3205
3206 \section1 VER_MAJ
3207
3208 Specifies the major version number of the library if the
3209 \c lib \l{#TEMPLATE}{template} is specified.
3210
3211 \section1 VER_MIN
3212
3213 Specifies the minor version number of the library if the
3214 \c lib \l{#TEMPLATE}{template} is specified.
3215
3216 \section1 VER_PAT
3217
3218 Specifies the patch version number of the library if the
3219 \c lib \l{#TEMPLATE}{template} is specified.
3220
3221 \section1 VPATH
3222
3223 Tells qmake where to search for files it cannot open. For example, if qmake
3224 looks for \c SOURCES and finds an entry that it cannot open, it looks
3225 through the entire VPATH list to see if it can find the file on its own.
3226
3227 See also \l{#DEPENDPATH}{DEPENDPATH}.
3228
3229 \section1 WINDOWS_TARGET_PLATFORM_VERSION
3230
3231 Specifies the targeted Windows version; this corresponds to the tag
3232 \c{WindowsTargetPlatformVersion} in vcxproj files.
3233
3234 On desktop Windows, the default value is the value of the environment
3235 variable \c{WindowsSDKVersion}.
3236
3237 \section1 WINDOWS_TARGET_PLATFORM_MIN_VERSION
3238
3239 Specifies the minimum version of the Windows target platform; this
3240 corresponds to the tag \c{WindowsTargetPlatformMinVersion} in vcxproj files.
3241
3242 Defaults to \c{WINDOWS_TARGET_PLATFORM_VERSION}.
3243
3244 \section1 YACCSOURCES
3245
3246 Specifies a list of Yacc source files to be included
3247 in the project. All dependencies, headers and source files will
3248 automatically be included in the project.
3249
3250 For example:
3251
3252 \snippet code/doc_src_qmake-manual.pro 58
3253
3254 \section1 _PRO_FILE_
3255
3256 Contains the path to the project file in use.
3257
3258 For example, the following line causes the location of the project
3259 file to be written to the console:
3260
3261 \snippet qmake/project_location.pro project file
3262
3263 \note Do not attempt to overwrite the value of this variable.
3264
3265 \section1 _PRO_FILE_PWD_
3266
3267 Contains the path to the directory containing the project file in use.
3268
3269 For example, the following line causes the location of the directory
3270 containing the project file to be written to the console:
3271
3272 \snippet qmake/project_location.pro project file directory
3273
3274 \note Do not attempt to overwrite the value of this variable.
3275 */
3276
3277 /*!
3278 \page qmake-function-reference.html
3279 \title Replace Functions
3280 \previouspage Variables
3281 \nextpage Test Functions
3282 \keyword qmake Function Reference - Replace Functions
3283
3284 qmake provides functions for processing the contents of variables
3285 during the configuration process. These functions are called
3286 \e {replace functions}. Typically, they return values that you can
3287 assign to other variables. You can obtain these values by prefixing a
3288 function with the \c $$ operator. Replace functions can be divided into
3289 built-in functions and function libraries.
3290
3291 See also \l{Test Functions}.
3292
3293 \section1 Built-in Replace Functions
3294
3295 Basic replace functions are implemented as built-in functions.
3296
3297 \section2 absolute_path(path[, base])
3298
3299 Returns the absolute path of \c path.
3300
3301 If \c base is not specified, uses the current directory as the base
3302 directory. If it is a relative path, it is resolved relative to the current
3303 directory before use.
3304
3305 For example, the following call returns the string
3306 \c {"/home/johndoe/myproject/readme.txt"}:
3307
3308 \snippet code/doc_src_qmake-manual.pro 159
3309
3310 This function was introduced in Qt 5.0.
3311
3312 See also \l{clean_path(path)}{clean_path()},
3313 \l{relative_path(filePath[, base])}{relative_path()}.
3314
3315 \section2 basename(variablename)
3316
3317 Returns the basename of the file specified in \c variablename.
3318
3319 For example:
3320
3321 \snippet code/doc_src_qmake-manual.pro 59
3322
3323 \section2 cat(filename[, mode])
3324
3325 Returns the contents of \c filename. You can specify the following options
3326 for \c mode:
3327
3328 \list
3329 \li \c blob returns the entire contents of the file as one value
3330 \li \c lines returns each line as a separate value (without line
3331 endings)
3332 \li \c true (default value) and \c false return file contents as
3333 separate values, split according to qmake value list splitting rules
3334 (as in variable assignments). If \c mode is \c false, values that
3335 contain only a newline character are inserted into the list to
3336 indicate where line breaks were in the file.
3337 \endlist
3338
3339 \section2 clean_path(path)
3340
3341 Returns \c path with directory separators normalized (converted to "/") and
3342 redundant ones removed, and "."s and ".."s resolved (as far as possible).
3343 This function is a wrapper around QDir::cleanPath.
3344
3345 This function was introduced in Qt 5.0.
3346
3347 See also \l{absolute_path(path[, base])}{absolute_path()},
3348 \l{relative_path(filePath[, base])}{relative_path()},
3349 \l{shell_path(path)}{shell_path()}, \l{system_path(path)}{system_path()}.
3350
3351 \section2 dirname(file)
3352
3353 Returns the directory name part of the specified file. For example:
3354
3355 \snippet qmake/dirname.pro 0
3356
3357 \section2 enumerate_vars
3358
3359 Returns a list of all defined variable names.
3360
3361 This function was introduced in Qt 5.0.
3362
3363 \section2 escape_expand(arg1 [, arg2 ..., argn])
3364
3365 Accepts an arbitrary number of arguments. It expands the
3366 escape sequences \c {\n}, \c {\r}, \c {\t} for each argument and returns
3367 the arguments as a list.
3368
3369 \note If you specify the string to expand literally, you need to escape the
3370 backslashes, as illustrated by the following code snippet:
3371
3372 \snippet code/doc_src_qmake-manual.pro 173
3373
3374 \section2 find(variablename, substr)
3375
3376 Returns all the values in \c variablename that match the regular expression
3377 \c substr.
3378
3379 \snippet code/doc_src_qmake-manual.pro 64
3380
3381 MY_VAR2 will contain '-Lone -Ltwo -Lthree -Lfour -Lfive', and MY_VAR3 will
3382 contain 'three two three'.
3383
3384 \section2 files(pattern[, recursive=false])
3385
3386 Expands the specified wildcard pattern and returns a list of filenames.
3387 If \c recursive is true, this function descends into subdirectories.
3388
3389 \section2 first(variablename)
3390
3391 Returns the first value of \c variablename.
3392
3393 For example, the following call returns \c firstname:
3394
3395 \snippet code/doc_src_qmake-manual.pro 161
3396
3397 See also \l{take_first(variablename)}{take_first()},
3398 \l{last(variablename)}{last()}.
3399
3400 \section2 format_number(number[, options...])
3401
3402 Returns \c number in the format specified by \c options. You can specify the
3403 following options:
3404
3405 \list
3406 \li \c ibase=n sets the base of the input to \c n
3407 \li \c obase=n sets the base of the output to \c n
3408 \li \c width=n sets the minimum width of the output to \c n. If the
3409 output is shorter than \c width, it is padded with spaces
3410 \li \c zeropad pads the output with zeroes instead of spaces
3411 \li \c padsign prepends a space to positive values in the output
3412 \li \c alwayssign prepends a plus sign to positive values in the output
3413 \li \c leftalign places the padding to the right of the value in the
3414 output
3415 \endlist
3416
3417 Floating-point numbers are currently not supported.
3418
3419 For example, the following call converts the hexadecimal number \c BAD to
3420 \c 002989:
3421
3422 \snippet code/doc_src_qmake-manual.pro 163
3423
3424 This function was introduced in Qt 5.0.
3425
3426 \section2 fromfile(filename, variablename)
3427
3428 Evaluates \c filename as a qmake project file and returns the value assigned
3429 to \c variablename.
3430
3431 See also \l{infile(filename, var, val)}{infile()}.
3432
3433 \section2 getenv(variablename)
3434
3435 Returns the value of the environment variable \c variablename.
3436 This is mostly equivalent to the \c $$(variablename) syntax.
3437 The \c getenv function, however, supports environment variables with
3438 parentheses in their name.
3439
3440 This function was introduced in Qt 5.12.
3441
3442 \section2 join(variablename, glue, before, after)
3443
3444 Joins the value of \c variablename with \c glue. If this value is
3445 not empty, this function prefixes the value with \c before and suffixes it
3446 with \c after. \c variablename is the only required field, the others default
3447 to empty strings. If you need to encode spaces in \c glue, \c before, or \c
3448 after, you must quote them.
3449
3450 \section2 last(variablename)
3451
3452 Returns the last value of \c variablename.
3453
3454 For example, the following call returns \c phone:
3455
3456 \snippet code/doc_src_qmake-manual.pro 162
3457
3458 See also \l{take_last(variablename)}{take_last()},
3459 \l{first(variablename)}{first()}.
3460
3461 \section2 list(arg1 [, arg2 ..., argn])
3462
3463 Takes an arbitrary number of arguments. It creates a uniquely
3464 named variable that contains a list of the arguments, and returns the name
3465 of that variable. You can use the variable to write a loop as illustrated by
3466 the following code snippet
3467
3468 \snippet code/doc_src_qmake-manual.pro 170
3469
3470 instead of:
3471
3472 \snippet code/doc_src_qmake-manual.pro 171
3473
3474 \section2 lower(arg1 [, arg2 ..., argn])
3475
3476 Takes an arbitrary number of arguments and converts them to lower case.
3477
3478 See also \l{upper(arg1 [, arg2 ..., argn])}{upper()}.
3479
3480 \section2 member(variablename [, start [, end]])
3481
3482 Returns the slice of the list value of \c variablename with the
3483 zero-based element indices between \c start and \c end (inclusive).
3484
3485 If \c start is not given, it defaults to zero. This usage is
3486 equivalent to \c $$first(variablename).
3487
3488 If \c end is not given, it defaults to \c start. This usage represents
3489 simple array indexing, as exactly one element will be returned.
3490
3491 It is also possible to specify start and end in a single argument, with
3492 the numbers separated by two periods.
3493
3494 Negative numbers represent indices starting from the end of the list,
3495 with -1 being the last element.
3496
3497 If either index is out of range, an empty list is returned.
3498
3499 If \c end is smaller than \c start, the elements are returned
3500 in reverse order.
3501
3502 \note The fact that the end index is inclusive and unordered implies
3503 that an empty list will be returned only when an index is invalid
3504 (which is implied by the input variable being empty).
3505
3506 See also \l{str_member(arg [, start [, end]])}{str_member()}.
3507
3508 \section2 num_add(arg1 [, arg2 ..., argn])
3509
3510 Takes an arbitrary number of numeric arguments and adds them up,
3511 returning the sum.
3512
3513 Subtraction is implicitly supported due to the possibility to simply
3514 prepend a minus sign to a numeric value to negate it:
3515
3516 \code
3517 sum = $$num_add($$first, -$$second)
3518 \endcode
3519
3520 If the operand may be already negative, another step is necessary to
3521 normalize the number:
3522
3523 \code
3524 second_neg = -$$second
3525 second_neg ~= s/^--//
3526 sum = $$num_add($$first, $$second_neg)
3527 \endcode
3528
3529 This function was introduced in Qt 5.8.
3530
3531 \section2 prompt(question [, decorate])
3532
3533 Displays the specified \c question, and returns a value read from stdin.
3534
3535 If \c decorate is \e true (the default), the question gets a generic
3536 prefix and suffix identifying it as a prompt.
3537
3538 \section2 quote(string)
3539
3540 Converts a whole \c string into a single entity and returns the result.
3541 This is just a fancy way of enclosing the string into double quotes.
3542
3543 \section2 re_escape(string)
3544
3545 Returns the \c string with every special regular expression character
3546 escaped with a backslash. This function is a wrapper around
3547 QRegularExpression::escape.
3548
3549 \section2 read_registry(tree, key[, flag])
3550
3551 Returns the value of registry key \c key inside the tree \c tree.
3552
3553 Only the trees \c HKEY_CURRENT_USER (\c HKCU) and \c HKEY_LOCAL_MACHINE
3554 (\c HKLM) are supported.
3555
3556 The \c flag may be \c WOW64_32KEY (\c 32) or \c WOW64_64KEY (\c 64).
3557
3558 \note This function is available only on Windows hosts.
3559
3560 This function was introduced in Qt 5.12.1.
3561
3562 \section2 relative_path(filePath[, base])
3563
3564 Returns the path to \c filePath relative to \c base.
3565
3566 If \c base is not specified, it is the current project
3567 directory. If it is relative, it is resolved relative to the
3568 current project directory before use.
3569
3570 If \c filePath is relative, it is first resolved against the base
3571 directory; in that case, this function effectively acts as
3572 $$clean_path().
3573
3574 This function was introduced in Qt 5.0.
3575
3576 See also \l{absolute_path(path[, base])}{absolute_path()},
3577 \l{clean_path(path)}{clean_path()}.
3578
3579 \section2 replace(string, old_string, new_string)
3580
3581 Replaces each instance of \c old_string with \c new_string in the
3582 contents of the variable supplied as \c string. For example, the
3583 code
3584
3585 \snippet qmake/replace.pro 0
3586
3587 prints the message:
3588
3589 \snippet code/doc_src_qmake-manual.pro 70
3590
3591 \section2 resolve_depends(variablename, prefix)
3592
3593 This is an internal function that you will typically not need.
3594
3595 This function was introduced in Qt 5.0.
3596
3597 \section2 reverse(variablename)
3598
3599 Returns the values of \c variablename in reverse order.
3600
3601 This function was introduced in Qt 5.0.
3602
3603 \section2 section(variablename, separator, begin, end)
3604
3605 Returns a section of the value of \c variablename. This function is a
3606 wrapper around QString::section.
3607
3608 For example, the following call outputs \c surname:
3609
3610 \snippet code/doc_src_qmake-manual.pro 167
3611
3612 \section2 shadowed(path)
3613
3614 Maps the path from the project source directory to the build directory.
3615 This function returns \c path for in-source builds. It returns an empty
3616 string if \c path points outside of the source tree.
3617
3618 This function was introduced in Qt 5.0.
3619
3620 \section2 shell_path(path)
3621
3622 Converts all directory separators within \c path to separators that are
3623 compatible with the shell that is used while building the project (that is,
3624 the shell that is invoked by the make tool). For example, slashes are
3625 converted to backslashes when the Windows shell is used.
3626
3627 This function was introduced in Qt 5.0.
3628
3629 See also \l{system_path(path)}{system_path()}.
3630
3631 \section2 shell_quote(arg)
3632
3633 Quotes \c arg for the shell that is used while building the project.
3634
3635 This function was introduced in Qt 5.0.
3636
3637 See also \l{system_quote(arg)}{system_quote()}.
3638
3639 \section2 size(variablename)
3640
3641 Returns the number of values of \c variablename.
3642
3643 See also \l{str_size(arg)}{str_size()}.
3644
3645 \section2 sort_depends(variablename, prefix)
3646
3647 This is an internal function that you will typically not need.
3648
3649 This function was introduced in Qt 5.0.
3650
3651 \section2 sorted(variablename)
3652
3653 Returns the list of values in \c variablename with entries sorted
3654 in ascending ASCII order.
3655
3656 Numerical sorting can be accomplished by zero-padding the values to
3657 a fixed length with the help of the
3658 \l{format_number(number[, options...])}{format_number()} function.
3659
3660 This function was introduced in Qt 5.8.
3661
3662 \section2 split(variablename, separator)
3663
3664 Splits the value of \c variablename into separate values, and returns them
3665 as a list. This function is a wrapper around QString::split.
3666
3667 For example:
3668
3669 \snippet code/doc_src_qmake-manual.pro 168
3670
3671 \section2 sprintf(string, arguments...)
3672
3673 Replaces %1-%9 in \c string with the arguments passed in the comma-separated
3674 list of function \c arguments and returns the processed string.
3675
3676 \section2 str_member(arg [, start [, end]])
3677
3678 This function is identical to \l{member(variablename [, start [, end]])}
3679 {member()}, except that it operates on a string value instead of a list
3680 variable, and consequently the indices refer to character positions.
3681
3682 This function can be used to implement many common string slicing
3683 operations:
3684
3685 \code
3686 # $$left(VAR, len)
3687 left = $$str_member(VAR, 0, $$num_add($$len, -1))
3688
3689 # $$right(VAR, len)
3690 right = $$str_member(VAR, -$$num, -1)
3691
3692 # $$mid(VAR, off, len)
3693 mid = $$str_member(VAR, $$off, $$num_add($$off, $$len, -1))
3694
3695 # $$mid(VAR, off)
3696 mid = $$str_member(VAR, $$off, -1)
3697
3698 # $$reverse(VAR)
3699 reverse = $$str_member(VAR, -1, 0)
3700 \endcode
3701
3702 \note In these implementations, a zero \c len argument needs to be
3703 handled separately.
3704
3705 See also \l{member(variablename [, start [, end]])}{member()},
3706 \l{num_add(arg1 [, arg2 ..., argn])}{num_add()}.
3707
3708 This function was introduced in Qt 5.8.
3709
3710 \section2 str_size(arg)
3711
3712 Returns the number of characters in the argument.
3713
3714 See also \l{size(variablename)}{size()}.
3715
3716 This function was introduced in Qt 5.8.
3717
3718 \section2 system(command[, mode[, stsvar]])
3719
3720 You can use this variant of the \c system function to obtain stdout from the
3721 command and assign it to a variable.
3722
3723 For example:
3724
3725 \snippet code/doc_src_qmake-manual.pro 72
3726
3727 Like \l {cat(filename[, mode])}{$$cat()}, the \a mode argument takes
3728 \c blob, \c lines, \c true, and \c false as value. However, the legacy
3729 word splitting rules (i.e. empty or \c true, and \c false) differ
3730 subtly.
3731
3732 If you pass \c stsvar, the command's exit status will be stored in that
3733 variable. If the command crashes, the status will be -1, otherwise a
3734 non-negative exit code of the command's choosing. Usually, comparing
3735 the status with zero (success) is sufficient.
3736
3737 See also the test variant of \l{system(command)}{system()}.
3738
3739 \section2 system_path(path)
3740
3741 Converts all directory separators within \c path to separators that are
3742 compatible with the shell that is used by the \c{system()} functions to
3743 invoke commands. For example, slashes are converted to backslashes for the
3744 Windows shell.
3745
3746 This function was introduced in Qt 5.0.
3747
3748 See also \l{shell_path(path)}{shell_path()}.
3749
3750 \section2 system_quote(arg)
3751
3752 Quotes \c arg for the shell that is used by the \c{system()}
3753 functions.
3754
3755 This function was introduced in Qt 5.0.
3756
3757 See also \l{shell_quote(arg)}{shell_quote()}.
3758
3759 \section2 take_first(variablename)
3760
3761 Returns the first value of \c variablename and removes it from the
3762 source variable.
3763
3764 This provides convenience for implementing queues, for example.
3765
3766 This function was introduced in Qt 5.8.
3767
3768 See also \l{take_last(variablename)}{take_last()},
3769 \l{first(variablename)}{first()}.
3770
3771 \section2 take_last(variablename)
3772
3773 Returns the last value of \c variablename and removes it from the
3774 source variable.
3775
3776 This provides convenience for implementing stacks, for example.
3777
3778 This function was introduced in Qt 5.8.
3779
3780 See also \l{take_first(variablename)}{take_first()},
3781 \l{last(variablename)}{last()}.
3782
3783 \section2 unique(variablename)
3784
3785 Returns the list of values in \c variablename with duplicate entries removed.
3786 For example:
3787
3788 \snippet code/doc_src_qmake-manual.pro 73
3789
3790 \section2 upper(arg1 [, arg2 ..., argn])
3791
3792 Takes an arbitrary number of arguments and converts them to upper case.
3793
3794 See also \l{lower(arg1 [, arg2 ..., argn])}{lower()}.
3795
3796 \section2 val_escape(variablename)
3797
3798 Escapes the values of \c variablename in a way that enables parsing them as
3799 qmake code.
3800
3801 This function was introduced in Qt 5.0.
3802 */
3803
3804 /*!
3805 \page qmake-test-function-reference.html
3806 \title Test Functions
3807 \previouspage Replace Functions
3808 \keyword qmake Function Reference - Test Functions
3809
3810 Test functions return a boolean value that you can test for in the
3811 conditional parts of scopes. Test functions can be divided into
3812 built-in functions and function libraries.
3813
3814 See also \l{Replace Functions}.
3815
3816 \section1 Built-in Test Functions
3817
3818 Basic test functions are implemented as built-in functions.
3819
3820 \section2 cache(variablename, [set|add|sub] [transient] [super|stash], [source variablename])
3821
3822 This is an internal function that you will typically not need.
3823
3824 This function was introduced in Qt 5.0.
3825
3826 \section2 CONFIG(config)
3827
3828 This function can be used to test for variables placed into the
3829 \l{CONFIG} variable. This is the same as scopes,
3830 but has the added advantage that a second parameter can be passed to test for
3831 the active config. As the order of values is important in \c CONFIG
3832 variables (that is, the last one set will be considered the active config for
3833 mutually exclusive values) a second parameter can be used to specify a set
3834 of values to consider. For example:
3835
3836 \snippet code/doc_src_qmake-manual.pro 60
3837
3838 Because release is considered the active setting (for feature parsing)
3839 it will be the CONFIG used to generate the build file. In the common
3840 case a second parameter is not needed, but for specific mutual
3841 exclusive tests it is invaluable.
3842
3843 \section2 contains(variablename, value)
3844
3845 Succeeds if the variable \c variablename contains the value \c value;
3846 otherwise fails. It is possible to specify a regular expression for
3847 parameter \e value.
3848
3849 You can check the return value of this function using a scope.
3850
3851 For example:
3852
3853 \snippet code/doc_src_qmake-manual.pro 61
3854
3855 The contents of the scope are only processed if the \c drivers
3856 variable contains the value \c network. If this is the case, the
3857 appropriate files are added to the \l{SOURCES} and \l{HEADERS}
3858 variables.
3859
3860 \section2 count(variablename, number)
3861
3862 Succeeds if the variable \c variablename contains a list with the
3863 specified \c number of values; otherwise fails.
3864
3865 This function is used to ensure that declarations inside a scope are
3866 only processed if the variable contains the correct number of values.
3867 For example:
3868
3869 \snippet qmake/functions.pro 2
3870
3871 \section2 debug(level, message)
3872
3873 Checks whether qmake runs at the specified debug level. If yes, it returns
3874 true and prints a debug message.
3875
3876 \section2 defined(name[, type])
3877
3878 Tests whether the function or variable \c name is defined. If \c type is
3879 omitted, checks all functions. To check only variables or particular type of
3880 functions, specify \c type. It can have the following values:
3881
3882 \list
3883 \li \c test only checks test functions
3884 \li \c replace only checks replace functions
3885 \li \c var only checks variables
3886 \endlist
3887
3888 \section2 equals(variablename, value)
3889
3890 Tests whether \c variablename equals the string \c value.
3891
3892 For example:
3893
3894 \snippet code/doc_src_qmake-manual.pro 160
3895
3896 \section2 error(string)
3897
3898 This function never returns a value. qmake displays \c string as an error
3899 message to the user and exits. This function should only be used for
3900 unrecoverable errors.
3901
3902 For example:
3903
3904 \snippet code/doc_src_qmake-manual.pro 62
3905
3906 \section2 eval(string)
3907
3908 Evaluates the contents of the string using
3909 qmake syntax rules and returns true.
3910 Definitions and assignments can be used in the string to modify the
3911 values of existing variables or create new definitions.
3912
3913 For example:
3914 \snippet qmake/functions.pro 4
3915
3916 \note Quotation marks can be used to delimit the string, and
3917 the return value can be discarded if it is not needed.
3918
3919 \section2 exists(filename)
3920
3921 Tests whether a file with the given \c filename exists.
3922 If the file exists, the function succeeds; otherwise it fails.
3923
3924 The \c filename argument may contain wildcards.
3925 In that case, this function succeeds if any file matches.
3926
3927 For example:
3928 \snippet code/doc_src_qmake-manual.pro 63
3929
3930 \note "/" should be used as a directory separator, regardless of the
3931 platform in use.
3932
3933 \section2 export(variablename)
3934
3935 Exports the current value of \c variablename from the local context of a
3936 function to the global context.
3937
3938 \section2 for(iterate, list)
3939
3940 Starts a loop that iterates over all values in \c list, setting \c iterate to each
3941 value in turn. As a convenience, if \c list is 1..10 then iterate will
3942 iterate over the values 1 through 10.
3943
3944 For example:
3945
3946 \snippet code/doc_src_qmake-manual.pro 65
3947
3948 Loops can be interrupted with \c{break()}. The \c{next()} statement skips
3949 the remainder of the loop's body and continues execution with the next
3950 iteration.
3951
3952 \section2 greaterThan(variablename, value)
3953
3954 Tests that the value of \c variablename is greater than \c value. First,
3955 this function attempts a numerical comparison. If at least one of the
3956 operands fails to convert, this function does a string comparison.
3957
3958 For example:
3959
3960 \snippet code/doc_src_qmake-manual.pro 164
3961
3962 It is impossible to compare two numbers as strings directly. As a
3963 workaround, construct temporary values with a non-numeric prefix and compare
3964 these.
3965
3966 For example:
3967
3968 \snippet code/doc_src_qmake-manual.pro 172
3969
3970 See also \l{lessThan(variablename, value)}{lessThan()}.
3971
3972 \section2 if(condition)
3973
3974 Evaluates \c condition. It is used to group boolean expressions.
3975
3976 For example:
3977
3978 \snippet code/doc_src_qmake-manual.pro 166
3979
3980 \section2 include(filename)
3981
3982 Includes the contents of the file specified by \c filename into the
3983 current project at the point where it is included. This function
3984 succeeds if \c filename is included; otherwise it fails. The included
3985 file is processed immediately.
3986
3987 You can check whether the file was included by using this function as
3988 the condition for a scope. For example:
3989
3990 \snippet code/doc_src_qmake-manual.pro 66
3991
3992 \section2 infile(filename, var, val)
3993
3994 Succeeds if the file \c filename (when parsed by qmake itself) contains the
3995 variable \c var with a value of \c val; otherwise fails. If you do not
3996 specify \c val, the function tests whether \c var has been assigned in
3997 the file.
3998
3999 \section2 isActiveConfig
4000
4001 This is an alias for the \c CONFIG function.
4002
4003 \section2 isEmpty(variablename)
4004
4005 Succeeds if the variable \c variablename is empty; otherwise fails.
4006 This is the equivalent of \c{count( variablename, 0 )}.
4007
4008 For example:
4009
4010 \snippet code/doc_src_qmake-manual.pro 67
4011
4012 \section2 isEqual
4013
4014 This is an alias for the \c equals function.
4015
4016 \section2 lessThan(variablename, value)
4017
4018 Tests that the value of \c variablename is less than \c value. Works as
4019 \l{greaterThan(variablename, value)}{greaterThan()}.
4020
4021 For example:
4022
4023 \snippet code/doc_src_qmake-manual.pro 165
4024
4025 \section2 load(feature)
4026
4027 Loads the feature file (\c .prf) specified by \c feature,
4028 unless the feature has already been loaded.
4029
4030 \section2 log(message)
4031
4032 Prints a message on the console. Unlike the \c message function, neither
4033 prepends text nor appends a line break.
4034
4035 This function was introduced in Qt 5.0.
4036
4037 See also \l{message(string)}{message()}.
4038
4039 \section2 message(string)
4040
4041 Always succeeds, and displays \c string as a general message to the user.
4042 Unlike the \c error() function, this function allows processing to continue.
4043
4044 \snippet code/doc_src_qmake-manual.pro 68
4045
4046 The above line causes "This is a message" to be written to the console.
4047 The use of quotation marks is optional, but recommended.
4048
4049 \note By default, messages are written out for each Makefile generated by
4050 qmake for a given project. If you want to ensure that messages only appear
4051 once for each project, test the \c build_pass variable
4052 \l{Scopes}{in conjunction with a scope} to filter out
4053 messages during builds. For example:
4054
4055 \snippet code/doc_src_qmake-manual.pro 69
4056
4057 \section2 mkpath(dirPath)
4058
4059 Creates the directory path \c dirPath. This function is a wrapper around the
4060 QDir::mkpath function.
4061
4062 This function was introduced in Qt 5.0.
4063
4064 \section2 requires(condition)
4065
4066 Evaluates \c condition. If the condition is false, qmake skips this
4067 project (and its \l{SUBDIRS}) when building.
4068
4069 \note You can also use the \l{REQUIRES} variable for this purpose. However, we
4070 recommend using this function, instead.
4071
4072 \section2 system(command)
4073
4074 Executes the given \c command in a secondary shell. Succeeds
4075 if the command returns with a zero exit status; otherwise fails.
4076 You can check the return value of this function using a scope.
4077
4078 For example:
4079
4080 \snippet code/doc_src_qmake-manual.pro 71
4081
4082 See also the replace variant of \l{system(command[, mode[, stsvar]])}
4083 {system()}.
4084
4085 \section2 touch(filename, reference_filename)
4086
4087 Updates the time stamp of \c filename to match the time stamp of
4088 \c reference_filename.
4089
4090 This function was introduced in Qt 5.0.
4091
4092 \section2 unset(variablename)
4093
4094 Removes \c variablename from the current context.
4095
4096 For example:
4097
4098 \snippet code/doc_src_qmake-manual.pro 169
4099
4100 \section2 versionAtLeast(variablename, versionNumber)
4101
4102 Tests that the version number from \c variablename is greater than or equal
4103 to \c versionNumber. The version number is considered to be a sequence of
4104 non-negative decimal numbers delimited by '.'; any non-numerical tail of
4105 the string will be ignored. Comparison is performed segment-wise from left
4106 to right; if one version is a prefix of the other, it is considered smaller.
4107
4108 This function was introduced in Qt 5.10.
4109
4110 \section2 versionAtMost(variablename, versionNumber)
4111
4112 Tests that the version number from \c variablename is less than or equal to
4113 \c versionNumber. Works as
4114 \l{versionAtLeast(variablename, versionNumber)}{versionAtLeast()}.
4115
4116 This function was introduced in Qt 5.10.
4117
4118 \section2 warning(string)
4119
4120 Always succeeds, and displays \c string as a warning message to the user.
4121
4122 \section2 write_file(filename, [variablename, [mode]])
4123
4124 Writes the values of \c variablename to a file with the name \c filename,
4125 each value on a separate line. If \c variablename is not specified, creates
4126 an empty file. If \c mode is \c append and the file already exists, appends
4127 to it instead of replacing it.
4128
4129 This function was introduced in Qt 5.0.
4130
4131 \section1 Test Function Library
4132
4133 Complex test functions are implemented in a library of .prf files.
4134
4135 \section2 packagesExist(packages)
4136
4137 Uses the PKGCONFIG mechanism to determine whether or not the given packages
4138 exist at the time of project parsing.
4139
4140 This can be useful to optionally enable or disable features. For example:
4141
4142 \snippet code/doc_src_qmake-manual.pro 157
4143
4144 And then, in the code:
4145
4146 \snippet code/doc_src_qmake-manual.pro 158
4147
4148 \section2 prepareRecursiveTarget(target)
4149
4150 Facilitates the creation of project-wide targets similar to the \c install
4151 target by preparing a target that iterates through all subdirectories. For
4152 example:
4153
4154 \snippet code/doc_src_qmake-manual.pro 174
4155
4156 Subdirs that have \c have_no_default or \c no_<target>_target specified in
4157 their .CONFIG are excluded from this target:
4158
4159 \snippet code/doc_src_qmake-manual.pro 175
4160
4161 You must add the prepared target manually to \l{QMAKE_EXTRA_TARGETS}:
4162
4163 \snippet code/doc_src_qmake-manual.pro 176
4164
4165 To make the target global, the code above needs to be included into every
4166 subdirs subproject. In addition, to make these targets do anything,
4167 non-subdirs subprojects need to include respective code. The easiest way to
4168 achieve this is creating a custom feature file. For example:
4169
4170 \snippet code/doc_src_qmake-manual.pro 177
4171
4172 The feature file needs to be injected into each subproject, for example by
4173 .qmake.conf:
4174
4175 \snippet code/doc_src_qmake-manual.pro 178
4176
4177 This function was introduced in Qt 5.0.
4178
4179 \section2 qtCompileTest(test)
4180
4181 Builds a test project. If the test passes, true is returned and
4182 \c {config_<test>} is added to the \l{CONFIG} variable. Otherwise, false is
4183 returned.
4184
4185 To make this function available, you need to load the respective feature
4186 file:
4187
4188 \snippet code/doc_src_qmake-manual.pro 179
4189
4190 This also sets the variable QMAKE_CONFIG_TESTS_DIR to the
4191 \c config.tests subdirectory of the project's parent directory.
4192 It is possible to override this value after loading the feature file.
4193
4194 Inside the tests directory, there has to be one subdirectory per test that
4195 contains a simple qmake project. The following code snippet illustrates the
4196 .pro file of the project:
4197
4198 \snippet code/doc_src_qmake-manual.pro 180
4199
4200 The following code snippet illustrates the main .cpp file of the project:
4201
4202 \snippet code/doc_src_qmake-manual.pro 181
4203
4204 The following code snippet shows the invocation of the test:
4205
4206 \snippet code/doc_src_qmake-manual.pro 182
4207
4208 If the test project is built successfully, the test passes.
4209
4210 The test results are automatically cached, which also makes them
4211 available to all subprojects. It is therefore recommended to run
4212 all configuration tests in the top-level project file.
4213
4214 To suppress the re-use of cached results, pass \c{CONFIG+=recheck}
4215 to qmake.
4216
4217 See also \l{load(feature)}{load()}.
4218
4219 This function was introduced in Qt 5.0.
4220
4221 \section2 qtHaveModule(name)
4222
4223 Checks whether the Qt module specified by \c name is present.
4224 For a list of possible values, see \l{Variables#QT}{QT}.
4225
4226 This function was introduced in Qt 5.0.1.
4227 */
4228
4229 /*!
4230 \page qmake-environment-reference.html
4231 \previouspage Using Precompiled Headers
4232 \nextpage Reference
4233
4234 \title Configuring qmake
4235
4236 \section1 Properties
4237
4238 qmake has a system for persistent configuration, which allows you to set a
4239 property in qmake once, and query it each time qmake is invoked. You can set
4240 a property in qmake as follows:
4241
4242 \snippet code/doc_src_qmake-manual.pro 74
4243
4244 The appropriate property and value should be substituted for
4245 \c PROPERTY and \c VALUE.
4246
4247 You can retrieve this information back from qmake as follows:
4248
4249 \snippet code/doc_src_qmake-manual.pro 75
4250
4251 \note \c{qmake -query} lists built-in properties in addition to the
4252 properties that you set with \c{qmake -set PROPERTY VALUE}.
4253
4254 This information will be saved into a QSettings object (meaning it
4255 will be stored in different places for different platforms).
4256
4257 The following list summarizes the \c built-in properties:
4258
4259 \list
4260 \li QMAKE_SPEC - the shortname of the host \c mkspec that is resolved
4261 and stored in the \l{QMAKESPEC} variable during a host build
4262 \li QMAKE_VERSION - the current version of qmake
4263 \li QMAKE_XSPEC - the shortname of the target \c mkspec that is resolved
4264 and stored in the \l{QMAKESPEC} variable during a target build
4265 \li QT_HOST_BINS - location of host executables
4266 \li QT_HOST_DATA - location of data for host executables used by qmake
4267 \li QT_HOST_LIBS - location of host libraries
4268 \li QT_HOST_LIBEXECS - location of executables required by host
4269 libraries at runtime
4270 \li QT_HOST_PREFIX - default prefix for all host paths
4271 \li QT_INSTALL_ARCHDATA - location of general architecture-dependent Qt
4272 data
4273 \li QT_INSTALL_BINS - location of Qt binaries (tools and applications)
4274 \li QT_INSTALL_CONFIGURATION - location for Qt settings. Not applicable
4275 on Windows
4276 \li QT_INSTALL_DATA - location of general architecture-independent Qt
4277 data
4278 \li QT_INSTALL_DOCS - location of documentation
4279 \li QT_INSTALL_EXAMPLES - location of examples
4280 \li QT_INSTALL_HEADERS - location for all header files
4281 \li QT_INSTALL_LIBEXECS - location of executables required by libraries at runtime
4282 \li QT_INSTALL_LIBS - location of libraries
4283 \li QT_INSTALL_PLUGINS - location of Qt plugins
4284 \li QT_INSTALL_PREFIX - default prefix for all paths
4285 \li QT_INSTALL_QML - location of QML 2.x extensions
4286 \li QT_INSTALL_TESTS - location of Qt test cases
4287 \li QT_INSTALL_TRANSLATIONS - location of translation information for
4288 Qt strings
4289 \li QT_SYSROOT - the sysroot used by the target build environment
4290 \li QT_VERSION - the Qt version. We recommend that you query Qt module specific
4291 version numbers by using $$QT.<module>.version variables instead.
4292 \endlist
4293
4294 For example, you can query the installation of Qt for this version of qmake with the
4295 \c QT_INSTALL_PREFIX property:
4296
4297 \snippet code/doc_src_qmake-manual.pro 77
4298
4299 You can query the values of properties in a project file as follows:
4300
4301 \snippet code/doc_src_qmake-manual.pro 78
4302
4303 \section1 QMAKESPEC
4304
4305 qmake requires a platform and compiler
4306 description file which contains many default values used to generate
4307 appropriate Makefiles. The standard Qt distribution comes with many of
4308 these files, located in the \c mkspecs subdirectory of the Qt installation.
4309
4310 The \c QMAKESPEC environment variable can contain any of the following:
4311
4312 \list
4313 \li A complete path to a directory containing a \c{qmake.conf} file.
4314 In this case qmake will open the
4315 \c{qmake.conf} file from within that directory. If the file does not
4316 exist, qmake will exit with an error.
4317 \li The name of a platform-compiler combination. In this case,
4318 qmake will search in the directory specified
4319 by the \c mkspecs subdirectory of the data path specified when Qt was
4320 compiled (see QLibraryInfo::DataPath).
4321 \endlist
4322
4323 \note The \c QMAKESPEC path will be automatically added to the generated
4324 Makefile after the contents of the \l{INCLUDEPATH} system variable.
4325
4326 \section1 Cache File
4327
4328 The cache file is a special file qmake reads to
4329 find settings not specified in the \c qmake.conf file, project files, or
4330 at the command line. When qmake is run, it looks for a file called
4331 \c{.qmake.cache} in parent directories of the current directory, unless you
4332 specify \c -nocache. If qmake
4333 fails to find this file, it will silently ignore this step of processing.
4334
4335 If qmake finds a \c{.qmake.cache} file then it will process this file first before
4336 it processes the project file.
4337
4338 \section1 File Extensions
4339
4340 Under normal circumstances qmake will try to
4341 use appropriate file extensions for your platform. However, it is
4342 sometimes necessary to override the default choices for each platform and
4343 explicitly define file extensions for qmake to
4344 use. This is achieved by redefining certain built-in variables. For
4345 example, the extension used for \l moc files can be redefined with the
4346 following assignment in a project file:
4347
4348 \snippet code/doc_src_qmake-manual.pro 85
4349
4350 The following variables can be used to redefine common file extensions recognized
4351 by qmake:
4352
4353 \list
4354 \li \l{QMAKE_EXT_MOC} modifies the extension placed on included moc files.
4355 \li \l{QMAKE_EXT_UI} modifies the extension used for \QD UI files
4356 (usually in \l{FORMS}).
4357 \li \l{QMAKE_EXT_PRL} modifies the extension placed on
4358 \l{Library Dependencies}{library dependency files}.
4359 \li \l{QMAKE_EXT_LEX} changes the suffix used in Lex files (usually in
4360 \l{LEXSOURCES}).
4361 \li \l{QMAKE_EXT_YACC} changes the suffix used in Yacc files (usually in
4362 \l{YACCSOURCES}).
4363 \li \l{QMAKE_EXT_OBJ} changes the suffix used on generated object files.
4364 \endlist
4365
4366 All of the above accept just the first value, so you must assign to it just one
4367 value that will be used throughout your project file. There are two variables that
4368 accept a list of values:
4369
4370 \list
4371 \li \l{QMAKE_EXT_CPP} causes qmake to interpret
4372 all files with these suffixes as C++ source files.
4373 \li \l{QMAKE_EXT_H} causes qmake to interpret
4374 all files with these suffixes as C and C++ header files.
4375 \endlist
4376 */
4377
4378 /*!
4379 \page qmake-language.html
4380 \title qmake Language
4381 \previouspage Platform Notes
4382 \nextpage Advanced Usage
4383
4384 Many qmake project files simply describe the
4385 sources and header files used by the project, using a list of
4386 \c{name = value} and \c{name += value} definitions.
4387 qmake also provides other operators, functions,
4388 and scopes that can be used to process the information supplied in
4389 variable declarations. These advanced features allow Makefiles to be
4390 generated for multiple platforms from a single project file.
4391
4392 \section1 Operators
4393
4394 In many project files, the assignment (\c{=}) and append (\c{+=}) operators can
4395 be used to include all the information about a project. The typical pattern of
4396 use is to assign a list of values to a variable, and append more values
4397 depending on the result of various tests. Since
4398 qmake defines certain variables using default
4399 values, it is sometimes necessary to use the removal (\c{-=}) operator to
4400 filter out values that are not required. The following sections describe how
4401 to use operators to manipulate the contents of variables.
4402
4403 \section2 Assigning Values
4404
4405 The \c = operator assigns a value to a variable:
4406
4407 \snippet code/doc_src_qmake-manual.pro 89
4408
4409 The above line sets the \l{TARGET} variable to \c myapp. This will overwrite any
4410 values previously set for \c TARGET with \c myapp.
4411
4412 \section2 Appending Values
4413
4414 The \c += operator appends a new value to the list of values in a variable:
4415
4416 \snippet code/doc_src_qmake-manual.pro 90
4417
4418 The above line appends \c USE_MY_STUFF to the list of pre-processor defines to be put
4419 in the generated Makefile.
4420
4421 \section2 Removing Values
4422
4423 The \c -= operator removes a value from the list of values in a variable:
4424
4425 \snippet code/doc_src_qmake-manual.pro 91
4426
4427 The above line removes \c USE_MY_STUFF from the list of pre-processor defines to be
4428 put in the generated Makefile.
4429
4430 \section2 Adding Unique Values
4431
4432 The \c *= operator adds a value to the list of values in a variable, but only
4433 if it is not already present. This prevents values from being included many
4434 times in a variable. For example:
4435
4436 \snippet code/doc_src_qmake-manual.pro 92
4437
4438 In the above line, \c USE_MY_STUFF will only be added to the list of pre-processor
4439 defines if it is not already defined. Note that the \l{unique(variablename)}
4440 {unique()} function can also be used to ensure that a variable only contains one
4441 instance of each value.
4442
4443 \section2 Replacing Values
4444
4445 The \c ~= operator replaces any values that match a regular expression with
4446 the specified value:
4447
4448 \snippet code/doc_src_qmake-manual.pro 93
4449
4450 In the above line, any values in the list that start with \c QT_D or \c QT_T are
4451 replaced with \c QT.
4452
4453 \section2 Variable Expansion
4454
4455 The \c $$ operator is used to extract the contents of a variable, and can be
4456 used to pass values between variables or supply them to functions:
4457
4458 \snippet code/doc_src_qmake-manual.pro 94
4459
4460 Variables can be used to store the contents of environment variables.
4461 These can be evaluated at the time when qmake
4462 is run, or included in the generated Makefile for evaluation when the
4463 project is built.
4464
4465 To obtain the contents of an environment value when
4466 qmake is run, use the \c $$(...) operator:
4467
4468 \snippet qmake/environment.pro 0
4469
4470 In the above assignment, the value of the \c PWD environment variable
4471 is read when the project file is processed.
4472
4473 To obtain the contents of an environment value at the time when the
4474 generated Makefile is processed, use the \c $(...) operator:
4475
4476 \snippet qmake/environment.pro 1
4477
4478 In the above assignment, the value of \c PWD is read immediately
4479 when the project file is processed, but \c $(PWD) is assigned to
4480 \c DESTDIR in the generated Makefile. This makes the build process
4481 more flexible as long as the environment variable is set correctly
4482 when the Makefile is processed.
4483
4484 \section2 Accessing qmake Properties
4485
4486 The special \c $$[...] operator can be used to access qmake properties:
4487
4488 \snippet qmake/qtconfiguration.pro 0
4489
4490 For more information, see \l{Configuring qmake}.
4491
4492 The properties accessible with this operator are typically used to
4493 enable third party plugins and components to be integrated in Qt.
4494 For example, a \QD plugin can be installed alongside \QD's built-in
4495 plugins if the following declaration is made in its project file:
4496
4497 \snippet code/doc_src_qmake-manual.pro 101
4498
4499 \section1 Scopes
4500
4501 Scopes are similar to \c if statements in procedural programming languages.
4502 If a certain condition is true, the declarations inside the scope are processed.
4503
4504 \section2 Scope Syntax
4505
4506 Scopes consist of a condition followed by an opening brace on the same line,
4507 a sequence of commands and definitions, and a closing brace on a new line:
4508
4509 \snippet qmake/scopes.pro syntax
4510
4511 The opening brace \e{must be written on the same line as the condition}.
4512 Scopes may be concatenated to include more than one condition, as described
4513 in the following sections.
4514
4515 \section2 Scopes and Conditions
4516
4517 A scope is written as a condition followed by a series of declarations
4518 contained within a pair of braces. For example:
4519
4520 \snippet qmake/scopes.pro 0
4521
4522 The above code will add the \c paintwidget_win.cpp file to the sources listed
4523 in the generated Makefile when building for a Windows platform. When
4524 building for other platforms, the define will be ignored.
4525
4526 The conditions used in a given scope can also be negated to provide an
4527 alternative set of declarations that will be processed only if the
4528 original condition is false. For example, to process something when building
4529 for all platforms \e except Windows, negate the scope like this:
4530
4531 \snippet qmake/scopes.pro 1
4532
4533 Scopes can be nested to combine more than one condition. For instance, to
4534 include a particular file for a certain platform only if
4535 debugging is enabled, write the following:
4536
4537 \snippet qmake/scopes.pro 2
4538
4539 To save writing many nested scopes, you can nest scopes using the \c :
4540 operator. The nested scopes in the above example can be rewritten in
4541 the following way:
4542
4543 \snippet qmake/scopes.pro 3
4544
4545 You may also use the \c : operator to perform single line conditional
4546 assignments. For example:
4547
4548 \snippet code/doc_src_qmake-manual.pro 95
4549
4550 The above line adds \c USE_MY_STUFF to the \l{DEFINES} variable only when
4551 building for the Windows platform.
4552 Generally, the \c : operator behaves like a logical AND operator, joining
4553 together a number of conditions, and requiring all of them to be true.
4554
4555 There is also the \c | operator to act like a logical OR operator, joining
4556 together a number of conditions, and requiring only one of them to be true.
4557
4558 \snippet qmake/scopes.pro 4
4559
4560 If you need to mix both operators, you can use the \c if function to specify
4561 operator precedence.
4562
4563 \snippet qmake/scopes.pro 5
4564
4565 The condition accepts the wildcard character to match a family of \c{CONFIG}
4566 values or mkspec names.
4567
4568 \snippet qmake/scopes.pro 6
4569
4570 \note Historically, checking the mkspec name with wildcards like above was
4571 qmake's way to check for the platform. Nowadays, we recommend to use values
4572 that are defined by the mkspec in the \c QMAKE_PLATFORM variable.
4573
4574 You can also provide alternative declarations to those within a scope by
4575 using an \c else scope. Each \c else scope is processed if the conditions
4576 for the preceding scopes are false.
4577 This allows you to write complex tests when combined with other scopes
4578 (separated by the \c : operator as above). For example:
4579
4580 \snippet code/doc_src_qmake-manual.pro 96
4581
4582 \section2 Configuration and Scopes
4583
4584 The values stored in the \l{CONFIG} variable are
4585 treated specially by qmake. Each of the possible
4586 values can be used as the condition for a scope. For example, the list of
4587 values held by \c CONFIG can be extended with the \c opengl value:
4588
4589 \snippet qmake/configscopes.pro 0
4590
4591 As a result of this operation, any scopes that test for \c opengl will
4592 be processed. We can use this feature to give the final executable an
4593 appropriate name:
4594
4595 \snippet qmake/configscopes.pro 1
4596 \snippet qmake/configscopes.pro 2
4597 \snippet qmake/configscopes.pro 3
4598
4599 This feature makes it easy to change the configuration for a project
4600 without losing all the custom settings that might be needed for a specific
4601 configuration. In the above code, the declarations in the first scope are
4602 processed, and the final executable will be called \c application-gl.
4603 However, if \c opengl is not specified, the declarations in the second
4604 scope are processed instead, and the final executable will be called
4605 \c application.
4606
4607 Since it is possible to put your own values on the \c CONFIG
4608 line, this provides you with a convenient way to customize project files
4609 and fine-tune the generated Makefiles.
4610
4611 \section2 Platform Scope Values
4612
4613 In addition to the \c win32, \c macx, and \c unix values used in many
4614 scope conditions, various other built-in platform and compiler-specific
4615 values can be tested with scopes. These are based on platform
4616 specifications provided in Qt's \c mkspecs directory. For example, the
4617 following lines from a project file show the current specification in
4618 use and test for the \c linux-g++ specification:
4619
4620 \snippet qmake/specifications.pro 0
4621
4622 You can test for any other platform-compiler combination as long as a
4623 specification exists for it in the \c mkspecs directory.
4624
4625 \section1 Variables
4626
4627 Many of the variables used in project files are special variables that
4628 qmake uses when generating Makefiles, such as \l{DEFINES}, \l{SOURCES}, and
4629 \l{HEADERS}. In addition, you can create variables for your own use. qmake
4630 creates new
4631 variables with a given name when it encounters an assignment to that name.
4632 For example:
4633
4634 \snippet code/doc_src_qmake-manual.pro 97
4635
4636 There are no restricitions on what you do to your own variables, as
4637 qmake will ignore them unless it needs to evaluate them when processing
4638 a scope.
4639
4640 You can also assign the value of a current variable to another
4641 variable by prefixing $$ to the variable name. For example:
4642
4643 \snippet code/doc_src_qmake-manual.pro 98
4644
4645 Now the MY_DEFINES variable contains what is in the DEFINES variable at
4646 this point in the project file. This is also equivalent to:
4647
4648 \snippet code/doc_src_qmake-manual.pro 99
4649
4650 The second notation allows you to append the contents of the variable to
4651 another value without separating the two with a space. For example, the
4652 following will ensure that the final executable will be given a name
4653 that includes the project template being used:
4654
4655 \snippet code/doc_src_qmake-manual.pro 100
4656
4657 \section1 Replace Functions
4658
4659 qmake provides a selection of built-in
4660 functions to allow the contents of variables to be processed. These
4661 functions process the arguments supplied to them and return a value, or
4662 list of values, as a result. To assign a result to a variable, use the \c $$
4663 operator with this type of function as you would to assign contents of one
4664 variable to another:
4665
4666 \snippet qmake/functions.pro 1
4667
4668 This type of function should be used on the right-hand side of
4669 assignments (that is, as an operand).
4670
4671 You can define your own functions for processing the contents of variables
4672 as follows:
4673
4674 \snippet code/doc_src_qmake-manual.pro 102
4675
4676 The following example function takes a variable name as its only
4677 argument, extracts a list of values from the variable with the
4678 \l{eval(string)}{eval()} built-in function, and compiles a list of files:
4679
4680 \snippet qmake/replacefunction.pro 0
4681
4682 \section1 Test Functions
4683
4684 qmake provides built-in functions that can be
4685 used as conditions when writing scopes. These functions do not return a
4686 value, but instead indicate \e success or \e failure:
4687
4688 \snippet qmake/functions.pro 3
4689
4690 This type of function should be used in conditional expressions
4691 only.
4692
4693 It is possible to define your own functions to provide conditions
4694 for scopes. The following example tests whether each file in a list
4695 exists and returns true if they all exist, or false if not:
4696
4697 \snippet qmake/testfunction.pro 0
4698 */
4699
4700 /*!
4701 \page qmake-advanced-usage.html
4702 \title Advanced Usage
4703 \previouspage qmake Language
4704 \nextpage Using Precompiled Headers
4705
4706 \section1 Adding New Configuration Features
4707
4708 qmake lets you create your own \c features that
4709 can be included in project files by adding their names to the list of
4710 values specified by the \l{CONFIG} variable. Features are collections of
4711 custom functions and definitions in \c{.prf} files that can reside in one
4712 of many standard directories. The locations of these directories are
4713 defined in a number of places, and qmake checks
4714 each of them in the following order when it looks for \c{.prf} files:
4715
4716 \omit
4717 TODO: Fix the list, as it is incomplete and partly incorrect.
4718 \endomit
4719
4720 \list 1
4721 \li In a directory listed in the \c QMAKEFEATURES environment variable that
4722 contains a list of directories delimited by the platform's path list separator
4723 (colon for Unix, semicolon for Windows).
4724 \li In a directory listed in the \c QMAKEFEATURES property variable that
4725 contains a list of directories delimited by the platform's path list separator.
4726 \omit
4727 \li In a features directory beneath the project's root directory (where
4728 the \c{.qmake.cache} file is generated).
4729 \endomit
4730 \li In a features directory residing within a \c mkspecs directory.
4731 \c mkspecs directories can be located beneath any of the directories
4732 listed in the \c QMAKEPATH environment variable that contains a
4733 list of directories delimited by the platform's path list separator.
4734 For example:
4735 \c{$QMAKEPATH/mkspecs/<features>}.
4736 \li In a features directory residing beneath the directory provided by the
4737 \l{QMAKESPEC} environment variable. For example: \c{$QMAKESPEC/<features>}.
4738 \li In a features directory residing in the \c data_install/mkspecs directory.
4739 For example: \c{data_install/mkspecs/<features>}.
4740 \li In a features directory that exists as a sibling of the directory
4741 specified by the \c QMAKESPEC environment variable.
4742 For example: \c{$QMAKESPEC/../<features>}.
4743 \endlist
4744
4745 The following features directories are searched for features files:
4746
4747 \list 1
4748 \li \c{features/unix}, \c{features/win32}, or \c{features/macx}, depending on
4749 the platform in use
4750 \li \c features/
4751 \endlist
4752
4753 For example, consider the following assignment in a project file:
4754
4755 \snippet code/doc_src_qmake-manual.pro 103
4756
4757 With this addition to the \c CONFIG variable,
4758 qmake will search the locations listed above for
4759 the \c myfeatures.prf file after it has finished parsing your project file.
4760 On Unix systems, it will look for the following file:
4761
4762 \list 1
4763 \li \c $QMAKEFEATURES/myfeatures.prf (for each directory listed in the
4764 \c QMAKEFEATURES environment variable)
4765 \li \c $$QMAKEFEATURES/myfeatures.prf (for each directory listed in the
4766 \c QMAKEFEATURES property variable)
4767 \li \c myfeatures.prf (in the project's root directory). The project root
4768 is determined by the top-level \c{.pro} file. However, if you place the
4769 \c{.qmake.cache} file in a sub-directory or the directory of a
4770 sub-project, then the project root becomes the sub-directory itself.
4771 \li \c $QMAKEPATH/mkspecs/features/unix/myfeatures.prf and
4772 \c $QMAKEPATH/mkspecs/features/myfeatures.prf (for each directory
4773 listed in the \c QMAKEPATH environment variable)
4774 \li \c $QMAKESPEC/features/unix/myfeatures.prf and
4775 \c $QMAKESPEC/features/myfeatures.prf
4776 \li \c data_install/mkspecs/features/unix/myfeatures.prf and
4777 \c data_install/mkspecs/features/myfeatures.prf
4778 \li \c $QMAKESPEC/../features/unix/myfeatures.prf and
4779 \c $QMAKESPEC/../features/myfeatures.prf
4780 \endlist
4781
4782 \note The \c{.prf} files must have names in lower case.
4783
4784 \section1 Installing Files
4785
4786 It is common on Unix to also use the build tool to install applications
4787 and libraries; for example, by invoking \c{make install}. For this reason,
4788 qmake has the concept of an \c {install set}, an
4789 object which contains instructions about the way a part of a project is to
4790 be installed. For example, a collection of documentation files can be
4791 described in the following way:
4792
4793 \snippet code/doc_src_qmake-manual.pro 79
4794
4795 The \c path member informs qmake that the files
4796 should be installed in \c /usr/local/program/doc (the path member), and the
4797 \c files member specifies the files that should be copied to the
4798 installation directory. In this case, everything in the \c docs directory
4799 will be copied to \c /usr/local/program/doc.
4800
4801 Once an install set has been fully described, you can append it to the
4802 install list with a line like this:
4803
4804 \snippet code/doc_src_qmake-manual.pro 80
4805
4806 qmake will ensure that the specified files are
4807 copied to the installation directory. If you require more control over
4808 this process, you can also provide a definition for the \c extra member of
4809 the object. For example, the following line tells
4810 qmake to execute a series of commands for this
4811 install set:
4812
4813 \snippet code/doc_src_qmake-manual.pro 81
4814
4815 The \c unix \l{Scopes and Conditions}{scope}
4816 ensures that these particular commands are only executed on Unix platforms.
4817 Appropriate commands for other platforms can be defined using other scope
4818 rules.
4819
4820 Commands specified in the \c extra member are executed before the instructions
4821 in the other members of the object are performed.
4822
4823 If you append a built-in install set to the \c INSTALLS variable and do
4824 not specify \c files or \c extra members, qmake
4825 will decide what needs to be copied for you. Currently, the \c target and \c dlltarget
4826 install sets are supported. For example:
4827
4828 \snippet code/doc_src_qmake-manual.pro 82
4829
4830 In the above lines, qmake knows what needs to
4831 be copied, and will handle the installation process automatically.
4832
4833 \section1 Adding Custom Targets
4834
4835 qmake tries to do everything expected of a
4836 cross-platform build tool. This is often less than ideal when you really
4837 need to run special platform-dependent commands. This can be achieved with
4838 specific instructions to the different qmake backends.
4839
4840 Customization of the Makefile output is performed through an object-style
4841 API as found in other places in qmake. Objects are defined automatically by
4842 specifying their \e members. For example:
4843
4844 \snippet code/doc_src_qmake-manual.pro 86
4845
4846 The definitions above define a qmake target called \c mytarget, containing a
4847 Makefile target called \c{.buildfile} which in turn is generated with the
4848 \c touch command. Finally, the
4849 \c{.depends} member specifies that \c mytarget depends on \c mytarget2,
4850 another target that is defined afterwards. \c mytarget2 is a dummy target.
4851 It is only defined to echo some text to the console.
4852
4853 The final step is to use the \c QMAKE_EXTRA_TARGETS variable to instruct
4854 qmake that this object is a target to be built:
4855
4856 \snippet code/doc_src_qmake-manual.pro 87
4857
4858 This is all you need to do to actually build custom targets. Of course,
4859 you may want to tie one of these targets to the
4860 \l{TARGET}{qmake build target}. To do this, you
4861 simply need to include your Makefile target in the list of
4862 \l{PRE_TARGETDEPS}.
4863
4864 Custom target specifications support the following members:
4865
4866 \table
4867 \header
4868 \li Member
4869 \li Description
4870 \row
4871 \li commands
4872 \li The commands for generating the custom build target.
4873 \row
4874 \li CONFIG
4875 \li Specific configuration options for the custom build target. Can be
4876 set to \c recursive to indicate that rules should be created in the
4877 Makefile to call the relevant target inside the sub-target specific
4878 Makefile. This member defaults to creating an entry for each of the
4879 sub-targets.
4880 \row
4881 \li depends
4882 \li The existing build targets that the custom build target depends on.
4883 \row
4884 \li recurse
4885 \li Specifies which sub-targets should be used when creating the rules
4886 in the Makefile to call in the sub-target specific Makefile. This
4887 member is used only when \c recursive is set in \c CONFIG. Typical
4888 values are "Debug" and "Release".
4889 \row
4890 \li recurse_target
4891 \li Specifies the target that should be built via the sub-target
4892 Makefile for the rule in the Makefile. This member adds something
4893 like \c {$(MAKE) -f Makefile.[subtarget] [recurse_target]}. This
4894 member is used only when \c recursive is set in \c CONFIG.
4895 \row
4896 \li target
4897 \li The name of the custom build target.
4898 \endtable
4899
4900 \section1 Adding Compilers
4901
4902 It is possible to customize qmake to support new compilers and
4903 preprocessors:
4904
4905 \snippet code/doc_src_qmake-manual.pro 88
4906
4907 With the above definitions, you can use a drop-in replacement for moc if one
4908 is available. The command is executed on all arguments given to the
4909 \c NEW_HEADERS variable (from the \c input member), and the result is written
4910 to the file defined by the \c output member. This file is added to the
4911 other source files in the project. Additionally, qmake will execute
4912 \c depend_command to generate dependency information, and place this
4913 information in the project as well.
4914
4915 Custom compiler specifications support the following members:
4916
4917 \table
4918 \header
4919 \li Member
4920 \li Description
4921 \row
4922 \li commands
4923 \li The commands used for for generating the output from the input.
4924 \row
4925 \li CONFIG
4926 \li Specific configuration options for the custom compiler. See the
4927 CONFIG table for details.
4928 \row
4929 \li depend_command
4930 \li Specifies a command used to generate the list of dependencies for
4931 the output.
4932 \row
4933 \li dependency_type
4934 \li Specifies the type of file the output is. If it is a known type
4935 (such as TYPE_C, TYPE_UI, TYPE_QRC), it is handled as one of those
4936 type of files.
4937 \row
4938 \li depends
4939 \li Specifies the dependencies of the output file.
4940 \row
4941 \li input
4942 \li The variable that specifies the files that should be processed with
4943 the custom compiler.
4944 \row
4945 \li name
4946 \li A description of what the custom compiler is doing. This is only
4947 used in some backends.
4948 \row
4949 \li output
4950 \li The filename that is created from the custom compiler.
4951 \row
4952 \li output_function
4953 \li Specifies a custom qmake function that is used to specify the
4954 filename to be created.
4955 \row
4956 \li variables
4957 \li Indicates that the variables specified here are replaced with
4958 $(QMAKE_COMP_VARNAME) when referred to in the pro file as
4959 $(VARNAME).
4960 \row
4961 \li variable_out
4962 \li The variable that the files created from the output should be added
4963 to.
4964 \endtable
4965
4966 The CONFIG member supports the following options:
4967
4968 \table
4969 \header
4970 \li Option
4971 \li Description
4972 \row
4973 \li combine
4974 \li Indicates that all of the input files are combined into a single
4975 output file.
4976 \row
4977 \li target_predeps
4978 \li Indicates that the output should be added to the list of
4979 \l{PRE_TARGETDEPS}.
4980 \row
4981 \li explicit_dependencies
4982 \li The dependencies for the output only get generated from the depends
4983 member and from nowhere else.
4984 \row
4985 \li dep_existing_only
4986 \li Every dependency that is a result of .depend_command is checked for
4987 existence. Non-existing dependencies are ignored.
4988 This value was introduced in Qt 5.13.2.
4989 \row
4990 \li dep_lines
4991 \li The output from the .depend_command is interpreted to be one file
4992 per line. The default is to split on whitespace and is maintained
4993 only for backwards compatibility reasons.
4994 \row
4995 \li no_link
4996 \li Indicates that the output should not be added to the list of objects
4997 to be linked in.
4998 \endtable
4999
5000 \section1 Library Dependencies
5001
5002 Often when linking against a library, qmake
5003 relies on the underlying platform to know what other libraries this
5004 library links against, and lets the platform pull them in. In many cases,
5005 however, this is not sufficient. For example, when statically linking a
5006 library, no other libraries are linked to, and therefore no dependencies
5007 to those libraries are created. However, an application that later links
5008 against this library will need to know where to find the symbols that
5009 the static library will require. qmake attempts to keep track of the
5010 dependencies of a library, where appropriate, if you explicitly enable
5011 tracking.
5012
5013 The first step is to enable dependency tracking in the library itself.
5014 To do this you must tell qmake to save information about the library:
5015
5016 \snippet code/doc_src_qmake-manual.pro 83
5017
5018 This is only relevant to the \c lib template, and will be ignored for all
5019 others. When this option is enabled, qmake will create a file ending in .prl
5020 which will save some meta-information about the library. This metafile is
5021 just like an ordinary project file, but only contains internal variable
5022 declarations. When installing this library, by specifying it as a target in
5023 an \l{INSTALLS} declaration, qmake will automatically copy the .prl file to
5024 the installation path.
5025
5026 The second step in this process is to enable reading of this meta
5027 information in the applications that use the static library:
5028
5029 \snippet code/doc_src_qmake-manual.pro 84
5030
5031 When this is enabled, qmake will process all
5032 libraries linked to by the application and find their meta-information.
5033 qmake will use this to determine the relevant
5034 linking information, specifically adding values to the application project
5035 file's list of \l{DEFINES} as well as \l{LIBS}. Once
5036 qmake has processed this file, it will then
5037 look through the newly introduced libraries in the \c LIBS variable, and
5038 find their dependent .prl files, continuing until all libraries have been
5039 resolved. At this point, the Makefile is created as usual, and the
5040 libraries are linked explicitly against the application.
5041
5042 The .prl files should be created by qmake only, and should not be
5043 transferred between operating systems, as they may contain
5044 platform-dependent information.
5045 */
5046
5047 /*!
5048 \page qmake-precompiledheaders.html
5049 \title Using Precompiled Headers
5050 \previouspage Advanced Usage
5051 \nextpage Configuring qmake
5052
5053
5054 Precompiled headers (PCH) are a performance feature supported by some
5055 compilers to compile a stable body of code, and store the compiled
5056 state of the code in a binary file. During subsequent compilations,
5057 the compiler will load the stored state, and continue compiling the
5058 specified file. Each subsequent compilation is faster because the
5059 stable code does not need to be recompiled.
5060
5061 qmake supports the use of precompiled headers
5062 on some platforms and build environments, including:
5063 \list
5064 \li Windows
5065 \list
5066 \li nmake
5067 \li Visual Studio projects (VS 2008 and later)
5068 \endlist
5069 \li \macos, iOS, tvOS, and watchOS
5070 \list
5071 \li Makefile
5072 \li Xcode
5073 \endlist
5074 \li Unix
5075 \list
5076 \li GCC 3.4 and above
5077 \li clang
5078 \endlist
5079 \endlist
5080
5081 \section1 Adding Precompiled Headers to Your Project
5082
5083 The precompiled header must contain code which is \e stable
5084 and \e static throughout your project. A typical precompiled header might
5085 look like this:
5086
5087 \snippet code/doc_src_qmake-manual.cpp 104
5088
5089 \note A precompiled header file needs to separate C includes from
5090 C++ includes, since the precompiled header file for C files may not
5091 contain C++ code.
5092
5093 \section2 Project Options
5094
5095 To make your project use precompiled headers, you only need to define the
5096 \l{PRECOMPILED_HEADER} variable in your project file:
5097
5098 \snippet code/doc_src_qmake-manual.pro 105
5099
5100 qmake will handle the rest, to ensure the
5101 creation and use of the precompiled header file. You do not need to
5102 include the precompiled header file in \c HEADERS, as
5103 qmake will do this if the configuration supports precompiled headers.
5104
5105 The MSVC and g++ specs targeting Windows enable \c precompile_header
5106 by default.
5107
5108 Using this option, you may trigger
5109 conditional blocks in your project file to add settings when using
5110 precompiled headers.
5111 For example:
5112
5113 \snippet code/doc_src_qmake-manual.pro 106
5114
5115 To use the precompiled header also for C files on MSVC nmake target, add
5116 \c precompile_header_c to the \l{CONFIG} variable. If the header is
5117 used also for C++ and it contains C++ keywords/includes, enclose them
5118 with \c{#ifdef __cplusplus}).
5119
5120 \section1 Notes on Possible Issues
5121
5122 On some platforms, the file name suffix for precompiled header files is
5123 the same as that for other object files. For example, the following
5124 declarations may cause two different object files with the same name to
5125 be generated:
5126
5127 \snippet code/doc_src_qmake-manual.pro 107
5128
5129 To avoid potential conflicts like these, give distinctive names to header
5130 files that will be precompiled.
5131
5132 \section1 Example Project
5133
5134 You can find the following source code in the
5135 \c{examples/qmake/precompile} directory in the Qt distribution:
5136
5137 \section2 \c mydialog.ui
5138
5139 The following image displays the mydialog.ui file in Qt Creator Design mode.
5140 You can view the code in the Edit mode.
5141
5142 \image qmake-precompile-ui.png {Screenshot of the dialog in design mode}
5143
5144 \section2 \c stable.h
5145
5146 \snippet qmake/precompile-stable.h 0
5147
5148 \omit
5149 ##Keeping the snippet in qtdoc is a workaround, because it contains code
5150 that would tell qdoc to start a new page. Remove it and put the
5151 following snippet back after modularizing the docs.
5152 \snippet examples/qmake/precompile/stable.h 0
5153 \endomit
5154
5155 \section2 \c myobject.h
5156
5157 \code
5158 #include <QObject>
5159
5160 class MyObject : public QObject
5161 {
5162 public:
5163 MyObject();
5164 ~MyObject();
5165 };
5166 \endcode
5167
5168 \omit
5169 ##Remove the code and put the snippets back after modularizing the docs.
5170 \snippet examples/qmake/precompile/myobject.h 0
5171 \endomit
5172
5173 \section2 \c myobject.cpp
5174
5175 \code
5176 #include <iostream>
5177 #include <QDebug>
5178 #include <QObject>
5179 #include "myobject.h"
5180
5181 MyObject::MyObject()
5182 : QObject()
5183 {
5184 std::cout << "MyObject::MyObject()\n";
5185 }
5186 \endcode
5187
5188 \omit
5189 \snippet examples/qmake/precompile/myobject.cpp 0
5190 \endomit
5191
5192 \section2 \c util.cpp
5193
5194 \code
5195 void util_function_does_nothing()
5196 {
5197 // Nothing here...
5198 int x = 0;
5199 ++x;
5200 }
5201 \endcode
5202
5203 \omit
5204 \snippet examples/qmake/precompile/util.cpp 0
5205 \endomit
5206
5207 \section2 \c main.cpp
5208
5209 \code
5210 #include <QApplication>
5211 #include <QPushButton>
5212 #include <QLabel>
5213 #include "myobject.h"
5214 #include "mydialog.h"
5215
5216 int main(int argc, char **argv)
5217 {
5218 QApplication app(argc, argv);
5219
5220 MyObject obj;
5221 MyDialog dialog;
5222
5223 dialog.connect(dialog.aButton, SIGNAL(clicked()), SLOT(close()));
5224 dialog.show();
5225
5226 return app.exec();
5227 }
5228 \endcode
5229
5230 \omit
5231 \snippet examples/qmake/precompile/main.cpp 0
5232 \endomit
5233
5234 \section2 \c precompile.pro
5235
5236 \code
5237 TEMPLATE = app
5238 LANGUAGE = C++
5239 CONFIG += cmdline precompile_header
5240
5241 # Use Precompiled headers (PCH)
5242 PRECOMPILED_HEADER = stable.h
5243
5244 HEADERS = stable.h \
5245 mydialog.h \
5246 myobject.h
5247 SOURCES = main.cpp \
5248 mydialog.cpp \
5249 myobject.cpp \
5250 util.cpp
5251 FORMS = mydialog.ui
5252 \endcode
5253
5254 \omit
5255 \snippet examples/qmake/precompile/precompile.pro 0
5256 \endomit
5257 */
5258
5259 /*!
5260 \keyword qmake-getting-started
5261 \page qmake-tutorial.html
5262 \title Getting Started with qmake
5263 \previouspage Overview
5264 \nextpage Creating Project Files
5265
5266 This tutorial teaches you the basics of qmake. The other topics in this
5267 manual contain more detailed information about using qmake.
5268
5269 \section1 Starting Off Simple
5270
5271 Let's assume that you have just finished a basic implementation of
5272 your application, and you have created the following files:
5273
5274 \list
5275 \li hello.cpp
5276 \li hello.h
5277 \li main.cpp
5278 \endlist
5279
5280 You will find these files in the \c{examples/qmake/tutorial} directory
5281 of the Qt distribution. The only other thing you know about the setup of
5282 the application is that it's written in Qt. First, using your favorite
5283 plain text editor, create a file called \c hello.pro in
5284 \c{examples/qmake/tutorial}. The first thing you need to do is add the
5285 lines that tell qmake about the source and
5286 header files that are part of your development project.
5287
5288 We'll add the source files to the project file first. To do this you
5289 need to use the \l{SOURCES} variable.
5290 Just start a new line with \c {SOURCES +=} and put hello.cpp after it.
5291 You should have something like this:
5292
5293 \snippet code/doc_src_qmake-manual.pro 108
5294
5295 We repeat this for each source file in the project, until we end up
5296 with the following:
5297
5298 \snippet code/doc_src_qmake-manual.pro 109
5299
5300 If you prefer to use a Make-like syntax, with all the files listed in
5301 one go you can use the newline escaping like this:
5302
5303 \snippet code/doc_src_qmake-manual.pro 110
5304
5305 Now that the source files are listed in the project file, the header
5306 files must be added. These are added in exactly the same way as source
5307 files, except that the variable name we use is \l{HEADERS}.
5308
5309 Once you have done this, your project file should look something like
5310 this:
5311
5312 \snippet code/doc_src_qmake-manual.pro 111
5313
5314 The target name is set automatically. It is the same as the project
5315 filename, but with the suffix appropriate for the platform. For example, if
5316 the project file is called \c hello.pro, the target will be \c hello.exe
5317 on Windows and \c hello on Unix. If you want to use a different name
5318 you can set it in the project file:
5319
5320 \snippet code/doc_src_qmake-manual.pro 112
5321
5322 The finished project file should look like this:
5323
5324 \snippet code/doc_src_qmake-manual.pro 113
5325
5326 You can now use qmake to generate a Makefile
5327 for your application. On the command line, in your project directory,
5328 type the following:
5329
5330 \snippet code/doc_src_qmake-manual.pro 114
5331
5332 \note If you installed Qt via a package manager, the binary
5333 may be \c{qmake6}.
5334
5335 Then type \c make or \c nmake depending on the compiler you use.
5336
5337 For Visual Studio users, qmake can also generate Visual Studio project
5338 files. For example:
5339
5340 \snippet code/doc_src_qmake-manual.pro 115
5341
5342 \section1 Making an Application Debuggable
5343
5344 The release version of an application does not contain any debugging
5345 symbols or other debugging information. During development, it is useful
5346 to produce a debugging version of the application that has the
5347 relevant information. This is easily achieved by adding \c debug to the
5348 \l{CONFIG} variable in the project file.
5349
5350 For example:
5351
5352 \snippet code/doc_src_qmake-manual.pro 116
5353
5354 Use qmake as before to generate a Makefile. You will now obtain useful
5355 information about your application when running it in a debugging
5356 environment.
5357
5358 \section1 Adding Platform-Specific Source Files
5359
5360 After a few hours of coding, you might have made a start on the
5361 platform-specific part of your application, and decided to keep the
5362 platform-dependent code separate. So you now have two new files to
5363 include into your project file: \c hellowin.cpp and \c
5364 hellounix.cpp. We cannot just add these to the \c SOURCES
5365 variable since that would place both files in the Makefile. So, what we
5366 need to do here is to use a scope which will be processed depending on
5367 which platform we are building for.
5368
5369 A simple scope that adds the platform-dependent file for
5370 Windows looks like this:
5371
5372 \snippet code/doc_src_qmake-manual.pro 117
5373
5374 When building for Windows, qmake adds \c hellowin.cpp to the list of source
5375 files. When building for any other platform, qmake simply ignores it. Now
5376 all that is left to be done is to create a scope for the Unix-specific file.
5377
5378 When you have done that, your project file should look
5379 something like this:
5380
5381 \snippet code/doc_src_qmake-manual.pro 118
5382
5383 Use qmake as before to generate a Makefile.
5384
5385 \section1 Stopping qmake If a File Does Not Exist
5386
5387 You may not want to create a Makefile if a certain file does not exist.
5388 We can check if a file exists by using the \l{exists(filename)}{exists()}
5389 function. We can stop qmake from processing by using the \l{error(string)}
5390 {error()} function. This works in the same way as scopes do. Simply replace
5391 the scope condition with the function. A check for a file called main.cpp looks
5392 like this:
5393
5394 \snippet code/doc_src_qmake-manual.pro 119
5395
5396 The \c{!} symbol is used to negate the test. That is, \c{exists( main.cpp )}
5397 is true if the file exists, and \c{!exists( main.cpp )} is true if the
5398 file does not exist.
5399
5400 \snippet code/doc_src_qmake-manual.pro 120
5401
5402 Use qmake as before to generate a makefile.
5403 If you rename \c main.cpp temporarily, you will see the message and
5404 qmake will stop processing.
5405
5406 \section1 Checking for More than One Condition
5407
5408 Suppose you use Windows and you want to be able to see statement
5409 output with \c {qDebug()} when you run your application on the command line.
5410 To see the output, you must build your application with the appropriate
5411 console setting. We can easily put \c console on the \c CONFIG
5412 line to include this setting in the Makefile on Windows. However,
5413 let's say that we only want to add the \c CONFIG line when we are running
5414 on Windows \e and when \c debug is already on the \c CONFIG line.
5415 This requires using two nested scopes. First create one scope, then create
5416 the other inside it. Put the settings to be processed inside the second
5417 scope, like this:
5418
5419 \snippet code/doc_src_qmake-manual.pro 121
5420
5421 Nested scopes can be joined together using colons, so the final
5422 project file looks like this:
5423
5424 \snippet code/doc_src_qmake-manual.pro 122
5425
5426 That's it! You have now completed the tutorial for
5427 qmake, and are ready to write project files for
5428 your development projects.
5429 */
5430
5431 /*!
5432 \page qmake-common-projects.html
5433 \title Building Common Project Types
5434 \previouspage Creating Project Files
5435 \nextpage Running qmake
5436
5437 This chapter describes how to set up qmake project files for three common
5438 project types that are based on Qt: application, library, and plugin.
5439 Although all project types use many of the same variables, each of
5440 them uses project-specific variables to customize output files.
5441
5442 Platform-specific variables are not described here. For more information,
5443 see \l{Qt for Windows - Deployment} and \l{Qt for macOS}.
5444
5445 \section1 Building an Application
5446
5447 The \c app template tells qmake to generate a
5448 Makefile that will build an application. With this template, the type of
5449 application can be specified by adding one of the following options to the
5450 \l{CONFIG} variable definition:
5451
5452 \table
5453 \header \li Option \li Description
5454 \row \li windows \li The application is a Windows GUI application.
5455 \row \li console \li \c app template only: the application is a Windows console
5456 application.
5457 \row \li testcase \li The application is \l{Building a Testcase}{an automated test}.
5458 \endtable
5459
5460 When using this template, the following qmake
5461 system variables are recognized. You should use these in your .pro file to
5462 specify information about your application. For additional
5463 platform-dependent system variables, you could have a look at the
5464 \l{Platform Notes}.
5465
5466 \list
5467 \li \l{HEADERS} - A list of header files for the application.
5468 \li \l{SOURCES} - A list of C++ source files for the application.
5469 \li \l{FORMS} - A list of UI files for the application (created using
5470 \QD).
5471 \li \l{LEXSOURCES} - A list of Lex source files for the application.
5472 \li \l{YACCSOURCES} - A list of Yacc source files for the
5473 application.
5474 \li \l{TARGET} - Name of the executable for the application. This defaults
5475 to the name of the project file. (The extension, if any, is added
5476 automatically).
5477 \li \l{DESTDIR} - The directory in which the target executable is placed.
5478 \li \l{DEFINES} - A list of any additional pre-processor defines needed for
5479 the application.
5480 \li \l{INCLUDEPATH} - A list of any additional include paths needed for the
5481 application.
5482 \li \l{DEPENDPATH} - The dependency search path for the application.
5483 \li \l{VPATH} - The search path to find supplied files.
5484 \li \l{DEF_FILE} - Windows only: A .def file to be linked against for the
5485 application.
5486 \endlist
5487
5488 You only need to use the system variables that you have values for. For
5489 example, if you do not have any extra INCLUDEPATHs then you do not need
5490 to specify any. qmake will add the necessary default values.
5491 An example project file might look like this:
5492
5493 \snippet code/doc_src_qmake-manual.pro 123
5494
5495 For items that are single valued, such as the template or the destination
5496 directory, we use "="; but for multi-valued items we use "+=" to \e
5497 add to the existing items of that type. Using "=" replaces the variable
5498 value with the new value. For example, if we write \c{DEFINES=USE_MY_STUFF},
5499 all other definitions are deleted.
5500
5501 \section1 Building a Testcase
5502
5503 A testcase project is an \c app project intended to be run as an automated
5504 test. Any \c app may be marked as a testcase by adding the value \c testcase
5505 to the \c CONFIG variable.
5506
5507 For testcase projects, qmake will insert a \c check
5508 target into the generated Makefile. This target will run the application.
5509 The test is considered to pass if it terminates with an exit code equal to zero.
5510
5511 The \c check target automatically recurses through
5512 \l{SUBDIRS} projects. This means it is
5513 possible to issue a \c{make check} command from within a SUBDIRS project
5514 to run an entire test suite.
5515
5516 The execution of the \c check target may be customized by certain Makefile
5517 variables. These variables are:
5518
5519 \table
5520 \header
5521 \li Variable
5522 \li Description
5523 \row
5524 \li TESTRUNNER
5525 \li A command or shell fragment prepended to each test command. An example
5526 use-case is a "timeout" script which will terminate a test if it does not
5527 complete within a specified time.
5528 \row
5529 \li TESTARGS
5530 \li Additional arguments appended to each test command. For example, it may
5531 be useful to pass additional arguments to set the output file and format
5532 from the test (such as the \c{-o filename,format} option supported by
5533 \l{QTestLib}).
5534 \endtable
5535
5536 \note The variables must be set while invoking the \c make tool, not in the
5537 .pro file. Most \c make tools support the setting of Makefile variables directly
5538 on the command-line:
5539
5540 \code
5541 # Run tests through test-wrapper and use JUnit XML output format.
5542 # In this example, test-wrapper is a fictional wrapper script which terminates
5543 # a test if it does not complete within the amount of seconds set by "--timeout".
5544 # The "-o result.xml,junitxml" options are interpreted by QTestLib.
5545 make check TESTRUNNER="test-wrapper --timeout 120" TESTARGS="-o result.xml,junitxml"
5546 \endcode
5547
5548 Testcase projects may be further customized with the following \c CONFIG options:
5549
5550 \table
5551 \header
5552 \li Option
5553 \li Description
5554 \row
5555 \li insignificant_test
5556 \li The exit code of the test will be ignored during \c{make check}.
5557 \endtable
5558
5559 Test cases will often be written with \l{QTest} or \c{TestCase}, but
5560 it is not a requirement to make use of \c{CONFIG+=testcase} and \c{make check}.
5561 The only primary requirement is that the test program exit with a zero exit code
5562 on success, and a non-zero exit code on failure.
5563
5564 \section1 Building a Library
5565
5566 The \c lib template tells qmake to generate a Makefile that will build a
5567 library. When using this template, the \l{VERSION} variable is supported,
5568 in addition to the system variables that the \c app template supports. Use
5569 the variables in your .pro file to specify information about the library.
5570
5571 When using the \c lib template, the following options can be added to the
5572 \l{CONFIG} variable to determine the type of library that is built:
5573
5574 \table
5575 \header \li Option \li Description
5576 \row \li dll \li The library is a shared library (dll).
5577 \row \li staticlib \li The library is a static library.
5578 \row \li plugin \li The library is a plugin.
5579 \endtable
5580
5581 The following option can also be defined to provide additional information about
5582 the library.
5583
5584 \list
5585 \li VERSION - The version number of the target library. For example, 2.3.1.
5586 \endlist
5587
5588 The target file name for the library is platform-dependent. For example, on
5589 X11, \macos, and iOS, the library name will be prefixed by \c lib. On Windows,
5590 no prefix is added to the file name.
5591
5592 \section1 Building a Plugin
5593
5594 Plugins are built using the \c lib template, as described in the previous
5595 section. This tells qmake to generate a
5596 Makefile for the project that will build a plugin in a suitable form for
5597 each platform, usually in the form of a library. As with ordinary
5598 libraries, the \l{VERSION} variable is used to specify information about the
5599 plugin.
5600
5601 \list
5602 \li VERSION - The version number of the target library. For example, 2.3.1.
5603 \endlist
5604
5605 \section2 Building a Qt Widgets Designer Plugin
5606
5607 \QD plugins are built using a specific set of configuration settings that
5608 depend on the way Qt was configured for your system. For convenience, these
5609 settings can be enabled by adding \c designer to the \l{Variables#QT}{QT}
5610 variable. For example:
5611
5612 \code
5613 QT += widgets designer
5614 \endcode
5615
5616 See the \l{Qt Widgets Designer Examples} for more examples of plugin-based
5617 projects.
5618
5619 \section1 Building and Installing in Debug and Release Modes
5620
5621 Sometimes, it is necessary to build a project in both debug and release
5622 modes. Although the \l{CONFIG} variable can hold both \c debug and \c release
5623 options, only the option that is specified last is applied.
5624
5625 \section2 Building in Both Modes
5626
5627 To enable a project to be built in both modes, you must add the
5628 \c debug_and_release option to the \c CONFIG variable:
5629
5630 \snippet qmake/debug_and_release.pro 0
5631 \snippet qmake/debug_and_release.pro 1
5632
5633 The scope in the above snippet modifies the build target in each mode to
5634 ensure that the resulting targets have different names. Providing different
5635 names for targets ensures that one will not overwrite the other.
5636
5637 When qmake processes the project file, it will
5638 generate a Makefile rule to allow the project to be built in both modes.
5639 This can be invoked in the following way:
5640
5641 \snippet code/doc_src_qmake-manual.pro 124
5642
5643 The \c build_all option can be added to the \c CONFIG variable in the
5644 project file to ensure that the project is built in both modes by default:
5645
5646 \snippet qmake/debug_and_release.pro 2
5647
5648 This allows the Makefile to be processed using the default rule:
5649
5650 \snippet code/doc_src_qmake-manual.pro 125
5651
5652 \section2 Installing in Both Modes
5653
5654 The \c build_all option also ensures that both versions of the target
5655 will be installed when the installation rule is invoked:
5656
5657 \snippet code/doc_src_qmake-manual.pro 126
5658
5659 It is possible to customize the names of the build targets depending on
5660 the target platform. For example, a library or plugin may be named using a
5661 different convention on Windows from the one used on Unix platforms:
5662
5663 \omit
5664 Note: This was originally used in the customwidgetplugin.pro file, but is
5665 no longer needed there.
5666 \endomit
5667 \snippet code/doc_src_qmake-manual.pro 127
5668
5669 The default behavior in the above snippet is to modify the name used for
5670 the build target when building in debug mode. An \c else clause could be
5671 added to the scope to do the same for release mode. Left as it is, the
5672 target name remains unmodified.
5673 */
5674
5675 /*!
5676 \page qmake-third-party-libraries.html
5677 \title Using Third-Party Libraries
5678 \brief A guide to using third party libraries with Qt and qmake
5679
5680 qmake allows you to use third-party libraries with Qt. Suppose you know
5681 of a cross-platform library that accepts audio samples of a cat's meows and
5682 translates them into English words. This library is named \c CatWhisperer,
5683 and has several files that it provides as part of its library.
5684 Your project, \c MyQtApp, stores these files in a folder named \c 3rdparty:
5685
5686 \list
5687 \li MyQtApp/
5688 \list
5689 \li MyQtApp.pro
5690 \li src/
5691 \list
5692 \li main.cpp
5693 \endlist
5694 \li 3rdparty/
5695 \list
5696 \li CatWhisperer
5697 \list
5698 \li include/
5699 \list
5700 \li CatWhisperer.h
5701 \endlist
5702 \li lib/
5703 \list
5704 \li libCatWhisperer.so
5705 \li CatWhisperer.lib
5706 \endlist
5707 \li bin/
5708 \list
5709 \li CatWhisperer.dll
5710 \endlist
5711 \endlist
5712 \endlist
5713 \endlist
5714 \endlist
5715
5716 To use the \c CatWhisperer library in \c MyQtApp, \c qmake requires the
5717 location and names of the \c CatWhisperer libraries.
5718 Optionally, you can also:
5719
5720 \list
5721 \li Provide the location of the \c CatWhisperer source code so that you
5722 don't have to type out the full path to each file when you include them
5723 in your own code.
5724 \li Choose the destination in which the \c MyQtApp executable will be
5725 created.
5726 \endlist
5727
5728 The information above is provided in the \c .pro file, so that \c qmake can
5729 parse it and produce makefiles. Makefiles contain all the information
5730 needed by your compiler and linker to produce output, whether it is an
5731 executable, another library file, etc. The next sections explain the syntax
5732 with which \c qmake expects you to provide this information.
5733
5734 \section1 Source Code
5735
5736 To be able to write
5737
5738 \code
5739 #include <CatWhisperer.h>
5740 \endcode
5741
5742 instead of
5743
5744 \code
5745 #include <3rdparty/CatWhisperer/include/CatWhisperer.h>
5746 \endcode
5747
5748 you can provide the path to the \c CatWhisperer \c include directory,
5749 using the \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} variable:
5750
5751 \code
5752 INCLUDEPATH += 3rdparty/CatWhisperer/include
5753 \endcode
5754
5755 \section1 Library Files
5756
5757 To let \c qmake know where to find the \c CatWhisperer library files,
5758 use the \l{qmake Variable Reference#LIBS}{LIBS} variable:
5759
5760 \code
5761 LIBS += -L"3rdparty/CatWhisperer/lib" -lCatWhisperer
5762 \endcode
5763
5764 The first part of the expression lets the linker know in which directory
5765 it should look for the library files. The double quotes are only necessary
5766 when the path contains spaces, so we could have omitted them in this
5767 example.
5768
5769 The second part tells the linker which libraries to link against. We have
5770 two different library files for UNIX platforms and Windows, respectively:
5771 \c libCatWhisperer.so and \c CatWhisperer.lib. It is not necessary
5772 to specify the \c .lib extension, nor the \c lib prefix
5773 (on UNIX platforms).
5774
5775 \section1 Destination Directory
5776
5777 By default, \c qmake creates the executable in the same directory as the
5778 \c .pro file. We can choose our own directory using the
5779 \l{qmake Variable Reference#DESTDIR}{DESTDIR} variable:
5780
5781 \code
5782 DESTDIR = bin
5783 \endcode
5784
5785 That's it! You can now use the \c CatWhisperer library in your project.
5786 The final \c .pro file looks like this:
5787
5788 \code
5789 TARGET = MyQtApp
5790
5791 TEMPLATE = app
5792
5793 INCLUDEPATH += 3rdparty/CatWhisperer/include
5794
5795 SOURCES += src/main.cpp
5796
5797 LIBS += -L"3rdparty/CatWhisperer/lib" -lCatWhisperer
5798 \endcode
5799
5800 \sa {\QC: Add libraries to qmake projects}
5801 */