/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing
**
** This file is part of Qt Creator
**
**
** GNU Free Documentation License
**
** 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.
**
**
****************************************************************************/

// **********************************************************************
// 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.

    Since \QC 1.1, CMake configuration files are supported. Since \QC 1.3, the
    Microsoft tool chain is supported if the CMake version is at least 2.8.

    \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}.

    \section1 Adding CMake Tools

    To specify paths to CMake executables, select \uicontrol Tools >
    \uicontrol Options > \uicontrol {Build & Run} > \uicontrol CMake >
    \uicontrol Add.

    \image qtcreator-cmakeexecutable.png

    \section1 Opening CMake Projects

    \note Before you open a CMake project, you must modify the \c {PATH}
    environment variable to include the bin folders of \c mingw and Qt.

    For instance, if Qt 5.5 is installed in \c {C:\Qt}, you would use the
    following command to set the environment variables in the command line
    prompt:
    \code
    set PATH=C:\Qt\Tools\mingw<VERSION>\bin;C:\Qt\5.5\<TARGET>\bin;
    \endcode
    Then start \QC by typing:
    \code
    C:\Qt\Tools\QtCreator\qtcreator.exe
    \endcode

    To open a CMake project:

    \list 1

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

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

    \endlist

    A wizard guides you through the rest of the process.

    \note If the CMake project does not have an in-place build, \QC
    lets you specify the directory in which the project is built
    (\l{glossary-shadow-build}{shadow build}).

    \image qtcreator-cmake-import-wizard1.png

    The screenshot below shows how you can specify command line arguments to
    CMake for your project.

    \image qtcreator-cmake-import-wizard2.png

    Normally, there is no need to pass any command line arguments for projects
    that are already built, as CMake caches that information.

    \section1 Editing CMake Configuration Files

    You can open CMake configuration files in \QC for editing. 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

    \QC builds CMake projects by running \c make, \c mingw32-make,
    \c nmake, or \c ninja depending on your platform. The build errors and
    warnings are parsed and displayed in the \uicontrol Issues output pane.

    By default, \QC uses the \uicontrol All \l{glossary-build-config}
    {build configuration}. You can select another build configuration in
    \uicontrol Projects > \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

    You can change the build directory after the initial import.

    The build and run kit that you select determines which CMake tool is used
    for building. For more information, see \l {Adding Kits}.

    \section1 Running CMake Projects

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

    For more information about known issues for the current version, see
    \l{Known Issues}.

    \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.

*/
