/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** 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.
**
****************************************************************************/

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

/*!
    \previouspage creator-configuring-projects.html
    \page creator-targets.html
    \nextpage creator-project-qmake.html

    \title Adding Kits

    \QC groups settings used for building and running projects as kits
    to make cross-platform and cross-configuration development easier. Each kit
    consists of a set of values that define one environment, such as a
    \l{glossary-device}{device}, compiler, Qt version, and debugger command
    to use, and some metadata, such as an icon and a name for the kit. Once
    you have defined kits, you can select them to build and run projects.

    \QC supports development for the desktop and for the following types of
    devices:

    \list
        \li \l{Connecting Android Devices}{Android Device}
        \li \l{Connecting Bare Metal Devices}{Bare Metal Device}
        \li \l{https://doc.qt.io/QtForDeviceCreation/b2qt-installation-guides.html}
            {Boot2Qt Device} (commercial only)
        \li \l{Emulator}{Boot2Qt Emulator Device} (commercial only)
        \li \l{Connecting Generic Remote Linux Devices}{Generic Remote Linux Device}
        \li \l{Connecting iOS Devices}{iOS Device}
        \li iOS Simulator
        \li \l{Connecting MCUs}{MCU Device} (commercial only)
        \li \l{Connecting QNX Devices}{QNX Device}
        \li \l{Building Applications for the Web}{WebAssembly Runtime}
        \li \l{Qt for UWP}{Windows Phone}
        \li Windows Phone Emulator
        \li Windows Runtime (local)
    \endlist

    \section1 Filtering Kit Settings

    Typically, only a subset of the kit settings is relevant for a particular
    setup. Therefore, \QC plugins register sets of relevant settings that you
    can view and modify in \uicontrol Tools > \uicontrol Options >
    \uicontrol Kits. For example, if you use CMake to build all your projects,
    you can hide Qbs and qmake settings by default.

    \image qtcreator-kits.png

    To hide and show settings in the \uicontrol Kits tab for the
    current kit, select \uicontrol {Settings Filter}. To view and
    modify the settings displayed when you add a new kit, select
    \uicontrol {Default Settings Filter}.

    \section1 Specifying Kit Settings

    To add kits:

    \list 1

        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Kits >
            \uicontrol Add.

            \image qtcreator-kits-add.png

            To clone the selected kit, select \uicontrol Clone.

        \li In the \uicontrol Name column, enter a name for the kit.

        \li Select the \inlineimage icons/qtcreator-desktopdevice-button.png
            button to select an image to use as an icon for the kit.

        \li In the \uicontrol {File system name} field, enter a name for the kit
            to use as a part of directory names. This value is used for the
            \e CurrentKit:FileSystemName variable, which determines the name of
            the shadow build directory, for example.

        \li In the \uicontrol{Device type} field, select the type of the device.

            Double-click the icon next to the field to select the image that is
            displayed in the kit selector for this kit. You can use any
            image in a supported file format (for example, PNG). The image is
            scaled to the size 64x64 pixels. For example, using the compiler
            logo as an icon allows you to easily see, which compiler is used to
            build the project for the selected kit.

        \li In the \uicontrol Device field, select a device.

        \li In the \uicontrol Sysroot field, specify the directory where the device
            image is located. If you are not cross-compiling, leave this field
            empty.

        \li In the \uicontrol {Emulator skin} field, select the skin to use for
            the \l {Emulator}{Boot2Qt Emulator Device}.

        \li In the \uicontrol {Compiler} field, select the C or C++ compiler
            that you use to build the project. You can add compilers to the list
            if they are installed on the development PC, but were not detected
            automatically. For more information, see \l{Adding Compilers}.
            This setting is used to tell the code model which compiler is used.
            If your project type and build tool support it, \QC also tells the
            build tool to use this compiler for building the project.

        \li In the \uicontrol Environment field, select \uicontrol Change to modify
            environment variable values for build environments in
            the \uicontrol {Edit Environment Changes} dialog. For more information
            about how to add and remove variable values, see \l{Batch Editing}.

        \li Select the \uicontrol {Force UTF-8 MSVC compiler output} check box
            to either switch the language of MSVC to English or to keep the
            language setting and just force UTF-8 output, depending on the
            MSVC compiler used.

        \li In the \uicontrol Debugger field, select the debugger to debug the project
            on the target platform. \QC automatically detects available
            debuggers and displays a suitable debugger in the field. You can
            add debuggers to the list. For more information, see
            \l{Adding Debuggers}.

            For Android kits, the \uicontrol {Android GDB server} field will
            display the path to GDB server executable.

        \li In the \uicontrol {Qt version} field, select the Qt version to use for
            building the project. You can add Qt versions to the list if they
            are installed on the development PC, but were not detected
            automatically. For more information, see \l{Adding Qt Versions}.

            \QC checks the directories listed in the \c{PATH} environment
            variable for the qmake executable. If a qmake executable is found,
            it is referred to as \b{Qt in PATH} and selected as the Qt
            version to use for the \uicontrol Desktop kit that is created by default.

        \li In the \uicontrol {Qt mkspec} field, specify the name of the mkspec
            configuration that should be used by qmake. If you leave this field
            empty, the default mkspec of the selected Qt version is used.

        \li In the \uicontrol {Additional Qbs profile settings} field, select
            \uicontrol Change to add settings to Qbs build profiles. For more
            information, see \l {Editing Qbs Profiles}.

        \li In the \uicontrol {CMake Tool} field, select the CMake executable
            to use for building the project. Select \uicontrol Manage to add
            installed CMake executables to the list. For more information, see
            \l{Adding CMake Tools}.

        \li In the \uicontrol {CMake generator} field, select \uicontrol Change
            to edit the CMake
            Generator to use for producing project files. Only the generators
            with names beginning with the string \uicontrol CodeBlocks produce
            all the necessary data for the \QC code model. \QC displays a
            warning if you select a generator that is not supported.
            For more information, see \l{Using Ninja as a CMake Generator}.

        \li In the \uicontrol {CMake configuration} field, select
            \uicontrol Change to edit the parameters of the CMake configuration
            for the kit.

        \li In the \uicontrol {Meson tool} field, select the Meson tool to use
            for building the project. Select \uicontrol Manage to add installed
            Meson tools to the list. For more information, see
            \l{Adding Meson Tools}.

        \li In the \uicontrol {Ninja tool} field, select the Ninja tool to use
            for building the project with Meson. Select \uicontrol Manage to add installed
            Ninja tools to the list.

    \endlist

    \QC uses the \e {default kit} if it does not have enough information to
    choose the kit to use. To set the selected kit as the default kit,
    select \uicontrol {Make Default}.

    \section1 Editing Qbs Profiles

    To view the Qbs profile associated with the kit, select \uicontrol Tools >
    \uicontrol Options > \uicontrol Qbs > \uicontrol Profiles.

    \image creator-qbs-profiles.png "Qbs Profiles tab"

    You can add keys and values to the profile or remove them from it, as well
    as modify existing values. For a list of available keys and values, see
    \l{http://doc.qt.io/qbs/list-of-modules.html}{List of Modules} in the Qbs
    Manual.

    To edit the Qbs profile associated with the kit:

    \list 1

        \li In \uicontrol Tools > \uicontrol Options > \uicontrol Kits, select
            the kit, and then select \uicontrol Change next to the
            \uicontrol {Additional Qbs Profile Settings} field to open the
            \uicontrol {Custom Properties} dialog.

            \image qtcreator-qbs-profile-settings.png "Custom Properties dialog"

        \li Double-click an empty cell in the \uicontrol Key column to specify
            the key to add or modify as: \c <module_name>.<property_name>.

        \li Double-click the cell on the same row in the \uicontrol Value column
            to specify a value as a JSON literal.

        \li Select \uicontrol Add to add the key-value pair.

        \li Click \uicontrol OK.

    \endlist

    To modify an existing value, double-click it in the \uicontrol Value field.

    To remove the selected property, select \uicontrol Remove.

*/
