// 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-cmake.html
    \previouspage creator-reference.html

    \ingroup creator-reference-build-systems

    \title CMake

    \brief CMake is an alternative to qmake for automating the generation of
    build systems.

    \l{https://cmake.org/}{CMake} automates the configuration of build systems.
    It controls the software compilation process by using simple
    configuration files, called \c {CMakeLists.txt} files. CMake generates
    native build configurations and workspaces that you can use in the compiler
    environment of your choice.

    You can use CMake from \QC to build applications for the desktop, as well
    as mobile and embedded devices. Or, build single files to test your changes.

    \section1 Supported CMake versions

    \QC requires CMake's \l{https://cmake.org/cmake/help/latest/manual/cmake-file-api.7.html}
    {file-based API}, and therefore you'll need CMake version 3.14, or later.

    For systems with older versions of CMake, only workarounds are available:

    \list
        \li For CMake version 3.5 or later, generate a
            \l{CMake: CMAKE_EXPORT_COMPILE_COMMANDS}{compilation database} and
            open that in \QC, as described in \l{Use compilation databases}.
        \li Create an ad-hoc project file for a qmake build using
            \c{qmake -project} and \l{Open projects}{open} that in \QC.
            Typically, you cannot compile such projects without manual changes.
        \li Manually create an ad-hoc project file for a
            \l{Import an existing project}{generic project} and
            open that in \QC.
            Typically, you cannot compile such projects without manual changes.
    \endlist

    \sa {Configure projects for building}, {Configure projects for running},
    {Build with CMake}{How to: Build with CMake}, {Building projects with CMake},
    {Debug CMake project files}, {Deploy applications to remote Linux devices}, {Open projects},
    {Use compilation databases}
*/

/*!
    \page creator-how-to-view-cmake-project-contents.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-build-with-cmake

    \title View CMake project contents

    The \l Projects view visualizes the build system structure of the project as
    a tree and lists all files that are part of the project.
    \QC automatically runs CMake to refresh project information in the
    view when you edit a \c CMakeLists.txt configuration file
    in a project. Also, refreshes project information when you build the project.

    \image {qtcreator-projects-view.webp} {CMake project in Projects view}

    To disable this behavior, go to \preferences > \uicontrol CMake >
    \uicontrol General and clear \uicontrol {Autorun CMake}.

    \image {qtcreator-preferences-cmake-general.webp} {General tab in CMake preferences}

    \section1 Re-configure CMake projects

    If \QC cannot load the CMake project, the \uicontrol Projects view shows a
    \uicontrol {<File System>} project node to avoid scanning the file
    system and load the project faster. The node shows the same files
    as the \l {File System} view.

    To re-configure the project:

    \list 1
        \li Go to \uicontrol Build, and select
            \uicontrol {Clear CMake Configuration}.
        \li Go to \uicontrol Build, and select \uicontrol {Run CMake}.
    \endlist

    \section1 Hide subfolder names in Projects view

    The \uicontrol Projects view shows the names of the subfolders where the
    source files are located. To hide the subfolder names and arrange the files
    only according to their source group, select \preferences >
    \uicontrol CMake > \uicontrol General, and then
    clear the \uicontrol {Show subfolders inside source group folders} check
    box. The change takes effect after you go to \uicontrol Build and select
    \uicontrol {Run CMake}.

    \sa {Build with CMake}{How to: Build with CMake}, {CMake}, {Open projects},
    {File System}, {Projects}
*/

/*!
    \page creator-how-to-read-cmake-documentation.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-build-with-cmake
    \ingroup creator-how-to-get-help

    \title Read CMake documentation

    CMake documentation is installed in Qt help file format (.qch) when you
    install CMake. It is automatically registered by \QC, and you can view it by:

    \list
        \li Hovering the mouse over a function, variable, property, policy,
            environment variable, or CMake find or include module to show
            tooltips
        \li Selecting any of the above elements, and then selecting \key F1 to show
            its documentation
        \li Switching to the \uicontrol Help mode
    \endlist

    To view the documentation online, open it in the \uicontrol Help mode and
    select \inlineimage {icons/online.png} {Open Online Documentation}
    (\uicontrol {Open Online Documentation}).

    \sa {Build with CMake}{How to: Build with CMake},
    {Read documentation}{How to: Read documentation}, {CMake}
*/

/*!
    \page creator-how-to-add-cmake-tools.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-build-with-cmake
    \ingroup creator-how-to-manage-kits

    \title Add CMake tools

    \QC automatically detects the CMake executable that you specify in the
    \c PATH. You can add paths to other CMake executables and use them in
    different build and run \l{Managing kits}{kits}.

    To see the CMake installations that \QC automatically detects:

    \list 1

        \li Select \preferences > \uicontrol CMake > \uicontrol Tools.

            \image {qtcreator-preferences-cmake-tools.webp} {Tools tab in CMake preferences}

        \li The \uicontrol Name field displays a name for the CMake
            installation.

        \li The \uicontrol Path field displays the path to the CMake
            executable.

        \li The \uicontrol {Help file} field displays the path to the
            CMake help file (.qch) that comes with CMake.

    \endlist

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

    \section1 Add or remove CMake tools

    To add a path to a CMake executable that \QC does not detect automatically,
    and to specify settings for it, select \uicontrol Add.

    To add a CMake executable on a remote Linux device or in Docker, select
    \uicontrol Remote in the dropdown menu in \uicontrol Browse
    (\uicontrol Choose on \macos) in the \uicontrol Path field.

    To make changes to automatically detected installations, select
    \uicontrol Clone.

    To remove the selected CMake executable from the list, select
    \uicontrol Remove.

    \section1 Set the default CMake tool

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

    \section1 Add CMake tools to kits

    To add the CMake tool to a build and run kit, select \preferences >
    \uicontrol Kits.
    The kit also specifies the CMake generator that is used for producing
    project files for \QC and the initial configuration parameters:

    \image {qtcreator-preferences-kits.webp} {Kits preferences}

    \sa {Build applications on remote Linux devices}, {Build on Docker devices},
    {Build with CMake}{How to: Build with CMake},
    {Manage kits}{How to: Manage kits}, {CMake}, {Managing kits}
*/

/*!
    \page creator-how-to-edit-cmake-config-files.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-build-with-cmake

    \title Edit CMake configuration files

    To open a \c CMakeLists.txt file for editing, right-click it in the
    \uicontrol Projects view and select \uicontrol {Open With} >
    \uicontrol {CMake Editor}.

    You can also use the \c cmo filter in the \l {Navigate with locator}{locator}
    to open the \c CMakeLists.txt file for the current run configuration
    in the editor. This is the same build target as when you go to
    \uicontrol Build and select \uicontrol {Build for Run Configuration}.

    The following features are supported:

    \list

        \li Selecting \key F2 when the cursor is on a:
            \list
                \li Filename - to open the file
                \li CMake function, macro, option, target, CMake's Find or
                    Include module, local variable created by \c set or \c list,
                    or package - to go to that item
            \endlist

        \li Keyword completion

        \li Code completion for local functions and variables, cache variables,
            \c ENV, targets, packages, and variables that \c find_package adds

        \li Pre-defined code snippets for setting CMake print properties and
            variables, as well as creating Qt console and GUI applications and
            sample Find modules

        \li Path completion

        \li Auto-indentation

        \li Matching parentheses and quotes

    \endlist

    Warnings and errors are displayed in \l {Issues}.

    \section1 Install missing Qt packages

    If you add a Qt module in \c find_package that you did not install, \QC
    creates an entry in the \uicontrol Issues view with the option to install
    the missing component with \QOI.

    \image {qtcreator-install-packages.webp} {Installing missing Qt packages}

    Click the link to install the package with \QOI.

    To turn off the messages, go to \preferences > \uicontrol CMake >
    \uicontrol General and clear \uicontrol {Maintenance Tool dependency provider}.

    \image {qtcreator-preferences-cmake-general.webp} {General tab in CMake preferences}

    \sa {Build with CMake}{How To: Build with CMake}, {CMake}, {Completion},
    {Snippets}
*/

/*!
    \page creator-how-to-complete-cmake-code.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-build-with-cmake

    \title Complete CMake code

    \QC uses \l{Download highlight definitions}{generic highlighting} to provide
    code completion specific arguments for the CMake commands. For
    example, only source file properties are suggested for the
    \l {CMake: set_source_files_properties command}, not the test or
    target properties.

    The following CMake-specific trigger tokens are supported:

    \list
        \li \c{$} for variables
        \li \c{$<} for generator expressions
        \li \c{$ENV} for environment variables
    \endlist

    Select \key Tab or \key Enter to accept the selected suggestion and complete
    the code.

    \sa {Build with CMake}{How to: Build with CMake}, {CMake}, {Completion},
    {Snippets}
*/

/*!
    \page creator-how-to-format-cmake-files.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-build-with-cmake

    \title Format CMake files

    You can use the \l {cmake-format} tool and local \c .cmake-format, \c .py, or
    \c .json configuration files to format any text in CMake files that
    you do not guard with a pair of fences. You must install the tool and tell
    \QC where you installed it.

    To automatically format CMake files upon file save:

    \list 1
        \li Select \preferences > \uicontrol CMake > \uicontrol Formatter.
            \image {qtcreator-preferences-cmake-formatter.webp} {Formatter tab in CMake preferences}
        \li In \uicontrol {CMakeFormat command}, enter the path to
            \c {cmake-format.exe}.
        \li Select \uicontrol {Automatic formatting on file save} to automatically
            format CMake files when you save them.

            To temporarily disable this setting while saving a file, go to
            \uicontrol File and select \uicontrol {Save Without Formatting}.
        \li In \uicontrol {Restrict to MIME types}, add the MIME types of the
            files to format, separated by semicolons. The default value,
            \c {text/x-cmake} formats CMake files. If the field is empty, all
            files are formatted.
        \li Select \uicontrol {Restrict to files contained in the current
            project} to only format CMake files that belong to the
            current project.
    \endlist

    \sa {Build with CMake}{How to: Build with CMake}, {Edit MIME types}, {CMake}
*/

/*!
    \page creator-how-to-manage-files-in-cmake-projects.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-build-with-cmake

    \title Manage files in CMake projects

    When you \l{Adding files}{add new or existing files} to
    a project, \QC automatically adds them to the \l {qt_add_executable},
    \l{CMake: add_executable command}{add_executable}, or \l {qt_add_library}
    function in the \c CMakeLists.txt file.

    If \QC cannot recognize where the target is created, it will use the
    \l{CMake: target_sources command} {target_sources} function to add the files.

    For Qt Quick projects, the files are added to the \l {qt_add_qml_module}
    function, prefixed with the \c QML_FILES, \c SOURCES, or \c RESOURCES
    function argument.

    When you rename or remove files in the \l {Projects} or \l {File System}
    view, \QC renames them in the \c CMakeLists.txt file or removes them from it.

    \sa {Adding files}, {Build with CMake}{How to: Build with CMake}, {CMake},
    {File System}, {Projects}
*/

/*!
    \page creator-how-to-add-external-libraries-to-cmake-projects.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-build-with-cmake

    \title Add libraries to CMake projects

    With CMake, you can:

    \list
        \li Import existing executable or library files from disk into a CMake
            project.
        \li Incorporate dependencies, such as other projects, assets, and
            artifacts into a build.
    \endlist

    For more information, see \l {CMake: Importing and Exporting Guide} and
    \l {CMake: Using Dependencies Guide}.

    \section1 Import existing libraries

    Use the \l qt_add_library command to create a library and link against it in
    the \c CMakeLists.txt file, as instructed in \l{Structuring projects}.

    Specify whether the library is statically or dynamically linked.
    For a statically linked internal library, add the
    \l{CMake: target_link_libraries command} to the \c CMakeLists.txt
    project file to specify dependencies.

    \section1 Use dependencies

    Through external libraries, \QC can support code completion and syntax
    highlighting as if the code were a part of the current project or the
    Qt library.

    \QC detects the external libraries using the \l{CMake: find_package command}.
    Some libraries come with the CMake installation. You can find those
    in the \c {Modules} directory of your CMake installation.
    For more information, see \l{CMake: cmake-packages(7)}.

    \section1 Find CMake module files

    For CMake projects that have external dependencies, use
    \l{CMake: Find Modules}{Find<package>.cmake} modules that
    expose imported targets. You can use the pre-defined \c sample_find_module
    \l{Snippets}{code snippet} to add sample commands
    to a \c .cmake file. You can then change the commands as necessary.

    Place \c Find modules in the \c ${CMAKE_CURRENT_SOURCE_DIR}/cmake directory,
    and append the directory name to the \c {CMAKE_MODULE_PATH} list variable.
    For example:

    \code
    list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
    \endcode

    \sa {Build with CMake}{How to: Build with CMake}, {CMake}, {Completion},
    {Snippets}
*/
