/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the Qt Build Suite.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** 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, Digia gives you certain additional
** rights.  These rights are described in the Digia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************


/*!
    \contentspage{index.html}{Qt Build Suite}
    \page index.html
    \nextpage overview.html

    \title Qbs Manual

    \section1 Version \qbsversion

    Qt Build Suite (Qbs) is a tool that helps simplify the build process for
    developing projects across multiple platforms. Qbs can be used for any
    software project, whether it is written in Qt or not.

    Qbs is an all-in-one tool that generates a build graph from a high-level
    project description (like qmake or cmake) and additionally undertakes the
    task of executing the commands in the low-level build graph (like make).

    \note Please report bugs and suggestions to the
    \l{http://bugreports.qt-project.org/}{Qt Bug Tracker}.

    \list
       \li  \l{Introducing Qbs}
       \li  \l{Setting Up Qbs}
           \list
               \li  \l{System Requirements}
               \li  \l{Building Qbs}
               \li  \l{Configuring Qbs}
               \li  \l{Managing Qt Versions}
           \endlist
       \li  \l{Using Qbs}
           \list
               \li  \l{Language Introduction}
               \li  \l{Building Applications with Qbs}
               \li  \l{Running Applications}
               \li  \l{Installing Files}
               \li  \l{Using Qbs Shell}
           \endlist
       \li  \l{Reference}
           \list
               \li  \l{Module qbs}
               \li  \l{Module cpp}
               \li  \l{Export Item}
               \li  \l{FileTagger Item}
               \li  \l{Group Item}
               \li  \l{Product Item}
               \li  \l{Project Item}
               \li  \l{SubProject Item}
               \li  \l{Properties Item}
               \li  \l{Rule Item}
               \li  \l{Transformer Item}
           \endlist
    \endlist
*/


/*!
    \contentspage index.html
    \previouspage index.html
    \page overview.html
    \nextpage setup.html

    \title Introducing Qbs

    Qbs builds applications based on the information in a project file that you
    specify in a QML dialect. Each project file specifies one project that can
    contain several products. You specify the type of the product: application,
    library, and so on.
*/


/*!
    \contentspage index.html
    \previouspage overview.html
    \page setup.html
    \nextpage system-requirements.html

    \title Setting Up Qbs

    \list
        \li  \l{System Requirements}
        \li  \l{Building Qbs}
        \li  \l{Configuring Qbs}
        \li  \l{Managing Qt Versions}
    \endlist
*/


/*!
    \contentspage index.html
    \previouspage setup.html
    \page system-requirements.html
    \nextpage building.html

    \title System Requirements

    To build Qbs from the source, you need the following:

    \list

        \li  Qt 4.8

    \endlist

*/


/*!
    \contentspage index.html
    \previouspage system-requirements.html
    \page building.html
    \nextpage configuring.html

    \title Building Qbs

    To build Qbs:

    \list 1

        \li  Enter the following command:
            \c {qmake -r qbs.pro && make}

    \endlist

*/


/*!
    \contentspage index.html
    \previouspage building.html
    \page configuring.html
    \nextpage qt-versions.html

    \title Configuring Qbs

    When you run Qbs from an in-source build, most paths are set up
    automatically. If you do not build in-source, configure the following
    paths:

    \code
    QBS_SOURCE_DIR=/path/to/qbs-source
    QBS_BUILD_DIR=/path/to/qbs-build
    qbs config preferences.qbsPath $QBS_SOURCE_DIR/share/qbs
    qbs config preferences.pluginsPath $QBS_BUILD_DIR/plugins
    \endcode

    Currently, you also must tell Qbs where it can find Qt.
    Please refer to \l{Managing Qt Versions} to set up your Qt builds.

    Open a build shell (on Windows open an MSVC command prompt,
    on other platforms you can usually open the default shell):
    \code
    qbs detect-toolchains
    \endcode

    The tool chain detector automatically sets up a profile for each detected tool chain.
    You can list the existing profiles by running:
    \code
    qbs config --list profiles
    \endcode

    Now you should be ready to build your first project with Qbs.
    Go into qbs/tests/manual/hello and type:

    \code
    qbs
    \endcode
*/

