/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qbs.
**
** $QT_BEGIN_LICENSE:FDL$
** 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 The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

// **********************************************************************
// 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}{Qbs}
    \page index.html
    \nextpage overview.html

    \title Qbs Manual

    \section1 Version \qbsversion

    \QBS is a tool that helps simplify the build process for
    developing projects across multiple platforms. \QBS can be used for any
    software project, regardless of programming language, toolkit, or libraries used.

    \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.io/}{Qt Bug Tracker}.

    \list
       \li  \l{Introduction}
       \li  \l{Setup}
           \list
               \li  \l{Installing}
               \li  \l{Configuring}
               \li  \l{Managing Qt Versions}
           \endlist
       \li  \l{Usage}
           \list
               \li  \l{Language Introduction}
               \li  \l{Building Applications}
               \li  \l{Running Applications}
               \li  \l{Installing Files}
               \li  \l{Using the Shell}
               \li  \l{Generators}
               \li  \l{Custom Modules and Items}
           \endlist
       \li  \l{How-tos}
       \li  \l{Reference}
           \list
                \li \l{List of All Items}
                \list
                    \li \l{List of Language Items}
                    \li \l{List of Convenience Items}
                \endlist
                \li \l{List of Built-in Services}
                \li \l{List of Command-line Tools}
                \li \l{List of Modules}
                \li \l{Command and JavaScriptCommand}
           \endlist

       \li  \l{Appendix A: Building Qbs}
       \li  \l{Appendix B: Code Attributions}
    \endlist
*/


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

    \title Introduction

    \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 \l{Product Item}{products}. You specify the type of the product: application,
    library, and so on.
*/


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

    \title Setup

    \list
        \li  \l{Installing}
        \li  \l{Configuring}
        \li  \l{Managing Qt Versions}
    \endlist
*/

