qmake Manual (EN) 1

Introduction to qmake

qmake is a tool created by Trolltech to write makefiles for different compilers and platforms.

Writing makefiles by hand can be difficult and error prone, especially if several makefiles are required for different compiler and platform combinations. With qmake, developers create a simple single 'project' file and run qmake to generate the appropriate makefiles. qmake takes care of all the compiler and platform dependencies, freeing developers to focus on their code. Trolltech uses qmake as the primary build tool for the Qt library, and for the tools supplied with Qt.

qmake also takes care of Qt's special requirements, automatically including build rules for moc and uic.

Installing qmake

qmake is built by default when Qt is built.

This section explains how to build qmake manually. Skip ahead to The 10 minute guide to using qmake, if you already have qmake.

Installing qmake manually

Before building Qt manually the following environment variables must be set:

QMAKESPEC
This must be set to the platform and compiler combination that you are using on your system.
For example, if you are using Windows and Microsoft Visual Studio, you would set this environment variable to win32-msvc. If you are using Solaris and g++, you would set this environment variable to solaris-g++.

The following is a list of environment variables available to choose from when setting QMAKESPEC:

aix-64 hpux-cc irix-032 netbsd-g++ solaris-cc unixware7-g++ aix-g++ hpux-g++ linux-cxx openbsd-g++ solaris-g++ win32-borland aix-xlc hpux-n64 linux-g++ openunix-cc sunos-g++ win32-g++ bsdi-g++ hpux-o64 linux-icc qnx-g++ tru64-cxx win32-msvc dgux-g++ hurd-g++ linux-kcc reliant-64 tru64-g++ win32-watc freebsd-g++ irix-64 macx-pbuilder reliant-cds ultrix-g++ win32-visa hpux-acc irix-g++ macx-g++ sco-g++ unixware-g hpux-acc irix-n32 solaris-64 unixware7-cc

The environment variable should be set to qws/envvar where envvar is one of the following:

linux-arm-g++ linux-generic-g++ linux-mips-g++ linux-x86-g++ linux-freebsd-g++ linux-ipaq-g++ linux-solaris-g++ qnx-rtp-g++
QTDIR
This must be set to where Qt is (or will be) installed. For example, c:\qt and \local\qt

Once the environment variables are set go into the qmake directory, $QTDIR/qmake, e.g. C:\qt\qmake. Now run make or nmake depending on your compiler.

When the make has completed, qmake is ready for use.

The 10 minute guide to using qmake

Creating a project file

qmake uses information stored in project (.pro) files to determine what should go in the makefiles it generates.

A basic project file contains information about the application, for example, which files are needed to compile the application, and which configuration settings to use.

Here's a simple example project file:

    SOURCES = hello.cpp
    HEADERS = hello.h
    CONFIG += qt warn_on release

We'll provide a brief line-by-line explanation, deferring the detail until later on in the manual.

    SOURCES = hello.cpp

This line specifies the source files that implement the application. In this case there is just one file, hello.cpp. Most applications require multiple files; this situation is dealt with by listing all the files on the same line space separated, like this:

    SOURCES = hello.cpp main.cpp

Alternatively, each file can be listed on a separate line, by escaping the newlines, like this:

    SOURCES = hello.cpp \
                main.cpp

A more verbose approach is to list each file separately, like this:

    SOURCES += hello.cpp
    SOURCES += main.cpp

This approach uses "+=" rather than "=" which is safer, because it always adds a new file to the existing list rather than replacing the list.

The HEADERS line is used to specify the header files created for use by the application, e.g.

    HEADERS += hello.h

Any of the approaches used to list source files may be used for header files.

The CONFIG line is used to give qmake information about the application's configuration.

    CONFIG += qt warn_on release

The "+=" is used here, because we add our configuration options to any that are already present. This is safer than using "=" which replaces all options with just those specified.

The qt part of the CONFIG line tells qmake that the application is built using Qt. This means that qmake will link against the Qt libraries when linking and add in the neccesary include paths for compiling.

The warn_on part of the CONFIG line tells qmake that it should set the compiler flags so that warnings are output.

The release part of the CONFIG line tells qmake that the application must be built as a release application. During development, programmers may prefer to replace release with debug, which is discussed later.

Project files are plain text (i.e. use an editor like notepad, vim or xemacs) and must be saved with a '.pro' extension. The name of the application's executable will be the same as the project file's name, but with an extension appropriate to the platform. For example, a project file called 'hello.pro' will produce 'hello.exe' on Windows and 'hello' on Unix.

Generating a makefile

When you have created your project file it is very easy to generate a makefile, all you need to do is go to where you have created your project file and type:

Makefiles are generated from the '.pro' files like this:

    qmake -o Makefile hello.pro

For Visual Studio users, qmake can also generate '.dsp' files, for example:

    qmake -t vcapp -o hello.dsp hello.pro

qmake Tutorial

Introduction to the qmake tutorial

This tutorial teaches you how to use qmake. We recommend that you read the qmake user guide after completing this tutorial.

Starting off simple

Let's assume that you have just finished a basic implementation of your application, and you have created the following files:

