/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing
**
** This file is part of Qt Creator
**
**
** GNU Free Documentation License
**
** 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.
**
**
****************************************************************************/

/*!
    \contentspage {Qt Creator Manual}
    \previouspage creator-project-cmake.html
    \page creator-project-qbs.html
    \nextpage creator-projects-autotools.html

    \title Setting Up a Qbs Project

    To use Qbs to build a project, you must create a .qbs file for the project.
    You can use \QC to create a C or C++ project that is built with Qbs.
    For more information about Qbs, see
    the \l{http://doc.qt.io/qbs/index.html}{Qbs Manual}.

    The application is built using the default Qbs profile that is associated
    with the build and run kit. \QC automatically creates a Qbs profile for each
    kit. You can edit the build profiles by adding new keys and values.

    \section1 Building Qbs

    If you build \QC yourself from the \QC Git repository, you also need to
    fetch the Qbs submodule to get Qbs support:

    \list 1

        \li Fetch the Qbs submodule in your \QC git checkout with
            \c {git submodule update --init}.

        \li Run qmake on \QC and build \QC again.

    \endlist

    \section1 Building Applications with Qbs

    To build your application with Qbs:

    \list 1

        \li Select \uicontrol File > \uicontrol {New File or Project} > \uicontrol {Plain C
            Project (Qbs Build)} or \uicontrol {Plain C++ Project (Qbs Build)} >
            \uicontrol Choose, and follow the instructions of the wizard to create a
            Qbs project.

            \image creator-qbs-project.png

        \li Edit the .qbs file for you project. Usually, you must add the
            \c Depends item for a Qt application. For examples, see the
            \c {examples} directory in the qbs repository.

        \li Select \uicontrol Projects to specify \uicontrol {Build Settings} for the
            project.

        \li Select \uicontrol {Build Steps} > \uicontrol Details to specify build steps:

            \image creator-qbs-build-app.png

            \list 1

                \li In the \uicontrol {Build variant} field, select \uicontrol Debug to
                    include debug symbols in the build for debugging the
                    application and \uicontrol Release to create the final
                    installation file.

                \li In the \uicontrol {Parallel jobs} field, specify the number of
                    parallel jobs to use for building.

                \li Select the \uicontrol {Enable QML debugging} check box to debug
                    Qt Quick application projects.

                    \note Debugging requires opening a socket at a well-known
                    port, which presents a security risk. Anyone on the Internet
                    could connect to the application that you are debugging and
                    execute any JavaScript functions. Therefore, you must make
                    sure that the port is properly protected by a firewall.

                \li In the \uicontrol Properties field, specify the properties to pass
                    to the project. Use colons (:) to separate keys from values.
                    For more information, see
                    \l{http://doc.qt.io/qbs/language-introduction.html}
                    {Modules} in the Qbs Manual.

                \li In the \uicontrol Flags field:

                    \list

                        \li Select \uicontrol {Dry run} to test building without
                            executing commands or making permanent
                            changes to the build graph.

                        \li Select \uicontrol {Keep going} to continue building when
                            errors occur, if possible.

                        \li Select \uicontrol {Show command lines} to print actual command lines
                            to the compile output pane instead of high-level descriptions.

                        \li Select \uicontrol {Install} to copy artifacts to their install location
                            after building them. This option is enabled by default.

                        \li Select \uicontrol {Clean install root} to remove the contents of
                            the install root directory before the build starts.

                    \endlist

            \endlist

            The \uicontrol {Equivalent command line} field displays the build command
            that is constructed based on the selected options.

        \li Select \uicontrol {Clean Steps} > \uicontrol Details to specify flags for the
            cleaning step.

            \image creator-qbs-build-clean.png

            \list

                \li Select \uicontrol {Clean all artifacts} to remove all build
                    artifacts.

                \li Select \uicontrol {Dry run} to test cleaning without executing
                    commands or making permanent changes to the build graph.

                \li Select \uicontrol {Keep going} to continue cleaning when errors
                    occur, if possible.

            \endlist

            The \uicontrol {Equivalent command line} field displays the clean command
            that is constructed based on the selected options.

        \li Select \uicontrol Build > \uicontrol {Build Project} to build the application.

        \li Click the
            \inlineimage qtcreator-run.png
            (\uicontrol Run) button to deploy and run the application.
        \endlist

    \section1 Editing Build Profiles

    \image qtcreator-options-qbs.png

    You can modify a build profile that is associated with a build and run kit
    by editing the values of the keys generated by \QC and by adding new values:

    \list 1

        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Qbs.

        \li In the \uicontrol Kit field, select a build and run kit.

        \li Select \uicontrol Edit to edit the profile associated with the kit.

        \li Select \uicontrol Add to add keys and values to the profile or to
            modify existing values.

        \li In the \uicontrol Key column, spefify the key to add or modify as:
            \c <module_name>.<property_name>.

        \li In the \uicontrol Value column, specify a value as a JSON literal.

        \li Click \uicontrol OK.

    \endlist

    The values that you have modified are displayed in red in the
    \uicontrol {Profile properties} field.

    For a list of available keys and values, see the
    \l{http://doc.qt.io/qbs/list-of-modules.html}{List of Modules} in the
    Qbs Manual.
*/
