4. The Qt Tools

Environment Variables

In order to successfully use Qt three environment variables have to be setup: QTDIR, PATH and QMAKESPEC.

In order to compile Qt, the QTDIR has to be set to point at the directory containing the Qt distribution. In my Mandrake 9 installation QTDIR is set to /usr/lib/qt3.

To be able to invoke the Qt tools from the command line the PATH variable needs to be set. Simply include ${QTDIR}/bin at the end of your PATH.

In order to use qmake properly the QMAKESPEC has to be setup. QMAKESPEC points at a directory holding files describing the target environment to qmake. Qt includes a directory called mkspecs, located at $QTDIR/mkspecs, containing a number of prepared specifications. Hopefully one of these fits you needs, for example an x86 Linux installation using gcc as the compiler uses linux-g++, thus QMAKESPEC should be set to $QTDIR/mkspecs/linux-g++.

How do you set environment variables? You may ask. In bash you type export QTDIR=/usr/lib/qt3, and export PATH=$PATH':/usr/lib/qt3/bin'. Put these expressions in your local .bashrc (in your home directory). To check if the variables are set, simply type, for example, echo $QTDIR at the prompt.

Qt Designer

The Qt Designer is the programming studio shipped with Qt. In Qt 2.x Designer was used as a dialog designer and all code was authored using other editors. In Qt 3.x Designer has been extended to handle C++ projects and code editing along with the old functionality. Throughout this tutorial we will use Qt Designer extensively as it greatly simplifies the development process.


As a Qt application has dependecies to the Qt libraries, its support libraries and sometimes to third part libraries, but at the same time attempts to be fully portable the make files can easily grow into complex beasts. Not only does the C++ source code have to be compiled, but the moc introduces an additional pre-compilation stage and, as we will see, user interfaces can be compiled from XML descriptions into C++ classes. To solve this problem qmake is used.

For the simplests cases, simply type qmake -project to analyze all code and emit a project description file (of the type *.pro). If qmake is executed without any parameters a Makefile intended for the host platform is generated. To build the project, simply run the make tool.

To build a proper make file qmake depends on the QMAKESPEC environment variable and the description to which it points. This description holds all information concerning the intended target.

If you just alter the code, without adding any new project files of external dependecies (including files from other libraries) there is no need to re-run qmake. Simply run the make tool to rebuild as you would with any other project. In other cases it can be necessary to rebuild the project description and the Makefile.

The greatest advantage, other than the relief of not having to authour complex Makefiles, is that the project description file is portable. As long as you have a qmake specification for your target platform you can build a Makefile and then the entire project, with the same project description.

If you really need target specific descriptions, such sections can be included in the project description files, thus making the Qt applications truly portable. For example, for a win32 specific config setting, use something like example 3-1.

win32 {
  CONFIG += special

Example 3-1

More advanced options are available. It is recommended that the interested reader study the Advanced Concepts chapter of the qmake on-line documentation.

Some Linux distributions only include the multi-threaded version of Qt, called libqt-mt.so and not libqt.so. This means that ld will complain (when running gcc, g++ and other tools invoking ld, or running ld directly) that it cannot find -lqt. There are three ways to solve this listed below. I recommend the first solution.


The user interface compiler translates .ui files generated by Designer into C++ classes. This tool is automatically configured by qmake.


The meta object compiler creates meta objects describing the classes with signals and slots. This tool is automatically configured by qmake.


Linguist uses the lrelease and lupdate tools. They are used to internationalize (i18n) Qt applications. This will be covered in a later chapter.



  1. Make sure that you have a working Qt system.

Recommended Reading

This is a part of digitalfanatics.org and is valid XHTML.