source: trunk/doc/src/qmake-manual.qdoc@ 109

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qmake-manual.html
    \title qmake Manual
    \startpage {index.html}{Qt Reference Documentation}
    \nextpage qmake Tutorial

    \ingroup buildsystem
    \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}.

    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 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.

    \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.