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

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

    For example, it is possible to add several paths to be searched for header
    files:

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

/*!
    \page qmake-running.html
    \title Running qmake
    \contentspage {qmake Manual}{Contents}
    \previouspage qmake Project Files
    \nextpage qmake Platform Notes

    The behavior of \c qmake can be customized when it is run by
    specifying various options on the command line. These allow the
    build process to be fine-tuned, provide useful diagnostic
    information, and can be used to specify the target platform for
    your project.

    \tableofcontents

    \target Commands
    \section1 Command-Line Options

    \section2 Syntax

    The syntax used to run \c qmake takes the following simple form:

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

    \c qmake supports two different modes of operation: In the default mode,
    \c qmake will use the description in a project file to generate a Makefile,
    but it is also possible to use \c qmake to generate project files.
    If you want to explicitly set the mode, you must specify it before all
    other options. The \c mode can be either of the following two values:

    \list
    \o \c -makefile \BR
        \c qmake output will be a Makefile.
    \o \c -project \BR
        \c qmake output will be a project file.
    \endlist

    The following \c options are used to specify both general and mode-specific
    settings. Options that only apply to the Makefile mode are described in the
    \l{#MakefileMode}{Makefile Mode Options} section; options that influence the
    creation of project files are described in the
    \l{#ProjectMode}{Project File Options} section.

    The \c files argument represents a list of one or more project files, separated
    by spaces.

    \section2 Options

    A wide range of options can be specified on the command line to \c qmake in
    order to customize the build process, and to override default settings for
    your platform. The following basic options provide usage information, specify
    where \c qmake writes the output file, and control the level of debugging
    information that will be written to the console:

    \list
    \o \c -help \BR
        \c qmake will go over these features and give some useful help.
    \o \c -o file \BR
        \c qmake output will be directed to \e file. If this option
        is not specified, \c qmake will try to use a suitable file name for its
        output, depending on the mode it is running in.\BR
        If '-' is specified, output is directed to stdout.
    \o \c -d \BR
        \c qmake will output debugging information.
    \endlist

    For projects that need to be built differently on each target platform, with
    many subdirectories, you can run \c qmake with each of the following
    options to set the corresponding platform-specific variable in each
    project file:

    \list
    \o \c -unix \BR
        \c qmake will run in unix mode.  In this mode, Unix file
        naming and path conventions will be used, additionally testing for \c unix
        (as a scope) will succeed. This is the default mode on all Unices.
    \o \c -macx \BR
        \c qmake will run in Mac OS X mode.  In this mode, Unix file
        naming and path conventions will be used, additionally testing for \c macx
        (as a scope) will succeed. This is the default mode on Mac OS X.
    \o \c -win32 \BR
        \c qmake will run in win32 mode.  In this mode, Windows file naming and path
        conventions will be used, additionally testing for \c win32 (as a scope)
        will succeed. This is the default mode on Windows.
    \endlist

    The template used for the project is usually specified by the \c TEMPLATE
    variable in the project file. We can override or modify this by using the
    following options:

    \list
    \o \c -t tmpl \BR
        \c qmake will override any set \c TEMPLATE variables with tmpl, but only
        \e after the .pro file has been processed.
    \o \c -tp prefix \BR
        \c qmake will add the prefix to the \c TEMPLATE variable.
    \endlist

    The level of warning information can be fine-tuned to help you find problems in
    your project file:

    \list
    \o \c -Wall \BR
          \c qmake will report all known warnings.
    \o \c -Wnone \BR
          No warning information will be generated by \c qmake.
    \o \c -Wparser \BR
          \c qmake will only generate parser warnings. This will alert
          you to common pitfalls and potential problems in the parsing of your
          project files.
    \o \c -Wlogic \BR
          \c qmake will warn of common pitfalls and potential problems in your
          project file. For example, \c qmake will report whether a file is placed
          into a list of files multiple times, or if a file cannot be found.
    \endlist

    \target MakefileMode
    \section2 Makefile Mode Options

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

    In Makefile mode, \c qmake will generate a Makefile that is used to build the
    project. Additionally, the following options may be used in this mode to
    influence the way the project file is generated:

    \list
    \o \c -after \BR
       \c qmake will process assignments given on the command line after
       the specified files.
    \o \c -nocache \BR
       \c qmake will ignore the .qmake.cache file.
    \o \c -nodepend \BR
       \c qmake will not generate any dependency information.
    \o \c -cache file \BR
       \c qmake will use \e file as the cache file, ignoring any other
       .qmake.cache files found.
    \o \c -spec spec \BR
       \c qmake will use \e spec as a path to platform and compiler information,
       and the value of \c QMAKESPEC will be ignored.
    \endlist

    You may also pass \c qmake assignments on the command line;
    they will be processed before all of the files specified. For example:

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

    This will generate a Makefile, from test.pro with Unix pathnames.  However
    many of the specified options aren't necessary as they are the default.
    Therefore, the line can be simplified on Unix to:

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

    If you are certain you want your variables processed after the
    files specified, then you may pass the \c -after option. When this
    is specified, all assignments on the command line after the \c -after
    option will be postponed until after the specified files are parsed.

    \target ProjectMode
    \section2 Project Mode Options

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

    In project mode, \c qmake will generate a project file. Additionally, you
    may supply the following options in this mode:

    \list
    \o \c -r \BR
       \c qmake will look through supplied directories recursively
    \o \c -nopwd \BR
       \c qmake will not look in your current working directory for
       source code and only use the specified \c files
    \endlist

    In this mode, the \c files argument can be a list of files or directories.
    If a directory is specified, it will be included in the \c DEPENDPATH
    variable, and relevant code from there will be included in the generated
    project file. If a file is given, it will be appended to the correct
    variable, depending on its extension; for example, .ui files are added
    to \c FORMS, and .cpp files are added to \c SOURCES.

    You may also pass assignments on the command line in this mode. When doing
    so, these assignments will be placed last in the generated project file.
*/

