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