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.

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 double quotes:

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:

win32:INCLUDEPATH += "C:/mylibs/extra headers"
unix:INCLUDEPATH += "/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:

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:

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.

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. More information about operators can be found in the Operators section of the qmake Advanced Usage chapter.

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.

More information about operators can be found in the Operators section of the qmake Advanced Usage chapter.

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

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