// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

// **********************************************************************
// 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 creator-project-qmake.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-manage-kits

    \title Add Qt versions

    You can install multiple versions of Qt on the development PC and use them to
    build your projects. For example, \l{glossary-device}{device} manufacturers
    offer special Qt versions for developing applications for their devices.

    To view the installed Qt versions, select \preferences > \uicontrol Kits >
    \uicontrol {Qt Versions}.

    \image {qtcreator-qt-versions.webp} {Qt Versions tab in Kits preferences}

    To view detailed information about each Qt version, select it in the list and
    select \uicontrol Details in the \uicontrol {Qt version for} section.

    To remove invalid Qt versions, select \uicontrol {Clean Up}.

    \section1 Register installed Qt versions

    You can link to a Qt that \l{Get and Install Qt}{\QOI} installed to
    automatically detect the installed Qt versions. However, you cannot link
    to a Qt that the system installed with some other package
    manager, such as your Linux distribution, brew on \macos, or Chocolatey on
    Windows, nor a self-built Qt. In those cases, select \uicontrol {Add} in
    the \uicontrol {Qt Versions} tab to add the Qt version manually, as
    instructed in \l{Set up new Qt versions}.

    To link to a Qt installation:

    \list 1
        \li Select \preferences > \uicontrol Kits > \uicontrol {Qt Versions} >
            \uicontrol {Link with Qt}.
            \image {qtcreator-link-with-qt.png} {Choose Qt Installation dialog}
        \li In the \uicontrol {Qt installation path} field, enter the path to
            the directory where you installed Qt.
        \li Select \uicontrol {Link with Qt} to automatically register Qt
            versions and kits in the Qt installation directory.
        \li Select \uicontrol {Restart Now} to restart \QC.
    \endlist

    To refresh the list of automatically detected Qt versions, select
    \uicontrol {Re-detect}.

    To remove the automatically detected Qt versions from the list, select
    \uicontrol {Remove Link}.

    If the \uicontrol {Qt Versions} tab does not show a Qt version
    under \uicontrol {Automatically Managed}, set it up manually.

    You specify the Qt version to use for each \l{glossary-buildandrun-kit}
    {kit} for building and running your projects in \preferences >
    \uicontrol Kits.

    \section1 Set up new Qt versions

    To register a Qt version, set the path to the directory that contains the
    qmake or \c {qtpaths} executable for that Qt version.

    To add a Qt version:

        \list 1

            \li Select \preferences > \uicontrol Kits >
                \uicontrol {Qt Versions} > \uicontrol Add.

                To add a Qt version on a remote Linux device or in Docker,
                select \key Shift and then select \uicontrol Add.

            \li Select the qmake or \c {qtpaths} executable for the Qt version
                to add.

            \li Select the Qt version to view and edit it.

            \li In the \uicontrol{Name} field, edit the name that \QC
                suggests for the Qt version.

            \li In the \uicontrol{qmake path} field, you can change the location
                of qmake or \c {qtpaths}.

            \li If the Qt version is for QNX, enter the path to the QNX SDK in the
                \uicontrol{QNX SDK} field.

        \endlist

    To remove a Qt version that you added manually, select it in the
    \uicontrol Manual list and then select \uicontrol Remove.

    \section1 Register documentation

    By default, \QC registers only the latest available version of the documentation for each
    installed Qt module.

    To register the documentation sets of all installed Qt versions, choose
    \uicontrol{All} from the \uicontrol{Register documentation} list.
    To register no Qt documentation at all, choose \uicontrol{None}.
    The default behavior is \uicontrol{Highest Version Only}.

    \section1 Troubleshoot Qt installations

    If \QC detects problems in the installation of a Qt version, it displays
    warnings and errors beside the name of the Qt version in the list. Select
    the Qt version to see more information about the issue and suggestions for
    fixing it.

    To verify the installation of a particular Qt version, \QC
    calls \c {qmake -query} and checks that the directories referenced in the
    output exist. If you installed Qt using \QOI, run
    \QMT to check for updates or to reinstall the Qt version.

    \section2 Self-built Qt versions

    To build projects with a self-built Qt version, add it as described in
    \l{Set up new Qt versions}.

    Your Qt has to meet the following minimum requirements:

    \list
        \li qmake is an executable that understands the \c -query command-line
            argument.
        \li The \c bin and \c include directories have to exist. \QC fetches
            these directories by running \c{qmake -query}.
    \endlist

    Add a kit for the Qt version and configure it for CMake.

    \QC issues warnings if:

    \list
        \li \c libQtCore.so is missing, so \QC cannot detect the ABI.
        \li \c toolchain.cmake is missing. For example, you built Qt with the
            \c -static option for an x86 platform.
    \endlist

    Try the following:

    \list
        \li Run \c {make install} in the build directory to install Qt into the
            configured location.
        \li Set the value of the \c CMAKE_PREFIX_PATH variable in \preferences >
            \uicontrol Kits > \uicontrol Kits > \uicontrol {CMake Configuration}
            to the location where you installed Qt.
    \endlist

    \image {qtcreator-edit-cmake-configuration-self-built-qt.webp} {Setting the path to a self-built Qt}

    \sa {Manage kits}{How to: Manage kits}, {Managing kits}
*/