/*!
    \page qmake-platform-notes.html
    \title qmake Platform Notes
    \contentspage {qmake Manual}{Contents}
    \previouspage Running qmake
    \nextpage qmake Advanced Usage

    Many cross-platform projects can be handled by the \c{qmake}'s basic
    configuration features. On some platforms, it is sometimes useful, or even
    necessary, to take advantage of platform-specific features. \c qmake knows
    about many of these features, and these can be accessed via specific
    variables that only have an effect on the platforms where they are relevant.

    \tableofcontents

    \section1 Mac OS X

    Features specific to this platform include support for creating universal
    binaries, frameworks and bundles.

    \section2 Source and Binary Packages

    The version of \c qmake supplied in source packages is configured slightly
    differently to that supplied in binary packages in that it uses a different
    feature specification. Where the source package typically uses the
    \c macx-g++ specification, the binary package is typically configured to
    use the \c macx-xcode specification.

    Users of each package can override this configuration by invoking \c qmake
    with the \c -spec option (see \l{Running qmake} for more information). This
    makes it possible, for example, to use \c qmake from a binary package to
    create a Makefile in a project directory with the following command line
    invocation:

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

    \section2 Using Frameworks

    \c qmake is able to automatically generate build rules for linking against
    frameworks in the standard framework directory on Mac OS X, located at
    \c{/Library/Frameworks/}.

    Directories other than the standard framework directory need to be specified
    to the build system, and this is achieved by appending linker options to the
    \l{qmake Variable Reference#QMAKE_LFLAGS}{QMAKE_LFLAGS} variable, as shown
    in the following example:

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

    The framework itself is linked in by appending the \c{-framework} options and
    the name of the framework to the \l{qmake Variable Reference#LIBS}{LIBS}
    variable:

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

    \section2 Creating Frameworks

    Any given library project can be configured so that the resulting library
    file is placed in a
    \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html}
    {framework}, ready for deployment. To do this, set up the project to use the
    \l{qmake Variable Reference#TEMPLATE}{\c lib template} and add the
    \c lib_bundle option to the
    \l{qmake Variable Reference#CONFIG}{CONFIG} variable:

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

    The data associated with the library is specified using the
    \l{qmake Variable Reference#QMAKE_BUNDLE_DATA}{QMAKE_BUNDLE_DATA}
    variable. This holds items that will be installed with a library
    bundle, and is often used to specify a collection of header files,
    as in the following example:

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

    Here, the \c FRAMEWORK_HEADERS variable is a user-defined variable that
    is used to define the headers required to use a particular framework.
    Appending it to the \c QMAKE_BUNDLE_DATA variable ensures that the
    information about these headers are added to the collection of
    resources that will be installed with the library bundle. Also, the
    framework's name and version are specified by
    \l{qmake Variable Reference#QMAKE_FRAMEWORK_BUNDLE_NAME}
    {QMAKE_FRAMEWORK_BUNDLE_NAME}
    and \l{qmake Variable Reference#QMAKE_FRAMEWORK_VERSION}
    {QMAKE_FRAMEWORK_VERSION} variables. By default, the values used for
    these are obtained from the \l{qmake Variable Reference#TARGET}{TARGET}
    and \l{qmake Variable Reference#VERSION}{VERSION} variables.

    See \l{Deploying an Application on Mac OS X} for more information about
    deploying applications and libraries.

    \section2 Creating Universal Binaries

    To create a universal binary for your application, you need to be using
    a version of Qt that has been configured with the \c{-universal} option.

    The architectures to be supported in the binary are specified with the
    \l{qmake Variable Reference#CONFIG}{CONFIG} variable. For example, the
    following assignment causes \c qmake to generate build rules to create
    a universal binary for both PowerPC and x86 architectures:

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

    Additionally, developers using a PowerPC-based platform need to set the
    \l{qmake Variable Reference#QMAKE_MAC_SDK}{QMAKE_MAC_SDK} variable.
    This process is discussed in more detail in the
    \l{Deploying an Application on Mac OS X#Architecture Dependencies}{deployment guide for Mac OS X}.

    \section2 Creating and Moving Xcode Projects

    Developers on Mac OS X can take advantage of \c{qmake}'s support for Xcode
    project files, as described in
    \l{Qt is Mac OS X Native#Development Tools}{Qt is Mac OS X Native},
    by running \c qmake to generate an Xcode project from an existing \c qmake
    project files. For example:

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

    Note that, if a project is later moved on the disk, \c qmake must be run
    again to process the project file and create a new Xcode project file.

    \section1 Windows

    Features specific to this platform include support for creating Visual
    Studio project files and handling manifest files when deploying Qt
    applications developed using Visual Studio 2005.

    \section2 Creating Visual Studio Project Files

    Developers using Visual Studio to write Qt applications can use the
    Visual Studio integration facilities provided with the
    \l{Qt Commercial Editions} and do not need to worry about how
    project dependencies are managed.

    However, some developers may need to import an existing \c qmake project
    into Visual Studio. \c qmake is able to take a project file and create a
    Visual Studio project that contains all the necessary information required
    by the development environment. This is achieved by setting the \c qmake
    \l{qmake Variable Reference#TEMPLATE}{project template} to either \c vcapp
    (for application projects) or \c vclib (for library projects).

    This can also be set using a command line option, for example:

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

    It is possible to recursively generate \c{.vcproj} files in subdirectories
    and a \c{.sln} file in the main directory, by typing:

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


    Each time you update the project file, you need to run \c qmake to generate
    an updated Visual Studio project.

    \section2 Visual Studio 2005 Manifest Files

    When deploying Qt applications built using Visual Studio 2005, it is
    necessary to ensure that the manifest file, created when the application
    was linked, is handled correctly. This is handled automatically for
    projects that generate DLLs.

    Removing manifest embedding for application executables can be done with
    the following assignment to the \l{qmake Variable Reference#CONFIG}
    {CONFIG} variable:

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

    Also, the manifest embedding for DLLs can be removed with the following
    assignment to the \l{qmake Variable Reference#CONFIG}{CONFIG} variable:

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

    This is discussed in more detail in the
    \l{Deploying an Application on Windows#Visual Studio 2005 Onwards}
    {deployment guide for Windows}.
*/

