// 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-systems

    \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 {CMake: 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 10
    (introduced in CMake 3.31), but does not enforce version checking.
    It reads and uses all the fields from version 10 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}

    \QC watches the \c CMakePresets.json presets files for changes.
    To manually update changes to the files, 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 \QC 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 \QC 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.

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

    \sa {Build with CMake}{How to: Build with CMake},
    {Building projects with CMake}, {CMake}, {CMake \QC vendor presets},
    {SDK Tool}
*/

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

    \ingroup creator-reference-build-systems

    \title CMake \QC vendor presets

    \brief Summary of CMake \QC 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 {Set up 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{Use junction points on Windows}
    \row
        \li \c {runDevice}
        \li Specifies the run device for the kit created from the preset.
            Overrides the automatic device selection based on \c CMAKE_SYSROOT.
            Can be a device type identifier (string) to use the default device
            of that type, or an object with \c {type} and additional settings.
            When using the object form, if no matching device exists, a new
            device is added to the device list. Valid device type identifiers
            are the strings returned by \c IDevice::type().
        \li \l {addDev}
    \endtable

    An example of CMake configuration presets:

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

    To force a specific run device for a preset-based kit:

    \code [json]
    "vendor": {
      "qt.io/QtCreator/1.0": {
        "runDevice": "GenericLinuxOsType"
      }
    }
    \endcode

    Or to disambiguate among multiple devices of the same type:

    \code [json]
    "vendor": {
      "qt.io/QtCreator/1.0": {
        "runDevice": {
          "type": "GenericLinuxOsType",
          "name": "my-raspberry-pi"
        }
      }
    }
    \endcode

    The object form also supports specifying full device settings, which are
    used to create a device if no matching device exists:

    \code [json]
    "vendor": {
      "qt.io/QtCreator/1.0": {
        "runDevice": {
          "type": "GenericLinuxOsType",
          "id": "MyRemoteDevice",
          "name": "my-raspberry-pi",
          "host": "192.168.1.100",
          "uname": "pi",
          "keyFile": "/home/user/.ssh/id_rsa",
          "sshPort": 22,
          "authentication": 1,
          "timeout": 5,
          "freePortsSpec": "8000-9000"
        }
      }
    }
    \endcode

    \QC looks for an existing device first by \c {id}, then by \c {name}. Only
    when neither matches does it add a new device, which then persists across
    sessions. Edit or remove it in \preferences > \uicontrol Devices >
    \uicontrol Devices, like any other device.

    The following options are supported in the object form. They correspond to
    the SDK Tool \c {addDev} options of the same name, except where noted; for a
    complete reference, see \l {addDev}.

    \table
    \header \li Option \li Description
    \row \li \c {type} \li Device type identifier (required). Corresponds to
        \c {--osType}, not to \c {--type}.
    \row \li \c {id} \li Unique ID for the device. If not set, \QC generates one
        from the project and preset names.
    \row \li \c {name} \li Display name for the device. Falls back to a
        generated name if not set.
    \row \li \c {host} \li Host name or IP address of the device.
    \row \li \c {uname} \li Username to access the device.
    \row \li \c {keyFile} \li Path to the user's private key file for SSH
        authentication.
    \row \li \c {sshPort} \li Port number for SSH connections (default: 22).
    \row \li \c {authentication} \li Authentication method: 0 for all methods,
        1 for SSH key pair.
    \row \li \c {timeout} \li Timeout for reusing the SSH connection in seconds
        (default: 5).
    \row \li \c {machineType} \li Machine type: 0 for hardware, 1 for an
        emulator (default: 0). Corresponds to \c {--type}.
    \row \li \c {freePortsSpec} \li Free ports specification string (for
        example, "8000-9000"). Corresponds to \c {--freePorts}.
    \endtable

    \section1 Build presets

    The following table summarizes the available build presets.

    \table
    \header
        \li Preset
        \li Description
    \row
        \li \c {useStaging}
        \li Enables staging for installation, which copies build artifacts
            to a separate staging directory before installation.
    \row
        \li \c {stagingDir}
        \li Path to the staging directory used when \c useStaging is enabled.
    \row
        \li \c {iOSAutomaticProvisioningUpdates}
        \li Automatically updates iOS provisioning profiles during the build.
    \row
        \li \c {clearSystemEnvironment}
        \li Clears system environment variables before running the build step.
    \endtable

    An example of \QC build preset vendor presets:

    \code [json]
    "vendor": {
      "qt.io/QtCreator/1.0": {
        "useStaging": true,
        "stagingDir": "${sourceDir}/staging",
        "iOSAutomaticProvisioningUpdates": true,
        "clearSystemEnvironment": false
      }
    }
    \endcode

    \section1 Run presets

    Run presets provide settings for running applications built with CMake.

    Each run setting has a \c target that matches a build target name. \QC creates
    one run configuration per run setting and applies the settings to it. Where a
    run setting does not set \c displayName, the run configuration is named after
    the target, with a numeric suffix from the second run setting for that target
    onwards (for example, \c myApp, \c myApp2, \c myApp3).

    Settings that the run configuration does not support are ignored. For example,
    \c useDyldSuffix has no effect unless you run the application locally on \macos.

    Run presets also support utility targets (\c add_custom_target in CMake). For
    these targets, \QC creates a run configuration that runs
    \c {cmake --build . --target <targetName>}. To specify a custom executable instead,
    use the \c executable field.

    The following table summarizes the available run settings:

    \table
    \header
        \li Preset
        \li Description
        \li Read More
    \row
        \li \c {target}
        \li The name of the CMake build target. For executables, this matches the
            target created in \c CMakeLists.txt. For utility targets, this matches
            the name used in \c add_custom_target(). If the target does not exist
            as a CMake build target, \QC creates a run configuration that
            runs the specified \c executable, or falls back to
            \c {cmake --build . --target <targetName>}.
        \li \l{Building projects with CMake}
    \row
        \li \c {displayName}
        \li Display name for the run configuration. If omitted, the \c target
            name is used. Use this to give meaningful names when a target has
            multiple run settings (for example, \c {"myApp - tests"}, \c {"myApp - debug"}).
        \li
    \row
        \li \c {executable}
        \li Path to the executable to run. Supports
            \l{CMake: Preset macros}.
        \li \l{Configure projects for running}
    \row
        \li \c {arguments}
        \li Command line arguments for the run configuration. Supports
            \l{CMake: Preset macros}.
        \li \l{Configure projects for running}
    \row
        \li \c {workingDirectory}
        \li Working directory for the run configuration. Supports
            \l{CMake: Preset macros}.
        \li \l{Configure projects for running}
    \row
        \li \c {useTerminal}
        \li Whether to run the application in a terminal window.
        \li \l{Configure projects for running}
    \row
        \li \c {useLibraryPaths}
        \li Adds build library search paths to the runtime environment.
            On \macos this sets \c DYLD_LIBRARY_PATH and \c DYLD_FRAMEWORK_PATH,
            on Linux it sets \c LD_LIBRARY_PATH, and on Windows it adds to \c PATH.
        \li \l{Configure projects for running}
    \row
        \li \c {useDyldSuffix}
        \li (\macos) Whether to load the debug version of linked frameworks by
            setting the \c DYLD_IMAGE_SUFFIX environment variable to \c _debug.
        \li \l{Debug linked frameworks}
    \row
        \li \c {useVncDisplay}
        \li (Remote Linux) Whether to start a VNC server on the device and run
            the application on its display.
        \li \l{View the application UI}
    \row
        \li \c {enableCategoriesFilter}
        \li Enables Qt logging category filtering by setting the \c QT_LOGGING_RULES
            and \c QT_MESSAGE_PATTERN environment variables.
        \li \l{Set the environment for all run configurations}
    \row
        \li \c {x11Forwarding}
        \li (Remote Linux) The X11 display to forward to (for example, \c :0.0).
        \li \l{Specify remote Linux run settings}
    \row
        \li \c {runAs}
        \li The user account to run as (Unix only). Valid values are \c default,
            \c root, or a custom username.
        \li \l{Run as a different user}
    \row
        \li \c {environment}
        \li A JSON object mapping environment variable names to their values.
        \li \l{Specify the environment for projects}
    \row
        \li \c {active}
        \li If set to \c true, the matched run configuration is set as the active
            (selected) run configuration for its build configuration. If multiple
            presets specify \c active, the last one processed wins.
        \li \l{Configure projects for running}
    \endtable

    An example of \QC run settings:

    \code [json]
    "vendor": {
      "qt.io/QtCreator/1.0": {
        "runSettings": [
          {
            "target": "myApp",
            "displayName": "My App - production",
            "arguments": "--verbose --config production",
            "workingDirectory": "${sourceDir}/output",
            "useTerminal": false,
            "useLibraryPaths": true,
            "environment": {
              "MY_VAR": "my_value"
            }
          },
          {
            "target": "myApp",
            "displayName": "My App - debug",
            "arguments": "--debug",
            "workingDirectory": "${sourceDir}/debug-output",
            "useDyldSuffix": true,
            "useLibraryPaths": true,
            "active": true
          },
          {
            "target": "run-tests",
            "useTerminal": true
          },
          {
            "target": "shell",
            "displayName": "Interactive Shell",
            "executable": "/bin/bash",
            "arguments": "--help",
            "useTerminal": true
          }
        ]
      }
    }
    \endcode

    This example creates four run configurations:
    \list
        \li \c {"My App - production"} (from the first run setting)
        \li \c {"My App - debug"} (from the second run setting, same target)
        \li \c run-tests (a utility target, runs \c {cmake --build . --target run-tests})
        \li \c {"Interactive Shell"} (a standalone executable, runs \c{/bin/bash})
    \endlist

    \section1 Compiler presets

    The following table summarizes the available presets.

    For more information about compiler preferences, see \l{Add compilers}.

    \table
    \header
        \li Preset
        \li Description
    \row
            \li \c {c}
            \li Path to the C compiler installation folder.
        \row
            \li \c {cxx}
            \li Path to the C++ compiler installation folder.
    \endtable

    An example of \QC compiler presets:

    \code [json]
    "vendor": {
      "qt.io/QtCreator/1.0": {
        "compiler": {
          "c" : "$env{HOME}/llvm/mac/bin/clang",
          "cxx" : "$env{HOME}/llvm/mac/bin/clang++"
        }
      }
    }
    \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:

    \code [json]
    "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

    \section1 Qt version presets

    The following table summarizes the available presets.

    For more information about Qt version preferences, see \l{Add Qt versions}.

    \table
        \header
            \li Preset
            \li Description
        \row
            \li \c {qt}
            \li Path to the Qt installation folder.
    \endtable

    An example of \QC Qt version presets:

    \code [json]
    "vendor": {
      "qt.io/QtCreator/1.0": {
        "qt": "$env{HOME}/Qt/6.11.0/macos/bin/qmake"
      }
    }
    \endcode

    \sa {Build with CMake}{How to: Build with CMake},
    {Building projects with CMake}, {CMake}, {CMake presets}, {SDK Tool}
*/
