qmake

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 manually

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

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.

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

QTDIR

This must be set to where Qt is (or will be) installed. For example, c:\qt and \local\qt

The 10 minute guide to using qmake

Project (.pro) files

'#' 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.



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.



The '=' operator



This operator simply assigns a value to a variable, it is used like this:



TARGET = myapp

This sets the TARGET variable to myapp. This will remove any previously set TARGET.



The '+=' operator



This operator appends a value to the list of values in a variable. It is used like this:



DEFINES += QT_DLL

This appends QT_DLL to the list of pre-processor defines to be put in the makefile.
The '-=' operator



This operator removes a value from the list of values in a variable. It is used like this:



DEFINES -= QT_DLL

This removes QT_DLL from the list of pre-processor defines to be put in the makefile.
The '*=' operator



This operator only adds a value to the list of values in a variable if it doesn't already exist. It is used like this:



DEFINES *= QT_DLL

QT_DLL will only be added to the list of pre-processor defines if it is not already defined.
The '~=' operator



This operator replaces any values that match the regexp with the specified value. It is used like this:



DEFINES ~= s/QT_[DT].+/QT

This removes any values in the list that start with QT_D or QT_T with QT.



Scopes

A scope are similar to 'if' statements, if a certain condition is true, the settings inside the scope are processed. A scope is written like this:



win32 {

DEFINES += QT_DLL

}



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