/*!
    \contentspage index.html
    \previouspage reference.html
    \page building-qbs.html
    \nextpage attributions.html

    \title Appendix A: Building Qbs

    \section1 System Requirements

    To build \QBS from the source, you need Qt 5.6.0, or later

    \section1 Building

    To build \QBS, enter the following command:

    \code
        qmake -r qbs.pro && make
    \endcode

    \section1 Configure Options

    \QBS recognizes the following qmake CONFIG options to customize the build:

    \table
    \header \li Option              \li Notes
    \row    \li qbs_enable_unit_tests           \li Enable additional autotests.
    \row    \li qbs_disable_rpath       \li Disable the use of rpath. This can be used when packaging
                                        \QBS for distributions which do not permit the use of rpath,
                                        such as Fedora.
    \row    \li qbs_no_dev_install  \li Exclude header files from installation, that is, perform a
                                        non-developer build.
    \row    \li qbs_enable_project_file_updates \li Enable API for updating project files. This
                                        implies a dependency to the Qt GUI module.
    \endtable

    \section1 Docker

    A set of Docker images for developing \QBS (which are maintained by the \QBS team) is available
    \l{https://hub.docker.com/u/qbsbuild/}{on Docker Hub}.
    Both Windows Server Core and Debian Linux container types are available.

    \note The source code for the \QBS development Docker images is located in the \c{docker/}
    directory of the \QBS source tree, if you wish to build them yourself.

    \section2 Linux Containers

    The easiest way to get started is to build \QBS using a Linux container. These types of
    containers are supported out of the box on all the supported host platforms: Windows, macOS,
    and Linux. Run the following to download the \QBS development image based on Debian 9
    \e Stretch:

    \code
        docker pull qbsbuild/qbsdev:stretch
    \endcode

    You can then create a new container with the \QBS source directory mounted from your host
    machine's file system, by running:

    \code
        docker run -it -v $PWD:/qbs -w /qbs qbsbuild/qbsdev:stretch
    \endcode

    Or with a slightly different syntax for Windows:

    \code
        docker run -it -v %CD%:/qbs -w /qbs qbsbuild/qbsdev:stretch
    \endcode

    You will now be in an interactive Linux shell where you can develop and build \QBS.

    \section2 Windows Containers

    To build \QBS for Windows using Windows containers, your host OS must be running Windows 10 Pro
    and have Hyper-V enabled. \l{https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers}{Switch your Docker environment to use Windows containers}, then run the
    following command to download the Windows 10 \QBS development image:

    \code
        docker pull qbsbuild/qbsdev:windowsservercore
    \endcode

    You can then create a new container with the \QBS source directory mounted from your host
    machine's file system, by running:

    \code
        docker run -it -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore
    \endcode

    If you want to use Windows containers on a macOS or Linux host, you will have to create a
    virtual machine running Windows 10 and register it with \c{docker-machine}. There is at least
    \l{https://github.com/StefanScherer/windows-docker-machine}{one Open Source project}
    that helps to facilitate this by using using Packer, Vagrant, and VirtualBox.

    The \c{docker run} command to spawn a Windows container on a Unix host will look slightly
    different (assuming \c windows is the name of the Docker machine associated with the Windows
    container hosting VM):

    \code
        eval $(docker-machine env windows)
        docker run -it -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore
    \endcode

    \section2 Building Release Packages

    Release packages for \QBS for Windows can be built using the following command on Windows:

    \code
        docker run --rm -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\make-release-archives
    \endcode

    For building release packages for Windows on macOS or Linux:

    \code
        eval $(docker-machine env windows)
        docker run --rm -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\\make-release-archives
    \endcode
*/


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

    \title Installing

    \QBS binaries are available for Windows, macOS, Linux, and FreeBSD.

    On all platforms, \QBS binaries are part of the \l{Qt Creator} and \l{Qt SDK}
    installers. You can find the \c qbs executable in the \c bin directory of
    Qt Creator, or within the application bundle's \c MacOS directory on macOS.

    \QBS can also be built locally from sources. For more information, see
    \l{Appendix A: Building Qbs}.

    \section1 Windows

    The Qt Project provides prebuilt binaries for Windows (x86 and x64) at
    \l{https://download.qt.io/official_releases/qbs/}. For commercial customers of
    The Qt Company, the binaries are available in the \l {Qt Account}.
    The binaries are packaged in a .zip folder that can be extracted to a location
    of your choice.

    \QBS is also available as a \l Chocolatey package, which can be installed in
    the usual way:

    \code
    choco install qbs
    \endcode

    The \c .nupkg file can also be downloaded directly from
    \l{https://download.qt.io/official_releases/qbs/} for
    \l{https://chocolatey.org/security#organizational-use-of-chocolatey}{offline installation}.

    \section1 macOS

    \QBS can be conveniently installed on macOS with the \l{MacPorts} or \l{Homebrew}
    package managers:

    \code
    brew install qbs
    \endcode

    or

    \code
    port install qbs
    \endcode

    \section1 Linux and FreeBSD

    \QBS is \l{https://repology.org/metapackage/qbs/versions}{available via the
    package management systems} of Linux distributions, and FreeBSD.
*/

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

    \title Configuring

    Open a build shell (on Windows open an MSVC command prompt,
    on other platforms you can usually open the default shell):
    \code
    qbs setup-toolchains --detect
    \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 examples/helloworld-minimal and type:

    \code
    qbs profile:<profile name>
    \endcode

    If you want to build projects that use Qt, additional steps are necessary. Please refer to
    \l{Managing Qt Versions} for more information.

*/

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

    \note If the \c setup-toolchains command has found more than one toolchain, you will need
    to manually link your Qt profile to one of them, like this:
    \code
    qbs config profiles.myqt.baseProfile <profile name>
    \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 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.
*/

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

    \title Usage

    \list
        \li  \l{Language Introduction}
        \li  \l{Building Applications}
        \li  \l{Running Applications}
        \li  \l{Installing Files}
        \li  \l{Using the Shell}
        \li  \l{Generators}
        \li  \l{Custom Modules and Items}
    \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 \l{Product Item}{products}. A product is the target of a build
    process, typically an application, library or maybe a tar ball.
    \note \QBS source files are assumed to be UTF-8 encoded.

    \section1 The Obligatory Hello World Example

    \QBS project files 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 (on Windows, the ".exe" extension is added by default).

    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.
    So we could have also written

    \code
    files: [ "main.cpp" ]
    \endcode

    \a Depends adds the dependency to the module \l{Module cpp}{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 Project File Code
    QML-like inheritance works also in \QBS.

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

    Product {
        property string craziness: "low"
    }

    ---hellocrazyworld.qbs---
    import "CrazyProduct.qbs" as CrazyProduct

    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 pathList includePaths
        // ...
        FileTagger {
            patterns: "*.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 make the dependency explicit.

    \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

    Sometimes 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", "macos", "darwin", "unix", etc.
            \note Do not confuse this with the \c{qbs.targetOS} property, which represents the
            operating system on which the binaries produced by \QBS will run.
    \row
        \li targetOS
        \li stringlist
        \li platform-dependent
        \li The target operating system.
            May contain "windows", "linux", "macos", "darwin", "unix",
            "ios", "android", "blackberry", "qnx", etc.
    \endtable

    You can set these properties on the command line or by using a profile.

    \code
    $ qbs                   # qbs.buildVariant:debug, profile:<default profile> (or profile:none, if no default profile exists)
    $ qbs release           # qbs.buildVariant:release, profile:<default profile>
    $ qbs debug release     # builds two configurations of the project
    $ qbs profile:none      # all module properties have their default values
    \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 Property Types

    While properties in \QBS generally work the same way as in QML, the set of possible property
    types has been adapted to reflect the specific needs of a build tool. The supported types
    are as follows:

    \table
    \header
        \li Property type
        \li Example
        \li Description
    \row
        \li \c bool
        \li \c{property bool someBoolean: false}
        \li The usual boolean values.
    \row
        \li \c int
        \li \c{property int theAnswer: 42}
        \li Integral numbers.
    \row
        \li \c path
        \li \c{property path aFile: "file.txt"}
        \li File paths resolved relative to the directory the product they are associated with
            is located in.
    \row
        \li \c pathList
        \li \c{property pathList twoFiles: ["file1.txt", "./file2.txt"]}
        \li A list of \c path values.
    \row
        \li \c string
        \li \c{property string parentalAdvisory: "explicit lyrics"}
        \li JavaScript strings.
    \row
        \li \c stringList
        \li \c{property stringList realWorldExample: ["no", "not really"]}
        \li A list of JavaScript strings.
    \row
        \li \c var
        \li \c{property var aMap: ({ key1: "value1", key2: "value2" })}
        \li Generic data, as in QML.
    \endtable


    \section1 Overriding Property Values from the Command Line

    Property values set in project files or profiles can be overridden on the command line.
    The syntax is \c{<prefix>.<prop-name>:<prop-value>}. The following command lines
    demonstrate how to set different kinds of properties:
    \code
    $ qbs projects.someProject.projectProperty:false          # set a property of a project
    $ qbs products.someProduct.productProperty:false          # set a property of a product
    $ qbs modules.cpp.treatWarningsAsErrors:true              # set a module property for all products
    $ qbs products.someProduct.cpp.treatWarningsAsErrors:true # set a module property for one product
    \endcode

    Property values on the command line can also be expressed in JavaScript form, the same way
    as you would write them in a project file. Make sure to take care of proper
    quoting, so that the shell does not interpret any of the values itself. Properties of type
    \c stringList can also be provided as comma-separated values, if none of the strings contain
    special characters:
    \code
    $ qbs projects.someProject.listProp:'["a", "b", "c"]'
    $ qbs projects.someProject.listProp:a,b,c               # same as above
    $ qbs projects.someProject.listProp:'["a b", "c"]'      # no CSV equivalent
    \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 {
            patterns: "*.cpp"
            fileTags: ["cpp"]
        }
    \endcode
    This construct means that each source file that matches the pattern \c{*.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 more 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"
            Group {
                overrideTags: false     // The overrideTags property defaults to true.
                fileTags: ["foobar"]
                files: ["main.cpp"]     // Gets the file tag "cpp" through a FileTagger item and
                                        // "foobar" from this group's fileTags property.
            }
            // ...
        }
    \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 artifacts into the
    output artifacts. Artifacts created by one rule can (and typically do) serve as inputs to
    another rule. In this way, rules are connected to one another via their input and output
    file tags.

    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

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

    \code
    cd examples/collidingmice
    qbs
    \endcode

    The application is built using the default build profile that is set up
    in your \QBS configuration.
    To build with other profiles, specify options for the build
    command. For example, to build debug and release configurations with a
    profile named "Android", enter the following command:

    \code
    qbs build profile:Android debug release
    \endcode

    The position of the property assignment is important. In the example
    above, the profile property is set for all build configurations that come
    afterwards.

    To set a property just for one build configuration, place the assignment after
    the build configuration name.
    In the following example, the property \c cpp.treatWarningsAsErrors is
    set to \c true for debug only and \c cpp.optimization is set to
    \c small for release only.

    \code
    qbs build debug cpp.treatWarningsAsErrors:true release cpp.optimization:small
    \endcode
*/

/*!
    \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 --clean-install-root qbs.installRoot:/tmp/myProjectRoot
    \endcode

    Here, we want the installDir properties from the project file to be interpreted relative
    to the directory \c{/tmp/myProjectRoot}, and we want that directory to be removed first.
    If the \c{qbs.installRoot} property is not given, a default is used, namely
    \c{<build root>/install-root}.
*/

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

    \title Using the Shell

    To use the \QBS shell, enter the following command:

    \code
    qbs shell
    \endcode

    This is mainly a debugging tool. It opens a shell with the same environment that qbs uses
    when building the project, so you can, for example, inspect which environment variables
    will be set up.

*/

/*!
    \contentspage index.html
    \previouspage generators.html
    \page custom-modules.html
    \nextpage howtos.html

    \title Custom Modules and Items

    Users of \QBS are not limited to the pre-defined \l{List of Modules}{modules} and
    \l{List of Language Items}{items}, they can also create their own. Here we describe how
    to set up custom modules and items so that \QBS will find them.

    \section1 File System Layout

    Items and modules are located under a common base directory, whose name and location is
    completely arbitrary. We will refer to it as \c search-path here. This directory has two
    subdirectories \c modules and \c imports, which contain \QBS modules and items, respectively.


    \section1 Custom Modules

    To introduce a custom module \c mymodule, create a directory \c{search-path/modules/mymodule/}.
    \note Module names are case-sensitive, and this also goes for the corresponding directory name.

    Then, put a file containing an instance of the \l{Module Item} in there and give it the \c{.qbs}
    extension. This module will be pulled in if a
    \l{Product Item}{product} declares a \l{Depends Item}{dependency} on \c mymodule.


    \section1 Custom Items

    To introduce a custom item \c MyItem, create the file \c{search-path/imports/MyItem.qbs}.


    \section1 Making \QBS Aware of Custom Modules and Items

    To be able to use your custom modules and items, you need to make them known to \QBS. You can
    do this per project or globally.

    \section2 Project-specific Modules and Items

    Let's assume you have a project that is located in \c{project_dir} and you have created some
    modules in \c{project_dir/custom-stuff/modules/} as well as some items in
    \c{project_dir/custom-stuff/imports/} that you want to use in the project.
    To achieve this, your top-level project file should look like this:
    \code
    // ...
    Project {
        // ..
        qbsSearchPaths: "custom-stuff"
        // ..
    }
    \endcode
    \note For technical reasons, the custom modules and items will not be available in the file
          that contains the \c qbsSearchPaths property. Any product that wants
          to make use of them needs to be in a different file that is pulled in
          via the \c references property, for example. This is not a serious limitation, since
          every well-structured project will be split up in this manner.

    \section2 Making Custom Modules and Items Available Across Projects

    What if your modules and items are generally useful and you want to access them in several
    projects? In this case, it's best to add the location to your preferences. For example:
    \code
    qbs config preferences.qbsSearchPaths /usr/local/share/custom-qbs-extensions
    \endcode

*/

/*!
    \contentspage index.html
    \previouspage shell.html
    \page generators.html
    \nextpage custom-modules.html

    \title Generators

    Generators are a \QBS sub-tool and set of APIs which enable arbitrary processing to be performed
    on the build graph. Currently they are used to implement IDE integration with popular IDEs like
    Visual Studio.

    \section1 Using Generators

    To generate a project for another build system like Visual Studio, use the
    \c qbs-generate sub-command and specify a generator using the \c{-g} option. For example:

    \code
    # For Visual Studio
    qbs generate -g visualstudio2015
    \endcode

    \QBS will then generate a series of files in the current directory, based on the generator that
    was chosen. For the Visual Studio generator, the resulting project files can be
    opened in the respective IDEs and all work can be performed there.

    The project files will expose as much information as possible to the IDE and will use \QBS to
    perform the actual build. \note You cannot modify build system files and expect the changes
    to be reflected in \QBS; you must edit your \QBS project files and re-run \c{qbs-generate} in
    order for the changes to be reflected in your IDE.

    \section1 Limitations

    Due to the high flexibility of the Qbs project format and build engine, some projects may be too
    complex to produce an equivalent project file for another build system.

    This list of limitations aims to be as small as possible, but one of the most notable (at least
    for the Visual Studio generator) is that certain properties must contain the same
    value across all build configurations. For example, the following is not allowed:

    \code
    Product {
        // ERROR: 'name' property cannot have different values based on the configuration
        name: qbs.configuration === "debug"
            ? "MyProduct_debug"
            : "MyProduct"
    }
    \endcode

    Note that this limitation only applies when property values are varied on the configuration
    name. For example, the following is OK (as long as the value of xyz itself does not vary across
    configurations):

    \code
    Product {
        // OK
        property bool isDebug: <some value>
        name: isDebug ? "MyProduct_debug" : "MyProduct"
    }
    \endcode

    The properties to which the limitation applies includes but is not limited to:

    \list
        \li \l{Product Item}{Product}.name
        \li \l{Module bundle}{bundle}.isBundle
    \endlist

    If a simple workaround is possible in a particular case (e.g. varying Product.targetName across
    configuration instead of Product.name), the generator will typically suggest it in the error
    message.
*/

/*!
    \contentspage index.html
    \previouspage building-qbs.html
    \page attributions.html

    \title Appendix B: Code Attributions

    \QBS contains third-party code, which we gratefully acknowledge:
    \generatelist{groupsbymodule attributions-qbs}
*/
