path: root/qmake/book/qmake-tutorial.leaf

\chapter qmake Tutorial

\section1 Introduction to the qmake tutorial

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

\section1 Starting off simple

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

\list
\i hello.cpp
\i hello.h
\i main.cpp
\endlist

You will find these files in \e {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 \e hello.pro in \e {qt/qmake/tutorial}.  The
first thing you need to do is add the lines that tell \e 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 \e
{SOURCES +=} and put hello.cpp after it.  You should have something
like:

\code
    SOURCES += hello.cpp
\endcode

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

\code
    SOURCES += hello.cpp
    SOURCES += main.cpp
\endcode

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:

\code
    SOURCES = hello.cpp \
	      main.cpp
\endcode

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:
\code
    HEADERS += hello.h
    SOURCES += hello.cpp 
    SOURCES += main.cpp 
\endcode

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:
\code
    TARGET = helloworld
\endcode

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

The finished project file should look like this:
\code
    CONFIG += qt
    HEADERS += hello.h
    SOURCES += hello.cpp
    SOURCES += main.cpp 
\endcode

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

\code
    qmake -o Makefile hello.pro
\endcode

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

\section1 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:
\code
    CONFIG += qt debug
    HEADERS += hello.h
    SOURCES += hello.cpp
    SOURCES += main.cpp 
\endcode

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

\section1 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 - \e hellowin.cpp and \e
hellounix.cpp.  We can't just add these to the \e 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 \e qmake is run on.

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

\code
    win32 {
	SOURCES += hellowin.cpp
    }
\endcode

So if \e qmake is run on Windows, it will add \e hellowin.cpp to the
list of source files.  If \e 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:

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

Use \e qmake as before to generate a makefile.  

\section1 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 \e 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:

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

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

\code
    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" )
    }
\endcode

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

\section1 Checking for more than one condition

Suppose you use Windows and you want to be able to see the tqDebug()
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 \e 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 \e and when
\e 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:

\code
    win32 {
	debug {
	    CONFIG += console
	}
    }
\endcode

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

\code
    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" )
    }
    win32:debug {
	CONFIG += console
    }
\endcode


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