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

/*!
    \page creator-build-settings-cmake-presets.html
    \previouspage creator-reference.html

    \ingroup creator-reference-build-configurations

    \title CMake Presets

    \brief Examples of supported CMake presets.

    \c CMakePresets.json has options for project-wide builds, whereas
    \c CMakeUserPresets.json has options for your local builds.

    Create the presets files in the format described in
    \l{https://cmake.org/cmake/help/v3.24/manual/cmake-presets.7.html}
    {cmake-presets(7)} and store them in the project's root directory.
    You can then see them in the \l {Projects} view.

    \QC supports \e configure, \e build, and \e test presets up to version 5
    (introduced in CMake 3.24), but does not enforce version checking.
    It reads and uses all the fields from version 5 if present.

    You can import the presets the first time you \l {Open projects}
    {open a project}, when no \c CMakeLists.txt.user file exists or you have
    disabled all kits in the project.

    \image {qtcreator-cmake-presets-configure.webp} {Opening a project that has CMake presets}

    You can view the presets in the \uicontrol {Initial Configuration} field and
    in the environment configuration field below it.

    \image {qtcreator-cmake-presets-environment.webp} {CMake environment configuration}

    To update changes to the \c CMakePresets.json file, go to \uicontrol Build,
    select \uicontrol {Reload CMake Presets}, and then select the presets file
    to load.

    \section1 Configure Presets

    The following configure presets instruct CMake to use the default generator
    on the platform and specify the build directory for all build types.
    \c NOT_COMMON_VALUE is displayed in \uicontrol {Initial Parameters}
    and \c AN_ENVIRONMENT_FLAG in the environment configuration field.

    \code
    {
      "version": 1,
      "configurePresets": [
        {
          "name": "preset",
          "displayName": "preset",
          "binaryDir": "${sourceDir}/build/preset",
          "cacheVariables": {
            "NOT_COMMON_VALUE": "NOT_COMMON_VALUE"
            },
          "environment": {
            "AN_ENVIRONMENT_FLAG": "1"
            }
          },
          "vendor": {
            "qt.io/QtCreator/1.0": {
               "AskBeforePresetsReload": false,
               "AskReConfigureInitialParams": false,
               "AutorunCMake": false,
               "PackageManagerAutoSetup": false,
               "ShowAdvancedOptionsByDefault": true,
               "ShowSourceSubFolders": false,
               "UseJunctionsForSourceAndBuildDirectories": true
               }
          }
      ]
    }
    \endcode

    For more information about the CMake project settings in the \c vendor
    section, see \l {CMake Qt Vendor Presets}.

    \section1 MinGW Example

    The following example configures a Qt project with:

    \list
        \li MinGW compiler
        \li build directory – \c <sourceDir>/build-release
        \li build type – \c CMAKE_BUILD_TYPE as \c Release
        \li generator – MinGW Makefiles
        \li path to a CMake executable
        \li path to the Qt installation via \c CMAKE_PREFIX_PATH
        \li GNU gdb 11.2.0 for MinGW 11.2.0 64-bit debugger
    \endlist

    \code
    {
      "version": 1,
      "configurePresets": [
        {
          "name": "mingw",
          "displayName": "MinGW 11.2.0",
          "generator": "MinGW Makefiles",
          "binaryDir": "${sourceDir}/build-release",
          "cmakeExecutable": "C:/Qt/Tools/CMake_64/bin/cmake.exe",
          "cacheVariables": {
            "CMAKE_BUILD_TYPE": "Release",
            "CMAKE_PREFIX_PATH": "C:/Qt/6.4.0/mingw_64"
          },
          "environment": {
            "PATH": "C:/Qt/Tools/mingw1120_64/bin;$penv{PATH}"
          },
          "vendor": {
            "qt.io/QtCreator/1.0": {
              "debugger": {
                "DisplayName": "GNU gdb 11.2.0 for MinGW 11.2.0 64-bit",
                "Abis": ["x86-windows-msys-pe-64bit"],
                "Binary": "C:/Qt/Tools/mingw1120_64/bin/gdb.exe",
                "EngineType": 1,
                "Version": "11.2.0"
              }
            }
          }
      ]
    }
    \endcode

    To speed up the process on Windows, specify the \c CMAKE_C_COMPILER and
    \c CMAKE_CXX_COMPILER in the \c cacheVariables section.

    For possible values of some of the \c debugger preferences, see
    \l {CMake Qt Vendor Presets}.

    \section1 Ninja Generator Example

    The following configure and build presets set Ninja Multi-Config as the
    generator, add \c Debug and \c Release build steps, and specify the path
    to \c ninja.exe as a value of the \c CMAKE_MAKE_PROGRAM variable:

    \code
    {
      "version": 2,
      "configurePresets": [
        {
          "name": "ninja-nmc",
          "displayName": "Ninja Multi-Config MinGW",
          "generator": "Ninja Multi-Config",
          "binaryDir": "${sourceDir}/build",
          "cacheVariables": {
            "CMAKE_CONFIGURATION_TYPES": "Debug;Release",
            "CMAKE_PREFIX_PATH": "C:/Qt/6.4.0/mingw_64",
            "CMAKE_MAKE_PROGRAM": "C:/Qt/Tools/Ninja/ninja.exe"
          },
          "environment": {
            "PATH": "c:/Qt/Tools/mingw1120_64/bin;$penv{PATH}"
          }
        }
      ],
      "buildPresets": [
        {
          "name": "release",
          "displayName": "Ninja Release",
          "configurePreset": "ninja-nmc",
          "configuration": "Release"
        },
        {
          "name": "debug",
          "displayName": "Ninja Debug",
          "configurePreset": "ninja-nmc",
          "configuration": "Debug"
        }
      ]
    }
    \endcode

    This example assumes that the CMake executable path is set in
    \preferences > \uicontrol CMake >
    \uicontrol Tools.

    \section1 MSVC Example

    When using MSVC compilers with NMAKE Makefiles, Ninja, or Ninja
    Multi-Config generators, you can use the \c external strategy for
    the \c architecture and \c toolset fields. This lets \QC set up
    the Visual C++ environment before invoking CMake.

    For example:

    \code
    "generator": "Ninja Multi-Config",
    "toolset": {
      "value": "v142,host=x64",
      "strategy": "external"
    },
    "architecture": {
      "value": "x64",
      "strategy": "external"
    },
    \endcode

    If you use MSVC compilers with non-VS generators and have several compilers
    in the \c PATH, you might also have to specify the compiler to use in
    \c cacheVariables or \c environmentVariables:

    \code
    "generator": "Ninja Multi-Config",
    "toolset": {
      "value": "v142,host=x64",
      "strategy": "external"
    },
    "architecture": {
      "value": "x64",
      "strategy": "external"
    },
    "cacheVariables": {
      "CMAKE_C_COMPILER": "cl.exe",
      "CMAKE_CXX_COMPILER": "cl.exe"
    }
    \endcode

    \section1 Cross-Compilation Example

    The following example configures a Qt project for cross-compilation on \macos
    for Windows and running with the \c wine emulator on \macos:

    \list
        \li generator – Ninja
        \li build directory – \c <sourceDir>/build-release
        \li LLVM/MinGW toolchain
        \li configuration type – \c CMAKE_BUILD_TYPE as \c Release
        \li LLDB 18.1.6 debugger
        \li \c wine emulator
    \endlist

    \code
    {
      "version": 4,
      "configurePresets": [
        {
          "name": "llvm-mingw",
          "displayName": "LLVM-MinGW 18.1.6",
          "generator": "Ninja",
          "binaryDir": "${sourceDir}/build-release",
          "toolchainFile": "llvm-mingw.cmake",
          "cacheVariables": {
            "CMAKE_BUILD_TYPE": "Release",
            "CMAKE_CROSSCOMPILING_EMULATOR": "/opt/homebrew/bin/wine"
          },
          "vendor": {
            "qt.io/QtCreator/1.0": {
              "debugger": {
                "DisplayName": "LLDB 18.1.6 (CMake Preset)",
                "Abis": ["x86-darwin-generic-mach_o-64bit", "arm-darwin-generic-mach_o-64bit"],
                "Binary": "/Users/jdoe/llvm-mingw/bin/lldb",
                "EngineType": 256,
                "Version": "18.1.6"
              }
            }
          }
        }
      ]
    }
    \endcode

    \section1 Using Conditions

    The following configure presets are used if they match \c condition. That is,
    if the \c hostSystemName equals \c Linux, the \c linux presets are used and
    if it equals \c Windows, the \c windows presets are used.

    \code
    {
      "version": 3,
      "configurePresets": [
        {
          "name": "linux",
          "displayName": "Linux GCC",
          "binaryDir": "${sourceDir}/build",
          "cacheVariables": {
            "CMAKE_PREFIX_PATH": "$env{HOME}/Qt/6.4.0/gcc_64"
          },
          "condition": {
            "type": "equals",
            "lhs": "${hostSystemName}",
            "rhs": "Linux"
          }
        },
        {
          "name": "windows",
          "displayName": "Windows MSVC",
          "binaryDir": "${sourceDir}/build",
          "cacheVariables": {
            "CMAKE_PREFIX_PATH": "$env{SYSTEMDRIVE}/Qt/6.4.0/msvc2019_64"
          },
          "condition": {
            "type": "equals",
            "lhs": "${hostSystemName}",
            "rhs": "Windows"
          }
        }
      ]
    }
    \endcode

    \section1 Test Presets

    The following test presets instruct CMake to stop test execution and
    print output from the test program upon failure, as well as display an
    error if the test cannot be found.

    \badcode
    {
      "version": 3,
      "testPresets": [
      {
        "name": "default",
        "configurePreset": "default",
        "output": {"outputOnFailure": true},
        "execution": {"noTestsAction": "error", "stopOnFailure": true}
        }
      ],
    }
    \endcode

    \sa {CMake Build Configuration}, {CMake}, {CMake Qt Vendor Presets},
    {SDK Tool}
*/