/*!
    \contentspage index.html
    \previouspage configuring.html
    \page qt-versions.html
    \nextpage usage.html

    \title Managing Qt Versions

    \section1 Introduction

    To let Qbs know where the Qt build or Qt version is that you want to use,
    you must register it.

    Register a Qt version like this:
    \code
    qbs setup-qt /usr/bin/qmake myqt
    \endcode

    This will create the \c myqt profile which can then be used on
    the command line:

    \code
    qbs profile:myqt
    \endcode


    \section1 Manual Setup

    Everything that the setup-qt tool does can be done manually, as described in this section.

    Here is an example for registering Qt, installed on Ubuntu GNU/Linux, again using a profile
    called \c myqt:

    \code
    qbs config profiles.myqt.Qt.core.binPath /usr/bin
    qbs config profiles.myqt.Qt.core.incPath /usr/include/qt4
    qbs config profiles.myqt.Qt.core.libPath /usr/lib/x86_64-linux-gnu
    qbs config profiles.myqt.Qt.core.mkspecPath /usr/share/qt4/mkspecs/linux-g++
    \endcode

    If you are using Qt 5, you must specify the version number like this:
    \code
    qbs config profiles.myqt.Qt.core.version 5.0.0
    \endcode

    \section1 Multiple Qt Builds

    To support multiple Qt builds, or in fact any combination of related settings, you need to
    create several profiles. The following example illustrates how to set up
    three different profiles, each for a different Qt build:

    \code
    qbs setup-qt ~/dev/qt/4.7/bin/qmake qt47
    qbs setup-qt ~/dev/qt/4.8/bin/qmake qt48
    qbs setup-qt ~/dev/qt/5.0/qtbase/bin/qmake qt5
    \endcode

    You can set the default Qt build like this:

    \code
    qbs config defaultProfile qt5
    \endcode

    To choose a Qt build that is different from the default, use:

    \code
    qbs build profile:qt48
    \endcode

    You can set other properties in a profile (not just Qt ones), in the same way
    you could override them from the command line. For example:

    \code
    qbs setup-qt C:\Qt\5.0.0\qtbase\bin\qmake.exe qt5
    qbs config profiles.qt5.qbs.architecture x86_64
    qbs config profiles.qt5.baseProfile msvc2010
    \endcode

    The last example uses the inheritance feature of profiles. All settings in the profile
    set as \c baseProfile are known in the derived profile as well.
    They can of course be overridden there.

    \section1 Customized Qt Settings

    If you have built your Qt with the option \c {-qtnamespace MyNamespace}
    then you must set the following \c config value:

    \code
    qbs config profiles.myqt.Qt.core.namespace MyNamespace
    \endcode

    The same goes for the -qtlibinfix option.

    \code
    qbs config profiles.myqt.Qt.core.libInfix MyInfix
    \endcode
*/

/*!
    \contentspage index.html
    \previouspage qt-versions.html
    \page usage.html
    \nextpage language-introduction.html

    \title Using Qbs

    \list
        \li  \l{Language Introduction}
        \li  \l{Building Applications with Qbs}
        \li  \l{Running Applications}
        \li  \l{Installing Files}
        \li  \l{Using Qbs Shell}
    \endlist

*/


