Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

[Prev: qmake's Advanced Concepts] [Home] [Next: qmake Command Reference]

## qmake Tutorial

### Introduction to the qmake tutorial

This is a tutorial in using qmake, if you haven't read through the rest of the manual then it is recommended to do so.

### 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/tutorial. The only other thing you know about the setup of the application is that it's written in Qt. First, using your favourite 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. So you should have something like:

    	SOURCES = hello.cpp

This isn't all of the source files, but we can't just put main.cpp on a new line, and if we used SOURCES += for each additional source file it would start to look messy. So in order to show that we want another file added to the SOURCES variable we put a \ after the first line and put main.cpp on a new line. So your project file should look something like:

    	SOURCES = hello.cpp \
    		  main.cpp

Now that we have the source files setup in the project file, we now need to tell qmake about the header files. Just add a similar line to the SOURCES one except use the HEADERS variable and put hello.h as the value.

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

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

Now we should set a target name, this is so that qmake knows what the resulting executable should be called. Here we use the TARGET variable and we will put hello as the value. You may have noticed that the extension isn't given, this is because qmake will handle this automatically.

The final thing we need to do to set up the CONFIG variable, since this is a Qt application, we need to put the qt value on the CONFIG line so that qmake will add the relevant libraries to be linked against and any other relevant settings needed when building a Qt application.

Your finished project file should look like:

    	SOURCES = hello.cpp \
    		  main.cpp
    	HEADERS = hello.h
    	TARGET = hello
    	CONFIG = qt

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

    	qmake -o makefile hello.pro

Then type make or nmake depending on the compiler you use. You now have your basic hello application built!

### Making the 'hello' application debuggable

Normally when you are developing an application you want to be able to debug the code, in order to be able to do this with the hello application we need to modify the project file to set it as a debug project.

Open the hello.pro file in your favourite editor if you haven't already done so. All you need to do add debug to the CONFIG variable line and when the project file is processed qmake will set up the makefile with the relevant settings so that the application can be debugged.

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

    	SOURCES = hello.cpp \
    		  main.cpp
    	HEADERS = hello.h
    	TARGET = hello
    	CONFIG = qt debug

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 more 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 - hello_win.cpp and hello_x11.cpp. But wait, we can't just add these to the SOURCES variable, 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 ran on.

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

    	win32 {
    		SOURCES += hello_win.cpp
    	}

So if qmake is ran on Windows it will add hello_win.cpp to the list of source files, if qmake is ran on any other platform it will simply ignore it. Now all that is left to be done, is create a scope for the x11 dependent file, as a hint, use x11.

When you have done that, your project file should now be looking something like:

    	SOURCES = hello.cpp \
    		  main.cpp
    	HEADERS = hello.h
    	TARGET = hello
    	CONFIG = qt debug
    	win32 {
    		SOURCES += hello_win.cpp
    	}
    	x11 {
    		SOURCES += hello_x11.cpp
    	}

Use qmake as before to generate a makefile and you will see the relevant platform dependent file included.

### 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, and we can stop qmake from processing by using the error() function. This works in the same way as scopes, which we have done already, just replace the scope condition with the function, so to check for the main.cpp file will look something like:

    	exists( main.cpp ) {
    	}

However, this will process the code inside the scope if the file exists, but we want to process the settings if the file doesn't exist. All we need to do to fix this is to put a ! before the function, and it will process the settings when the file does not exist.

All that is left to do is to use the error() function to output a suitable error message, this is just a simple function, just put the text in quotes inside the brackets.

So now, your project file should look like:

    	SOURCES = hello.cpp \
    		  main.cpp
    	HEADERS = hello.h
    	TARGET = hello
    	CONFIG = qt debug
    	win32 {
    		SOURCES += hello_win.cpp
    	}
    	x11 {
    		SOURCES += hello_x11.cpp
    	}
    	!exists( main.cpp ) {
    		error( "The file 'main.cpp' does not exist!" )
    	}

Use qmake as before to generate a makefile and 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, as any Windows based Qt developer will tell you, 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 lets say that we only want to put on the CONFIG line if we are running on Windows and debug is on the CONFIG line also. To do this requires using two scopes nested, just create one scope, then create the other inside that one, and inside that scope put in the settings to be processed.

Try to do this without looking at the resulting project file and see if you get it right.

If you get it right then your final project file should look like:

    	SOURCES = hello.cpp \
    		  main.cpp
    	HEADERS = hello.h
    	TARGET = hello
    	CONFIG = qt debug
    	win32 {
    		SOURCES += hello_win.cpp
    	}
    	x11 {
    		SOURCES += hello_x11.cpp
    	}
    	!exists( main.cpp ) {
    		error( "The file 'main.cpp' does not exist!" )
    	}
    	win32 {
    		debug{
    			CONFIG += console
    		}
    	}

That's it! You have now completed the tutorial for qmake, you are now ready to write project files for your real life development projects and to use qmake to generate the makefiles for them.

[Prev: qmake's Advanced Concepts] [Home] [Next: qmake Command Reference]