qmake Project Files

Project files contain all the information required by qmake to build your application, library, or plugin. The resources used by your project are generally specified using a series of declarations, but support for simple programming constructs allow you to describe different build processes for different platforms and environments.

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 will 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 the control flow structures to fine-tune the build process.

The following sections describe the different types of elements used in project files.

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 list of values in the HEADERS and 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 lines show how lists of values are assigned to variables:

 HEADERS = mainwindow.h paintwidget.h

Note that the first assignment only includes values that are specified on the same line as the SOURCES variable. The second assignment splits the items across lines by using the \\ character.

The list of values in a variable is extended in the following way:

 SOURCES = main.cpp mainwindow.cpp \
           paintwidget.cpp
 CONFIG += qt

The CONFIG variable is another special variable that qmake uses when generating a Makefile. It is discussed in the section on general configuration later in this chapter. In the above line, qt is added to the list of existing values contained in CONFIG.

The following table lists the variables that qmake recognizes, and describes what they should contain.

Variable	Contents
CONFIG	General project configuration options.
DESTDIR	The directory in which the executable or binary file will be placed.
FORMS	A list of UI files to be processed by uic.
HEADERS	A list of filenames of header (.h) files used when building the project.
QT	Qt-specific configuration options.
RESOURCES	A list of resource (.rc) files to be included in the final project. See the The Qt Resource System for more information about these files.
SOURCES	A list of source code files to be used when building the project.
TEMPLATE	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.

The contents of a variable can be read by prepending the variable name with $$. This can be used to assign the contents of one variable to another:

 TEMP_SOURCES = $$SOURCES

The $$ operator is used extensively with built-in functions that operate on strings and lists of values. These are described in the chapter on qmake Advanced Usage.

Whitespace

Normally, variables are used to contain whitespace-separated lists of values. However, it is sometimes necessary to specify values containing spaces. These must be quoted by using the quote() function in the following way:

 DEST = "Program Files"

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 INCLUDEPATH and LIBS variables for the Windows platform. In cases like these, the quote() function can be used in the following way:

 win32:INCLUDEPATH += $$quote(C:/mylibs/extra headers)
 unix:INCLUDEPATH += $$quote(/home/user/extra headers)

Comments

You can add comments to project files. Comments begin with the # character and continue to the end of the same line. For example:

 # Comments usually start at the beginning of a line, but they
 # can also follow other content on the same line.

To include the # character in variable assignments, it is necessary to use the contents of the built-in LITERAL_HASH variable. See the variable reference for more information.

Built-in Functions and Control Flow

qmake provides a number of built-in functions to allow the contents of variables to be processed. The most commonly used function in simple project files is the 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 include function is used. The include function is most commonly used to include other project files:

 include(other.pro)

Support for conditional structures is made available via scopes that behave like if statements in programming languages:

 win32 {
     SOURCES += paintwidget_win.cpp
 }

The assignments inside the braces are only made if the condition is true. In this case, the special win32 variable must be set; this happens automatically on Windows, but this can also be specified on other platforms by running qmake with the -win32 command line option (see Running qmake for more information). The opening brace must stand on the same line as the condition.

Simple loops are constructed by iterating over lists of values using the built-in for function. The following code adds directories to the SUBDIRS variable, but only if they exist:

 EXTRAS = handlers tests docs
 for(dir, EXTRAS) {
     exists($$dir) {
         SUBDIRS += $$dir
     }
 }

More complex operations on variables that would usually require loops are provided by built-in functions such as find, unique, and count. These functions, and many others are provided to manipulate strings and paths, support user input, and call external tools. A list of the functions available can be found in the qmake Advanced Usage chapter of this manual.

Project Templates

The 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 types of project available are listed in the following table with information about the files that qmake will generate for each of them:

Template	Description of qmake output
app (default)	Creates a Makefile to build an application.
lib	Creates a Makefile to build a library.
subdirs	Creates a Makefile containing rules for the subdirectories specified using the SUBDIRS variable. Each subdirectory must contain its own project file.
vcapp	Creates a Visual Studio Project file to build an application.
vclib	Creates a Visual Studio Project file to build a library.
vcsubdirs	Creates a Visual Studio Solution file to build projects in sub-directories.

See the qmake Tutorial for advice on writing project files for projects that use the app and lib templates.

When the 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 make tool on the newly-created Makefile. The SUBDIRS variable is used to contain a list of all the subdirectories to be processed.

