Qt 4.8: qmake Project Files

Qt Reference Documentation

Using qmake Running qmake

# 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 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:

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. 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:

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

Using qmake Running qmake