1.6. qmake, Project Files, and Makefile

1.6. `qmake`, Project Files, and `Makefile`
	Chapter 1. C++ Introduction

1.6. `qmake`, Project Files, and `Makefile`

[ fromfile: qmake.xml id: qmake ]

C++ applications are generally composed of many source files, header files, and external libraries.
During development/testing source files and libraries get added, changed, removed.
To build an executable that reflects the current state of the project, such changes require all affected files to be compiled and the resulting object files to be properly linked.

The most widely used utility for handling the job of building a project is make.^[6]
make reads the details of the project specifications and the instructions for the compiler from a Makefile, which resembles a shell script but contains (at a minimum)

Rules for building certain kinds of files (e.g., to get a .o file from a .cpp file, you must run gcc -c on the .cpp file)
Sources and Headers lists that contain the names of all source and header files needed by the project
Targets that specify which executables (or libraries) must be built
Dependencies that list which targets need to be rebuilt when certain files get changed

The make command, by default, loads the file named Makefile from your current working directory and performs the specified build steps (compiling and linking).

make recompiles only the files that need to be recompiled

Figure 1.1. (q)make build steps

A project file is needed for qmake to create a Makefile.
A project file lists all source and header files needed by the project and specifies some other project properties.
The command qmake -project -o projectname.pro creates a project file based entirely on the current working directory.

the command qmake creates a Makefile based on the project file.
The command make can then attempt to build an executable by following the instructions in the Makefile.^[7]

The following transcript shows how to use qmake to build the same little program that we discussed, compiled, and ran in Example 1.1.
The files that are created after each step of the build process are italicized.

src/early-examples/example0> ls
fac.cpp
src/early-examples/example0> qmake -project
src/early-examples/example0> ls
example0.pro fac.cpp
src/early-examples/example0> cat example0.pro

TEMPLATE = app
TARGET =
DEPENDPATH += .
INCLUDEPATH += .

# Input
SOURCES += fac.cpp
src/early-examples/example0> qmake
src/early-examples/example0> ls
example0.pro fac.cpp Makefile
src/early-examples/example0> make
g++ -c -pipe -O2 -Wall -W -D_REENTRANT -DQT_NO_DEBUG -DQT_GUI_LIB
  -DQT_CORE_LIB -DQT_SHARED -I/usr/share/qt4/mkspecs/linux-g++ -I.
  -I/usr/include/qt4/QtCore -I/usr/include/qt4/QtCore
  -I/usr/include/qt4/QtGui -I/usr/include/qt4/QtGui -I/usr/include/qt4
  -I. -I. -I. -o fac.o fac.cpp
g++ -o example0 fac.o  -L/usr/lib -lQtGui -lQtCore -lpthread
src/early-examples/example0> ls
example0 example0.pro fac.cpp fac.o Makefile
src/early-examples/example0>

Notice that you can see the arguments passed to the compiler when you run make.
If any errors are encountered, you will also see them.
Now you can run this application.

src/early-examples/example0> ./example0
Factorial of: 10
The Factorial of 10 is: 3628800
src/early-examples/example0> ./example0
Factorial of: -3
No negative values, please!
Factorial of: 0
The Factorial of 0 is: 1
src/early-examples/example0>

Instead of running the compiler directly from the command-line, you should henceforth use qmake and make,

Section C.1 discusses the make command and Makefiles in a bit more detail.

The project file is a map of the project.
The .pro file is the first place to look when you encounter "not found" or "undefined" messages during the build process (especially at link time).
For further details we recommend that you read Qt's guide to qmake.

When adding a source file, header file, or library reference to a project, be sure to update the project file to reflect the addition.
As items are added to the .pro file, it's good practice to add comments, as you would do in other source code files.
A comment is a line that begins with the '#' character.

In Example 1.6, you can see common qmake variable settings that can be helpful to add to all of your projects.
By placing a copy of this file in a convenient location and adding the line
```
 include (/path/to/wherever you put/common.pri) 
```
to your project file, you can save yourself some typing.

Example 1.6. src/common.pri

# required if you want to see qDebug() messages
CONFIG += debug

# place auto-generated files in "invisible" subdirectories
win32 {
    MOC_DIR = _moc
    UI_DIR = _ui
    OBJECTS_DIR = _obj
} else {
    UI_DIR = .ui
    MOC_DIR = .moc
    OBJECTS_DIR = .obj
}

# rules below apply to TEMPLATE=app projects only:
app {
    # place executable in same folder:
    DESTDIR=$$OUT_PWD

    # don't place executables in an app bundle on mac os
    # this also permits console apps to work on the mac
    mac {
        CONFIG -= app_bundle
    }

    # Open a console for stdin, stdout, and stderr Windows:
    win32 {
        CONFIG += console
    }
}

	`CONFIG += console` (for MSVC users)
	`CONFIG += console` Only needed on Windows platforms Permits output to `qDebug()`, `stdout` and `stderr`

CONFIG -= app_bundle (for Mac OSX)

	`CONFIG -= app_bundle` (for Mac OSX)
For console apps on the Mac, you can prevent the creation of an "app bundle" that places your executable in a subdirectory by adding the line CONFIG -= app_bundle in your project file. That will also permit interactions with standard I/O. You can then use the command-line qmake -spec macx-g++ to produce a `Makefile`. The command `make>` can then produce a single executable for your app. `CONFIG -= app_bundle` Only needed for console apps on the Mac Permits interaction with stdio. Prevents build from creating an "application bundle". Everything ends up in a single executable.

For console apps on the Mac, you can prevent the creation of an "app bundle" that places your executable in a subdirectory by adding the line
```
CONFIG -= app_bundle
```
in your project file.
That will also permit interactions with standard I/O.
You can then use the command-line
```
qmake -spec macx-g++
```
to produce a Makefile.
The command make> can then produce a single executable for your app.

CONFIG -= app_bundle
- Only needed for console apps on the Mac
- Permits interaction with stdio.
- Prevents build from creating an "application bundle".
- Everything ends up in a single executable.

^[6] Depending on your development environment, you may find variants of make, such as mingw32-make, gmake, or cmake. In MS Dev Studio, you'll find nmake.

^[7]To produce a Makefile in MacOSX, you need to add the line CONFIG -= app_bundle to the project file and you need to type qmake -spec macx-g++ instead of just qmake.


1.5.1. Exercises: Introduction to Functions		1.6.1. `#include`: Finding Header Files