/*!
    \contentspage index.html
    \previouspage usage.html
    \page language-introduction.html
    \nextpage building-applications.html

    \title Language Introduction

    Qbs uses project files (*.qbs) to describe the contents of a project.
    A project contains one or more \e products. A product is the target of a build
    process, typically an application, library or maybe a tar ball.

    \section1 The Obligatory Hello World Example

    The project files in this example are written using a QML dialect.
    A very simple C++ hello world project looks like this:
    \code ---helloworld.qbs---
        import qbs 1.0

        Application {
            name: "helloworld"
            files: "main.cpp"
            Depends { name: "cpp" }
        }
    \endcode

    The import statement gives us access to some built-in types and specifies the
    used language version.

    \a Application describes the product we want to build. In this case, an
    application. This is just a shortcut for writing
    \code
        Product {
            type: "application"
            // ...
        }
    \endcode

    The \a name is the name of the product. In this case it is also the
    name of the produced executable.
    In the property \a files, we specify the source files for our product.
    Unlike QML, the right-hand side can be either a string or a string list.
    A single string is converted to a stringlist containing just one element.

    \a Depends adds the dependency to the module \a{cpp}. This is necessary to let Qbs know that
    we have a C++ project and want to compile main.cpp with a C++ compiler. For more information
    about Qbs modules, see \l{Modules}.


    \section1 Reusing Qbs Project File Code
    QML-like inheritance works also in Qbs.

    \code
    ---CrazyProduct.qbs---
    import qbs 1.0

    Product {
        property string craziness: "low"
    }

    ---hellocrazyworld.qbs---
    CrazyProduct {
        craziness: "enormous"
        name: "hellocrazyworld"
        // ...
    }
    \endcode

    You can put JS code into separate \c{.js} files and then import them.
    \code
    ---helpers.js---
    function planetsCorrectlyAligned()
    {
        // implementation
    }

    ---myproject.qbs---
    import qbs 1.0
    import "helpers.js" as Helpers

    Product {
        name: "myproject"
        Group {
            condition: Helpers.planetsCorrectlyAligned()
            file: "magic_hack.cpp"
        }
        // ...
    }
    \endcode


    \section1 Modules

    A \e module is a collection of properties and language items that are used for
    building a product if the product depends on (or loads) the module.

    For example, the \a cpp module looks like this (simplified):
    \code
    Module {
        name: "cpp"
        property string warningLevel
        property string optimization
        property bool debugInformation
        property path precompiledHeader
        // ...
        FileTagger {
            pattern: "*.cpp"
            fileTags: ["cpp"]
        }
        Rule {...}  // compiler
        Rule {...}  // application linker
        Rule {...}  // static lib linker
        Rule {...}  // dynamic lib linker
    }
    \endcode

    The properties that can be set for the \a cpp module are used to control the behavior of
    your C++ tool chain.
    In addition, you can use FileTaggers and Rules that are explained later.

    As soon as your product depends on a module, it can set the properties of the
    module. You specify the optimization level for your product (and all build variants) like this:

    \code ---helloworld.qbs---
        import qbs 1.0

        Application {
            name: "helloworld"
            files: ["main.cpp"]
            cpp.optimization: "ludicrousSpeed"
            Depends { name: "cpp" }
        }
    \endcode

    A module can implicitly depend on other modules. For example, the \c Qt.core module depends
    on \c{cpp}. But to set the properties of a module you must explicitly import
    it.

    \code
        // THIS DOES NOT WORK
        Application {
            name: "helloworld"
            files: ["main.cpp"]
            Depends { name: "Qt.core" }
            cpp.optimization: "ludicrousSpeed"
            // ERROR! We do not know about "cpp" here,
            // though "Qt.core" depends on "cpp".
        }

        // THIS WORKS
        Application {
            name: "helloworld"
            files: ["main.cpp"]
            Depends { name: "Qt.core" }
            Depends { name: "cpp" }
            cpp.optimization: "ludicrousSpeed"
        }
    \endcode

    \section2 Different Properties for a Single File

    Not only the product, but all the source files of the product can have their own
    set of module properties. For example, assume you have some files that are known to crash
    your compiler if you turn on optimizations. You want to turn off
    optimizations for just these files and this is how you do it:

    \code
        Application {
            name: "helloworld"
            files: "main.cpp"
            Group {
                files: ["bad_file.cpp", "other_bad_file.cpp"]
                cpp.optimization: "none"
            }
            Depends { name: "cpp" }
        }
    \endcode

    \section2 Selecting Files by Properties

    The classical (pre-lighthouse) Qt case is that you have a file that is only going to
    be compiled on a certain platform. This is how you do it:
    \code
        Group {
            condition: qbs.targetOS.contains("windows")
            files: [
                "harddiskdeleter_win.cpp",
                "blowupmonitor_win.cpp",
                "setkeyboardonfire_win.cpp"
            ]
        }
        Group {
            condition: qbs.targetOS.contains("linux")
            files: [
                "harddiskdeleter_linux.cpp",
                "blowupmonitor_linux.cpp",
                "setkeyboardonfire_linux.cpp"
            ]
        }
    \endcode

    In the above example, \a qbs.targetOS is a property of the \a target of the the \a qbs
    module. The \a qbs module is always implicitly loaded. Its main properties
    are:

    \table
    \header
        \li Property
        \li Type
        \li Default
        \li Description
    \row
        \li buildVariant
        \li string
        \li "debug"
        \li Name of the current build variant. By default, "debug" and "release"
        are valid values but the user can add more in a project file.
    \row
        \li hostOS
        \li stringlist
        \li platform-dependent
        \li The host operating system.
            May contain "windows", "linux", "osx", "darwin", "unix", etc.
    \row
        \li targetOS
        \li stringlist
        \li platform-dependent
        \li The target operating system.
            May contain "windows", "linux", "osx", "darwin", "unix",
            "ios", "android", "blackberry", "qnx", etc.
    \endtable

    You can set these properties on the command line or by using a profile. The property \a
    qbs.buildVariant is handled in a special way.

    \code
    $ qbs                   # qbs.buildVariant:debug, profile:<default profile>
    $ qbs release           # qbs.buildVariant:release, profile:<default profile>
    $ qbs profile:Maemo     # qbs.buildVariant:debug, profile:Maemo
    $ qbs debug release     # builds two variants of the project
    \endcode

    To select files by build variant:
    \code
        Group {
            condition: qbs.buildVariant == "debug"
            files: "debughelper.cpp"
        }
    \endcode

    To set properties for a build variant:
    \code
        Properties {
            condition: qbs.buildVariant == "debug"
            cpp.debugInformation: true
            cpp.optimization: "none"
        }
    \endcode
    Or, to use a more QML-like style:
    \code
        cpp.debugInformation: qbs.buildVariant == "debug" ? true : false
        cpp.optimization: qbs.buildVariant == "debug" ? "none" : "fast"
    \endcode


    \section1 File Tags and Taggers

    Qbs itself knows nothing about C++ files or file extensions. All source files
    in a product are handled equally. However, you can assign \a{file tags} to an artifact
    to act as a marker or to specify a file type.

    An artifact can have multiple file tags.
    For example, you can use the \a Group item to group files with the same file tags (or a set of
    properties).

    \code
        Product {
            Group {
                files: ["file1.cpp", "file2.cpp"]
                fileTags: ["cpp"]
            }
            Group {
                files: "mydsl_scanner.l"
                fileTags: ["flex", "foobar"]
            }
            // ...
        }
    \endcode

    When you load the \a cpp module, you also load the following item:
    \code
        FileTagger {
            pattern: "*.cpp"
            fileTags: ["cpp"]
        }
    \endcode
    This construct means that each source file that matches the p *.cpp (and
    has not explicitly set a file tag) gets the file tag \c{cpp}.

    The above example can be simplified to
    \code
        Product {
            Depends: "cpp"
            files: ["file1.cpp", "file2.cpp"]
            Group {
                files: "mydsl_scanner.l"
                fileTags: ["flex", "foobar"]
            }
            // ...
        }
    \endcode

    The \a FileTagger from the \a cpp module automatically assigns the \c cpp
    file tag to the source files. Groups that just contain the \a files
    property can be simply expressed by using the \a files property of the product.

    File tags are used by \a rules to transform one type of artifact into
    another. For instance, the C++ compiler rule transforms artifacts with the file tag
    \c cpp to artifacts with the file tag \c{obj}.

    In addition, it is possible to use file taggers to tag files and specify custom file tags:
    \code
        Product {
            Depends: "cpp"
            files: ["main.cpp"]         // Gets the file tag "cpp" through a FileTagger item.
            Group {
                overrideTags: false     // The overrideTags property defaults to true.
                files: ["main.cpp"]
                fileTags: ["foobar"]    // Gets the file tag "foobar" in addition to "cpp".
            }
            // ...
        }
    \endcode

    \section1 Rules

    Qbs applies a \e rule to a pool of artifacts (in the beginning it is just the set of
    source files of the project) and chooses the ones that match the input file
    tags specified by the rule. Then it creates output artifacts in the build graph that have other
    filenames and file tags. It also creates a script that transforms the input artifact into the
    output artifact.

    For examples of rules, see the share/qbs/modules directory in the Qbs
    repository.

    You can define rules in your own module to be provided along with
    your project. Or you can put a rule directly into your project file.

    For more information, see \l{Rule Item}.
*/


