path: root/doc/qbs.qdoc

/****************************************************************************
**
** 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 qbs-overview.html

    \title Qbs Manual

    \section1 Version \qtcversion

    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{Qbs Functions}
               \li  \l{Rule Item}
               \li  \l{Group Item}
               \li  \l{FileTagger Item}
               \li  \l{Product Item}
           \endlist
    \endlist
*/


/*!
    \contentspage index.html
    \previouspage index.html
    \page qbs-overview.html
    \nextpage qbs-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 qbs-overview.html
    \page qbs-setup.html
    \nextpage qbs-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 qbs-setup.html
    \page qbs-system-requirements.html
    \nextpage qbs-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 qbs-system-requirements.html
    \page qbs-building.html
    \nextpage qbs-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 qbs-building.html
    \page qbs-configuring.html
    \nextpage qbs-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.

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

    The toolchain detector will automatically set up a profile for each detected toolchain.
    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 qbs-configuring.html
    \page qbs-qt-versions.html
    \nextpage qbs-usage.html

    \title Managing Qt Versions

    \section1 Introduction

    To let qbs know where a Qt build or Qt version is you want to use,
    it has to be registered.

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

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

    \code
    qbs profile:myqt
    \endcode


    \section1 Manual Setup

    All what the setup-qt tool does can be done manually.
    That's described in this section.

    Here's an example for registering Qt, installed on Ubuntu GNU/Linux, again using a profile "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're using Qt 5, you must specify the version number.
    \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 settings you
    need to set together, you need to create several profiles. This is how you'd 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 you want to use like this:

    \code
    qbs config defaultProfile qt5
    \endcode

    To choose a Qt build that's 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.qbs.baseProfile msvc2010
    \endcode

    The last example uses the inheritance feature of profiles: All settings in the profile
    set as "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 -qtnamespace MyNamespace
    then you must set the following 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 qbs-configuring.html
    \page qbs-usage.html
    \nextpage qbs-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 qbs-usage.html
    \page qbs-language-introduction.html
    \nextpage qbs-building-applications.html

    \title Language Introduction

    Qbs uses project files (*.qbs) to describe the contents of a project.
    A project contains one or more 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

    These project files are written using a QML dialect.
    A very simple C++ hello world project looks like this:
    \code ---helloworld.qbs---
        import qbs.base 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 a product we want to build. In this case an
    application. This is just a short cut for writing
    \code
        Product {
            type: "application"
            // ...
        }
    \endcode

    The \a name obviously is the name of the product and in this case 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} (see below for an
    explanation of qbs modules).
    This is necessary to let qbs know that we have a C++ project and want
    to compile main.cpp with a C++ compiler.


    \section1 Reusing qbs project file code
    QML-like inheritance is also working in qbs.

    \code
    ---CrazyProduct.qbs---
    import qbs.base 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 then.
    \code
    ---helpers.js---
    function planetsCorrectlyAligned()
    {
        // implementation
    }

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

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


    \section1 Modules

    So what are these "modules"?
    A 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

    What we see here is a bunch of properties that can be set for the \a cpp
    module. These are used to control the behaviour of your C++ toolchain.
    Also we have things like FileTaggers and Rules. These are covered later.

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

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

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

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

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

        // THIS IS WORKING
        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 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: you have a file that's only going to
    be compiled on a certain platform. This is how you do it:
    \code
        Group {
            condition: qbs.targetOS == "windows"
            files: [
                "harddiskdeleter_win.cpp",
                "blowupmonitor_win.cpp",
                "setkeyboardonfire_win.cpp"
            ]
        }
        Group {
            condition: qbs.targetOS == "linux"
            files: [
                "harddiskdeleter_linux.cpp",
                "blowupmonitor_linux.cpp",
                "setkeyboardonfire_linux.cpp"
            ]
        }
    \endcode

    That odd \a qbs.targetOS thingy is the property \a target of the module \a
    qbs. The module \a qbs 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 string
        \li platform-dependent
        \li The host operating system. Currently "windows", "linux" or "mac".
    \row
        \li targetOS
        \li string
        \li platform-dependent
        \li The target operating system. Currently "windows", "linux" or "mac".
    \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

    So if you want to select files by build variant, this is how you do it:
    \code
        Group {
            condition: qbs.buildVariant == "debug"
            files: "debughelper.cpp"
        }
    \endcode

    Setting properties for a build variant works like this:
    \code
        Properties {
            condition: qbs.buildVariant == "debug"
            cpp.debugInformation: true
            cpp.optimization: "none"
        }
    \endcode
    or more QML style:
    \code
        cpp.debugInformation: qbs.buildVariant == "debug" ? true : false
        cpp.optimization: qbs.buildVariant == "debug" ? "none" : "fast"
    \endcode


    \section1 File tags and taggers

    The qbs tool itself knows nothing about C++ files or its file extensions. All source file
    in a product are handled equally. There's the concept of a \a{file tag},
    which is basically a marker or a type that can be assigned to an artifact.

    An artifact can have multiple file tags.
    Use the \a Group item to group files with the same file tags (and/or set of
    properties).

    Example:
    \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 then you also load the following item:
    \code
        FileTagger {
            pattern: "*.cpp"
            fileTags: ["cpp"]
        }
    \endcode
    This construct means that every source file that matches the glob *.cpp (and
    hasn't 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}.

    It's possible to use file taggers to tag files and specify custom file tags in
    addition:
    \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

    A rule looks at the pool of artifacts (in the beginning it's just the set of
    source files of the project) and chooses the ones that match its input file
    tags. Then it creates output artifacts in the build graph that have other
    filenames and file tags. It also creates a transformer which is basically a
    script that, well, 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, which can be provided along with
    your project. Or you can put a rule directly into your project file.

    Rules reference: \l{Rules}.
*/