hello.cpp
hello.h
main.cpp

You will find these files in qt/qmake/examples/tutorial. The only other thing you know about the setup of the application is that it's written in Qt. First, using your favorite plain text editor, create a file called hello.pro in qt/qmake/tutorial. The first thing you need to do is add the lines that tell qmake about the source and header files that are part of your development project.

We'll add the source files to the project file first. To do this you need to use the SOURCES variable. Just start a new line with SOURCES += and put hello.cpp after it. You should have something like:

SOURCES += hello.cpp

We repeat this for each source file in the project, until we end up with:

SOURCES += hello.cpp SOURCES += main.cpp

If you prefer to use a Make-like syntax, with all the files listed in one go you can use the newline escaping like this:

SOURCES = hello.cpp \ main.cpp

Now that the source files are listed in the project file, the header files must be added. These are added in exactly the same way as source files, except that the variable name is HEADERS:

Once you have done this, your project file should look something like this:

HEADERS += hello.h SOURCES += hello.cpp SOURCES += main.cpp

The target name is set automatically; it is the same as the project file, but with the suffix appropriate to the platform. For example, if the project file is called 'hello.pro', the target will be 'hello.exe' on Windows and 'hello' on Unix. If you want to use a different name you can set it in the project file:

TARGET = helloworld

The final step is to set the CONFIG variable. Since this is a Qt application, we need to put 'qt' on the CONFIG line so that qmake will add the relevant libraries to be linked against and ensure that build lines for moc and uic are included in the makefile.

The finished project file should look like this:

CONFIG += qt HEADERS += hello.h SOURCES += hello.cpp SOURCES += main.cpp

You can now use qmake to generate a makefile for your application. On the command line, in your application directory, type:

qmake -o Makefile hello.pro

Then type make or nmake depending on the compiler you use.

Making an application debuggable

The release version of an application doesn't contain any debugging symbols or other debuggin information. During development it is useful to produce a debugging version of the application that has the relevant information. This is easily achieved by adding 'debug' to the CONFIG variable in the project file.

For example:

CONFIG += qt debug HEADERS += hello.h SOURCES += hello.cpp SOURCES += main.cpp

Use qmake as before to generate a makefile and you will be able to debug your application.

Adding platform specific source files

After a few hours of coding, you might have made a start on the platform specific part of your application, and decided to keep the platform dependent code separate. So you now have two new files to include into your project file - hellowin.cpp and hellounix.cpp. We can't just add these to the SOURCES variable since this will put both files in the makefile. So what we need to do here is to use a scope which will be processed depending on which platform qmake is run on.

A simple scope which will add in the platform dependent file for Windows looks like this:

win32 { SOURCES += hellowin.cpp }

So if qmake is run on Windows, it will add hellowin.cpp to the list of source files. If qmake is run on any other platform, it will simply ignore it. Now all that is left to be done is to create a scope for the unix dependent file.

When you have done that, your project file should now look something like this:

CONFIG += qt debug HEADERS += hello.h SOURCES += hello.cpp SOURCES += main.cpp win32 { SOURCES += hellowin.cpp } unix { SOURCES += hellounix.cpp }

Use qmake as before to generate a makefile.

Stopping qmake if a file doesn't exist

You may not want to create a makefile if a certain file doesn't exist. We can check if a file exists by using the exists() function. We can stop qmake from processing by using the error() function. This works in the same way as scopes. Simply replace the scope condition with the function. A check for a main.cpp file looks like this:

!exists( main.cpp ) { error( "No main.cpp file found" ) }

The "!" is used to negate the test, i.e. exists( main.cpp ) is true if the file exists and !exists( main.cpp ) is true if the file doesn't exist.

CONFIG += qt debug HEADERS += hello.h SOURCES += hello.cpp SOURCES += main.cpp win32 { SOURCES += hellowin.cpp } unix { SOURCES += hellounix.cpp } !exists( main.cpp ) { error( "No main.cpp file found" ) }

Use qmake as before to generate a makefile. If you rename main.cpp temporarily, you will see the message and qmake will stop processing.

Checking for more than one condition

Suppose you use Windows and you want to be able to see the qDebug() statements when you run your application on the command line. Unless you build your application with the console setting, you won't see the output. We can easily put console on the CONFIG line so that on Windows the makefile will have this setting. But let's say that we only want to add the CONFIG line if we are running on Windows and when debug is already on the CONFIG line. This requires using two nested scopes; just create one scope, then create the other inside that one. Put the settings to be processed inside the last scope, like this:

win32 { debug { CONFIG += console } }

Nested scopes can be joined together using colons, so the final project file looks like this:

That's it! You have now completed the tutorial for qmake, and are ready to write project files for your development projects.

qmake Concepts

Introducing qmake

qmake is an easy-to-use tool from Trolltech that creates makefiles for development projects across different platforms. qmake simplifies the generation of makefiles so that only a few lines of information are needed to create a makefile. qmake can be used for any software project whether it is written in Qt or not, although it also contains additional features to support Qt development.

qmake generates a makefile based on the information in a project file. Project files are created by the developer. Project files are usually simple, but can be quite sophisticated if required. qmake can also generate projects for Microsoft Visual studio without having to change the project file.