/*!
    \contentspage index.html
    \previouspage language-introduction.html
    \page building-applications.html
    \nextpage running-applications.html

    \title Building Applications with Qbs

    To build applications from the command line, enter the following commands:

    \code
    cd tests/manual/collidingmice
    qbs
    \endcode

    The application is built for the default target, which is the system on the
    development PC. To build for other targets, specify options for the build
    command. For example, to build debug and release configurations for the
    default target and the Symbian target in parallel, enter the following
    command:

    \code
    qbs build debug release profile:Symbian
    \endcode

    This assumes you have already set up a profile called "Symbian".
*/

/*!
    \contentspage index.html
    \previouspage running-applications.html
    \page installing-files.html
    \nextpage shell.html

    \title Installing Files

    To install your project, specify the necessary information in the project file:

    \code
    Application {
        Group {
            name: "Runtime resources"
            files: "*.qml"
            qbs.install: true
            qbs.installDir: "share/myproject"
        }
        Group {
            name: "The App itself"
            fileTagsFilter: "application"
            qbs.install: true
            qbs.installDir: "bin"
        }
    }
    \endcode

    In this example, we want to install a couple of QML files and an executable.
    The actual installation is then done like this (using the default profile):

    \code
    qbs install --install-root /tmp/myProjectRoot --remove-first
    \endcode

    Here, we want the "installDir" properties from the project file to be interpreted relative
    to the directory "/tmp/myProjectRoot", and we want that directory to be removed first.
    If the "--install-root" option is not given, a default is used, namely "<build root>/install-root".
    Qbs understands the special install root value "@sysroot", which stands for the value of
    the property qbs.sysroot.
*/