/*!
    \page creator-build-settings-cmake-presets-qt-vendor.html
    \previouspage creator-reference.html

    \ingroup creator-reference-build-configurations

    \title CMake Qt Vendor Presets

    \brief Summary of CMake Qt vendor presets.

    Specify \QC preferences in the \c vendor section in \c CMakePresets.json and
    \c CMakeUserPresets.json.

    \section1 CMake configuration presets

    The following table summarizes the available presets.

    \table
    \header
        \li Preset
        \li Description
        \li Read More
    \row
        \li \c {AutorunCMake}
        \li Runs CMake to refresh project information when you edit
            a \c CMakeLists.txt configuration file in a project. Also,
            refreshes project information when you build the project.
        \li \l{View CMake project contents}
    \row
        \li \c {AskBeforePresetsReload}
        \li Asks before acting when you go to \uicontrol Build and select
            \uicontrol {Reload CMake Presets}.
        \li \l{CMake Presets}
    \row
        \li \c {AskReConfigureInitialParams}
        \li Asks before acting when you select
            \uicontrol {Re-configure with Initial Variables}.
        \li \l{Re-configuring with Initial Variables}
    \row
        \li \c {PackageManagerAutoSetup}
        \li Sets up the \l {Conan Package Manager}{Conan} or
            \l {vcpkg Package Manager}{vcpkg} package manager for use with CMake.
        \li \l{Using CMake with Package Managers}
    \row
        \li \c {ShowAdvancedOptionsByDefault}
        \li Shows all CMake variables by default in
            \uicontrol {Initial Configuration} and
            \uicontrol {Current Configuration}.
        \li \l{Viewing Advanced Variables}
    \row
        \li \c {ShowSourceSubfolders}
        \li Hides subfolder names and arranges the files according to their
            source group in the \uicontrol Projects view.
        \li \l{Hide subfolder names in Projects view}
    \row
        \li \c {UseJunctionsForSourceAndBuildDirectories}
        \li On Windows, uses junction points for CMake configure, build, and
            install operations.
        \li \l{Using Junction Points on Windows}
    \endtable

    An example of CMake configuration presets:

    \badcode
    "vendor": {
      "qt.io/QtCreator/1.0": {
        "AskBeforePresetsReload": false,
        "AskReConfigureInitialParams": false,
        "AutorunCMake": false,
        "PackageManagerAutoSetup": false,
        "ShowAdvancedOptionsByDefault": true,
        "ShowSourceSubFolders": false,
        "UseJunctionsForSourceAndBuildDirectories": true
      }
    }
    \endcode

    \section1 Debugger presets

    The following table summarizes the available presets.

    For more information about debugger preferences, see \l{Add debuggers}.

    \table
        \header
            \li Preset
            \li Description
        \row
            \li \c {Abis}
            \li Comma-separated list of system architecture definitions.
        \row
            \li \c {Binary}
            \li Path to the debugger executable. Can be an absolute path, the
                value \c auto, or an ABI. Finds the appropriate debugger for MSVC
                toolchains where \QC does not know the binary path.
        \row
            \li \c {DisplayName}
            \li Name of the debugger.
        \row
            \li \c {EngineType}
            \li Debugger engine type:
                \list
                    \li 1 for GDB
                    \li 4 for CDB
                    \li 8 for PDB
                    \li 256 for LLDB
                    \li 512 for GDB DAP
                    \li 1024 for LLDB DAP
                    \li 4096 for uVision Debugger
                \endlist
        \row
            \li \c {Version}
            \li Version number of the debugger.
    \endtable

    An example of \QC debugger presets:

    \badcode
    "vendor": {
      "qt.io/QtCreator/1.0": {
        "debugger": {
          "DisplayName": "GNU gdb 11.2.0 for MinGW 11.2.0 64-bit",
          "Abis": ["x86-windows-msys-pe-64bit"],
          "Binary": "C:/Qt/Tools/mingw1120_64/bin/gdb.exe",
          "EngineType": 1,
          "Version": "11.2.0"
        }
      }
    }
    \endcode

    \sa {CMake Build Configuration}, {CMake}, {CMake Presets}, {SDK Tool}
*/