General Configuration

The CONFIG variable specifies the options and features that the compiler should use and the libraries that should be linked against. Anything can be added to the CONFIG variable, but the options covered below are recognized by qmake internally.

The following options control the compiler flags that are used to build the project:

Option	Description
release	The project is to be built in release mode. This is ignored if debug is also specified.
debug	The project is to be built in debug mode.
debug_and_release	The project is built in both debug and release modes.
debug_and_release_target	The project is built in both debug and release modes. TARGET is built into both the debug and release directories.
build_all	If debug_and_release is specified, the project is built in both debug and release modes by default.
autogen_precompile_source	Automatically generates a .cpp file that includes the precompiled header file specified in the .pro file.
ordered	When using the subdirs template, this option specifies that the directories listed should be processed in the order in which they are given.
warn_on	The compiler should output as many warnings as possible. This is ignored if warn_off is specified.
warn_off	The compiler should output as few warnings as possible.
copy_dir_files	Enables the install rule to also copy directories, not just files.

The debug_and_release option is special in that it enables both debug and release versions of a project to be built. In such a case, the Makefile that qmake generates includes a rule that builds both versions, and this can be invoked in the following way:

 make all

Adding the build_all option to the CONFIG variable makes this rule the default when building the project, and installation targets will be created for both debug and release builds.

Note that each of the options specified in the 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 CONFIG() function. For example, the following lines show the function as the condition in a scope to test whether only the opengl option is in use:

 CONFIG(opengl) {
     message(Building with OpenGL support.)
 } else {
     message(OpenGL support is not available.)
 }

This enables different configurations to be defined for release and debug builds, and is described in more detail in the Scopes section of the Advanced Usage chapter of this manual.

The following options define the type of project to be built. Note that some of these options only take effect when used on the relevant platform. On other platforms, they have no effect.

Option	Description
qt	The project is a Qt application and should link against the Qt library. You can use the QT variable to control any additional Qt modules that are required by your application.
thread	The project is a multi-threaded application.
x11	The project is an X11 application or library.

When using application or library project templates, more specialized configuration options can be used to fine tune the build process. These are explained in details in the Common Projects chapter of this manual.

For example, if your application uses the Qt library and you want to build it as a multi-threaded application in debug mode, your project file will contain the following line:

 CONFIG += qt thread debug

Note, that you must use "+=", not "=", or qmake will not be able to use Qt's configuration to determine the settings needed for your project.

Declaring Qt Libraries

If the CONFIG variable contains the 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 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:

 CONFIG += qt
 QT += network xml

Note that QT includes the core and gui modules by default, so the above declaration adds the network and XML modules to this default list. The following assignment omits the default modules, and will lead to errors when the application's source code is being compiled:

 QT = network xml # This will omit the core and gui modules.

If you want to build a project without the gui module, you need to exclude it with the "-=" operator. By default, QT contains both core and gui, so the following line will result in a minimal Qt project being built:

 QT -= gui # Only the core module is used.

The table below shows the options that can be used with the QT variable and the features that are associated with each of them:

Option	Features
core (included by default)	QtCore module
gui (included by default)	QtGui module
network	QtNetwork module
opengl	QtOpenGL module
sql	QtSql module
svg	QtSvg module
xml	QtXml module
xmlpatterns	QtXmlPatterns module
qt3support	Qt3Support module

Note that adding the opengl option to the QT variable automatically causes the equivalent option to be added to the CONFIG variable. Therefore, for Qt applications, it is not necessary to add the opengl option to both CONFIG and QT.

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 CONFIG variable.

For example, qmake can configure the build process to take advantage of external libraries that are supported by pkg-config, such as the D-Bus and ogg libraries, with the following lines:

 CONFIG += link_pkgconfig
 PKGCONFIG += ogg dbus-1

More information about features can be found in the Adding New Configuration Features section of the qmake Advanced Usage chapter.

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 LIBS variable. The paths to the libraries themselves can be given, or the familiar Unix-style notation for specifying libraries and paths can be used if preferred.

For example, the following lines show how a library can be specified:

 LIBS += -L/usr/local/lib -lmath

The paths containing header files can also be specified in a similar way using the INCLUDEPATH variable.

For example, it is possible to add several paths to be searched for header files:

 INCLUDEPATH = c:/msdev/include d:/stl/include