Configuring qmake's Environment
Properties
qmake
has a system of persistent information, this allows you to set
a variable in qmake once, and each time qmake is invoked this value can be queried. Use the following to set a property in qmake:
qmake -set VARIABLE VALUE
The appropriate variable and value should be substituted for VARIABLE
and VALUE
.
To retrieve this information back from qmake you can do:
qmake -query VARIABLE qmake -query #queries all current VARIABLE/VALUE pairs..
Note: qmake -query
will only list variables that you have previously set with qmake -set VARIABLE VALUE
.
This information will be saved into a QSettings object (meaning it will be stored in different places for different platforms). As VARIABLE
is versioned as well, you can set one value in an older version of qmake
, and newer versions will retrieve this value. However, if you set VARIABLE
for a newer version of qmake
, the older version will not use this value. You can however query a specific version of a variable if you prefix that version of qmake
to VARIABLE
, as in the following example:
qmake -query "1.06a/VARIABLE"
qmake
also has the notion of builtin
properties, for example you can query the installation of Qt for this version of qmake
with the QT_INSTALL_PREFIX
property:
qmake -query "QT_INSTALL_PREFIX"
These built-in properties cannot have a version prefixed to them as they are not versioned, and each version of qmake
will have its own built-in set of these values. The list below outlines the built-in properties:
QT_INSTALL_PREFIX
- Where the version of Qt this qmake is built for residesQT_INSTALL_DATA
- Where data for this version of Qt residesQMAKE_VERSION
- The current version of qmake
Finally, these values can be queried in a project file with a special notation such as:
QMAKE_VERS = $$[QMAKE_VERSION]
QMAKESPEC
qmake
requires a platform and compiler description file which contains many default values used to generate appropriate Makefiles. The standard Qt distribution comes with many of these files, located in the mkspecs
subdirectory of the Qt installation.
The QMAKESPEC
environment variable can contain any of the following:
- A complete path to a directory containing a
qmake.conf
file. In this caseqmake
will open theqmake.conf
file from within that directory. If the file does not exist,qmake
will exit with an error. - The name of a platform-compiler combination. In this case,
qmake
will search in the directory specified by themkspecs
subdirectory of the data path specified when Qt was compiled (see QLibraryInfo::DataPath).
Note: The QMAKESPEC
path will automatically be added to the INCLUDEPATH system variable.
INSTALLS
It is common on Unix to also use the build tool to install applications and libraries; for example, by invoking make install
. For this reason, qmake
has the concept of an install set, an object which contains instructions about the way part of a project is to be installed. For example, a collection of documentation files can be described in the following way:
documentation.path = /usr/local/program/doc documentation.files = docs/*
The path
member informs qmake
that the files should be installed in /usr/local/program/doc
(the path member), and the files
member specifies the files that should be copied to the installation directory. In this case, everything in the docs
directory will be coped to /usr/local/program/doc
.
Once an install set has been fully described, you can append it to the install list with a line like this:
INSTALLS += documentation
qmake
will ensure that the specified files are copied to the installation directory. If you require greater control over this process, you can also provide a definition for the extra
member of the object. For example, the following line tells qmake
to execute a series of commands for this install set:
unix:documentation.extra = create_docs; mv master.doc toc.doc
The unix
scope (see Scopes and Conditions) ensures that these particular commands are only executed on Unix platforms. Appropriate commands for other platforms can be defined using other scope rules.
Commands specified in the extra
member are executed before the instructions in the other members of the object are performed.
If you append a built-in install set to the INSTALLS
variable and do not specify files
or extra
members, qmake
will decide what needs to be copied for you. Currently, the only supported built-in install set is target
:
target.path = /usr/local/myprogram INSTALLS += target
In the above lines, qmake
knows what needs to be copied, and will handle the installation process automatically.
Cache File
The cache file is a special file qmake
reads to find settings not specified in the qmake.conf
file, project files, or at the command line. If -nocache
is not specified when qmake
is run, it will try to find a file called .qmake.cache
in parent directories of the current directory. If it fails to find this file, it will silently ignore this step of processing.
If it finds a .qmake.cache
file then it will process this file first before it processes the project file.
Library Dependencies
Often when linking against a library, qmake
relies on the underlying platform to know what other libraries this library links against, and lets the platform pull them in. In many cases, however, this is not sufficent. For example, when statically linking a library, no other libraries are linked to, and therefore no dependencies to those libraries are created. However, an application that later links against this library will need to know where to find the symbols that the static library will require. To help with this situation, qmake
attempts to follow a library's dependencies where appropriate, but this behavior must be explicitly enabled by following two steps.
The first step is to enable dependency tracking in the library itself. To do this you must tell qmake
to save information about the library:
CONFIG += create_prl
This is only relevant to the lib
template, and will be ignored for all others. When this option is enabled, qmake
will create a file ending in .prl which will save some meta-information about the library. This metafile is just like an ordinary project file, but only contains internal variable declarations. You are free to view this file and, if it is deleted, qmake
will know to recreate it when necessary, either when the project file is later read, or if a dependent library (described below) has changed. When installing this library, by specifying it as a target in an INSTALLS
declaration, qmake
will automatically copy the .prl file to the installation path.
The second step in this process is to enable reading of this meta information in the applications that use the static library:
CONFIG += link_prl
When this is enabled, qmake
will process all libraries linked to by the application and find their meta-information. qmake
will use this to determine the relevant linking information, specifically adding values to the application project file's list of DEFINES
as well as LIBS
. Once qmake
has processed this file, it will then look through the newly introduced libraries in the LIBS
variable, and find their dependent .prl files, continuing until all libraries have been resolved. At this point, the Makefile is created as usual, and the libraries are linked explicitly against the application.
The internals of the .prl file are left closed so they can easily change later. They are not designed to be changed by hand, should only be created by {qmake Manual#qmake}{qmake
}, and should not be transferred between operating systems as they may contain platform-dependent information.
File Extensions
Under normal circumstances qmake
will try to use appropriate file extensions for your platform. However, it is sometimes necessary to override the default choices for each platform and explicitly define file extensions for qmake
to use. This is achieved by redefining certain built-in variables; for example the extension used for moc files can be redefined with the following assignment in a project file:
QMAKE_EXT_MOC = .mymoc
The following variables can be used to redefine common file extensions recognized by qmake
:
- QMAKE_EXT_MOC - This modifies the extension placed on included moc files.
- QMAKE_EXT_UI - This modifies the extension used for designer UI files (usually in
FORMS
). - QMAKE_EXT_PRL - This modifies the extension placed on library dependency files.
- QMAKE_EXT_LEX - This changes the suffix used in files (usually in
LEXSOURCES
). - QMAKE_EXT_YACC - This changes the suffix used in files (usually in
YACCSOURCES
). - QMAKE_EXT_OBJ - This changes the suffix used on generated object files.
All of the above accept just the first value, so you must assign to it just one value that will be used throughout your project file. There are two variables that accept a list of values:
- QMAKE_EXT_CPP - Causes
qmake
to interpret all files with these suffixes as C++ source files. - QMAKE_EXT_H - Causes qmake Manual#{qmake}{
qmake
} to interpret all files with these suffixes as C and C++ header files.
Customizing Makefile Output
qmake
tries to do everything expected of a cross-platform build tool. This is often less than ideal when you really need to run special platform-dependent commands. This can be achieved with specific instructions to the different qmake
backends.
Customization of the Makefile output is performed through an object-style API as found in other places in qmake
. Objects are defined automatically by specifying their members; for example:
mytarget.target = .buildfile mytarget.commands = touch $$mytarget.target mytarget.depends = mytarget2 mytarget2.commands = @echo Building $$mytarget.target
The definitions above define a qmake
target called mytarget
, containing a Makefile target called .buildfile
which in turn is generated with the touch
command. Finally, the .depends
member specifies that mytarget
depends on mytarget2
, another target that is defined afterwards. mytarget2
is a dummy target; it is only defined to echo some text to the console.
The final step is to instruct qmake
that this object is a target to be built:
QMAKE_EXTRA_TARGETS += mytarget mytarget2
This is all you need to do to actually build custom targets. Of course, you may want to tie one of these targets to the qmake build target. To do this, you simply need to include your Makefile target in the list of PRE_TARGETDEPS.
The following tables are an overview of the options available to you with the QMAKE_EXTRA_TARGETS variable.
Member | Description |
---|---|
commands | The commands for generating the custom build target. |
CONFIG | Specific configuration options for the custom build target. See the CONFIG table for details. |
depends | The existing build targets that the custom build target depends on. |
recurse | Specifies which sub-targets should used when creating the rules in the Makefile to call in the sub-target specific Makefile. This is only used when recursive is set in the CONFIG. |
recurse_target | Specifies the target that should be built via the sub-target Makefile for the rule in the Makefile. This adds something like $(MAKE) -f Makefile.[subtarget] [recurse_target]. This is only used when recursive is set in the CONFIG. |
target | The file being created by the custom build target. |
List of members specific to the CONFIG option:
Member | Description |
---|---|
recursive | Indicates that rules should be created in the Makefile and thus call the relevant target inside the sub-target specific Makefile. This defaults to creating an entry for each of the sub-targets. |
For convenience, there is also a method of customizing projects for new compilers or preprocessors:
new_moc.output = moc_${QMAKE_FILE_BASE}.cpp new_moc.commands = moc ${QMAKE_FILE_NAME} -o ${QMAKE_FILE_OUT} new_moc.depend_command = g++ -E -M ${QMAKE_FILE_NAME} | sed "s,^.*: ,," new_moc.input = NEW_HEADERS QMAKE_EXTRA_COMPILERS += new_moc
With the above definitions, you can use a drop-in replacement for moc if one is available. The commands is executed on all arguments given to the NEW_HEADERS
variable (from the input
member), and the result is written to the file defined by the output
member; this file is added to the other source files in the project. Additionally, qmake
will execute depend_command
to generate dependency information, and place this information in the project as well.
These commands can easily be placed into a cache file, allowing subsequent project files to add arguments to NEW_HEADERS
.
The following tables are an overview of the options available to you with the QMAKE_EXTRA_COMPILERS variable.
Member | Description |
---|---|
commands | The commands used for for generating the output from the input. |
CONFIG | Specific configuration options for the custom compiler. See the CONFIG table for details. |
depend_command | Specifies a command used to generate the list of dependencies for the output. |
dependency_type | Specifies the type of file the output is, if it is a known type (such as TYPE_C, TYPE_UI, TYPE_QRC) then it is handled as one of those type of files. |
depends | Specifies the dependencies of the output file. |
input | The variable that contains the files that should be processed with the custom compiler. |
name | A description of what the custom compiler is doing. This is only used in some backends. |
output | The filename that is created from the custom compiler. |
output_function | Specifies a custom qmake function that is used to specify the filename to be created. |
variable_out | The variable that the files created from the output should be added to. |
List of members specific to the CONFIG option:
Member | Description |
---|---|
commands | The commands used for for generating the output from the input. |
CONFIG | Specific configuration options for the custom compiler. See the CONFIG table for details. |
depend_command | Specifies a command used to generate the list of dependencies for the output. |
dependency_type | Specifies the type of file the output is, if it is a known type (such as TYPE_C, TYPE_UI, TYPE_QRC) then it is handled as one of those type of files. |
depends | Specifies the dependencies of the output file. |
input | The variable that contains the files that should be processed with the custom compiler. |
name | A description of what the custom compiler is doing. This is only used in some backends. |
output | The filename that is created from the custom compiler. |
output_function | Specifies a custom qmake function that is used to specify the filename to be created. |
variables | Indicates that the variables specified here are replaced with $(QMAKE_COMP_VARNAME) when refered to in the pro file as $(VARNAME). |
variable_out | The variable that the files created from the output should be added to. |
List of members specific to the CONFIG option:
Member | Description |
---|---|
combine | Indicates that all of the input files are combined into a single output file. |
target_predeps | Indicates that the output should be added to the list of PRE_TARGETDEPS. |
explicit_dependencies | The dependencies for the output only get generated from the depends member and from nowhere else. |
no_link | Indicates that the output should not be added to the list of objects to be linked in. |
Note: Symbian platform specific: Generating objects to be linked in is not supported on the Symbian platform, so either the CONFIG
option no_link
or variable variable_out
should always be defined for extra compilers.
© 2016 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.