/**************************************************************************** ** ** Copyright (C) 2019 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:FDL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and The Qt Company. For licensing terms ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** ** GNU Free Documentation License Usage ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of ** this file. Please review the following information to ensure ** the GNU Free Documentation License version 1.3 requirements ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \page qmake-manual.html \title qmake Manual \startpage index.html \nextpage Overview \ingroup qttools \keyword qmake The qmake tool helps simplify the build process for development projects across different platforms. It automates the generation of Makefiles so that only a few lines of information are needed to create each Makefile. You can use qmake for any software project, whether it is written with Qt or not. qmake generates a Makefile based on the information in a project file. Project files are created by the developer, and are usually simple, but more sophisticated project files can be created for complex projects. qmake contains additional features to support development with Qt, automatically including build rules for \l{moc.html}{moc} and \l{uic.html}{uic}. qmake can also generate projects for Microsoft Visual studio without requiring the developer to change the project file. \section1 Table of Contents \list \li \l{Overview} \li \l{Getting Started} \li \l{Creating Project Files} \li \l{Building Common Project Types} \li \l{Running qmake} \li \l{Platform Notes} \li \l{qmake Language} \li \l{Advanced Usage} \li \l{Using Precompiled Headers} \li \l{Configuring qmake} \li \l{Reference} \list \li \l{Variables} \li \l{Replace Functions} \list \li \l{Built-in Replace Functions} \endlist \li \l{Test Functions} \list \li \l{Built-in Test Functions} \li \l{Test Function Library} \endlist \endlist \endlist */ /*! \page qmake-overview.html \title Overview \previouspage qmake Manual \nextpage Getting Started The qmake tool provides you with a project-oriented system for managing the build process for applications, libraries, and other components. This approach gives you control over the source files used, and allows each of the steps in the process to be described concisely, typically within a single file. qmake expands the information in each project file to a Makefile that executes the necessary commands for compiling and linking. \section1 Describing a Project Projects are described by the contents of project (\c .pro) files. qmake uses the information within the files to generate Makefiles that contain all the commands that are needed to build each project. Project files typically contain a list of source and header files, general configuration information, and any application-specific details, such as a list of extra libraries to link against, or a list of extra include paths to use. Project files can contain a number of different elements, including comments, variable declarations, built-in functions, and some simple control structures. In most simple projects, it is only necessary to declare the source and header files that are used to build the project with some basic configuration options. For more information about how to create a simple project file, see \l{Getting Started}. You can create more sophisticated project files for complex projects. For an overview of project files, see \l{Creating Project Files}. For detailed information about the variables and functions that you can use in project files, see \l{Reference}. You can use application or library project templates to specify specialized configuration options to fine tune the build process. For more information, see \l{Building Common Project Types}. You can use the \l{Qt Creator: Creating Projects}{Qt Creator new project wizard} to create the project file. You choose the project template, and Qt Creator creates a project file with default values that enable you to build and run the project. You can modify the project file to suit your purposes. You can also use qmake to generate project files. For a full description of qmake command line options, see \l{Running qmake}. The basic configuration features of qmake can handle most cross-platform projects. However, it might be useful, or even necessary, to use some platform-specific variables. For more information, see \l{Platform Notes}. \section1 Building a Project For simple projects, you only need to run qmake in the top level directory of your project to generate a Makefile. You can then run your platform's \c make tool to build the project according to the Makefile. For more information about the environment variables that qmake uses when configuring the build process, see \l{Configuring qmake}. \section1 Using Third Party Libraries The guide to \l{Third Party Libraries} shows you how to use simple third party libraries in your Qt project. \section1 Precompiling Headers In large projects, it is possible to take advantage of precompiled header files to speed up the build process. For more information, see \l{Using Precompiled Headers}. */ /*! \page qmake-project-files.html \title Creating Project Files \previouspage Getting Started \nextpage Building Common Project Types Project files contain all the information required by qmake to build your application, library, or plugin. Generally, you use a series of declarations to specify the resources in the project, but support for simple programming constructs enables you to describe different build processes for different platforms and environments. \section1 Project File Elements The project file format used by qmake can be used to support both simple and fairly complex build systems. Simple project files use a straightforward declarative style, defining standard variables to indicate the source and header files that are used in the project. Complex projects may use control flow structures to fine-tune the build process. The following sections describe the different types of elements used in project files. \target ProjectFileElementsVariables \section2 Variables In a project file, variables are used to hold lists of strings. In the simplest projects, these variables inform qmake about the configuration options to use, or supply filenames and paths to use in the build process. qmake looks for certain variables in each project file, and it uses the contents of these to determine what it should write to a Makefile. For example, the lists of values in the \l{HEADERS} and \l{SOURCES} variables are used to tell qmake about header and source files in the same directory as the project file. Variables can also be used internally to store temporary lists of values, and existing lists of values can be overwritten or extended with new values. The following snippet illustrates how lists of values are assigned to variables: \snippet qmake/variables.pro 0 The list of values in a variable is extended in the following way: \snippet qmake/variables.pro 1 \note The first assignment only includes values that are specified on the same line as the \c HEADERS variable. The second assignment splits the values in the \c SOURCES variable across lines by using a backslash (\\). The \l{CONFIG} variable is another special variable that qmake uses when generating a Makefile. It is discussed in \l{General Configuration}. In the snippet above, \c console is added to the list of existing values contained in \c CONFIG. The following table lists some frequently used variables and describes their contents. For a full list of variables and their descriptions, see \l{Variables}. \table \header \li Variable \li Contents \row \li \l{CONFIG} \li General project configuration options. \row \li \l{DESTDIR} \li The directory in which the executable or binary file will be placed. \row \li \l{FORMS} \li A list of UI files to be processed by the \l{uic}{user interface compiler (uic)}. \row \li \l{HEADERS} \li A list of filenames of header (.h) files used when building the project. \row \li \l{Variables#QT}{QT} \li A list of Qt modules used in the project. \row \li \l{RESOURCES} \li A list of resource (.qrc) files to be included in the final project. See the \l{The Qt Resource System} for more information about these files. \row \li \l{SOURCES} \li A list of source code files to be used when building the project. \row \li \l{TEMPLATE} \li The template to use for the project. This determines whether the output of the build process will be an application, a library, or a plugin. \endtable The contents of a variable can be read by prepending the variable name with \c $$. This can be used to assign the contents of one variable to another: \snippet qmake/dereferencing.pro 0 The \c $$ operator is used extensively with built-in functions that operate on strings and lists of values. For more information, see \l{qmake Language}. \section3 Whitespace Usually, whitespace separates values in variable assignments. To specify values that contain spaces, you must enclose the values in double quotes: \snippet qmake/quoting.pro 0 The quoted text is treated as a single item in the list of values held by the variable. A similar approach is used to deal with paths that contain spaces, particularly when defining the \l{INCLUDEPATH} and \l{LIBS} variables for the Windows platform: \snippet qmake/spaces.pro quoting include paths with spaces \section2 Comments You can add comments to project files. Comments begin with the \c # character and continue to the end of the same line. For example: \snippet qmake/comments.pro 0 To include the \c # character in variable assignments, it is necessary to use the contents of the built-in \l{LITERAL_HASH} variable. \section2 Built-in Functions and Control Flow qmake provides a number of built-in functions to enable the contents of variables to be processed. The most commonly used function in simple project files is the \l{include(filename)}{include()} function which takes a filename as an argument. The contents of the given file are included in the project file at the place where the \c include function is used. The \c include function is most commonly used to include other project files: \snippet qmake/include.pro 0 Support for conditional structures is made available via \l{Scopes}{scopes} that behave like \c if statements in programming languages: \snippet qmake/scopes.pro 0 The assignments inside the braces are only made if the condition is true. In this case, the \c win32 \l{CONFIG} option must be set. This happens automatically on Windows. The opening brace must stand on the same line as the condition. More complex operations on variables that would usually require loops are provided by built-in functions such as \l{findfunction}{find()}, \l{unique}{unique()}, and \l{countfunction}{count()}. These functions, and many others are provided to manipulate strings and paths, support user input, and call external tools. For more information about using the functions, see \l{qmake Language}. For lists of all functions and their descriptions, see \l{Replace Functions} and \l{Test Functions}. \section1 Project Templates The \l{TEMPLATE} variable is used to define the type of project that will be built. If this is not declared in the project file, qmake assumes that an application should be built, and will generate an appropriate Makefile (or equivalent file) for the purpose. The following table summarizes the types of projects available and describes the files that qmake will generate for each of them: \table \header \li Template \li qmake Output \row \li app (default) \li Makefile to build an application. \row \li lib \li Makefile to build a library. \row \li aux \li Makefile to build nothing. Use this if no compiler needs to be invoked to create the target, for instance because your project is written in an interpreted language. \note This template type is only available for Makefile-based generators. In particular, it will not work with the vcxproj and Xcode generators. \row \li subdirs \li Makefile containing rules for the subdirectories specified using the \l{SUBDIRS} variable. Each subdirectory must contain its own project file. \row \li vcapp \li Visual Studio Project file to build an application. \row \li vclib \li Visual Studio Project file to build a library. \row \li vcsubdirs \li Visual Studio Solution file to build projects in sub-directories. \endtable See \l{Building Common Project Types} for advice on writing project files for projects that use the \c app and \c lib templates. When the \c subdirs template is used, qmake generates a Makefile to examine each specified subdirectory, process any project file it finds there, and run the platform's \c make tool on the newly-created Makefile. The \c SUBDIRS variable is used to contain a list of all the subdirectories to be processed. \target GeneralConfiguration \section1 General Configuration The \l{CONFIG} variable specifies the options and features that the project should be configured with. The project can be built in \e release mode or \e debug mode, or both. If debug and release are both specified, the last one takes effect. If you specify the \c debug_and_release option to build both the debug and release versions of a project, the Makefile that qmake generates includes a rule that builds both versions. This can be invoked in the following way: \snippet code/doc_src_qmake-manual.pro 0 Adding the \c build_all option to the \c CONFIG variable makes this rule the default when building the project. \note Each of the options specified in the \c CONFIG variable can also be used as a scope condition. You can test for the presence of certain configuration options by using the built-in \l{CONFIG(config)}{CONFIG()} function. For example, the following lines show the function as the condition in a scope to test whether only the \c opengl option is in use: \snippet qmake/configscopes.pro 4 \snippet qmake/configscopes.pro 5 This enables different configurations to be defined for \c release and \c debug builds. For more information, see \l{Scopes}{Using Scopes}. The following options define the type of project to be built. \note Some of these options only take effect when used on the relevant platform. \table \header \li Option \li Description \row \li qt \li The project is a Qt application and should link against the Qt library. You can use the \c QT variable to control any additional Qt modules that are required by your application. This value is added by default, but you can remove it to use qmake for a non-Qt project. \row \li x11 \li The project is an X11 application or library. This value is not needed if the target uses Qt. \endtable The \l{TEMPLATE}{application and library project templates} provide you with more specialized configuration options to fine tune the build process. The options are explained in detail in \l{Building Common Project Types}. For example, if your application uses the Qt library and you want to build it in \c debug mode, your project file will contain the following line: \snippet code/doc_src_qmake-manual.pro 1 \note You must use "+=", not "=", or qmake will not be able to use Qt's configuration to determine the settings needed for your project. \section1 Declaring Qt Libraries If the \l{CONFIG} variable contains the \c qt value, qmake's support for Qt applications is enabled. This makes it possible to fine-tune which of the Qt modules are used by your application. This is achieved with the \l{Variables#QT}{QT} variable which can be used to declare the required extension modules. For example, we can enable the XML and network modules in the following way: \snippet code/doc_src_qmake-manual.pro 2 \note \c QT includes the \c core and \c gui modules by default, so the above declaration \e adds the network and XML modules to this default list. The following assignment \e omits the default modules, and will lead to errors when the application's source code is being compiled: \snippet code/doc_src_qmake-manual.pro 3 If you want to build a project \e without the \c gui module, you need to exclude it with the "-=" operator. By default, \c QT contains both \c core and \c gui, so the following line will result in a minimal Qt project being built: \snippet code/doc_src_qmake-manual.pro 4 For a list of Qt modules that you can add to the \c QT variable, see \l{Variables#QT}{QT}. \section1 Configuration Features qmake can be set up with extra configuration features that are specified in feature (.prf) files. These extra features often provide support for custom tools that are used during the build process. To add a feature to the build process, append the feature name (the stem of the feature filename) to the \c CONFIG variable. For example, qmake can configure the build process to take advantage of external libraries that are supported by \l{http://www.freedesktop.org/wiki/Software/pkg-config}{pkg-config}, such as the D-Bus and ogg libraries, with the following lines: \snippet code/doc_src_qmake-manual.pro 5 For more information about adding features, see \l{Adding New Configuration Features}. \section1 Declaring Other Libraries If you are using other libraries in your project in addition to those supplied with Qt, you need to specify them in your project file. The paths that qmake searches for libraries and the specific libraries to link against can be added to the list of values in the \l{LIBS} variable. You can specify the paths to the libraries or use the Unix-style notation for specifying libraries and paths. For example, the following lines show how a library can be specified: \snippet code/doc_src_qmake-manual.pro 6 The paths containing header files can also be specified in a similar way using the \l{INCLUDEPATH} variable. For example, to add several paths to be searched for header files: \snippet code/doc_src_qmake-manual.pro 7 */ /*! \page qmake-running.html \title Running qmake \previouspage Building Common Project Types \nextpage Platform Notes The behavior of qmake can be customized when it is run by specifying various options on the command line. These allow the build process to be fine-tuned, provide useful diagnostic information, and can be used to specify the target platform for your project. \section1 Command Syntax The syntax used to run qmake takes the following simple form: \snippet code/doc_src_qmake-manual.pro 8 \section1 Operating Modes qmake supports two different modes of operation. In the default mode, qmake uses the information in a project file to generate a Makefile, but it is also possible to use qmake to generate project files. If you want to explicitly set the mode, you must specify it before all other options. The \c mode can be either of the following two values: \list \li \c -makefile \BR qmake output will be a Makefile. \li \c -project \BR qmake output will be a project file. \BR \note It is likely that the created file will need to be edited. For example, adding the \c QT variable to suit what modules are required for the project. \endlist You can use the \c options to specify both general and mode-specific settings. Options that only apply to the Makefile mode are described in the \l{#MakefileMode}{Makefile Mode Options} section, whereas options that influence the creation of project files are described in the \l{#ProjectMode}{Project Mode Options} section. \section1 Files The \c files argument represents a list of one or more project files, separated by spaces. \section1 General Options A wide range of options can be specified on the command line to qmake in order to customize the build process, and to override default settings for your platform. The following basic options provide help on using qmake, specify where qmake writes the output file, and control the level of debugging information that will be written to the console: \list \li \c -help \BR qmake will go over these features and give some useful help. \li \c {-o file} \BR qmake output will be directed to \c file. If this option is not specified, qmake will try to use a suitable file name for its output, depending on the mode it is running in.\BR If '-' is specified, output is directed to stdout. \li \c -d \BR qmake will output debugging information. Adding \c -d more than once increases verbosity. \endlist The template used for the project is usually specified by the \l{TEMPLATE} variable in the project file. You can override or modify this by using the following options: \list \li \c {-t tmpl} \BR qmake will override any set \c TEMPLATE variables with \c tmpl, but only \e after the .pro file has been processed. \li \c {-tp prefix} \BR qmake will add \c prefix to the \c TEMPLATE variable. \endlist The level of warning information can be fine-tuned to help you find problems in your project file: \list \li \c -Wall \BR qmake will report all known warnings. \li \c -Wnone \BR No warning information will be generated by qmake. \li \c -Wparser \BR qmake will only generate parser warnings. This will alert you to common pitfalls and potential problems in the parsing of your project files. \li \c -Wlogic \BR qmake will warn of common pitfalls and potential problems in your project file. For example, qmake will report multiple occurrences of files in lists and missing files. \endlist \target MakefileMode \section1 Makefile Mode Options \snippet code/doc_src_qmake-manual.pro 9 In Makefile mode, qmake will generate a Makefile that is used to build the project. Additionally, the following options may be used in this mode to influence the way the project file is generated: \list \li \c -after \BR qmake will process assignments given on the command line after the specified files. \li \c -nocache \BR qmake will ignore the \c{.qmake.cache} file. \li \c -nodepend \BR qmake will not generate any dependency information. \li \c {-cache file} \BR qmake will use \c file as the cache file, ignoring any other .qmake.cache files found. \li \c {-spec spec} \BR qmake will use \c spec as a path to platform and compiler information, and ignore the value of \l{QMAKESPEC}. \endlist You may also pass qmake assignments on the command line. They are processed before all of the files specified. For example, the following command generates a Makefile from test.pro: \snippet code/doc_src_qmake-manual.pro 10 However, some of the specified options can be omitted as they are default values: \snippet code/doc_src_qmake-manual.pro 11 If you are certain you want your variables processed after the files specified, then you may pass the \c -after option. When this is specified, all assignments on the command line after the \c -after option will be postponed until after the specified files are parsed. \target ProjectMode \section1 Project Mode Options \snippet code/doc_src_qmake-manual.pro 12 In project mode, qmake will generate a project file. Additionally, you may supply the following options in this mode: \list \li \c -r \BR qmake will look through supplied directories recursively. \li \c -nopwd \BR qmake will not look in your current working directory for source code. It will only use the specified \c files. \endlist In this mode, the \c files argument can be a list of files or directories. If a directory is specified, it will be included in the \l{DEPENDPATH} variable, and relevant code from there will be included in the generated project file. If a file is given, it will be appended to the correct variable, depending on its extension. For example, UI files are added to \l{FORMS}, and C++ files are added to \l{SOURCES}. You may also pass assignments on the command line in this mode. When doing so, these assignments will be placed last in the generated project file. */ /*! \page qmake-platform-notes.html \title Platform Notes \previouspage Running qmake \nextpage qmake Language Many cross-platform projects can be handled by the basic qmake configuration features. However, on some platforms, it is sometimes useful, or even necessary, to take advantage of platform-specific features. qmake knows about many of these features, which can be accessed via specific variables that only take effect on the platforms where they are relevant. \section1 \macos, iOS, tvOS, and watchOS Features specific to these platforms include support for creating universal binaries, frameworks and bundles. \section2 Source and Binary Packages The version of qmake supplied in source packages is configured slightly differently to that supplied in binary packages in that it uses a different feature specification. Where the source package typically uses the \c macx-g++ specification, the binary package is typically configured to use the \c macx-xcode specification. Users of each package can override this configuration by invoking qmake with the \c -spec option (see \l{Running qmake} for more information). For example, to use qmake from a binary package to create a Makefile in a project directory, invoke the following command: \snippet code/doc_src_qmake-manual.pro 13 \section2 Using Frameworks qmake is able to automatically generate build rules for linking against frameworks in the standard framework directory on \macos, located at \c{/Library/Frameworks/}. Directories other than the standard framework directory need to be specified to the build system, and this is achieved by appending linker options to the \l{LIBS} variable, as shown in the following example: \snippet code/doc_src_qmake-manual.pro 14 The framework itself is linked in by appending the \c{-framework} options and the name of the framework to the \l{LIBS} variable: \snippet code/doc_src_qmake-manual.pro 15 \section2 Creating Frameworks Any given library project can be configured so that the resulting library file is placed in a \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html} {framework}, ready for deployment. To do this, set up the project to use the \l{TEMPLATE}{\c lib template} and add the \c lib_bundle option to the \l{CONFIG} variable: \snippet code/doc_src_qmake-manual.pro 16 The data associated with the library is specified using the \l{QMAKE_BUNDLE_DATA} variable. This holds items that will be installed with a library bundle, and is often used to specify a collection of header files, as in the following example: \snippet code/doc_src_qmake-manual.pro 17 You use the \c FRAMEWORK_HEADERS variable to specify the headers required by a particular framework. Appending it to the \c QMAKE_BUNDLE_DATA variable ensures that information about these headers is added to the collection of resources that will be installed with the library bundle. Also, the framework name and version are specified by the \l {QMAKE_FRAMEWORK_BUNDLE_NAME} and \l{QMAKE_FRAMEWORK_VERSION} variables. By default, the values used for these variables are obtained from the \l{TARGET} and \l{VERSION} variables. See \l{Qt for macOS - Deployment} for more information about deploying applications and libraries. \section2 Creating and Moving Xcode Projects Developers on \macos can take advantage of the qmake support for Xcode project files, as described in \l{Qt for macOS#Additional Command-Line Options}{Qt for \macos} documentation. by running qmake to generate an Xcode project from an existing qmake project file. For example: \snippet code/doc_src_qmake-manual.pro 19 \note If a project is later moved on the disk, qmake must be run again to process the project file and create a new Xcode project file. \section2 Supporting Two Build Targets Simultaneously Implementing this is currently not feasible, because the Xcode concept of Active Build Configurations is conceptually different from the qmake idea of build targets. The Xcode Active Build Configurations settings are for modifying Xcode configurations, compiler flags and similar build options. Unlike Visual Studio, Xcode does not allow for the selection of specific library files based on whether debug or release build configurations are selected. The qmake debug and release settings control which library files are linked to the executable. It is currently not possible to set files in Xcode configuration settings from the qmake generated Xcode project file. The way the libraries are linked in the \e {Frameworks & Libraries} phase in the Xcode build system. Furthermore, the selected \e {Active Build Configuration} is stored in a .pbxuser file, which is generated by Xcode on first load, not created by qmake. \section1 Windows Features specific to this platform include support for Windows resource files (provided or auto-generated), creating Visual Studio project files, and handling manifest files when deploying Qt applications developed using Visual Studio 2005, or later. \section2 Adding Windows Resource Files This section describes how to handle a Windows resource file with qmake to have it linked to an application executable (EXE) or dynamic link library (DLL). qmake can optionally auto-generate a suitably filled Windows resource file. A linked Windows resource file may contain many elements that can be accessed by its EXE or DLL. However, the \l{The Qt Resource System}{Qt resource system} should be used for accessing linked-in resources in a platform-independent way. But some standard elements of the linked Windows resource file are accessed by Windows itself. For example, in Windows explorer the version tab of the file properties is filled by resource elements. In addition, the program icon of the EXE is read from these elements. So it is good practice for a Qt created Windows EXE or DLL to use both techniques at the same time: link platform-independent resources via the \l{The Qt Resource System}{Qt resource system} and add Windows specific resources via a Windows resource file. Typically, a resource-definition script (.rc file) is compiled to a Windows resource file. Within the Microsoft toolchain, the RC tool generates a .res file, which can be linked with the Microsoft linker to an EXE or DLL. The MinGW toolchain uses the windres tool to generate an .o file that can be linked with the MinGW linker to an EXE or DLL. The optional auto-generation of a suitably filled .rc file by qmake is triggered by setting at least one of the system variables \l{VERSION} and \l{RC_ICONS}. The generated .rc file is automatically compiled and linked. Elements that are added to the .rc file are defined by the system variables \l{QMAKE_TARGET_COMPANY}, \l{QMAKE_TARGET_DESCRIPTION}, \l{QMAKE_TARGET_COPYRIGHT}, \l{QMAKE_TARGET_PRODUCT}, \l{QMAKE_TARGET_ORIGINAL_FILENAME}, \l{QMAKE_TARGET_INTERNALNAME}, \l{QMAKE_TARGET_COMMENTS}, \l{QMAKE_TARGET_TRADEMARKS}, \l{QMAKE_MANIFEST}, \l{RC_CODEPAGE}, \l{RC_ICONS}, \l{RC_LANG} and \l{VERSION}. If these elements are not sufficient, qmake has the two system variables \l{RC_FILE} and \l{RES_FILE} that point directly to an externally created .rc or .res file. By setting one of these variables, the specified file is linked to the EXE or DLL. \note The generation of the .rc file by qmake is blocked, if \l{RC_FILE} or \l{RES_FILE} is set. In this case, no further changes are made to the given .rc file or the .res or .o file by qmake; the variables pertaining to .rc file generation have no effect. \section2 Creating Visual Studio Project Files This section describes how to import an existing qmake project into Visual Studio. qmake is able to take a project file and create a Visual Studio project that contains all the necessary information required by the development environment. This is achieved by setting the qmake \l{TEMPLATE}{project template} to either \c vcapp (for application projects) or \c vclib (for library projects). This can also be set using a command line option, for example: \snippet code/doc_src_qmake-manual.pro 20 It is possible to recursively generate \c{.vcproj} files in subdirectories and a \c{.sln} file in the main directory, by typing: \snippet code/doc_src_qmake-manual.pro 21 Each time you update the project file, you need to run qmake to generate an updated Visual Studio project. \note If you are using the Visual Studio Add-in, select \gui Qt > \gui{Import from .pro file} to import \c .pro files. \section2 Visual Studio Manifest Files When deploying Qt applications built using Visual Studio 2005, or later, make sure that the manifest file that was created when the application was linked is handled correctly. This is handled automatically for projects that generate DLLs. Removing manifest embedding for application executables can be done with the following assignment to the \l{CONFIG} variable: \snippet code/doc_src_qmake-manual.pro 22 Also, the manifest embedding for DLLs can be removed with the following assignment to the \c CONFIG variable: \snippet code/doc_src_qmake-manual.pro 23 This is discussed in more detail in the \l{Qt for Windows - Deployment#Manifest files} {deployment guide for Windows}. */ /*! \page qmake-reference.html \title Reference \previouspage Configuring qmake \nextpage Variables The reference sections describe in detail the variables and functions that are available for use in qmake project files. \section1 Variable Reference \l{Variables} describes the variables that are recognized by qmake when configuring the build process for projects. \section1 Function Reference There are two types of qmake functions: replace functions and test functions. Replace functions return a value list, while test functions return a boolean result. The functions are implemented in two places: fundamental functionality is offered as built-in functions. More complex functions are implemented in a library of feature files (.prf). The functions are divided into categories according to their type: \list \li \l{Replace Functions} \li \l{Test Functions} \endlist */ /*! \page qmake-variable-reference.html \title Variables \previouspage Reference \nextpage Replace Functions \keyword qmake Variable Reference The fundamental behavior of qmake is influenced by variable declarations that define the build process of each project. Some of these declare resources, such as headers and source files, that are common to each platform. Others are used to customize the behavior of compilers and linkers on specific platforms. Platform-specific variables follow the naming pattern of the variables which they extend or modify, but include the name of the relevant platform in their name. For example, a makespec may use \c QMAKE_LIBS to specify a list of libraries that each project needs to link against, and \c QMAKE_LIBS_X11 would be used to extend this list. \target ANDROID_ABIS \section1 ANDROID_ABIS \note This variable applies only to Android targets. Specifies a list of Android target ABIs. Valid values are: armeabi-v7a, arm64-v8a, x86, x86_64. You can provide the ABIs as a qmake argument: \badcode qmake ANDROID_ABIS="armeabi-v7a arm64-v8a" \endcode \note It is possible to use this variable inside the *.pro file, however, it is not recommended since it will override any ABIs specified on the \c qmake command line. \target ANDROID_API_VERSION \section1 ANDROID_API_VERSION \note This variable applies only to Android targets. Specifies the Android API level number. For more information, see \l{Android: Build Numbers}{Android Build Numbers}. \target ANDROID_APPLICATION_ARGUMENTS \section1 ANDROID_APPLICATION_ARGUMENTS \note This variable applies only to Android targets. Specifies extra command-line arguments to the Android app using the \c AndroidManifest.xml with the tag "android.app.arguments". This takes a string of arguments: \badcode ANDROID_APPLICATION_ARGUMENTS = "arg1 arg2 arg3" \endcode \target ANDROID_BUNDLED_JAR_DEPENDENCIES \section1 ANDROID_BUNDLED_JAR_DEPENDENCIES \note This variable applies only to Android modules. This is useful when writing a Qt module. It specifies a list of pre-bundled dependencies used by the module in a \c .jar format, for example: \badcode ANDROID_BUNDLED_JAR_DEPENDENCIES += jar/Qt6Android.jar \endcode \target ANDROID_DEPLOYMENT_DEPENDENCIES \section1 ANDROID_DEPLOYMENT_DEPENDENCIES \note This variable applies only to Android targets. By default, \l androiddeployqt will detect the dependencies of your application. However, since run-time usage of plugins cannot be detected, there could be false positives, as your application might depend on any plugin that is a potential dependency. If you want to minimize the size of your \c APK, it's possible to override the automatic detection using the this variable. This should contain a list of all Qt files which need to be included, with paths relative to the Qt install root. \note Only the Qt files specified with this variable are included. Failing to include all the correct files can result in crashes. It's also important to make sure the files are listed in the correct loading order. This variable provides a way to override the automatic detection entirely, so if a library is listed before its dependencies, it will fail to load on some devices. \target ANDROID_DEPLOYMENT_SETTINGS_FILE \section1 ANDROID_DEPLOYMENT_SETTINGS_FILE \note This variable applies only to Android targets. Specifies the path to the \c {android-deployment-settings.json} file needed by \l androiddeployqt and \c androidtestrunner. This overrides the path to the settings file generated by qmake, thus you have to make sure to provide a valid settings file. \target ANDROID_EXTRA_LIBS \section1 ANDROID_EXTRA_LIBS \note This variable applies only to Android targets. A list of external libraries that will be copied into your application's \c libs folder and loaded on start-up. This can be used, for instance, to enable OpenSSL in your application. For more information, see \l{Adding OpenSSL Support for Android}. To include external libraries for multiple ABIs, where each ABIs has its own directory, use the following: \badcode for (abi, ANDROID_ABIS): ANDROID_EXTRA_LIBS += $$PWD/$${abi}/library_name.so \endcode Otherwise, if the ABI is included in the library name, use the following: \badcode for (abi, ANDROID_ABIS): ANDROID_EXTRA_LIBS += $$PWD/library_name_$${abi}.so \endcode \target ANDROID_EXTRA_PLUGINS \section1 ANDROID_EXTRA_PLUGINS \note This variable applies only to Android targets. Specifies a path to C++ plugins or resources that your application has to bundle but that cannot be delivered through the assets system, such as QML plugins. With this variable, \l androiddeployqt will make sure everything is packaged and deployed properly. \c ANDROID_EXTRA_PLUGINS must point to the directory where the extra plugin(s) are built. In addition, the build directory structure must follow a naming convention similar to Qt plugins, that is, \e {plugins/}. The plugins libraries should have the name format \e {libplugins___.so}. To achieve that the plugin pro file could be defined as follows: \badcode TEMPLATE = lib CONFIG += plugin PLUGIN_TYPE = imageformats DESTDIR = $$top_builddir/plugins/myplugin TARGET = $$qt5LibraryTarget(myplugin, "plugins/$$PLUGIN_TYPE/") \endcode with top_builddir defined in .qmake.conf as: \badcode top_builddir=$$shadowed($$PWD) \endcode This will ensure that the correct name mangling is applied to the plugin library (\e plugins/myplugin/libplugins_imageformats_myplugin_armeabi-v7a.so). Then, assuming an extra image format plugin \e myplugin is built as \e {$$DESTDIR/plugins/myplugin/}, the following ensures it is packaged correctly: \badcode ANDROID_EXTRA_PLUGINS += $$top_builddir/plugins \endcode \target ANDROID_FEATURES \section1 ANDROID_FEATURES \note This variable applies only to Android modules. Specifies a module's features list: \badcode ANDROID_FEATURES += android.hardware.location.gps \endcode For more information, see \l{Android: }{Android Docs}. \target ANDROID_LIB_DEPENDENCIES \section1 ANDROID_LIB_DEPENDENCIES \note This variable applies only to Android modules. This is useful when writing a Qt module. It specifies a list of pre-built dependencies used by the module, for example: \badcode ANDROID_LIB_DEPENDENCIES += \ plugins/libplugins_platforms_qtforandroid.so \endcode \target ANDROID_MIN_SDK_VERSION \section1 ANDROID_MIN_SDK_VERSION \note This variable applies only to Android targets. Specifies the minimum Android API level for the project. By default, this variable is set to API level 23. \target ANDROID_PACKAGE_SOURCE_DIR \section1 ANDROID_PACKAGE_SOURCE_DIR \note This variable applies only to Android targets. Specifies the path for a custom Android package template. The Android package template contains: \list \li AndroidManifest.xml file \li build.gradle file and other Gradle scripts \li res/values/libs.xml file \endlist The path specified by this variable can contain custom Java classes under \c src directory. By default, the \l androiddeployqt tool copies the application template from the Qt for Android installation path into your project's build directory, then it copies the contents of the path specified by this variable on top of that, overwriting any existing files. For instance, you can make a custom \c {AndroidManifest.xml} for your application, then place this directly into the directory specified by this variable. \target ANDROID_PERMISSIONS \section1 ANDROID_PERMISSIONS \note This variable applies only to Android modules. Specifies a module's permissions list: \badcode ANDROID_PERMISSIONS += android.permission.ACCESS_FINE_LOCATION \endcode For more information, see \l{Android: }{Android Docs}. \target ANDROID_TARGET_SDK_VERSION \section1 ANDROID_TARGET_SDK_VERSION \note This variable applies only to Android targets. Specifies the target Android API level for the project. By default, this variable is set to API level 28. \target ANDROID_VERSION_CODE \section1 ANDROID_VERSION_CODE \note This variable applies only to Android targets. Specifies the application's version number. For more information, see \l{Android: App Versioning}{Android App Versioning}. \target ANDROID_VERSION_NAME \section1 ANDROID_VERSION_NAME \note This variable applies only to Android targets. Specifies the application's version in as a human readable string. For more information, see \l{Android: App Versioning}{Android App Versioning}. \target CONFIG \section1 CONFIG Specifies project configuration and compiler options. The values are recognized internally by qmake and have special meaning. The following \c CONFIG values control compiler and linker flags: \table \header \li Option \li Description \row \li release \li The project is to be built in release mode. If \c debug is also specified, the last one takes effect. \row \li debug \li The project is to be built in debug mode. \row \li debug_and_release \li The project is prepared to be built in \e both debug and release modes. \row \li debug_and_release_target \li This option is set by default. If \c debug_and_release is also set, the debug and release builds end up in separate debug and release directories. \row \li build_all \li If \c debug_and_release is specified, the project is built in both debug and release modes by default. \row \li autogen_precompile_source \li Automatically generates a \c .cpp file that includes the precompiled header file specified in the .pro file. \row \li ordered \li When using the \c subdirs template, this option specifies that the directories listed should be processed in the order in which they are given. \note The use of this option is discouraged. Specify dependencies as described in the \l{#SUBDIRS}{SUBDIRS} variable documentation. \row \li precompile_header \li Enables support for the use of \l{Using Precompiled Headers}{precompiled headers} in projects. \row \li precompile_header_c (MSVC only) \li Enables support for the use of \l{Using Precompiled Headers}{precompiled headers} for C files. \row \li warn_on \li The compiler should output as many warnings as possible. If \c warn_off is also specified, the last one takes effect. \row \li warn_off \li The compiler should output as few warnings as possible. \row \li exceptions \li Exception support is enabled. Set by default. \row \li exceptions_off \li Exception support is disabled. \row \li ltcg \li Link time code generation is enabled. This option is off by default. \row \li rtti \li RTTI support is enabled. By default, the compiler default is used. \row \li rtti_off \li RTTI support is disabled. By default, the compiler default is used. \row \li stl \li STL support is enabled. By default, the compiler default is used. \row \li stl_off \li STL support is disabled. By default, the compiler default is used. \row \li thread \li Thread support is enabled. This is enabled when CONFIG includes \c qt, which is the default. \row \li no_utf8_source \li Specifies that the project's source files does not use the UTF-8 encoding. Instead, the compiler default is used. \row \li hide_symbols \li Set the default visibility of symbols in the binary to hidden. By default, the compiler default is used. \row \li c99 \li C99 support is enabled. This option has no effect if the compiler does not support C99, or can't select the C standard. By default, the compiler default is used. \row \li c11 \li C11 support is enabled. This option has no effect if the compiler does not support C11, or can't select the C standard. By default, the compiler default is used. \row \li strict_c \li Disables support for C compiler extensions. By default, they are enabled. \row \li c++11 \li C++11 support is enabled. This option has no effect if the compiler does not support C++11, or can't select the C++ standard. By default, support is enabled. \row \li c++14 \li C++14 support is enabled. This option has no effect if the compiler does not support C++14, or can't select the C++ standard. By default, the compiler default is used. \row \li c++1z \li C++17 support is enabled. This option has no effect if the compiler does not support C++17, or can't select the C++ standard. By default, support is disabled. \row \li c++17 \li Same as c++1z. \row \li c++2a \li C++2a support is enabled. This option has no effect if the compiler does not support C++2a, or can't select the C++ standard. By default, support is disabled. \row \li c++latest \li Support for the latest C++ language standard is enabled that is supported by the compiler. By default, this option is disabled. \row \li strict_c++ \li Disables support for C++ compiler extensions. By default, they are enabled. \row \li depend_includepath \li Appending the value of INCLUDEPATH to DEPENDPATH is enabled. Set by default. \row \li lrelease \li Run \c lrelease for all files listed in \l TRANSLATIONS and \l EXTRA_TRANSLATIONS. If \c embed_translations is not set, install the generated .qm files into QM_FILES_INSTALL_PATH. Use QMAKE_LRELEASE_FLAGS to add options to the lrelease call. Not set by default. \row \li embed_translations \li Embed the generated translations from \c lrelease in the executable, under \l{QM_FILES_RESOURCE_PREFIX}. Requires \c lrelease to be set, too. Not set by default. \row \li create_libtool \li Create a libtool .la file for the currently built library. \row \li create_pc \li Create a pkg-config .pc file for the currently built library. \row \li no_batch \li NMake only: Turn off generation of NMake batch rules or inference rules. \row \li skip_target_version_ext \li Suppress the automatic version number appended to the DLL file name on Windows. \row \li suppress_vcproj_warnings \li Suppress warnings of the VS project generator. \row \li windeployqt \li Automatically invoke windeployqt after linking, and add the output as deployment items. \row \li dont_recurse \li Suppress qmake recursion for the current subproject. \row \li no_include_pwd \li Do not add the current directory to INCLUDEPATHS. \endtable When you use the \c debug_and_release option (which is the default under Windows), the project will be processed three times: one time to produce a "meta" Makefile, and two more times to produce a Makefile.Debug and a Makefile.Release. During the latter passes, \c build_pass and the respective \c debug or \c release option is appended to \c CONFIG. This makes it possible to perform build-specific tasks. For example: \snippet code/doc_src_qmake-manual.pro 25 As an alternative to manually writing build type conditionals, some variables offer build-specific variants, for example \l{#QMAKE_LFLAGS_RELEASE}{QMAKE_LFLAGS_RELEASE} in addition to the general \l{#QMAKE_LFLAGS}{QMAKE_LFLAGS}. These should be used when available. The meta Makefile makes the sub-builds invokable via the \c debug and \c release targets, and a combined build via the \c all target. When the \c build_all \c CONFIG option is used, the combined build is the default. Otherwise, the last specified \c CONFIG option from the set (\c debug, \c release) determines the default. In this case, you can explicitly invoke the \c all target to build both configurations at once: \snippet code/doc_src_qmake-manual.pro 24 \note The details are slightly different when producing Visual Studio and Xcode projects. When linking a library, qmake relies on the underlying platform to know what other libraries this library links against. However, if linking statically, qmake will not get this information unless we use the following \c CONFIG options: \table \header \li Option \li Description \row \li create_prl \li This option enables qmake to track these dependencies. When this option is enabled, qmake will create a file with the extension \c .prl which will save meta-information about the library (see \l{LibDepend}{Library Dependencies} for more info). \row \li link_prl \li When this option is enabled, qmake will process all libraries linked to by the application and find their meta-information (see \l{LibDepend}{Library Dependencies} for more info). \row \li no_install_prl \li This option disables the generation of installation rules for generated .prl files. \endtable \note The \c create_prl option is required when \e {building} a static library, while \c link_prl is required when \e {using} a static library. The following options define the application or library type: \table \header \li Option \li Description \row \li qt \li The target is a Qt application or library and requires the Qt library and header files. The proper include and library paths for the Qt library will automatically be added to the project. This is defined by default, and can be fine-tuned with the \c{\l{#qt}{QT}} variable. \row \li x11 \li The target is an X11 application or library. The proper include paths and libraries will automatically be added to the project. \row \li testcase \li The target is an automated test. \l{Building Common Project Types#building-a-testcase}{A check target} will be added to the generated Makefile to run the test. Only relevant when generating Makefiles. \row \li insignificant_test \li The exit code of the automated test will be ignored. Only relevant if \c testcase is also set. \row \li windows \li The target is a Win32 window application (app only). The proper include paths, compiler flags and libraries will automatically be added to the project. \row \li console \li The target is a Win32 console application (app only). The proper include paths, compiler flags and libraries will automatically be added to the project. Consider using the option \c{cmdline} for cross-platform applications. \row \li cmdline \li The target is a cross-platform command line application. On Windows, this implies \c{CONFIG += console}. On macOS, this implies \c{CONFIG -= app_bundle}. \row \li shared \li{1,2} The target is a shared object/DLL. The proper include paths, compiler flags and libraries will automatically be added to the project. Note that \c dll can also be used on all platforms; a shared library file with the appropriate suffix for the target platform (.dll or .so) will be created. \row \li dll \row \li static \li{1,2} The target is a static library (lib only). The proper compiler flags will automatically be added to the project. \row \li staticlib \row \li plugin \li The target is a plugin (lib only). This enables dll as well. \row \li designer \li The target is a plugin for \QD. \row \li no_lflags_merge \li Ensures that the list of libraries stored in the \c LIBS variable is not reduced to a list of unique values before it is used. \row \li metatypes \li Create a \c {_metatypes.json} file for the current project. \c {} is the all lowercase base name of \l TARGET. \row \li qmltypes \li Automatically register QML types defined in C++. For more information, see \l {Defining QML Types from C++}. Also, create a \c {