/*!
    \contentspage index.html
    \previouspage building-applications.html
    \page running-applications.html
    \nextpage installing-files.html

    \title Running Applications

    Running ./targets/debug/CollidingMice fails if Qt 4.8 is not in your PATH
    (in Windows) or LD_LIBRARY_PATH (in Linux).

    Therefore, enter the following command to run an application:

    \code
    qbs run --products CollidingMice
    \endcode

    This command also builds and installs the given product, if necessary.
*/


/*!
    \contentspage index.html
    \previouspage installing-files.html
    \page shell.html
    \nextpage reference.html

    \title Using Qbs Shell

    To use the Qbs shell, enter the following command:

    \code
    qbs shell
    \endcode

*/


/*!
    \contentspage index.html
    \previouspage shell.html
    \page reference.html
    \nextpage module-qbs.html

    \title Reference

    \list
        \li \l{Module qbs}
        \li \l{Module cpp}
        \li \l{Export Item}
        \li \l{FileTagger Item}
        \li \l{Group Item}
        \li \l{Product Item}
        \li \l{Project Item}
        \li \l{SubProject Item}
        \li \l{Properties Item}
        \li \l{Rule Item}
        \li \l{Transformer Item}
    \endlist
*/


/*!
    \contentspage index.html
    \previouspage reference.html
    \page module-qbs.html
    \nextpage module-cpp.html

    \title Module qbs

    The \c qbs module is implicitly loaded in every product. It contains properties of the current
    build environment, independent of the used programming languages and toolchains.


    \section1 buildVariant

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{"debug"}
    \endtable

    Contains the name of the build variant for the current build.


    \section1 debugInformation

    \table
    \row    \li \b{Type:}     \li \c bool
    \row    \li \b{Default:}  \li \c{true} for debug builds, \c{false} otherwise
    \endtable

    Specifies whether to generate debug information.


    \section1 enableDebugCode

    \table
    \row    \li \b{Type:}     \li \c bool
    \row    \li \b{Default:}  \li \c{true} for debug builds, \c{false} otherwise
    \endtable

    Specifies whether to compile debug code in the product.
    This is typically enabled for debug builds and disabled for release builds.


    \section1 optimization

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Allowed Values:}  \li \c{"none"}, \c{"fast"}, \c{"small"}
    \row    \li \b{Default:}         \li \c{"none"} for debug builds, \c{"fast"} for release builds
    \endtable

    Specifies the general type of optimization that should be performed by all toolchains.


    \section1 hostOS

    \table
    \row    \li \b{Type:}            \li \c{stringList} (read only)
    \endtable

    This property is set by qbs internally and specifies the OS qbs is running on.
    The possible values for this property are the values of \c targetOS,
    though some may not be supported.


    \section1 targetOS

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Possible Values:} \li one or more of:
            \c{"aix"},
            \c{"android"},
            \c{"blackberry"},
            \c{"bsd"},
            \c{"bsd4"},
            \c{"bsdi"},
            \c{"cygwin"},
            \c{"darwin"},
            \c{"dgux"},
            \c{"dynix"},
            \c{"freebsd"},
            \c{"hpux"},
            \c{"hurd"},
            \c{"integrity"},
            \c{"ios"},
            \c{"ios-simulator"},
            \c{"irix"},
            \c{"linux"},
            \c{"lynx"},
            \c{"osx"},
            \c{"msdos"},
            \c{"nacl"},
            \c{"netbsd"},
            \c{"openbsd"},
            \c{"os2"},
            \c{"os2emx"},
            \c{"osf"},
            \c{"qnx"},
            \c{"qnx6"},
            \c{"reliant"},
            \c{"sco"},
            \c{"solaris"},
            \c{"symbian"},
            \c{"ultrix"},
            \c{"unix"},
            \c{"unixware"},
            \c{"vxworks"},
            \c{"windows"},
            \c{"windowsce"},
            \c{"windowsphone"},
            \c{"windowsrt"}
    \endtable

    Specifies the OS you want to build the project for.
    This is typically set in a profile.


    \section1 architecture

    \table
    \row    \li \b{Type:}            \li \c{string}
    \endtable

    Specifies the target platform's processor architecture.
    This is typically set in a profile.
    Currently used values are: \c{"x86"}, \c{"x86_64"} and \c{"arm"}.


    \section1 endianness

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Allowed Values:}  \li \c{"big"}, \c{"little"}, \c{"mixed"}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Specifies the endianness of the target platform's processor architecture.


    \section1 toolchain

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Allowed Values:}  \li \c{"gcc"}, \c{"llvm"}, \c{"clang"}, \c{"mingw"}, \c{"msvc"}
    \endtable

    Specifies the attributes of the toolchain that is going to be used for this build.


    \section1 sysroot

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Specifies the sysroot of the target platform. This property is typically set in a profile
    for cross-compiling.


    \section1 install

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{false}
    \endtable

    Specifies whether to install a certain set of files.
    This is typically set in a \c{Group} item to mark a number of files as installable.


    \section1 installDir

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Specifies the installation directory for the files of a product or a \c{Group}. The value of
    this property is a path that is relative to \c installPrefix.

    \section1 installPrefix

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{empty}
    \endtable

    Specifies the global installation prefix. It is implicitly prepended to all values
    of \c installDir. The \c installPrefix itself is relative to the install root, which is not
    a property of qbs, but an external installation parameter.

    \section1 pathListSeparator

    \table
    \row    \li \b{Type:}            \li \c{string}
    \endtable

    Holds the platform-specific separator for path list that is used in environment variables or
    other contexts. E.g. on Windows is this \c{";"}, on Unix derivatives \c{":"}.
*/


