/****************************************************************************
**
** Copyright (C) 2016 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.
// **********************************************************************

/*!
    \contentspage {Qt Creator Manual}
    \previouspage creator-project-other.html
    \page creator-project-cmake.html
    \nextpage creator-project-qbs.html

    \title Setting Up a CMake Project

    CMake is an alternative to qmake for automating the generation of build
    configurations. 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.

    \QC automatically detects the CMake executable specified in the \c PATH.
    You can add paths to other CMake executables and use them in different
    build and run \l{glossary-buildandrun-kit}{kits}.

    \QC automatically runs CMake to regenerate makefiles when you edit a
    \c CMakeLists.txt configuration file in a project. If the project uses
    several configuration files, you can disable the automatic generation of
    makefiles by selecting \uicontrol Tools > \uicontrol Options >
    \uicontrol {Build & Run} > \uicontrol CMake. Makefiles are automatically
    regenerated when you build the project.

    \section1 Adding CMake Tools

    \QC supports CMake version 3.0, or later. For best results you should use
    CMake version 3.3.2 or later. Earlier versions provide less information
    to the code model, which will then fail to resolve includes and defines.

    To specify paths to CMake executables and to add them to kits:

    \list 1

        \li Select \uicontrol Tools > \uicontrol Options >
            \uicontrol {Build & Run} > \uicontrol CMake > \uicontrol Add.

            \image qtcreator-cmakeexecutable.png

        \li In the \uicontrol Name field, specify a name for the tool.

        \li In the \uicontrol Path field, specify the path to the CMake
            executable.

        \li Deselect the \uicontrol {Autorun CMake} check box to prevent \QC
            from running CMake when you make changes to \c {CMakeLists.txt}
            files.

        \li Select \uicontrol Apply to save your changes.

        \li Select the \uicontrol Kits tab to add the CMake tool to a build and
            run kit. The kit also specifies the CMake Generator that is used for
            producing project files for \QC and the configuration variables that
            are used:

            \image qtcreator-kits.png

            For more information, see \l {Adding Kits}.

    \endlist

    \section1 Creating CMake Projects

    To create a CMake project:

    \list 1

        \li Select \uicontrol File > \uicontrol {New File or Project} >
            \uicontrol {Non-Qt Project} > \uicontrol {Plain C Application} or
            \uicontrol {Plain C++ Application} > \uicontrol Choose.

        \li In the \uicontrol Name field, enter a name for the project.

        \li In the \uicontrol {Create in} field, enter the path for the project
            files, and then select \uicontrol Next (or \uicontrol Continue on
            \macos).

        \li In the \uicontrol {Build system} field, select \uicontrol CMake, and
            then select \uicontrol Next.

        \li Select CMake kits for the platforms that you want to build the
            application for, and then select \uicontrol Next.

        \li Review the project settings, and click \uicontrol{Finish} (or
            \uicontrol Done on \macos).

        \li Select \uicontrol {Run CMake} to generate a .cbp file.

            \image qtcreator-cmake-run-cmake.png

            Some projects require command line arguments to the initial CMake
            call. CMake will remember the arguments during subsequent calls.

    \endlist

    \QC generates a \c {main.cpp} and \c {CMakeLists.txt} file that you can
    modify in the \uicontrol Edit mode.

    \section1 Opening CMake Projects

    To open an existing CMake project:

    \list 1

        \li Select \uicontrol File > \uicontrol {Open File or Project}.

        \li Select the \c {CMakeLists.txt} file from your CMake project.

        \li Select a kit that is configured to use CMake for building the
            project.

        \li In \uicontrol Projects, right-click the project name to open the
            context menu, and then select \uicontrol {Run CMake} to have the
            project contents listed in the view.

    \endlist

    \section1 Editing CMake Configuration Files

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

    The following features are supported:

    \list

        \li Pressing \key F2 when the cursor is on a filename to open the file

        \li Keyword completion

        \li Auto-indentation

        \li Matching parentheses and quotes

    \endlist

    \section1 Building CMake Projects

    To build CMake projects, select \uicontrol {Build Project} or press
    \key Ctrl+B (or \key Cmd+B on \macos).

    \QC builds CMake projects by running \c make, \c mingw32-make, \c nmake, or
    \c ninja depending on the selected kit.

    By default, \QC uses the \uicontrol Default \l{glossary-build-config}
    {build configuration}. You can select another build configuration in
    \uicontrol Projects > \uicontrol {Build Settings} >
    \uicontrol {Edit build configuration}. In addition to
    debug and release build configurations, you can create a release build that
    contains debug information or a release build with the smallest possible
    size.

    \image qtcreator-cmake-build-settings.png

    In the \uicontrol {Build directory} field, you can specify the directory in
    which the project is built (\l{glossary-shadow-build}{shadow build}).

    To view all settings, select the \uicontrol Advanced check box.

    To modify the value of a build setting, select it, and then select
    \uicontrol Edit. The new value is displayed in italics until you save the
    changes by selecting \uicontrol {Apply Configuration Changes}. Any
    configuration change might trigger a follow-up configuration change, so keep
    saving until no more values are displayed in italics.

    You can add arguments and targets for the build command in
    \uicontrol {Build Steps}.

    \image qtcreator-cmake-build-steps.png

    You can add arguments and targets for the clean command in
    \uicontrol {Clean Steps}.

    \image qtcreator-cmake-clean-steps.png

    The build errors and warnings are parsed and displayed in the
    \uicontrol Issues output pane.

    \section1 Running CMake Projects

    \QC automatically adds \uicontrol {Run Configurations} for all targets
    specified in the CMake project file.

    \image qtcreator-cmake-run-settings.png

    To run CMake projects, select \uicontrol Run or press \key Ctrl+R (or
    \key Cmd+R on \macos).

    \section1 Deploying CMake Projects to Embedded Linux Devices

    \QC cannot extract files to be installed from a CMake project, and
    therefore, only executable targets are automatically added to deployment
    files. You must specify all other files in the \c {QtCreatorDeployment.txt}
    file that you create and place in either the root directory of the CMake
    project or the build directory of the active build configuration.
    Currently, \QC first checks the root directory and only if no
    \c {QtCreatorDeployment.txt} exists it checks the active build directory.

    Use the following syntax in the file:

    \code
    <deployment/prefix>
    <relative/source/file1>:<relative/destination/dir1>
    ...
    <relative/source/filen>:<relative/destination/dirn>
    \endcode

    Where:

    \list

        \li \c {<deployment/prefix>} is the (absolute) path prefix to where
            files are copied on the remote machine.

        \li \c {<relative/source/file>} is the file path relative to the CMake
            project root. No directories or wildcards are allowed in this
            value.

        \li \c {<relative/destination/dir>} is the destination directory path
            relative to \c {deployment/prefix}.

    \endlist

    To automate the creation of \c {QtCreatorDeployment.txt} file:

    \list 1

        \li Define the following macros in the top level \c {CMakeLists.txt}
            file:

            \code
            file(WRITE "${CMAKE_SOURCE_DIR}/QtCreatorDeployment.txt" "<deployment/prefix>\n")

            macro(add_deployment_file SRC DEST)
                file(RELATIVE_PATH path ${CMAKE_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR})
                file(APPEND "${CMAKE_SOURCE_DIR}/QtCreatorDeployment.txt" "${path}/${SRC}:${DEST}\n")
            endmacro()

            macro(add_deployment_directory SRC DEST)
                file(GLOB_RECURSE files RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" "${SRC}/*")
                foreach(filename ${files})
                    get_filename_component(path ${filename} PATH)
                    add_deployment_file("${filename}" "${DEST}/${path}")
                endforeach(filename)
            endmacro()
            \endcode

        \li Use \c {add_deployment_file(<file/name>)} to add files and
            \c {add_deployment_directory(<folder/name>)} to add directories
             (including subdirectories) to the \c QtCreatorDeployment.txt file.

        \li Re-run \c cmake after you add or remove files using the macros.

    \endlist

    \section1 Adding External Libraries to CMake Projects

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

    \QC detects the external libraries using the \c {FIND_PACKAGE()}
    macro. Some libraries come with the CMake installation. You can find those
    in the \c {Modules} directory of your CMake installation.

    \note If you provide your own libraries, you also need to provide your own
    \c {FindFoo.cmake} file. For more information, see
    \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.

    Syntax completion and highlighting work once your project successfully
    builds and links against the external library.

*/