/*!
    \page qmake-reference.html
    \title qmake Reference
    \contentspage {qmake Manual}{Contents}
    \previouspage Using Precompiled Headers
    \nextpage qmake Variable Reference

    This reference is a detailed index of all the variables and function
    that are available for use in \c qmake project files.

    \section1 Variable Reference

    The \l{qmake Variable Reference} describes the variables that are
    recognized by \c qmake when configuring the build process for
    projects.

    \section1 Function Reference

    The \l{qmake Function Reference} describes the function that can be
    used to process the contents of variables defined in project files.

    \target FrequentlyUsedVariables
    \section1 Frequently Used Variables

    The following variables are frequently used in project files to describe
    common aspects of the build process. These are fully described in the
    \l{qmake-variable-reference.html}{Variable Reference}.

    \list
    \o \l{qmake Variable Reference#CONFIG}{CONFIG}
    \o \l{qmake Variable Reference#DEF_FILE}{DEF_FILE}
    \o \l{qmake Variable Reference#DEFINES}{DEFINES}
    \o \l{qmake Variable Reference#DESTDIR}{DESTDIR}
    \o \l{qmake Variable Reference#DISTFILES}{DISTFILES}
    \o \l{qmake Variable Reference#DLLDESTDIR}{DLLDESTDIR}
    \o \l{qmake Variable Reference#FORMS}{FORMS}
    \o \l{qmake Variable Reference#FORMS3}{FORMS3}
    \o \l{qmake Variable Reference#GUID}{GUID}
    \o \l{qmake Variable Reference#HEADERS}{HEADERS}
    \o \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH}
    \o \l{qmake Variable Reference#LEXSOURCES}{LEXSOURCES}
    \o \l{qmake Variable Reference#LIBS}{LIBS}
    \o \l{qmake Variable Reference#MOC_DIR}{MOC_DIR}
    \o \l{qmake Variable Reference#OBJECTS_DIR}{OBJECTS_DIR}
    \o \l{qmake Variable Reference#QT}{QT}
    \o \l{qmake Variable Reference#RCC_DIR}{RCC_DIR}
    \o \l{qmake Variable Reference#REQUIRES}{REQUIRES}
    \o \l{qmake Variable Reference#SOURCES}{SOURCES}
    \o \l{qmake Variable Reference#SUBDIRS}{SUBDIRS}
    \o \l{qmake Variable Reference#TARGET}{TARGET}
    \o \l{qmake Variable Reference#TEMPLATE}{TEMPLATE}
    \o \l{qmake Variable Reference#TRANSLATIONS}{TRANSLATIONS}
    \o \l{qmake Variable Reference#UI_DIR}{UI_DIR}
    \o \l{qmake Variable Reference#UI_HEADERS_DIR}{UI_HEADERS_DIR}
    \o \l{qmake Variable Reference#UI_SOURCES_DIR}{UI_SOURCES_DIR}
    \o \l{qmake Variable Reference#VERSION}{VERSION}
    \o \l{qmake Variable Reference#YACCSOURCES}{YACCSOURCES}
    \endlist

    \section1 Environment Variables and Configuration

    The \l{Configuring qmake's Environment} chapter of this manual
    describes the environment variables that \c qmake uses when
    configuring the build process.
*/

/*!
    \page qmake-variable-reference.html
    \title qmake Variable Reference
    \contentspage {qmake Manual}{Contents}
    \previouspage qmake Reference
    \nextpage qmake Function Reference

    \c{qmake}'s fundamental behavior is influenced by variable declarations that
    define the build process of each project. Some of these declare resources,
    such as headers and source files, that are common to each platform; others
    are used to customize the behavior of compilers and linkers on specific
    platforms.

    Platform-specific variables follow the naming pattern of the
    variables which they extend or modify, but include the name of the relevant
    platform in their name. For example, \c QMAKE_LIBS can be used to specify a list
    of libraries that a project needs to link against, and \c QMAKE_LIBS_X11 can be
    used to extend or override this list.

    \tableofcontents{3}

    \target CONFIG
    \section1 CONFIG