qmake's Concepts

The QMAKESPEC environment variable

Before qmake can be used to build makefiles, the QMAKESPEC environment variable must be set to the platform-compiler combination that is being used on the system. The QMAKESPEC environment variable tells qmake where to look to find platform and compiler specific information. This ensures that the right libraries are used, and that the generated makefile uses the correct syntax. A list of the currently supported platform-compiler combinations can be found in qt/mkspecs. Just set your environment variable to one of the directories listed.

For example, if you are using Microsoft Visual Studio on Windows, then you would set the QMAKESPEC environment variable to win32-msvc. If you are using gcc on Solaris then you would set your QMAKESPEC environment variable to solaris-g++.

Inside each of the directories in qt/mkspecs, there is a qmake.conf file which contains the platform and compiler specific information. These settings are applied to any project that is built using qmake and should not be modified unless you're an expert. For example, if all your applications had to link against a particular library, you might add this information to the relevant qmake.conf file.

Project (.pro) files

A project file is used to tell qmake the details it needs to know about creating a makefile for the application. For instance, a list of source files and header files that should be put into the project file; any application specific configuration, such as an extra library that should be linked against, or an extra include path.

'#' comments

You can add comments to project files. Comments begin with the '#' symbol and run to the end of the line.

Templates

The template variable tells qmake what sort of makefile should be generated for the application. The following choices are available:

app - Creates a makefile that builds an application. This is the default, so if a template is not specified, this is used.
lib - Creates a makefile that builds a library.
vcapp - Creates a Visual Studio Project file which builds an application.
vclib - Creates a Visual Studio Project file which builds a library.
subdirs - This is a special template which creates a makefile which will go into the specified directories and create a makefile for the project file and call make on it.

The 'app' template

The 'app' template tells qmake to generate a makefile that will build an application. When using this template the following qmake system variables are recognized. You should use these in your .pro file to specify information about your application.

HEADERS - A list of all the header files for the application.
SOURCES - A list of all the source files for the application.
FORMS - A list of all the .ui files (created using Qt Designer) for the application.
LEXSOURCES - A list of all the lex source files for the application.
YACCSOURCES - A list of all the yacc source files for the application.
TARGET - Name of the executable for the application. This defaults to the name of the project file. (The extension, if any, is added automatically).
DESTDIR - The directory in which the target executable is placed.
DEFINES - A list of any additional pre-processor defines needed for the application.
INCLUDEPATH - A list of any additional include paths needed for the application.
DEPENDPATH - The dependency search path for the application.
VPATH - The search path to find supplied files.
DEF_FILE - Windows only: A .def file to be linked against for the application.
RC_FILE - Windows only: A resource file for the application.
RES_FILE - Windows only: A resource file to be linked against for the application.

You only need to use the system variables that you have values for, for instance, if you don't have any extra INCLUDEPATHs then you don't need to specify any, qmake will add in the default ones needed. For instance, an example project file might look like this:

TEMPLATE = app
DESTDIR  = c:\helloapp
HEADERS += hello.h
SOURCES += hello.cpp 
SOURCES += main.cpp
DEFINES += QT_DLL
CONFIG  += qt warn_on release

For items that are single valued, e.g. the template or the destination directory, we use "="; but for multi-valued items we use "+=" to add to the existing items of that type. Using "=" replaces the item's value with the new value, for example if we wrote DEFINES=QT_DLL, all other definitions would be deleted.

The 'lib' template

The 'lib' template tells qmake to generate a makefile that will build a library. When using this template, in addition to the system variables mentioned above for the 'app' template the VERSION variable is supported. You should use these in your .pro file to specify information about the library.

VERSION - The version number of the target library, for example, 2.3.1.

The 'subdirs' template

The 'subdirs' template tells qmake to generate a makefile that will go into the specified subdirectories and generate a makefile for the project file in the directory and call make on it.

The only system variable that is recognised for this template is the SUBDIRS variable. This variable contains a list of all the subdirectories that contain project files to be processed. It is essential that the project file in the sub directory has the same name as the subdirectory, so that qmake can find it. For example, if the subdirectory is called 'myapp' then the project file in that directory should be called myapp.pro in that directory.

The CONFIG variable

The config variable specifies the options 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 recognised by qmake internally.

The following options control what compiler flags are used:

release - The application is to be built in release mode. This is ignored if 'debug' is specified.
debug - The application is to be built in debug mode.
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.

The following options define the type of library/application to be built:

qt - The application is a Qt application and should link against the Qt library.
thread - The application is a multi-threaded application.
x11 - The application is an X11 application or library.
windows - 'app' template only: the application is a Windows window application.
console - 'app' template only: the application is a Windows console application.
dll - 'lib' template only: The library is a shared library (dll).
staticlib - 'lib' template only: The library is a static library.
plugin - 'lib' template only: The library is a plugin; this enables the dll option.

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

    CONFIG += qt thread debug

Note, that you must use "+=", not "=", or qmake will not be able to use the settings used to build Qt as a guide as what type of Qt library was built.