/*!
    \contentspage index.html
    \previouspage qbs-language-introduction.html
    \page qbs-building-applications.html
    \nextpage qbs-installing-files.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 qbs-building-applications.html
    \page qbs-installing-files.html
    \nextpage qbs-running.html

    \title Installing Files

    If you want to install your project, the first thing to do is to 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 being used, namely the value of the
    property "qbs.sysroot" or, if that one is not set, "<build root>/install-root".
*/

/*!
    \contentspage index.html
    \previouspage qbs-installing-files.html
    \page qbs-running-applications.html
    \nextpage qbs-shell.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 qbs-running-applications.html
    \page qbs-shell.html
    \nextpage qbs-reference.html

    \title Using Qbs Shell

    \code
    qbs shell
    \endcode

*/


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

    \title Reference

    \list
        \li \l{Qbs Functions}
        \li \l{Rule Item}
        \li \l{Group Item}
        \li \l{FileTagger Item}
        \li \l{Product Item}
    \endlist
*/


/*!
    \contentspage index.html
    \previouspage qbs-functions.html
    \page qbs-rule-item.html
    \nextpage qbs-group-item.html

    \title Rule Item

    A "multiplex rule" creates one transformer that takes all
    input artifacts with the matching input file tag and creates
    one or more artifacts (e.g. C++ linker).
    A "non-multiplex rule" creates one transformer per matching input file (e.g. C++
    compiler).

    \section1 Rule properties

    \table
    \header
        \li Property
        \li Type
        \li Default
        \li Description
    \row
        \li multiplex
        \li bool
        \li false
        \li Determines if this is a multiplex rule.
    \row
        \li inputs
        \li string list
        \li undefined
        \li File tags the input artifacts must match.
           All output artifacts will depend on all artifacts in the product with
           the given input file tags. Also these artifacts are available in the
           inputs variable of the prepare script.
    \row
        \li usings
        \li string list
        \li undefined
        \li File tags the artifacts of product dependencies must match.
           Let there be a product \a foo which appears as
           \code
            Depends {
                name: "foo"
            }
           \endcode
           in the current product. All artifacts of \a foo that match the given
           file tags will appear in the \a inputs variable of the prepare
           script. Also, every output artifact of this rule will be dependent on
           those artifacts.
    \row
        \li explicitlyDependsOn
        \li string list
        \li undefined
        \li Every artifact that matches the file tags in \a explicitlyDependsOn
           is added to the dependencies of every output node.
    \row
        \li scanners
        \li string list
        \li undefined
        \li List of dependency scanner ids for this rule. The scanners are
           running just before the prepare script is executed.
    \row
        \li prepare
        \li script
        \li undefined
        \li Script that prepares the commands to transform the inputs to outputs.
    \endtable

*/

