/****************************************************************************
**
** Copyright (C) 2017 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.
// **********************************************************************


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


    \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 Profiles and Preferences}
               \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{Target Platforms}
               \li  \l{Using the Shell}
               \li  \l{Generators}
               \li  \l{Multiplexing}
               \li  \l{Custom Modules and Items}
               \li  \l{Special Property Values}
               \li  \l{Module Providers}
           \endlist
        \li  \l{Tutorial}
           \list
                \li  \l{tutorial-1.html}{Console Application}
                \li  \l{tutorial-2.html}{Static Library}
                \li  \l{tutorial-3.html}{Dynamic Library}
                \li  \l{tutorial-4.html}{Convenience Items}
                \li  \l{tutorial-5.html}{Autotest}
                \li  \l{tutorial-6.html}{Project Properties}
                \li  \l{tutorial-7.html}{Buildconfig Module}
                \li  \l{tutorial-8.html}{Configurable Library}
                \li  \l{tutorial-9.html}{Version Header}
                \li  \l{tutorial-10.html}{C++20 Modules}
            \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}
                    \li \l{List of Probes}
                \endlist
                \li \l{List of Built-in Services}
                \li \l{Command-Line Interface}
                \li \l{List of Modules}
                \li \l{List of Module Providers}
                \li \l{Command and JavaScriptCommand}
           \endlist

       \li  \l{Appendix A: Building Qbs}
       \li  \l{Appendix B: Migrating from Other Build Systems}
       \li  \l{Appendix C: The JSON API}
       \li  \l{Appendix D: Licenses and Code Attributions}
    \endlist
*/


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

    \title Introduction

    \QBS is a build automation tool designed to conveniently manage the build
    process of software projects across multiple platforms.

    \section1 Features

    \QBS provides the following benefits:

    \list
        \li Declarative paradigm
        \li Well-defined language
        \li Platform and programming language independence
        \li Correct and fast incremental builds
        \li Extensible architecture
        \li Easy integration to IDEs
    \endlist

    \section2 Declarative Paradigm

    When writing a project, it is important to describe the build tasks and
    dependencies between them, rather than the build order. It is difficult to
    determine the correct build order in complex projects, especially during
    parallel builds. The build tool should bear that burden, not the developer.

    With a declarative language, \QBS enables you to express intent rather than
    specifying single build steps. This provides the appropriate level of
    abstraction for a build system. For example, \e dependencies can be created
    between \e products, such that the target \e artifacts of the dependency
    can be used as input to the build \e rules in the context of the depending
    product. In addition, you can \e export dependencies and \e properties to
    other products.

    \QBS is modular with clean interfaces between modules. A \e module is a
    collection of properties and \e {language items} that are used for
    building a product if the product depends on the module. The properties
    that can be set for a module are used to control the behavior of the
    toolchain used to build the module.

    \QBS itself knows nothing about file types or extensions, and therefore all
    source files in a product are handled equally. However, you can assign
    \e {file tags} to an artifact to act as markers or to specify a file type.
    \QBS applies a rule to the source files of the project and chooses the
    ones that match the input file tags specified by the rule. It then creates
    artifacts in the build graph that have other filenames and file tags.

    Products and projects can contain \e probes that are run prior to building,
    for instance to locate dependent headers, libraries, and other files outside
    the project directory.

    \section2 Well-Defined Language

    \QBS projects are specified in a QML dialect. QML is a concise, easy to
    learn, and intuitive language that is used successfully in the Qt project.
    Its core is declarative, but it can be extended with JavaScript snippets
    for extra flexibility.

    \QBS builds applications based on the information in a project file. Each
    project file specifies one \l{Project}{project} that can contain
    several \l{Product}{products}. You specify the type of the product,
    such as an \e application, and the dependencies the product has on other
    products.

    The product type determines the set of \l{Rule}{rules} that \QBS
    applies to produce artifacts from input files. The input files can be
    divided into \l{Group}{groups} according to their type or purpose, for
    example. A group can also be used to attach \l{Properties}{properties}
    to products.

    The following is an example of a minimal project file that specifies the
    product type, application name, source file, and a dependency on the
    \l{cpp} module:

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

    For more information, see \l{Language Introduction}.

    \section2 Platform and Programming Language Independence

    \QBS can be used for any software project, regardless of programming
    language, toolkit, or libraries used. \QBS has built-in support for
    building applications for Windows, Linux, macOS, Android, iOS, tvOS,
    watchOS, QNX, and FreeBSD, as well as for cross-compilation. It can be
    easily extended to support further platforms.

    Invoking \l{build}{qbs build} from the command line automatically builds the
    project for the current host platform using the best available toolchain and
    settings, unless a default profile is set. You can configure additional
    profiles for each toolchain you want to use and select the profile to use
    at build time.

    For example, to build applications for Android devices, you would need to
    set up a profile for the Android toolchain and select it when you build the
    application. If you name the profile \e Android, you would then enter the
    following command:

    \code
    qbs build profile:Android
    \endcode

    For more information, see \l{Building Applications}.

    Platform and programming language support is implemented as a set of
    \l{List of Modules}{modules} that your product depends on. In the language
    example above, the dependency on the \l{cpp} module determines
    that the C++ sources are compiled and linked into a binary.

    Alternatively, you could use the \l{CppApplication}
    convenience item that implies a dependency on the \l{cpp} module:

    \code
    CppApplication {
        name: "helloworld"
        files: "main.cpp"
    }
    \endcode

    Additionally, if the sources use Qt, you need a dependency to the
    \l{Qt.core} module, and so on.

    In addition to building projects, \QBS can install the build artifacts to
    a location from where they can be run on the desktop or on a device. \QBS
    modules can be used to create installers for the end users of the
    applications. For example, the \l{dmg} module contains
    properties and rules for building Apple Disk Images, which are typically
    used to distribute applications and installers on macOS. The
    \l{innosetup}, \l{nsis}, and \l{wix} modules contain properties and rules
    for building installers for Windows platforms.

    \section2 Correct and Fast Incremental Builds

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

    \QBS automatically takes advantage of multi-processor and multi-core systems
    to achieve maximum build parallelization. By default, running \c qbs without
    any arguments is roughly equivalent to running \c {make -j<n>} where \c n is
    the number of CPU cores. Similarly, \QBS allows the number of concurrent
    jobs to be explicitly specified using its own \c -j option.

    \QBS has knowledge about the whole project, and therefore builds remain
    correct even when you build sub-projects, because \QBS ensures that all
    dependencies are built too. This virtually eliminates the need for clean
    builds.

    \QBS uses dynamic build graphs with build rules that can generate a variable
    number of files and that are executed only when needed. When figuring out
    which rules to execute, \QBS starts at the product type and then looks for
    a way to produce artifacts with matching file tags from source files, using
    a chain of rules that are connected by their respective input and output
    tags. For an example of how rules are applied when building products, see
    \l{Rules and Product Types}.

    The \QBS build rules can produce a variable number of outputs.
    If the input changes, only the required rules are applied at build time.
    If a rule is applied, all the dependent rules are applied as well, but only
    those. This feature ensures the correctness of the build graph after source
    code changes without having to re-configure the whole project.

    Changing properties that do not affect the build, because they are not used
    by rules, will not cause the project to be rebuilt. The use of properties is
    tracked. Generated artifacts that cease to exist are deleted to avoid
    picking outdated generated artifacts and indefinitely increasing the size of
    the build directory.

    Fast incremental builds are crucial for a fast edit-build-run cycle.
    Instead of retrieving the timestamps of generated files, \QBS uses the time
    stamps stored in the build graph. This is especially important on Windows,
    where file system operations are slow.

    If the project files were not changed, the build graph is loaded from disk.
    It is stored in a binary format that can be loaded much faster than the real
    project files. The project files are parsed only if they were changed.

    \section2 Extensible Architecture

    You can create your own custom \l{List of Modules}{modules} and
    \l{List of Language Items}{items} and make \QBS aware of them.

    You store the custom modules and items in a subdirectory of the project
    directory and specify the path to the subdirectory as a value of the
    \l{Project::}{qbsSearchPaths} property. For example, if the custom module is
    located at \c my-modules/modules/modulename/modulename.qbs, you would
    specify it in the project file as follows:

    \code
    Project {
        qbsSearchPaths: "my-modules"
    \endcode

    For more information, see \l{Custom Modules and Items}.

    \section2 IDE Integration

    \QBS can be used not only from the command line, but also in combination
    with an IDE, such as Qt Creator or Visual Studio Code. These IDEs directly
    support \QBS projects using the new \QBS \l{session} feature. Thus, these IDEs
    can retrieve all the information required to build a single file or project
    through a session's JSON protocol \l{Appendix C: The JSON API}{API}.

    In addition, \QBS can generate projects for Visual Studio, IAR EW, and
    Keil uVision, but it still is an experimental option. For more information,
    see \l {Generators}.

    \section3 Qt Creator

    \l{http://doc.qt.io/qtcreator/index.html}{Qt Creator} provides accurate
    information about the build progress and displays a project tree that
    reflects the logical structure of the project, instead of presenting low-level
    information, such as the file system structure. Adding or removing source
    files keeps the existing project file structure intact.

    For more information about using \QBS to build projects from Qt Creator, see
    \l{http://doc.qt.io/qtcreator/creator-project-qbs.html}{Setting Up Qbs}.

    \section3 Visual Studio Code

    \l{https://code.visualstudio.com/}{Visual Studio Code} provides the
    \l{https://marketplace.visualstudio.com/items?itemName=qbs-community.qbs-tools}
    {qbs-community} plugin that provides accurate information about the build progress
    and displays a project tree that reflects the logical structure of the project.
    Also, it can provide low-level information, such as the file system structure.

    For more information about using \QBS to build projects from Visual Studio Code,
    see \l{https://github.com/denis-shienkov/vscode-qbs/blob/master/docs/how-to.md}
    {How To}.

    \section1 Build Process

    \image qbs-build-process.png

    The build process of a product starts by examining the \l{Product::}{type}
    property of the product. It contains a list of \e {file tags} that are
    similar to MIME types.

    The following example product contains one file tag, \e application:

    \code
    Product {
        Depends { name: "cpp" }
        type: ["application"]
        files: ["main.cpp", "class.cpp", "class.h"]
    }
    \endcode

    \QBS then searches through all \e rules available in the context, meaning
    rules that are defined in the project or those that are made available
    through the dependency on a module, such as the compiler and linker rules
    pulled in from the \c cpp dependency in the example.

    When \QBS finds a rule that produces one or more artifacts with the relevant
    file tag, it looks at the depencencies of that rule and finds out that it
    produces artifacts tagged \c obj. It then finds a rule that produces \c obj
    artifacts that takes \c .cpp artifacts as input.

    \code
    Module {
        // ...
        Rule {
            inputs: ["cpp"]
            Artifact {
                filePath: input.fileName + ".o"
                fileTags: ["obj"]
            }
            prepare: {
                // g++ -c main.cpp -o main.o ...
            }
        }
        //...
    }
    \endcode

    There is no rule in the current context that produces \c .cpp files, but
    we have defined \c .cpp files as inputs for the product. When we added a
    dependency on the \l{cpp} module, that dependency also pulled in another \QBS
    primitive called the \l{FileTagger}{file tagger}. The file tagger
    looked for files matching the pattern \c *.cpp, and then applied the \c cpp
    tag to those input files:

    \code
    Module {
        // ...
        FileTagger {
            patterns: "*.cpp"
            fileTags: ["cpp"]
        }
        //...
    }
    \endcode

    Since the \c .cpp files are input files, they by definition have no other
    dependencies, and we can go back the opposite way in the tree starting with
    the compiler rule described above.

    This design works well for generated files. The \c .cpp artifacts could come
    from another rule that produced them by processing some other input, either
    instead of or in addition to the raw files listed in the product.

    The compiler rule will be invoked twice, once for each \c .cpp file,
    producing a separate object file for each one. Then the linker rule will be
    invoked. Its \c multiplex property is set to \c true, which means that
    instead of producing one output per input and invoking the rule multiple
    times, all input will be collected before invoking the rule only once to
    produce the final application object.

    The standard versus multiplex rules map well to the compiler and linker
    processes. The compiler takes one input file to produce one output file,
    whereas the linker takes multiple input files to produce one output file.

    Finally, after the linker rule has been invoked, it produces an artifact
    tagged \c application. Because the product's type property did not contain
    other file tags, the build process is now complete.
*/


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

    \title Setup

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

/*!
    \previouspage reference.html
    \page building-qbs.html
    \nextpage porting-to-qbs.html

    \title Appendix A: Building Qbs

    \QBS can be \l{Installing}{installed from binary packages} or built from
    sources, as described in this appendix. In addition, this appendix describes
    how to use Docker images for developing \QBS.

    \section1 Supported Platforms

    \QBS can be installed and run on the following platforms:

    \list
        \li Windows 7, or later
        \li Linux (tested on Debian 8 and 9, Ubuntu 16.04, OpenSuSE 13.2, and
            Arch Linux)
        \li macOS 10.7, or later
    \endlist

    \section1 System Requirements

    To build \QBS from the source, you need:

    \list
        \li Qt 5.15, or later
        \li Windows: MinGW with GCC 4.9 or Microsoft Visual Studio 2015,
            or later
        \li Linux: GCC 4.9, or later, or Clang 3.9.0, or later
        \li macOS: Xcode 6.2, or later
    \endlist

    An installed toolchain has to match the one that Qt was compiled with.

    \section2 Documentation

    Building the \QBS documentation requires Python 2.7 or 3.2 or above,
    as well as some third party Python modules. These can be installed via \c pip:

    \code
        pip install beautifulsoup4 lxml
    \endcode

    Regenerating the man page requires the \c help2man tool.

    \section1 Building \QBS with СMake

    To build \QBS, enter the following commands:

    \code
        mkdir build && cd build
        cmake -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ ..
        make
    \endcode

    Where \c ${QT_DIR} is the directory where Qt is installed. Passing the \c Qt5_DIR option
    is not necessary if \c qmake is present in \c PATH.

    Depending on your platform, you might use \c mingw32-make, \c nmake, or
    \c jom instead of \c make.

    Alternatively, you can use the
    \l{https://cmake.org/cmake/help/latest/generator/Ninja.html}{Ninja} generator:
    \code
        cmake -GNinja -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ ..
        ninja
    \endcode

    \section2 CMake Configure Options

    \QBS recognizes the following CMake options (passed to CMake in the form of \c{-DOPTION=value})
    to customize the build:

    \table
    \header \li Option              \li Notes                       \li Default value
    \row    \li WITH_TESTS          \li Enable autotests.           \li \c ON
    \row    \li WITH_UNIT_TESTS     \li Enable additional autotests. \li \c OFF
                                           \li \c OFF
    \row    \li INSTALL_PUBLIC_HEADERS     \li Whether to install public headers. \li \c ON
    \endtable

    \section2 Using ccache with CMake

    To enable using \l{https://ccache.dev}{ccache} when building \QBS, pass the following options
    to CMake:
    \code
        cmake -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache ..
    \endcode

    \section1 Building \QBS with \QBS

    It is also possible to build \QBS with the previously installed \QBS version.
    To build \QBS, enter the following command in the source directory:
    \code
        qbs
    \endcode
    This will use the \c defaultProfile or pick up the Qt version and the toolchain from the \c PATH
    if the \c defaultProfile is not set. See \l {Configuring Profiles and Preferences} for details
    about profiles.

    To run automatic tests, the \c autotest-runner product should be built:
    \code
        qbs build -p autotest-runner
    \endcode
    \QBS will use an empty profile when running tests which means it will try to autodetect
    toolchains, Qt versions and other things based on the system environment.
    It is possible to specify which profile should be used during the test-run by passing the
    \c QBS_AUTOTEST_PROFILE environment variable.
    This variable should be set prior to building \QBS itself; otherwise the \c resolve command
    should be used to update the environment stored in the buildgraph:
    \code
        export QBS_AUTOTEST_PROFILE=qt
        qbs resolve
        qbs build -p autotest-runner
    \endcode

    It is also possible to set up a separate profile for a particular testsuite.
    A profile for the \c tst_blackbox_android suite can be set up as follows:
    \code
        qbs setup-android pie
        export QBS_AUTOTEST_PROFILE_BLACKBOX_ANDROID=pie
    \endcode

    It might be useful to set up the directory with the \QBS settings to isolate the test
    environment:
    \code
        export QBS_AUTOTEST_SETTINGS_DIR=~/path/to/qbs/settings
    \endcode

    \section2 \QBS Build Options

    The \c qbsbuildconfig module can be used to customize the build.
    Properties of that module can be passed using command line as follows:
    \code
        qbs build modules.qbsbuildconfig.enableAddressSanitizer:true
    \endcode

    \QBS recognizes the following properties:
    \table
    \header
        \li Property
        \li Default value
        \li Notes
    \row
        \li enableAddressSanitizer
        \li \c false
        \li Whether to use address sanitizer or not. Enabling this option will add the
            -fsanitize=address flag.
    \row
        \li enableUnitTests
        \li \c false
        \li Enable additional autotests. Enabling this option will export some symbols that would
            otherwise be private.
    \row
        \li enableRPath
        \li \c true
        \li Use this property to 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 installApiHeaders
        \li \c true
        \li Holds whether to install the header files for the \QBS libraries or not. This option
            is required to build against the \QBS libraries.
    \row
        \li enableBundledQt
        \li \c false
        \li Holds whether the Qt libraries that \QBS depends on will be bundled with \QBS during
            the \c install step. This option is only implemented on macOS.
    \row
        \li libDirName
        \li \c "lib"
        \li Directory name used by \c libInstallDir and \c importLibInstallDir properties.
    \row
        \li appInstallDir
        \li \c "bin"
        \li Relative directory path under the install prefix path to put application binaries.
    \row
        \li libInstallDir
        \li \c "bin" on Windows, \c libDirName otherwise
        \li Relative directory path under the install prefix path where to put shared libraries
            (excluding plugins, see the \c relativePluginsPath property).
    \row
        \li importLibInstallDir
        \li \c libDirName
        \li Relative directory path under the install prefix path where to put import libs.
    \row
        \li libexecInstallDir
        \li \c appInstallDir on Windows, \c "libexec/qbs" otherwise
        \li Relative directory path under the install prefix path where to put auxiliary binaries
            executed by the \QBS libraries.
    \row
        \li systemSettingsDir
        \li \c undefined
        \li Directory that will be used by \QBS to store its settings. If not specified, a default
            platform-dependent directory is used.
    \row
        \li installManPage
        \li \c true on Unix, \c false otherwise
        \li Whether to install man pages.
    \row
        \li installHtml
        \li \c true
        \li Whether to install HTML help pages.
    \row
        \li installQch
        \li \c false
        \li Whether to install qch files. See
            \l{https://doc.qt.io/qt-5/qthelp-framework.html}{The Qt Help Framework} for details
            about qch files.
    \row
        \li generatePkgConfigFiles
        \li auto-detected
        \li Whether to generate files for pkg-config.
    \row
        \li generateQbsModules
        \li auto-detected
        \li Whether to generate \QBS modules for the exported \QBS libraries. Use this when
            building another product against \QBS libraries using \QBS as build system.
    \row
        \li docInstallDir
        \li \c "share/doc/qbs/html"
        \li Relative directory path under the install prefix path where to put documentation.
    \row
        \li pkgConfigInstallDir
        \li \c libDirName + \c "/pkgconfig"
        \li Relative directory path under the install prefix path where to put pkg-config files.
    \row
        \li qbsModulesBaseDir
        \li \c libDirName + \c "/qbs/modules"
        \li Relative directory path under the install prefix path where to put \QBS modules.
            Applies only when \c generateQbsModules is \c true.
    \row
        \li relativeLibexecPath
        \li \c "../" + \c libexecInstallDir
        \li Path to the auxiliary binaries relative to the application binary.
    \row
        \li relativePluginsPath
        \li \c "../" + \c libDirName
        \li Path to plugin libraries relative to the application binary.
    \row
        \li relativeSearchPath
        \li \c ".."
        \li Relative path to the directory where to look for \QBS development modules and items.
    \row
        \li libRPaths
        \li auto-detected
        \li List of rpaths.
    \row
        \li resourcesInstallDir
        \li \c ""
        \li Relative directory path under the install prefix path where to put shared resources
            like documentation, \QBS user modules and items.
    \row
        \li pluginsInstallDir
        \li \c libDirName + \c "/qbs/plugins"
        \li Relative path to the directory where to put plugins to.
    \endtable

    \section1 Using 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 10 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.

    The images provide everything that is necessary to build and test \QBS:

    \list
        \li Qt SDK for building \QBS with \c qmake
        \li Latest stable release of \QBS for building \QBS with \QBS
    \endlist

    We are using docker-compose for building and running the Docker images because it simplifies
    the Docker command line and ensures that the correct image tag is used. All available images
    are listed in the \c docker-compose.yml file in the project root directory.

    Run the following command to download the \QBS development image based on Ubuntu 20.04
    \e Focal:

    \code
        docker-compose pull focal
    \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-compose run --rm focal
    \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}.

    We are using docker-compose for building and running the Docker images because it simplifies
    the Docker command line and ensures that the correct image tag is used. All available images
    are listed in the \c docker-compose.yml file in the project root directory.

    Run the following command to download the \QBS development image based on Windows 10:

    \code
        docker-compose pull windows
    \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-compose run --rm windows
    \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-compose run --rm windows
    \endcode

    \section2 Building Release Packages

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

    \code
        docker-compose run --rm windows cmd /c scripts\make-release-archives
    \endcode

    For building release packages for Windows on macOS or Linux:

    \code
        eval $(docker-machine env windows)
        docker-compose run --rm windows cmd /c scripts\\make-release-archives
    \endcode
*/


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

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

    \title Configuring Profiles and Preferences

    Profiles contain properties that apply to one or more projects. They are
    stored independently of the project files and are usually not shared between
    build hosts. Typically, profiles contain module properties, such as
    installation paths of tools or libraries on the host computer. This approach
    has the following advantages, among others:

    \list
        \li Team members with different computer setups can work together
            smoothly because no host-specific settings end up in the project
            files.
        \li Different versions of a tool or library can be used to build the
            same project without affecting each other.
    \endlist

    For example, a profile for building C++ applications contains at least the
    installation path and the type of the compiler toolchain. A profile for
    building Qt applications contains the toolchain-specific properties as well
    as \l{Qt::qmakeFilePaths}{the path to the Qt installation}.

    This topic describes profiles stored in the \QBS settings. In some cases it
    might be beneficial to keep profiles explicitly in the project sources. This
    can be achieved with the \l{Profile} item.

    \section1 Setting Up Toolchain Profiles

    \QBS comes with a helper tool \l{setup-toolchains} that can
    create profiles for many toolchains. Open a terminal window and type:

    \code
    qbs setup-toolchains --detect
    \endcode

    This will automatically set up a profile for each detected toolchain on your
    computer. You can list the existing profiles by running:

    \code
    qbs config --list profiles
    \endcode

    Some toolchains, especially for bare-metal targets, may require additional
    module properties. Those can be added with the \l{config} or the
    \l{config-ui} tools. Now you should be ready to build your first project
    with \QBS. Go into examples/helloworld-minimal and type:

    \code
    qbs build profile:<profile name>
    \endcode

    You have successfully built your first \QBS project. If you want to build
    projects that use Qt, additional steps might be necessary. Please refer to
    \l{Managing Qt Versions} for more information.

    \section1 Global Preferences

    In addition to profiles, \QBS provides some global preferences such as \c
    qbsSearchPaths and \c defaultProfile.

    \section1 Managing Profiles and Preferences

    You can use the \l{config} command to manage all \QBS configuration
    settings, such as profiles and global preferences from the command line,
    for example:

    \code
    qbs config profiles.<someprofile>.qbs.architecture arm
    \endcode

    For convenience, \QBS provides a tool \l{config-ui} where you can manage the
    settings in a hierarchical view.

    \image qbs-settings-gui.png

    \QBS Settings displays the keys in the specified settings directory and
    their values. To expand all keys, select \uicontrol View >
    \uicontrol {Expand All} (\key Ctrl+E or \key Cmd+E on macOS). To collapse
    all keys, select \uicontrol {Collapse All} (\key Ctrl+C or \key Cmd+C).

    To change the value of a key, double-click it and enter the new value.

    To save your changes, select \uicontrol File > \uicontrol Save.

    To refresh the settings from the settings directory, select \uicontrol File
    > \uicontrol Reload.

*/

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

    \title Managing Qt Versions

    \section1 Introduction

    If your environment has the right \c qmake binary in its \c PATH and is also set up
    properly for a matching toolchain, then you do not necessarily need a profile
    to build projects with a Qt dependency. Otherwise, you should create one:

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

/*!
    \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{Target Platforms}
        \li  \l{Using the Shell}
        \li  \l{Generators}
        \li  \l{Multiplexing}
        \li  \l{Custom Modules and Items}
        \li  \l{Special Property Values}
        \li  \l{Module Providers}
    \endlist

*/

/*!
    \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}{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---
        Application {
            name: "helloworld"
            files: "main.cpp"
            Depends { name: "cpp" }
        }
    \endcode

    \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 \l{cpp} module. 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---
    Product {
        property string craziness: "low"

        files: [
            "Crazy.h",
            "Crazy.cpp"
        ]
    }

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

    CrazyProduct {
        craziness: "enormous"
        name: "hellocrazyworld"
        files: base.concat(["main.cpp"])
        // ...
    }
    \endcode

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

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

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

    See \l {Special Property Values} for more details about the \l base property.

    \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++ toolchain.
    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---
        Application {
            name: "helloworld"
            files: ["main.cpp"]
            cpp.optimization: "ludicrousSpeed"
            Depends { name: "cpp" }
        }
    \endcode

    A module can depend on other modules. For example, the
    \l{Qt.core} module depends on the \l{cpp} module. The module dependencies are transitive,
    i.e. in a Product, all dependent modules are accessible:

    \code
        Application {
            name: "helloworld"
            files: ["main.cpp"]
            Depends { name: "Qt.core" }
            // the "cpp" module is available since
            // "Qt.core" depends on "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.includes("windows")
            files: [
                "harddiskdeleter_win.cpp",
                "blowupmonitor_win.cpp",
                "setkeyboardonfire_win.cpp"
            ]
        }
        Group {
            condition: qbs.targetOS.includes("linux")
            files: [
                "harddiskdeleter_linux.cpp",
                "blowupmonitor_linux.cpp",
                "setkeyboardonfire_linux.cpp"
            ]
        }
    \endcode

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

    \list
        \li \l{qbs::}{buildVariant} that specifies the name of the build variant
            for the current build.
        \li \l{qbs::}{targetOS} that specifies the operating system you want to
            build the project for.
    \endlist

    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 config:release              # qbs.buildVariant:release, profile:<default profile>
    $ qbs config:debug config: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.
    \row
        \li \c varList
        \li \c{property var aMapList: [{ key1: "value1", key2: "value2" }, { key1: "value3" }]}
        \li A list of generic data, typically JavaScript objects.
    \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}.
*/


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

    \title Building Applications

    This section assumes that \QBS is present in \c PATH. For the details how to install \QBS, see
    the \l{Installing} page.

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

    \code
    cd examples/collidingmice
    qbs
    \endcode

    By default, \QBS uses all the CPU cores available to achieve maximum build
    parallelization. To explicitly specify the number of concurrent jobs, use
    the \c -j option. For example, to run 4 concurrent jobs, enter the following
    command:

    \code
    qbs -j4
    \endcode

    The application is built using the default build profile that is set up
    in your \QBS configuration.

    You can use the \l{config} command to set the max number of jobs per profile.
    For example, to set four jobs as the default option for a profile named
    \e Android, enter the following command:

    \code
    qbs config profiles.Android.preferences.jobs 4
    \endcode

    To build with other profiles than the default one, specify options for the
    \l{build} command. For example, to build debug and release configurations with
    the \e Android profile, enter the following command:

    \code
    qbs build profile:Android config:debug config: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 \l{cpp::treatWarningsAsErrors}
    {cpp.treatWarningsAsErrors} is set to \c true for debug only and
    \l{cpp::optimization}{cpp.optimization} is set to \c small for release only.

    \code
    qbs build config:debug modules.cpp.treatWarningsAsErrors:true config:release modules.cpp.optimization:small
    \endcode

    Projects are built in the debug build configuration by default.
*/

/*!
    \previouspage running-applications.html
    \page installing-files.html
    \nextpage {Target Platforms}

    \title Installing Files

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

    \code
    Application {
        Group {
            name: "Icons"
            files: "*.png"
            qbs.install: true
            qbs.installDir: "share/icons/myproject"
        }
        Group {
            name: "Docs"
            fileTagsFilter: "generated_docs"
            qbs.install: true
            qbs.installDir: "share/man/man7"
        }
    }
    \endcode

    In this example, we want to install some \c{.png} files and documentation built by the project.
    The Application is installed automatically unless the \l{Application::install}{install}
    property is set to \c false.

    When building, \QBS installs artifacts into the default root folder, namely
    \c{<build root>/install-root}. The \l{qbs::installPrefix}{qbs.installPrefix} and
    \l{qbs::installDir}{qbs.installDir} properties are appended to the root folder.
    \code
    qbs build qbs.installPrefix:/usr
    \endcode
    In this example, the executable will be installed into the \c{<build root>/install-root/usr/bin}
    folder and the QML files will be installed into the
    \c{<build root>/install-root/usr/share/myproject} folder.

    To skip installation during the build, use the \c --no-install option.

    To override the default location, use the \c --install-root option of the \c{qbs install}
    command:
    \code
    qbs build --no-install qbs.installPrefix:/usr
    sudo qbs install --no-build --install-root /
    \endcode
    In this example, artifacts will be installed directly into the \c /usr folder. Since the
    \c{qbs install} command implies \c build, we use the \c --no-build parameter to ensure that
    we do not accidentally rebuild the project, thereby changing the artifacts' owner to \c root.

    Sometimes, it makes sense to install the application into a temporary root folder, keeping the
    same folder structure within that root folder as in the examples above; for instance,
    when building a Linux package such as \c deb or \c rmp. To install the application into the
    \c /tmp/myProjectRoot folder, use the following command:

    \code
    $ qbs install --install-root /tmp/myProjectRoot
    \endcode

    In this example, the executable will be installed into the \c{/tmp/myProjectRoot/usr/bin} folder
    and QML files will be installed into the \c{/tmp/myProjectRoot/usr/share/myproject} folder.

    To remove all files from the install root prior to installing, use the \c --clean-install-root
    parameter:

    \code
    qbs install --clean-install-root --install-root /tmp/myProjectRoot
    \endcode

    For more information about how the installation path is constructed, see
    \l {Installation Properties}.
*/

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

    \title Running Applications

    Qbs has the convenience \l{run}{qbs run} command that simplifies running applications.

    For example, entering the following command runs the Qt Creator application:

    \code
    qbs run --products qtcreator
    \endcode

    By default, running an application also builds it and installs it to a
    location from where it can be run on the desktop or on a device. Also, this command
    \l{Module::setupRunEnvironment}{sets up} the environment so that the application can find
    dependent libraries.

    This is not the case when running the binary manually - you'll have to make sure that the
    app will find its dependencies and/or is relocatable. You can achieve that by
    \l{How do I make use of rpaths?}{configuring rpaths} properly or setting the appropriate
    environment variable for the respective host system.

*/

/*!
    \previouspage {Target Platforms}
    \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.

*/

/*!
    \previouspage multiplexing.html
    \page custom-modules.html
    \nextpage special-property-values.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} in there and give it the \c{.qbs}
    extension. This module will be pulled in if a
    \l{Product}{product} declares a \l{Depends}{dependency} on \c mymodule.


    \section1 Custom Items

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

    \note Item file names must start with a capital letter due to the fact that type names can
    only start with a capital letter. Otherwise, the file will be silently ignored.

    \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 \l{Project::qbsSearchPaths}
    {Project.qbsSearchPaths} property. Any product that wants to make use of
    them needs to be in a different file that is pulled in via the
    \l{Project::references}{Project.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 is best to add the location to your preferences.
    For example:
    \code
    qbs config preferences.qbsSearchPaths /usr/local/share/custom-qbs-extensions
    \endcode

*/

/*!
    \previouspage custom-modules.html
    \page special-property-values.html
    \nextpage module-providers.html

    \title Special Property Values

    Depending on the context, \QBS provides the following special values for use in property
    bindings and JavaScript code:

    \list
        \li \l base
        \li \l exportingProduct
        \li \l filePath
        \li \l importingProduct
        \li \l module
        \li \l original
        \li \l outer
        \li \l path
        \li \l product
        \li \l project
    \endlist

    \section2 \c base
    This value is useful when making use of inheritance. It stands for the value of the respective
    property in the item one level up in the inheritance chain. For instance:
    \code
    Product { // defined in MyProduct.qbs
        Depends { name: "mymodule" }
        mymodule.someProperty: ["value1"]
    }
    ------ some other file ------
    MyProduct {
        mymodule.someProperty: base.concat(["value2"]) // => ["value1", "value2"]
    }
    \endcode

    \section2 \c exportingProduct
    Within an \l Export item, you can use the \c exportingProduct variable to refer to
    the product which defines the Export item:

    \code
    Product {
        Export {
            Depends { name: "cpp" }
            cpp.includePaths: exportingProduct.sourceDirectory
        }
    }
    \endcode

    \section2 \c filePath

    This value holds the full file path to the \c .qbs file it appears in. This property is
    rarely used, but might be useful when debugging:
    \code
    Product {
        property bool dummy: {
            console.info("I'm located at " + filePath);
        }
    }
    \endcode

    \section2 \c importingProduct
    Within an \l Export item, you can use the \c importingProduct variable to refer to
    the product that pulls in the resulting module:

    \code
    Product {
        Export {
            Depends { name: "cpp" }
            cpp.includePaths: importingProduct.buildDirectory
        }
    }
    \endcode
    Usually, you should use the \l product variable instead for consistency with \l Module items.

    \section2 \c module

    This value holds the properties of the module that contains the current item:
    \code
    Module {
        property bool enableGroup
        property bool enableRule
        Group {
            condition: enableGroup // available without qualification because Module is a direct parent item
            Rule {
                condition: module.enableRule // Shortcut for product.<module name>.enableRule
                // ...
            }
        }
    }
    \endcode

    \section2 \c original
    On the right-hand side of a module property binding, this refers to the value of the property
    in the module itself (possibly overridden from a profile). Use it to set a module property
    conditionally:
    \code
    Module { // This is mymodule
        property string aProperty: "z"
    }
    ----------
    Product {
        Depends { name: "mymodule" }
        Depends { name: "myothermodule" }
        // "y" if myothermodule.anotherProperty is "x", "z" otherwise:
        mymodule.aProperty: myothermodule.anotherProperty === "x" ? "y" : original
    }
    \endcode
    \note In all but the most exotic cases, a \l{Properties} item is the preferred way to
          achieve the same result:
    \code
    Product {
        Depends { name: "mymodule" }
        Depends { name: "myothermodule" }
        Properties {
            condition: myothermodule.anotherProperty === "x"
            mymodule.aProperty: "y"
        }
    \endcode

    \section2 \c outer
    This value is used in nested items, where it refers to the value of the respective property
    in the surrounding item. It is only valid in \l{Group} and \l{Properties} items:
    \code
    Product {
        Depends { name: "mymodule" }
        mymodule.someProperty: ["value1"]
        Group {
            name: "special files"
            files: ["somefile1", "somefile2"]
            mymodule.someProperty: outer.concat(["value"]) // => ["value1", "value2"]
        }
    }
    \endcode

    \section2 \c path

    This value holds the path to the folder where the \c .qbs file is located. Use it to e.g. add
    the product's directory to file paths:
    \code
    Product {
        Depends { name: "cpp" }
        cpp.includePaths: path
    }
    \endcode

    \section2 \c product

    This value holds the properties of the product that contains the current item or pulls in the
    current module:
    \code
    Module {
        Rule {
            Artifact {
                fileTags: product.type
                filePath: {
                    var result = input.fileName;
                    // module properties are available as well
                    if (product.qbs.buildVariant === "debug")
                        result = result + "_debug";
                    result = result + ".out";
                    return result;
                }
            }
        }
    }
    \endcode
    Within the \l Export item, same as \l importingProduct.

    \section2 \c project
    This value holds the properties of the project that references the current item or pulls in the
    current module:
    \code
    Project {
        property bool enableProduct: true
        Product {
            name: "theProduct"
            condition: project.enableProduct
        }
    }
    \endcode
    If the nearest project in the project tree does not have the desired property, \QBS looks it
    up in the parent project, potentially all the way up to the top-level project.
*/

/*!
    \previouspage special-property-values.html
    \page module-providers.html
    \nextpage tutorial.html

    \title Module Providers

    There are use cases for which a pre-defined module is not flexible enough.
    For instance, the overall set of modules related to a certain task might depend
    on some information present on the local platform.

    Use Module Providers to create new modules during the \c resolve stage, for example when
    locating external dependencies such as libraries.

    Consider the following example:

    \code
    CppApplication {
        files: "main.cpp"
        Depends { name: "zlib" }
        qbsModuleProviders: ["conan", "qbspkgconfig"]
    }
    \endcode
    Here, we want to use the \l{https://www.zlib.net}{zlib} compression library in our application.
    Since there is no pre-defined module called \c "zlib", \QBS will try to create it using
    Module Providers. \QBS will invoke all providers specified in the
    \l{Product::qbsModuleProviders}{qbsModuleProviders} property and those providers will create
    the requested module if possible. Providers contribute to the \l{Product::}{qbsSearchPaths}
    in the order specified by this property, so modules generated by providers specified earlier
    are prioritised. In the example above, modules created by the \l conan provider have higher
    priority than modules created by \c qbspkgconfig.

    \section1 Lookup Based on Module Name
    Originally, the \l{Qt} module provider was a the only provider in \QBS and we wanted to make
    its usage transparent to users. Thus, it was implemented by automatically kicking in when \QBS
    saw the dependency on the \c Qt module such as "Qt.core". It is also possible to specify the
    order of providers explicitly:
    \code
    CppApplication {
        files: "main.cpp"
        Depends { name: "Qt.core" }
        qbsModuleProviders: ["Qt", "qbspkgconfig"]
    }
    \endcode
    That way, users have more control over the module priorities.

    Note that setting the \c qbsModuleProviders property disables the lookup based on the
    module name entirely.

    \section1 Provider Eagerness
    Historically, providers were implemented in an \e eager way meaning that once a provider is
    called, it creates as many modules as it can. For example, when called, the \l{qbspkgconfig}
    provider created a module for each .pc file found in the system. Even though providers are
    quite fast, this violates the zero-overhead principle (you don't pay for what you don't use).
    Thus, we introduced non-eager providers which only create one module at a time when that
    module is requested by the \l{Depends} item. This behavior is controlled by the
    \l{ModuleProvider::isEager}{isEager} property. We advise against using eager providers in
    new code.

    \section1 Selecting Module Providers

    As described above, you can select which providers to run using the
    \l{Product::qbsModuleProviders}{qbsModuleProviders} property. This property can be set on the
    Product as well as the \l{Project::qbsModuleProviders}{Project} level:

    \code
    $ qbs resolve project.qbsModuleProviders:providerA    \ # sets property globally for the Project
        projects.SomeProject.qbsModuleProviders:providerB \ # overrides property for the specific Project
        products.SomeProduct.qbsModuleProviders:providerC \ # overrides property for the specific Product
    \endcode

    \section1 Parameterizing Module Providers

    You can pass information to module providers from the command line, via profiles or
    from within a product, in a similar way as you would do for modules. For instance, the
    following invocation of \QBS passes information to two module providers \c a and \c b:
    \code
    $ qbs moduleProviders.a.p1:true moduleProviders.a.p2:true moduleProviders.b.p:false
    \endcode
    \QBS will set the properties of the respective module providers accordingly.
    In the above example, module provider \c a needs to declare two boolean properties \c p1
    and \c p2, and they will be set to \c true and \c false, respectively.

    \note The following section contains some implementation details. Reading this section is not
    required for most people's everyday work.

    \section1 How \QBS Uses Module Providers

    If \QBS encounters a \l Depends item whose name does not match a known module,
    it checks whether such a module can be generated. This procedure works as follows:
    \list 1
        \li If the \l{Product::qbsModuleProviders}{qbsModuleProviders} property is not
            \c undefined, for each provider name in the list, all
            \l{Project::qbsSearchPaths}{search paths} are scanned for a file called
            \c {module-providers/<name>.qbs} or \c {module-providers/<name>/provider.qbs}.
        \li If the \l{Product::qbsModuleProviders}{qbsModuleProviders} property is \c undefined,
            \l{Project::qbsSearchPaths}{search paths} are scanned for a file called
            \c {module-providers/<name>/provider.qbs}, where \c <name> is the name of the dependency
            as specified in the \c Depends item. Multi-component names such as "a.b" are turned
            into nested directories, and each of them is scanned, starting with the deepest path.
            For instance, if the dependency's name is \c {a.b}, then \QBS will look for
            \c {a/b/provider.qbs} and then \c {a/provider.qbs}.
        \li If such a file is found, it needs to contain a \l ModuleProvider item. This item
            is instantiated, which potentially leads to the creation of one or more modules,
            and \QBS retrieves the search paths to find these modules from the item.
            The details are described in the \l ModuleProvider documentation.
        \li If a matching module provider was found and provided new search paths,
            a second attempt will be made to locate the dependency using the new paths.
            The search for a matching module provider ends as soon as one was found, regardless
            of whether it created any modules or not.
    \endlist

*/

/*!
    \previouspage shell.html
    \page generators.html
    \nextpage multiplexing.html

    \title Generators

    Generators are a \QBS sub-tool and set of APIs that enable arbitrary
    processing to be performed on the build graph. Currently, they are used to
    integrate \QBS with popular IDEs, such as Microsoft Visual Studio, and to
    generate Clang compilation databases.

    \section1 Generating Microsoft Visual Studio Projects

    To generate a project for another build system, such as Microsoft Visual
    Studio, use the \l{generate}{qbs generate} command and specify a generator
    using the \l{generate-generator}{-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. The resulting project files can be opened in the respective IDE
    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
    \l{generate}{qbs generate} in order for the changes to be reflected in your
    IDE.

    \section1 Generating IAR Embedded Workbench Projects

    To generate a project for \l{https://www.iar.com/iar-embedded-workbench/}
    {IAR Embedded Workbench}, use the \l{generate}{qbs generate} command and specify
    a generator using the \l{generate-generator}{-g} option. For example:

    \code
    # For IAREW v8xxxx
    qbs generate -g iarew8 profile:<your/qbs/profile>
    qbs generate -g iarew8 -d <path/to/build/directory> -f <path/to/qbs/project> profile:<your/qbs/profile>
    \endcode

    \note You need to specify a specific QBS profile, which is required for a generator
    to fetch a target architecture to generate the project.

    \note IAR EW generator creates a native target project.

    Supported IAR EW generators are listed in a table below:

    \table
    \header \li Generator       \li IAR EW Version      \li Target Architecture
    \row    \li iarew8          \li All 8.x.y versions  \li ARM
    \row    \li iarew7          \li All 7.x.y versions  \li AVR, MSP430
    \row    \li iarew10         \li All 10.x.y versions \li 8051 (aka MCS51)
    \row    \li iarew3          \li All 3.x.y versions  \li STM8
    \endtable

    \section1 KEIL uVision Projects

    To generate a project for \l{https://www2.keil.com/mdk5/uvision/}
    {KEIL uVision}, use the \l{generate}{qbs generate} command and specify
    a generator using the \l{generate-generator}{-g} option. For example:

    \code
    # For KEIL UV5
    qbs generate -g keiluv5 profile:<your/qbs/profile>
    qbs generate -g keiluv5 -d <path/to/build/directory> -f <path/to/qbs/project> profile:<your/qbs/profile>
    \endcode

    \note You need to specify a specific QBS profile, which is required for a generator
    to fetch a target architecture to generate the project.

    \note KEIL UV generator creates a native target project.

    Supported KEIL UV generators are listed in a table below:

    \table
    \header \li Generator       \li KEIL UV Version     \li Target Architecture
    \row    \li keiluv5         \li All 5.x.y versions  \li 8051 (aka MCS51), ARM
    \endtable

    \section1 Generating Clang Compilation Databases

    To generate a \l{JSON Compilation Database Format Specification}
    {Clang compilation database (clangdb)}, use the following command:

    \code
    qbs generate --generator clangdb
    \endcode

    \section1 Generating Makefiles

    To generate a Makefile, use the following command:
    \code
    qbs generate --generator makefile
    \endcode

    \section2 Targets

    The generated Makefile will contain targets for all output artifacts known to \QBS.

    In addition, the following targets are created for every product:
    \list
        \li \c {<product-name>} to build the product
        \li \c {clean-<product-name>} to remove all files generated by the above target
        \li \c {install-<product-name>} to install the product's artifacts that have
                                        \c{qbs.install} set
    \endlist
    In the above list, the placeholder \c{<product-name>} stands for the product's name with
    all characters that are not ASCII letters, digits, dots or underscores replaced
    with underscore characters.

    The special target \c all builds all products whose \l{Product::builtByDefault}{builtByDefault}
    property is enabled. This is the default target. It is complemented by \c install and \c clean.

    \note The Makefile will not be able to build artifacts created by
    \l{JavaScriptCommand}{JavaScriptCommands}, because there is no command line to run for them.

    \section2 Pre-defined Variables

    The build directory and the install root are set to whatever you specified when calling the
    generator. If you did not specify anything, \QBS' default values are used. You can override
    these values when invoking the \c make tool by explicitly setting the \c{BUILD_ROOT}
    and \c{INSTALL_ROOT} variables, respectively. For instance:
    \code
    $ qbs generate -g makefile config:make modules.qbs.installRoot:/opt/mydir
    $ make -f make/Makefile                                 # Will install to /opt/mydir
    $ make -f make/Makefile INSTALL_ROOT=/opt/myotherdir    # Will install to /opt/myotherdir
    \endcode

    \section2 Spaces in Directory Names

    Due to the difficulties involved in making this work correctly, \QBS will refuse to generate
    a Makefile if the source, build or install root directories contain spaces. It will
    try to handle spaces in file names of output artifacts, though.

    \section2 Platform-specific Differences in Format

    \QBS assumes that the Makefile will be invoked on the current host platform, so that
    platform's tools will be used for copying and removing files, and path separators will
    be converted to backslashes on Windows. When dealing with spaces in artifact names,
    on Unix-like systems compatibility with GNU make is assumed with regards to quoting.

    \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 Microsoft 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 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::name}{Product.name}
        \li \l{bundle::isBundle}{bundle.isBundle}
    \endlist

    If a simple workaround is possible in a particular case (for example,
    varying \l{Product::targetName}{Product.targetName} across configuration
    instead of \l{Product::name}{Product.name}, the generator will typically
    suggest it in the error message.
*/

/*!
    \previouspage generators.html
    \page multiplexing.html
    \nextpage custom-modules.html

    \title Multiplexing

    Multiplexing is an advanced \QBS feature that allows a product to be
    transparently built in multiple \e passes along with an optional, final
    \e aggregate pass that allows the output artifacts of the initial passes
    to be combined or otherwise operated on in some way.

    The multiplexing feature is used to implement certain platform-specific
    behavior: specifically, it allows applications and libraries on Apple
    platforms to be compiled into \e fat binaries containing multiple CPU
    architectures, the creation of Apple frameworks containing multiple
    \e variants (for example, combined debug and release builds), and the
    creation of Android application and library packages containing native
    code built for multiple Android ABIs.

    A product can be multiplexed over the \l{qbs::architectures}
    {qbs.architectures} property (which maps to \l{qbs::architecture}
    {qbs.architecture}), \l{qbs::buildVariants}{qbs.buildVariants} property
    (which maps to \l{qbs::buildVariant}{qbs.buildVariant}), and \l{qbs::profiles}
    {qbs.profiles} (which maps to \l{Project::profile}{Project.profile}).

    For example, to build a "fat" \c iOS binary containing two architectures, use the following
    command:
    \code
        qbs build modules.qbs.targetPlatform:ios modules.qbs.architectures:arm64,armv7a
    \endcode

    \note The implementation details around multiplexing are subject to change.

    Product multiplexing works by examining the
    \l{Product::multiplexByQbsProperties}{Product.multiplexByQbsProperties}
    property, which can
    be set to the list of properties your product should multiplex over. For
    example, \c multiplexByQbsProperties might contain two strings,
    \c "architectures" and \c "buildVariants". \QBS evaluates the values of
    \c qbs.architectures and \c qbs.buildVariants, which in turn might contain
    the values \c ["x86", "x86_64"] and \c ["debug", "release"]. \QBS will build
    all the possible configurations of the product: \c {(x86, debug)},
    \c {(x86, release)}, \c {(x86_64, debug)}, and \c {(x86_64, release)}.

    If the \l{Product::aggregate}{Product.aggregate} property is \c true, the
    product will also be
    built a fifth time, with the values of the multiplexed properties left
    undefined. The aggregate product will have an automatic dependency on the
    original four instances of the product, allowing it to collect their output
    artifacts and to operate on them.

    The aggregate product is used in situations where the target artifacts of
    the individually multiplexed instances must be combined into one final
    aggregate artifact that makes up the overall product.
    Bundle products on Apple platforms use the aggregate product to create the
    bundle artifacts (such as \c Info.plist and \c PkgInfo) that are independent
    of a particular architecture or build variant. In addition, they use the
    \c lipo tool to join together the built native code for different
    architectures (such as \c x86 and \c x86_64) into the final,
    multi-architecture fat binary that the app bundle contains.
*/

/*!
    \previouspage json-api.html
    \page attributions.html

    \title Appendix D: Licenses and Code Attributions

    \section1 Licenses

    The \QBS library and tools are available under commercial licenses from
    \l{Qt Licensing}{The Qt Company}. In addition, they are available under
    \l{GNU Lesser General Public License, Version 3} (LGPL version 3) and
    \l{GNU General Public License, version 2} (GPL version 2).

    Shared functionality, which might be pulled in by user build scripts, is
    available under commercial licenses,
    \l{GNU Lesser General Public License, Version 2.1} (LGPL version 2.1) with
    \l{The Qt Company LGPL Exception version 1.1}, and LGPL version 3.

    Autotests are available under commercial licenses and
    \l{GNU General Public License Version 3, Annotated with The Qt Company GPL Exception 1.0}.

    Examples are available under commercial licenses and \l{BSD}.

    \section2 GNU Lesser General Public License, Version 3

    \quotefile ../LICENSE.LGPLv3

    \section2 GNU General Public License Version 3, Annotated with The Qt Company GPL Exception 1.0

    \quotefile ../LICENSE.GPL3-EXCEPT

    \section2 GNU Lesser General Public License, Version 2.1

    \quotefile ../LICENSE.LGPLv21

    \section2 The Qt Company LGPL Exception version 1.1

    \quotefile ../LGPL_EXCEPTION.txt

    \section1 Third-Party Attibutions

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