/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \page qmake-manual.html

    \title qmake Manual

    \startpage {index.html}{Qt Reference Documentation}

    \nextpage qmake Tutorial

    \ingroup qttools

    \keyword qmake

    \c qmake is a tool that helps simplify the build

    process for development project across different platforms.  \c qmake

    automates the generation of Makefiles so that only a few lines of

    information are needed to create each Makefile. \c qmake can be used for

    any software project, whether it is written in Qt or not.

    \c qmake generates a Makefile based on the information in a project

    file.  Project files are created by the developer, and are usually

    simple, but more sophisticated project files can be created for

    complex projects.

    \c qmake contains additional features to support development with Qt,

    automatically including build rules for \l{moc.html}{moc}

    and \l{uic.html}{uic}.

    \c qmake can also generate projects for Microsoft Visual studio

    without requiring the developer to change the project file.

    \section1 Getting Started

    The \l{qmake Tutorial} and guide to \l{qmake Common Projects} provide overviews

    that aim to help new users get started with \c qmake.

    \list

    \o \l{qmake Tutorial}

      \tableofcontents{1 qmake Tutorial}

    \endlist

    \list

    \o \l{qmake Common Projects}

      \tableofcontents{1 qmake Common Projects}

    \endlist

    \section1 Table of Contents

    \list

    \o \l{Using qmake}

      \tableofcontents{1 Using qmake}

    \o \l{qmake Project Files}

      \tableofcontents{1 qmake Project Files}

    \o \l{Running qmake}

      \tableofcontents{1 Running qmake}

    \o \l{qmake Platform Notes}

      \tableofcontents{1 qmake Platform Notes}

    \o \l{qmake Advanced Usage}

      \tableofcontents{1 qmake Advanced Usage}

    \o \l{Using Precompiled Headers}

      \tableofcontents{1 Using Precompiled Headers}

    \o \l{qmake Reference}

      \tableofcontents{1 qmake Reference}

    \o \l{qmake Variable Reference}

      \tableofcontents{1 qmake Variable Reference}

    \o \l{qmake Function Reference}

      \tableofcontents{1 qmake Function Reference}

    \o \l{Configuring qmake's Environment}

      \tableofcontents{1 Configuring qmake's Environment}

    \endlist

*/

/*!

    \page qmake-using.html

    \title Using qmake

    \contentspage {qmake Manual}{Contents}

    \previouspage qmake Manual

    \nextpage qmake Project Files

    \c qmake provides a project-oriented system for managing the build

    process for applications, libraries, and other components. This

    approach gives developers control over the source files used, and

    allows each of the steps in the process to be described concisely,

    typically within a single file. \c qmake expands the information in

    each project file to a Makefile that executes the necessary commands

    for compiling and linking.

    In this document, we provide a basic introduction to project files,

    describe some of the main features of \c qmake, and show how to use

    \c qmake on the command line.

    \section1 Describing a Project

    Projects are described by the contents of project (\c .pro) files.

    The information within these is used by \c qmake to generate a Makefile

    containing all the commands that are needed to build each project.

    Project files typically contain a list of source and header files,

    general configuration information, and any application-specific details,

    such as a list of extra libraries to link against, or a list of extra

    include paths to use.

    Project files can contain a number of different elements, including

    comments, variable declarations, built-in functions, and some simple

    control structures. In most simple projects, it is only necessary

    to declare the source and header files that are used to build the

    project with some basic configuration options.

    Complete examples of project files can be found in the

    \l{qmake Tutorial}.

    An introduction to project files can be found in the

    \l{qmake Project Files} chapter, and a more detailed description is

    available in the \l{qmake Reference}.

    \section1 Building a Project

    For simple projects, you only need to run \c qmake in the top

    level directory of your project. By default, \c qmake generates a

    Makefile that you then use to build the project, and you can then

    run your platform's \c make tool to build the project.

    \c qmake can also be used to generate project files. A full

    description of \c{qmake}'s command line options can be found in the

    \l{Running qmake} chapter of this manual.

    \section1 Using Precompiled Headers

    In large projects, it is possible to take advantage of precompiled

    header files to speed up the build process. This feature is described

    in detail in the \l{Using Precompiled Headers} chapter.

*/

/*!

    \page qmake-project-files.html

    \title qmake Project Files

    \contentspage {qmake Manual}{Contents}

    \previouspage Using qmake

    \nextpage Running qmake

    Project files contain all the information required by \c qmake to build

    your application, library, or plugin. The resources used by your project

    are generally specified using a series of declarations, but support for

    simple programming constructs allow you to describe different build

    processes for different platforms and environments.

    \tableofcontents

    \section1 Project File Elements

    The project file format used by \c qmake can be used to support both

    simple and fairly complex build systems. Simple project files will

    use a straightforward declarative style, defining standard variables

    to indicate the source and header files that are used in the project.

    Complex projects may use the control flow structures to fine-tune the

    build process.

    The following sections describe the different types of elements used

    in project files.

    \section2 Variables

    In a project file, variables are used to hold lists of strings.

    In the simplest projects, these variables inform \c qmake about the

    configuration options to use, or supply filenames and paths to use

    in the build process.

    \c qmake looks for certain variables in each project file, and it

    uses the contents of these to determine what it should write to a

    Makefile. For example, the list of values in the \c HEADERS and

    \c SOURCES variables are used to tell \c qmake about header and

    source files in the same directory as the project file.

    Variables can also be used internally to store temporary lists of values,

    and existing lists of values can be overwritten or extended with new

    values.

    The following lines show how lists of values are assigned to variables:

    \snippet doc/src/snippets/qmake/variables.pro 0

    Note that the first assignment only includes values that are specified on

    the same line as the \c SOURCES variable. The second assignment splits

    the items across lines by using the \c \\ character.

    The list of values in a variable is extended in the following way:

    \snippet doc/src/snippets/qmake/variables.pro 1

    The \c CONFIG variable is another special variable that \c qmake

    uses when generating a Makefile. It is discussed in the section on

    \l{#GeneralConfiguration}{general configuration} later in this chapter.

    In the above line, \c qt is added to the list of existing values

    contained in \c CONFIG.

    The following table lists the variables that \c qmake recognizes, and

    describes what they should contain.

    \table

    \header \o Variable \o Contents

    \row \o CONFIG    \o General project configuration options.

    \row \o DESTDIR   \o The directory in which the executable or binary file will

                      be placed.

    \row \o FORMS     \o A list of UI files to be processed by \c uic.

    \row \o HEADERS   \o A list of filenames of header (.h) files used when

                      building the project.

    \row \o QT        \o Qt-specific configuration options.

    \row \o RESOURCES \o A list of resource (.rc) files to be included in the

                      final project. See the \l{The Qt Resource System} for

                      more information about these files.

    \row \o SOURCES   \o A list of source code files to be used when building

                      the project.

    \row \o TEMPLATE  \o The template to use for the project. This determines

                      whether the output of the build process will be an

                      application, a library, or a plugin.

    \endtable

    The contents of a variable can be read by prepending the variable name with

    \c $$. This can be used to assign the contents of one variable to another:

    \snippet doc/src/snippets/qmake/dereferencing.pro 0

    The \c $$ operator is used extensively with built-in functions that operate

    on strings and lists of values. These are described in the chapter on

    \l{qmake Advanced Usage}.

    \section3 Whitespace

    Normally, variables are used to contain whitespace-separated lists

    of values. However, it is sometimes necessary to specify values containing

    spaces. These must be quoted by using the

    \l{qmake Function Reference#quote-string}{quote()} function in the following way:

    \snippet doc/src/snippets/qmake/quoting.pro 0

    The quoted text is treated as a single item in the list of values held by

    the variable. A similar approach is used to deal with paths that contain

    spaces, particularly when defining the

    \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} and

    \l{qmake Variable Reference#LIBS}{LIBS} variables for the Windows platform.

    In cases like these, the \l{qmake Function Reference#quote(string)}{quote()}

    function can be used in the following way:

    \snippet doc/src/snippets/qmake/spaces.pro quoting include paths with spaces

    \section2 Comments

    You can add comments to project files. Comments begin with the \c

    # character and continue to the end of the same line. For example:

    \snippet doc/src/snippets/qmake/comments.pro 0

    To include the \c # character in variable assignments, it is necessary

    to use the contents of the built-in \c LITERAL_HASH variable. See the

    \l{qmake Variable Reference#LITERAL_HASH}{variable reference} for more

    information.

    \section2 Built-in Functions and Control Flow

    \c qmake provides a number of built-in functions to allow the contents

    of variables to be processed. The most commonly used function in simple

    project files is the \c include function which takes a filename as an

    argument. The contents of the given file are included in the project

    file at the place where the \c include function is used.

    The \c include function is most commonly used to include other project

    files:

    \snippet doc/src/snippets/qmake/include.pro 0

    Support for conditional structures is made available via

    \l{qmake Advanced Usage#scopes}{scopes} that behave like \c if

    statements in programming languages:

    \snippet doc/src/snippets/qmake/scopes.pro 0

    The assignments inside the braces are only made if the condition is

    true. In this case, the special \c win32 variable must be set; this

    happens automatically on Windows, but this can also be specified on

    other platforms by running \c qmake with the \c{-win32} command line

    option (see \l{Running qmake} for more information). The opening

    brace must stand on the same line as the condition.

    Simple loops are constructed by iterating over lists of values using

    the built-in \c for function. The following code adds directories

    to the \l{qmake Variable Reference#SUBDIRS}{SUBDIRS} variable, but

    only if they exist:

    \snippet doc/src/snippets/qmake/functions.pro 0

    More complex operations on variables that would usually require loops

    are provided by built-in functions such as \c find, \c unique, and

    \c count. These functions, and many others are provided to manipulate

    strings and paths, support user input, and call external tools. A list

    of the functions available can be found in the

    \l{qmake Advanced Usage} chapter of this manual.

    \section1 Project Templates

    The \c TEMPLATE variable is used to define the type of project that will

    be built. If this is not declared in the project file, \c qmake assumes

    that an application should be built, and will generate an appropriate

    Makefile (or equivalent file) for the purpose.

    The types of project available are listed in the following table with

    information about the files that \c qmake will generate for each of them:

    \table

    \header \o Template      \o Description of \c qmake output

    \row    \o app (default) \o Creates a Makefile to build an application.

    \row    \o lib           \o Creates a Makefile to build a library.

    \row    \o subdirs       \o Creates a Makefile containing rules for the

    subdirectories specified using the \l{qmake Variable Reference#SUBDIRS}{SUBDIRS}

    variable. Each subdirectory must contain its own project file.

    \row    \o vcapp         \o Creates a Visual Studio Project file to build

                             an application.

    \row    \o vclib         \o Creates a Visual Studio Project file to build a library.

    \endtable

    See the \l{qmake Tutorial} for advice on writing project files for

    projects that use the \c app and \c lib templates.

    When the \c subdirs template is used, \c qmake generates a Makefile

    to examine each specified subdirectory, process any project file it finds

    there, and run the platform's \c make tool on the newly-created Makefile.

    The \l{qmake Variable Reference#SUBDIRS}{SUBDIRS} variable is used to

    contain a list of all the subdirectories to be processed.

    \target GeneralConfiguration

    \section1 General Configuration

    The \l{qmake Variable Reference#CONFIG}{CONFIG variable} specifies the

    options and features that the compiler should use and the libraries that

    should be linked against. Anything can be added to the \c CONFIG variable,

    but the options covered below are recognized by \c qmake internally.

    The following options control the compiler flags that are used to build the

    project:

    \table

    \header \o Option   \o Description

    \row    \o release  \o The project is to be built in release mode.

            This is ignored if \c debug is also specified.

    \row    \o debug    \o The project is to be built in debug mode.

    \row    \o debug_and_release \o The project is built in \e both debug and

            release modes.

    \row    \o debug_and_release_target \o The project is built in \e both debug 

    and release modes. TARGET is built into \e both the debug and release directories.

    \row    \o build_all \o If \c debug_and_release is specified, the project is

            built in both debug and release modes by default.

    \row    \o autogen_precompile_source \o Automatically generates a \c .cpp file that includes 

    the precompiled header file specified in the .pro file.

    \row    \o ordered  \o When using the \c subdirs template, this option

            specifies that the directories listed should be processed in the

            order in which they are given.

    \row    \o warn_on  \o The compiler should output as many warnings as possible.

            This is ignored if \c warn_off is specified.

    \row    \o warn_off \o The compiler should output as few warnings as possible.

    \row    \o copy_dir_files \o Enables the install rule to also copy directories, not just files.  

    \endtable

    The \c debug_and_release option is special in that it enables \e both debug and

    release versions of a project to be built. In such a case, the Makefile that

    \c qmake generates includes a rule that builds both versions, and this can be

    invoked in the following way:

    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 0

    Adding the \c build_all option to the \c CONFIG variable makes this rule

    the default when building the project, and installation targets will be

    created for both debug and release builds.

    Note that each of the options specified in the \c CONFIG variable can also be

    used as a scope condition.

    You can test for the presence of certain configuration options by using the

    built-in \l{qmake Function Reference#CONFIG(config)}{CONFIG()} function.

    For example, the following lines show the function as the condition in a scope

    to test whether only the \c opengl option is in use:

    \snippet doc/src/snippets/qmake/configscopes.pro 4

    \snippet doc/src/snippets/qmake/configscopes.pro 5

    This enables different configurations to be defined for \c release and

    \c debug builds, and is described in more detail in the

    \l{qmake Advanced Usage#Scopes}{Scopes} section of the

    \l{qmake Advanced Usage}{Advanced Usage} chapter of this manual.

    The following options define the type of project to be built. Note that some

    of these options only take effect when used on the relevant platform. On other

    platforms, they have no effect.

    \table

    \header \o Option \o Description

    \row    \o qt     \o The project is a Qt application and should link against the Qt

                      library. You can use the \c QT variable to control any additional

                      Qt modules that are required by your application.

    \row    \o thread \o The project is a multi-threaded application.

    \row    \o x11    \o The project is an X11 application or library.

    \endtable

    When using \l{qmake Variable Reference#TEMPLATE}{application or library project

    templates}, more specialized configuration options can be used to fine tune the

    build process. These are explained in details in the

    \l{qmake-common-projects.html}{Common Projects} chapter of this manual.

    For example, if your application uses the Qt library and you want to

    build it as a multi-threaded application in \c debug mode, your project

    file will contain the following line:

    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 1

    Note, that you must use "+=", not "=", or \c qmake will not be able to

    use Qt's configuration to determine the settings needed for your project.

    \section1 Declaring Qt Libraries

    If the \c CONFIG variable contains the \c qt value, qmake's support for Qt

    applications is enabled. This makes it possible to fine-tune which of the

    Qt modules are used by your application. This is achieved with the \c QT

    variable which can be used to declare the required extension modules.

    For example, we can enable the XML and network modules in the following way:

    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 2

    Note that \c QT includes the \c core and \c gui modules by default, so the

    above declaration \e adds the network and XML modules to this default list.

    The following assignment \e omits the default modules, and will lead to

    errors when the application's source code is being compiled:

    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 3

    If you want to build a project \e without the \c gui module, you need to

    exclude it with the "-=" operator. By default, \c QT contains both

    \c core and \c gui, so the following line will result in a minimal

    Qt project being built:

    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 4

    The table below shows the options that can be used with the \c QT variable

    and the features that are associated with each of them:

    \table

    \header \o Option                     \o Features

    \row    \o core (included by default) \o QtCore module

    \row    \o gui  (included by default) \o QtGui module

    \row    \o network                    \o QtNetwork module

    \row    \o opengl                     \o QtOpenGL module

    \row    \o sql                        \o QtSql module

    \row    \o svg                        \o QtSvg module

    \row    \o xml                        \o QtXml module

    \row    \o xmlpatterns                \o QtXmlPatterns module

    \row    \o qt3support                 \o Qt3Support module

    \endtable

    Note that adding the \c opengl option to the \c QT variable automatically

    causes the equivalent option to be added to the \c CONFIG variable.

    Therefore, for Qt applications, it is not necessary to add the \c opengl

    option to both \c CONFIG and \c{QT}.

    \section1 Configuration Features

    \c qmake can be set up with extra configuration features that are specified

    in feature (.prf) files. These extra features often provide support for

    custom tools that are used during the build process. To add a feature to

    the build process, append the feature name (the stem of the feature filename)

    to the \c CONFIG variable.

    For example, \c qmake can configure the build process to take advantage

    of external libraries that are supported by

    \l{http://www.freedesktop.org/wiki/Software_2fpkgconfig}{pkg-config},

    such as the D-Bus and ogg libraries, with the following lines:

    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 5

    More information about features can be found in the

    \l{qmake Advanced Usage#Adding New Configuration Features}

    {Adding New Configuration Features} section of the \l{qmake Advanced Usage}

    chapter.

    \section1 Declaring Other Libraries

    If you are using other libraries in your project in addition to those

    supplied with Qt, you need to specify them in your project file.

    The paths that \c qmake searches for libraries and the specific libraries

    to link against can be added to the list of values in the

    \l{qmake Variable Reference#LIBS}{LIBS} variable. The paths to the libraries

    themselves can be given, or the familiar Unix-style notation for specifying

    libraries and paths can be used if preferred.

    For example, the following lines show how a library can be specified:

    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 6

    The paths containing header files can also be specified in a similar way

    using the \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} variable.