/*!
    \contentspage index.html
    \previouspage qbs-rule-item.html
    \page qbs-group-item.html
    \nextpage qbs-filetagger-item.html

    \title Group Item

    This item is attached to a product and is used to group files that have something in common. For instance:
     \code
     Application {
         Group {
             name: "common files"
             files: ["myclass.h", "myclass_common_impl.cpp"]
         }
         Group {
             name: "Windows files"
             condition: targetOs === "windows"
             files: "myclass_win_impl.cpp"
         }
         Group {
             name: "Linux files"
             condition: targetOs === "linux"
             files: "myclass_linux_impl.cpp"
         }
         Group {
             name: "Files to install"
             qbs.install: true
             qbs.installDir: "share"
             files "runtime_resource.txt"
         }
     }
     \endcode
     When specifying files, you can use the wildcards "*", "?" and "[]", which have their usual meaning.
     By default, matching files are only picked up directly from the parent directory, but you can tell qbs to
     consider the whole directory tree. It is also possible to exclude certain files from the list.
     Here's an example:
     \code
     Group {
         name: "Word processing documents"
         files: ["*.doc", "*.rtf"]
         recursive: true
         qbs.install: true
         qbs.installDir: "share"
         excludeFiles: "do_not_install_this_file.*"
     }
     \endcode
     \note Wildcards can match only regular files, not directories.

     A group can also be used to attach properties to build artifacts such as executables or
     libraries. In the following example, an application is installed to "<install root>/bin".
     \code
     Application {
         Group {
             fileTagsFilter: "application"
             qbs.install: true
             qbs.installDir: "bin"
         }
     }
     \endcode

    \section1 Group Properties

    \table
    \header
        \li Property
        \li Type
        \li Default
        \li Description
    \row
        \li name
        \li string
        \li "Group x", where x is a unique number among all the groups in the product
        \li The name of the group. Not used internally; mainly useful for IDEs.
    \row
        \li files
        \li list
        \li empty list
        \li The files in the group. Mutually exclusive with fileTagsFilter.
    \row
        \li prefix
        \li string
        \li empty string
        \li A prefix to append to all files. Slashes are allowed and have directory semantics.
    \row
        \li fileTagsFilter
        \li list
        \li empty list
        \li Artifact file tags to match. Any properties set in this group will be applied
            to the product's generated artifacts whose file tags intersect with the ones
            listed here. Mutually exclusive with files.
    \row
        \li condition
        \li bool
        \li true
        \li Determines whether the files in the group are actually considered part of the project.
    \row
        \li fileTags
        \li list
        \li empty list
        \li Tags to attach to the group's files. These can then be matched by a rule.
            Note that file taggers are never applied to a file that has this property set.
    \row
        \li overrideTags
        \li bool
        \li true
        \li If the same file appears in the files list of both the top level of a product and
            a group and this property is true, then the file tags set via the group
            replace the ones set via the product. If it is false, the "group tags" are are added to
            the "product tags".
    \row
        \li recursive
        \li bool
        \li false
        \li For use with wildcards; determines whether to descend into subdirectories.
    \row
        \li excludeFiles
        \li list
        \li empty list
        \li For use with wildcards; the files in this list are "subtracted" from the files list.
    \endtable
*/

/*!
    \contentspage index.html
    \previouspage qbs-group-item.html
    \page qbs-filetagger-item.html
    \nextpage qbs-product-item.html

    \title FileTagger Item

    This item maps file patterns to tags. It can be attached to a product or a module.
    In the latter case, its effect is the same as if it had been attached to all products having
    a dependency on the respective module. For instance, qbs' cpp module has, among others,
    the following file tagger:
    \code
    FileTagger {
        pattern: "*.cpp"
        fileTags: ["cpp"]
    }
    \endcode
    As a result, all files ending with ".cpp" in products depending on the cpp module automatically
    get the "cpp" tag, which will cause them to be compiled, because a C++ compiler rule
    has "cpp" in its list of matching input tags.

    File taggers are disabled if file tags are set explicitly in a product or group.
    For example, cpp files in the following product will not get the "cpp" tag:
    \code
    Product {
        Depends { name: "cpp" }
        Group {
            files: "*.cpp"
            fileTags: "other"
        }
    }
    \endcode

    \section1 FileTagger Properties

    \table
    \header
        \li Property
        \li Type
        \li Default
        \li Description
    \row
        \li pattern
        \li string
        \li none
        \li The pattern to match against. Supports the usual wildcards '*', '?' and '[]'.
    \row
        \li fileTags
        \li list
        \li empty list
        \li Tags to attach to a product's files. These can then be matched by a rule.
    \endtable
*/

/*!
    \contentspage index.html
    \previouspage qbs-reference.html
    \page qbs-functions.html
    \nextpage qbs-rule-item.html

    \title Qbs Functions

*/

/*!
    \contentspage index.html
    \previouspage qbs-filetagger-item.html
    \page qbs-product-item.html

    \title Product Item

    \table
        \header
            \li Product Item
            \li Description
            \li Property
            \li Property Description
        \row
            \li Product
            \li Generic product.
            \li
            \li
        \row
            \li
            \li
            \li condition
            \li Boolean value. If false, the product is excluded from build. Default is true.
        \row
            \li
            \li
            \li name
            \li The name of the product for referencing it in Depends items.
        \row
            \li
            \li
            \li type
            \li A list of file tags the product is going to create.
        \row
            \li
            \li
            \li targetName
            \li The base file name of the generated file. If not set, \a name is used.
        \row
            \li
            \li
            \li destination
            \li The destination directory of the produced file. Relative to the build dir.
        \row
            \li
            \li
            \li files
            \li List of source files.
        \row
            \li
            \li
            \li consoleApplication
            \li Boolean value. If set to true, a console application is generated.
               If false, a GUI application is generated. Default is undefined / not set,
               which means the linker decides. This only has an effect on Windows.
        \row
            \li Application
            \li Product with type "application" or "applicationbundle" on Mac.
            \li
            \li
        \row
            \li DynamicLibrary
            \li Product with type "dynamiclibrary". Produces a DLL or shared object.
            \li
            \li
        \row
            \li StaticLibrary
            \li Product with type "staticlibrary". Produces a static library.
            \li
            \li
    \endtable
*/