qt-creator/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc

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

/*!
    \previouspage creator-build-settings.html
    \page creator-build-settings-cmake.html
    \nextpage creator-build-settings-qmake.html

    \title CMake Build Configuration

    Configuring medium-sized to large CMake projects in \QC can be a
    challenge due to the number of options that you need to pass to
    CMake to configure the project correctly. To make this easier,
    \QC creates an initial configuration for you based on the kit
    settings and displays it in the \uicontrol {Initial CMake parameters}
    field and in a table that lists the parameter names and values.

    \image qtcreator-cmake-build-settings-initial.png "CMake build settings"

    Parameter names are listed in the \uicontrol Key column. Names with a
    common prefix (up to the first underscore character) are grouped under
    the prefix.

    \section1 Multi-Config Support

    \QC supports
    \l{https://cmake.org/cmake/help/latest/prop_gbl/GENERATOR_IS_MULTI_CONFIG.html}
    {Multi-config generators}, such as Xcode, Visual Studio, and Ninja
    Multi-Config. This means that you need to configure CMake only once, have
    only one build directory, and can switch between build types faster.

    However, this means that \QC can no longer simply parse the first CMake
    file-api JSON export. Therefore, the value of the \uicontrol {Build type}
    field must match that of the \c CMAKE_BUILD_TYPE variable for the single
    configuration generators (Ninja, Makefile) to determine, which generator
    to use.

    When developing with Qt 6 for iOS, only the Xcode generator is supported.

    \section1 Modifying Initial Parameters

    In the \uicontrol Value column, you can view and edit the actual values
    of the parameters that are passed to CMake.

    \image qtcreator-cmake-build-settings.png "CMake parameters"

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

    To add parameters, select \uicontrol Add, and then select the type of
    the parameter that you are adding: \uicontrol Boolean, \uicontrol String,
    \uicontrol Directory, or \uicontrol File.

    To change the type of the selected parameter, right-click the
    parameter name in the \uicontrol Key column, and then select
    \uicontrol {Force to bool}, \uicontrol {Force to file},
    \uicontrol {Force to directory}, or \uicontrol {Force to string}
    in the context menu.

    To copy the name or value of the selected parameter to the clipboard,
    select \uicontrol Copy in the context menu.

    To modify the value of a parameter, double-click it, or select it,
    and then select \uicontrol Edit.

    You can apply actions to multiple parameters at a time. To clear
    the selection, select \uicontrol {Clear Selection}.

    To remove the selected parameters, select \uicontrol Unset. To undo
    the removal, select \uicontrol Set.

    To reset all the changes that you made, select \uicontrol Reset.

    To modify the environment variable values for the CMake build environment,
    select \uicontrol {Batch Edit}. For more information, see \l{Batch Editing}.

    To save the changes, select \uicontrol {Apply Configuration Changes}.
    Keep in mind that a configuration change might trigger a follow-up
    configuration change.

    The parameter values that you change are passed via \c -D<option>=<value>
    to CMake, which stores the options in the CMakeCache.txt file. This means
    that if you remove the build directory, all the custom parameters that are
    not part of the initial CMake parameters are also removed.

    To reconfigure a project using the modified parameters,
    select \uicontrol Build > \uicontrol {Clear CMake Configuration}, which
    removes the CMakeCache.txt file. This enables you to do a full rebuild.

    \section1 Re-configuring with Initial Parameters

    To reset CMake parameters to the initial ones, select
    \uicontrol {Re-configure with Initial Parameters}.

    To be asked before \QC resets the changes, select \uicontrol Tools >
    \uicontrol Options > \uicontrol {Build & Run} > \uicontrol CMake >
    \uicontrol {Ask before re-configuring with initial parameters}.

    \image qtcreator-build-run-options-cmake.png "CMake Build & Run options"

    \section1 Viewing CMake Output

    Output from CMake is displayed next to the \uicontrol {Build Settings} and
    \uicontrol {Run Settings} panes in the \uicontrol Projects mode.

    \image qtcreator-build-cmake-output.png "CMake output in Projects mode"

    To clear the search results, select the \inlineimage icons/clean_pane_small.png
    (\uicontrol Clear) button.

    You can enter a string in the \uicontrol Filter field to filter output.
    To specify filtering options, select the
    \inlineimage icons/magnifier.png "Filtering options menu"
    button. You can filter output by using regular expressions or
    case-sensitivity. Select \uicontrol {Show Non-matching Lines} to
    hide the lines that match the filter.

    Press \key {Ctrl+F} to \l{Finding and Replacing}{search} for a string from
    the output.

    To increase or decrease the output text size, select \inlineimage icons/plus.png
    (\uicontrol {Zoom In}) or \inlineimage icons/minus.png
    (\uicontrol {Zoom Out}), or press \key Ctrl++ or \key Ctrl+-.

    \section1 CMake Build Steps

    \QC builds CMake projects by running \c {cmake . --build}, which then runs
    the CMake generator specified in the project configuration: \c make,
    \c mingw32-make, \c nmake, or \c ninja, for example. The CMake generator
    produces project files for \QC. Multi-config generators are also supported.

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

    \image qtcreator-cmake-build-steps.png "CMake build steps"

    \note While the other CMake generators are installed together with Qt,
    you usually need to install Ninja yourself.

    \section1 Using Ninja as a CMake Generator

    To use \l {https://ninja-build.org/}{Ninja} with CMake, you must install it
    and select it as the CMake generator in the build and run kit:

    \list 1
        \li Install Ninja.
        \li Add the path to the Ninja executable to the value of the PATH system
            variable.
        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Kits, and
            then select the build and run kit for the project.
        \li Select \uicontrol Change next to the \uicontrol {CMake generator}
            field to open the \uicontrol {CMake Generator} dialog.
            \image qtcreator-build-steps-cmake-ninja.png
        \li In the \uicontrol Generator field, select \uicontrol Ninja.
        \li Select \uicontrol OK to return to the \uicontrol Kits tab.
        \li Select \uicontrol OK or \uicontrol Apply to save your changes.
    \endlist

    \note To make sure that old build artifacts don't get in the way
    the first time you build the project after the change, select
    \uicontrol Build > \uicontrol {Rebuild Project}. This cleans up the
    build directory and performs a new build.

    \section1 Using CMake with Conan

    \QC can automatically set up the \l {Setting Up Conan}
    {Conan package manager} for use with CMake.

    Select \uicontrol Tools > \uicontrol Options > \uicontrol {Build & Run} >
    \uicontrol CMake > \uicontrol {Package manager auto setup} to set the
    value of the \c CMAKE_PROJECT_INCLUDE_BEFORE variable to the path to a
    CMake script that installs dependencies from a \c conanfile.txt,
    \c conanfile.py, or \c vcpkg.json file in the project source directory.

    \section1 CMake Clean Steps

    When building with CMake, you can add arguments to pass to CMake and the
    generator 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
    \l Issues output pane.
*/