/*!
    \contentspage index.html
    \previouspage module-qbs.html
    \page module-cpp.html
    \nextpage export-item.html

    \title Module cpp

    The \c cpp module contains the properties and rules for toolchains of the C/C++ family.
    On OS X this includes support for Objective-C/C++.

    \section1 General Properties


    \section2 architecture

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{qbs.architecture}
    \endtable

    Target architecture. See \c{qbs.architecture}.

    \section2 debugInformation

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{qbs.debugInformation}
    \endtable

    Generate debug information. See \c{qbs.debugInformation}.

    \section2 defines

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of preprocessor macros that gets passed to the compiler.
    To set macro values use the following syntax:
    \code
    cpp.defines: ["USE_COLORS=1", 'COLOR_STR="blanched almond"']
    \endcode

    \section2 platformDefines

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of preprocessor macros that are used for all projects that are built for the current
    target platform. User project files usually do not set this property.

    \section2 compilerDefines

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of preprocessor macros that are used for all projects that are using the current toolchain.
    User project files usually do not set this property.

    \section2 includePaths

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of include paths. Relative paths are considered to be relative to the .qbs product file
    they are used in.

    \section2 systemIncludePaths

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of include paths that are passed as system include paths to the compiler.
    For header files in those paths warnings will be ignored.
    Relative paths are considered to be relative to the .qbs product file they are used in.

    \section2 libraryPaths

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of library search paths. Relative paths are considered to be relative to the .qbs product
    file they are used in.

    \section2 dynamicLibraries

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of dynamic libraries to be linked. If the library is part of your project, consider
    using a Depends item instead.

    \section2 staticLibraries

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of static libraries to be linked. If the library is part of your project, consider
    using a Depends item instead.

    \section2 prefixHeaders

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of files to automatically include at the beginning of each source file in the product.

    \section2 precompiledHeader

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Name of the C++ header file to be precompiled.

    \section2 precompiledHeaderDir

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{product.buildDirectory}
    \endtable

    The directory that will contain the precompiled C++ header file.
    Usually you won't need to set this.

    \section2 optimization

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{qbs.optimization}
    \endtable

    Optimization level. See \c{qbs.optimization}.

    \section2 treatWarningsAsErrors

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{false}
    \endtable

    Warnings will be handled as errors and cause the build to fail.

    \section2 warningLevel

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{"all"}
    \endtable

    Specifies the installation directory for the files of a product or a \c{Group}. The value of
    this property is a path that is relative to the install root.

    \section2 commonCompilerFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Flags that are added to all compilation commands independently of the language.

    \section2 cppFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the C preprocessor.

    \section2 cFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the C compiler.

    \section2 cxxFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the C++ compiler.

    \section2 objcFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the Objective-C compiler.

    \section2 objcxxFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the Objective-C++ compiler.

    \section2 linkerFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the linker.

    \section2 compilerName

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-detect-toolchains
    \endtable

    Name of the compiler binary. This is set in the build profile.

    \section2 compilerPath

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-detect-toolchains
    \endtable

    Directory where the compiler binary is located. This is set in the build profile.

    \section2 compilerWrapper

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Wrapper binary and its arguments for wrapping compiler calls.
    This is useful for compiler wrappers like ccache and alike.


    \section1 Properties Specific to iOS and OS X

    \section2 frameworkPaths

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of framework search paths. Relative paths are considered to be relative to the .qbs product
    file they are used in.

    \section2 systemFrameworkPaths

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of framework search paths. Relative paths are considered to be relative to the .qbs product
    file they are used in. Header files in frameworks in those paths will not cause warnings.

    \section2 frameworks

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of frameworks to be linked.
    If the framework is part of your project, consider using a Depends item instead.

    \section2 weakFrameworks

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of frameworks to be weakly linked.
    If the framework is part of your project, consider using a Depends item instead.

    \section2 infoPlistFile

    \table
    \row    \li \b{Type:}            \li \c{path}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Path to the Info.plist file used by the bundle.
    The contents of this file will be aggregated with the values in \c{infoPlist}.
    If \c{infoPlistFile} and \c{infoPlist} contain the same key, the latter will take precedence,
    but may also be overridden during postprocessing (see \c{processInfoPlist}).
    If undefined, will not be taken into account.

    \section2 infoPlist

    \table
    \row    \li \b{Type:}            \li \c{object}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Dictionary of key-value pairs to add to the bundle's Info.plist.
    The contents of this property will be aggregated with the values from \c{infoPlistFile}.
    If \c{infoPlist} and \c{infoPlistFile} contain the same key, the former will take precedence,
    but may also be overridden during postprocessing (see \c{processInfoPlist}).
    If undefined, will not be taken into account.

    \section2 processInfoPlist

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{true}
    \endtable

    Whether to perform post-processing on the aggregated Info.plist contents.
    If this property is \c{true}, various post-processing operations will be applied to the
    bundle's property list dictionary after it has been aggregated from the contents of the file
    specified by the \c{infoPlistFile} property and the \c{infoPlist} property.
    First, values from a list of defaults will be added to the dictionary if they were not already
    present. Then, values from the AdditionalInfo key of the platform SDK's Info.plist file will be
    added to the dictionary if they were not already present, as well as some other miscellaneous
    keys, such as BuildMachineOSBuild and UIDeviceFamily (on iOS).
    Finally, variable expansions will be performed such that substrings of the form ${VAR} will be
    replaced with their corresponding environment variables.

    \section2 infoPlistFormat

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Allowed Values:}  \li \c{"xml1"}, \c{"binary1"}, \c{"json"}, \c{"same-as-input"}
    \row    \li \b{Default:}         \li \c{"binary1"} for iOS; \c{"same-as-input"} or \c{"xml1"}
                                         for OS X depending on whether \c{infoPlistFile} is
                                         specified; undefined for all other operating systems.
    \endtable

    The file format to write the product's resulting Info.plist in.


    \section1 Properties Specific to iOS

    \section2 minimumIosVersion

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li undefined, but may be set by generated profiles
    \endtable

    A version number in the format [major].[minor] indicating the earliest version of OS X that the
    product should run on. Passes -miphoneos-version-min=<version> to the compiler.
    If undefined, compiler defaults will be used.


    \section1 Properties Specific to OS X

    \section2 minimumOsxVersion

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li undefined, but may be set by generated profiles
    \endtable

    A version number in the format [major].[minor] indicating the earliest version of OS X that the
    product should run on. Passes -mmacosx-version-min=<version> to the compiler.
    If undefined, compiler defaults will be used.


    \section1 Properties Specific to Unix Platforms

    \section2 positionIndependentCode

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Generate position independent code.

    \section2 rpaths

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of rpaths that are passed to the linker.

    \section2 visibility

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Allowed Values:}  \li \c{"default"}, \c{"hidden"}, \c{"hiddenInlines"}
    \row    \li \b{Default:}         \li \c{"default"}
    \endtable

    Visibility level for exported symbols.


    \section1 Properties Specific to Windows

    \section2 windowsApiCharacterSet

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Allowed Values:}  \li \c{"unicode"}, \c{"mbcs"}, \c{undefined}
    \row    \li \b{Default:}         \li \c{"unicode"}
    \endtable

    Specifies the character set used in the Win32 API. "unicode" will define the
    preprocessor symbols UNICODE and _UNICODE, "mbcs" will define _MBCS, and
    setting the value to undefined will use the default character set.

    \section2 minimumWindowsVersion

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li undefined, but may be set by generated profiles
    \endtable

    A version number in the format [major].[minor] indicating the earliest version of Windows that
    the product should run on. Defines WINVER, _WIN32_WINNT, and _WIN32_WINDOWS, and applies a
    version number to the linker flags /SUBSYSTEM and /OSVERSION for MSVC or
    -Wl,--major-subsystem-version, -Wl,--minor-subsystem-version, -Wl,--major-os-version and
    -Wl,--minor-os-version for MinGW.
    If undefined, compiler defaults will be used.
*/
