forked from qt-creator/qt-creator
becb0af00a
- Add links to the kit management topics from other topics
- Always use \l{Kits} to link to Preferences > Kits
This has lived a little, as I've changed the category names
Change-Id: Ibcb137824a23bfe7e320a215eb461f689c43db77
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>
306 lines
14 KiB
Plaintext
306 lines
14 KiB
Plaintext
// Copyright (C) 2024 The Qt Company Ltd.
|
|
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
|
|
|
|
/*!
|
|
\page creator-build-settings-cmake.html
|
|
\previouspage creator-reference.html
|
|
|
|
\ingroup creator-reference-build-configurations
|
|
|
|
\title CMake Build Configuration
|
|
|
|
\brief Settings for building applications with CMake.
|
|
|
|
Specify build settings for the selected \l{Kits}{kit} in
|
|
\uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Build >
|
|
\uicontrol {Build Settings}.
|
|
|
|
Configuring medium-sized to large CMake projects in \QC can be a
|
|
challenge due to the number of variables 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 \l{Kits}
|
|
{kit preferences} and displays it in \uicontrol {Initial Configuration} in
|
|
the \uicontrol {Build Settings} of the project.
|
|
Or, you can use CMake presets to configure CMake.
|
|
|
|
The \uicontrol Configure field displays the effective CMake call that
|
|
\QC constructs using the values of the \uicontrol {Build directory} and
|
|
\uicontrol {Build type} fields.
|
|
|
|
\image qtcreator-build-settings-cmake-configure.webp {CMake configure command}
|
|
|
|
You can specify additional CMake options, such as \c {--find-debug},
|
|
\c {--trace-expand}, or \c {--warn-uninitialized}, in
|
|
\uicontrol {Additional CMake options}. For more information about
|
|
the options, click the link in the field name or see \l{CMake: cmake(1)}.
|
|
|
|
Select \uicontrol {Kit Configuration} to edit the CMake settings for the
|
|
build and run kit selected for the project.
|
|
|
|
You can use \l{CMake Presets}{CMake presets} files to specify common
|
|
configure, build, and test options and share them with others.
|
|
|
|
\section1 Initial Configuration
|
|
|
|
\image qtcreator-build-settings-cmake-initial.webp {Initial CMake configuration}
|
|
|
|
\uicontrol {Initial Configuration} lists the variables that \QC uses to
|
|
configure the CMake project for the first time. It shows the default values
|
|
that come from the kit's CMake configuration in italics. \QC saves the
|
|
initial configuration list of variables in the project's source
|
|
directory as the \e CMakeLists.txt.user file.
|
|
|
|
\section1 Current Configuration
|
|
|
|
\image qtcreator-build-settings-cmake-current.webp {Current CMake configuration}
|
|
|
|
\uicontrol {Current Configuration} lists the CMake variables in the
|
|
\c cmake-file-api JSON export in the \c {.cmake/api/v1/reply} directory.
|
|
It shows the variables that come from the initial configuration in italics
|
|
and mismatched values in red.
|
|
|
|
After selecting the \uicontrol {Run CMake} button, you can view and
|
|
change the actual values of the variables that \QC passes to CMake.
|
|
The \uicontrol Key column lists variable names, and the \uicontrol Value
|
|
column lists their current values. For more information about the variables,
|
|
select \uicontrol Help in the context menu or see
|
|
\l{CMake: cmake-variables(7)}. For more information about Qt-specific
|
|
variables, see \l{CMake Variable Reference}.
|
|
|
|
\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 Variable Values
|
|
|
|
You can view and edit the actual values of the variables that
|
|
are passed to CMake in \uicontrol {Initial Configuration} or
|
|
\uicontrol {Current Configuration}.
|
|
|
|
\image qtcreator-build-settings-cmake-current.webp {Current CMake configuration}
|
|
|
|
You can select several variables and apply an action to them. To clear
|
|
the selection, click anywhere in the view.
|
|
|
|
To batch edit variable values, select \uicontrol {Batch Edit}.
|
|
|
|
\image qtcreator-edit-cmake-configuration.webp {Edit CMake Configuration dialog}
|
|
|
|
To build using the current configuration, select \uicontrol {Run CMake}.
|
|
While building, the button text changes to \uicontrol {Stop CMake}. Select
|
|
the button to cancel the current build.
|
|
|
|
\section2 Adding Variables
|
|
|
|
To add variables, select \uicontrol Add, and then select the type of
|
|
the variable that you are adding: \uicontrol Boolean, \uicontrol String,
|
|
\uicontrol Directory, or \uicontrol File.
|
|
|
|
To change the type of the selected variable, right-click the
|
|
variable 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 variable to the clipboard,
|
|
select \uicontrol Copy in the context menu.
|
|
|
|
\section2 Changing Variable Values
|
|
|
|
To change the value of a variable, double-click it, or select it,
|
|
and then select \uicontrol Edit. If the initial, current, and kit
|
|
configuration get out of sync, select \uicontrol {Apply Kit Value} or
|
|
\uicontrol {Apply Initial Configuration Value} in the context menu in
|
|
\uicontrol {Initial Configuration} or \uicontrol {Current Configuration}.
|
|
|
|
To reset all the changes that you made, select \uicontrol Reset.
|
|
|
|
The variable 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 variables that are
|
|
not part of the initial CMake configuration are also removed.
|
|
|
|
To reconfigure a project using the changed variable values,
|
|
select \uicontrol Build > \uicontrol {Clear CMake Configuration}, which
|
|
removes the CMakeCache.txt file. This enables you to do a full rebuild.
|
|
|
|
\section2 Removing Variables
|
|
|
|
To remove the selected variables, select \uicontrol Unset. To undo
|
|
the removal, select \uicontrol Set.
|
|
|
|
\section2 Viewing Advanced Variables
|
|
|
|
To view all variables, select the \uicontrol Advanced check box.
|
|
|
|
To view all variables by default, go to \preferences > \uicontrol CMake >
|
|
\uicontrol General and select \uicontrol {Show advanced options by default}.
|
|
|
|
\image qtcreator-preferences-cmake-general.webp "General tab in CMake Preferences"
|
|
|
|
\section1 Re-configuring with Initial Variables
|
|
|
|
To reset CMake variables to the initial ones, select
|
|
\uicontrol {Re-configure with Initial Variables} in
|
|
\uicontrol {Initial Configuration}. \QC deletes the current CMake
|
|
configuration and runs CMake. The initial configuration values are
|
|
stored in the CMakeLists.txt.user file, so deleting a build directory
|
|
does not delete the initial configuration.
|
|
|
|
To be asked before \QC resets the changes, go to \preferences >
|
|
\uicontrol CMake > \uicontrol General and select
|
|
\uicontrol {Ask before re-configuring with initial parameters}.
|
|
|
|
\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{Search in current file}{search} for a string in
|
|
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+-.
|
|
|
|
To hide the output, select the \inlineimage icons/rightsidebaricon.png
|
|
(\uicontrol {Hide Right Sidebar}) button or press \key {Alt+Shift+0}.
|
|
|
|
\section1 CLICOLOR_FORCE Environment Variable
|
|
|
|
\QC sets the environment variable \c CLICOLOR_FORCE to \e 1 to show
|
|
ANSI-colored output for CMake. This might affect the process output.
|
|
|
|
If the output looks incorrect or different from earlier \QC versions, try
|
|
setting \c CLICOLOR_FORCE to \e 0 in \uicontrol {Use Build Environment}.
|
|
|
|
\image qtcreator-build-configuration-set-clicolor-force.webp {Build Environment with CLICOLOR_FORCE set}
|
|
|
|
\section1 Using Junction Points on Windows
|
|
|
|
To overcome issues with long paths on Windows, create and use
|
|
\l{https://learn.microsoft.com/en-us/sysinternals/downloads/junction}
|
|
{junction points} for the source and build directories. At a junction point,
|
|
a directory serves as an alias to another directory on the computer.
|
|
|
|
To use the junction points for CMake configure, build, and install
|
|
operations, go to \preferences > \uicontrol CMake > \uicontrol General and
|
|
select \uicontrol {Use junctions for CMake configuration and build operations}.
|
|
|
|
\image qtcreator-preferences-cmake-general.webp {CMake General preferences}
|
|
|
|
\QC stores junction points in \c {C:\ProgramData\QtCreator\Links}. To use
|
|
another path, set it as the value of the \c QTC_CMAKE_JUNCTIONS_DIR
|
|
environment variable.
|
|
|
|
Set the \c QTC_CMAKE_JUNCTIONS_HASH_LENGTH environment variable to shorten
|
|
the MD5 hash key length from the default length value of 32.
|
|
|
|
\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.webp {CMake build steps}
|
|
|
|
\note While the other CMake generators are installed together with Qt,
|
|
you usually need to install Ninja yourself.
|
|
|
|
To install the application to a staging directory when cross-compiling,
|
|
select the \uicontrol {Stage for installation} check box and specify
|
|
the path to a directory in the \uicontrol {Staging directory} field.
|
|
The packaging tool constructs the package from the contents of the
|
|
directory.
|
|
|
|
\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 In \uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Build
|
|
> \uicontrol {Build Settings}, select \uicontrol {Kit Configuration}.
|
|
\image qtcreator-cmake-kit-configuration.png {Kit CMake Configuration dialog}
|
|
\li Select \uicontrol Change next to the \uicontrol {CMake generator}
|
|
field to open the \uicontrol {CMake Generator} dialog.
|
|
\image qtcreator-cmake-generator.webp {CMake Generator dialog}
|
|
\li In \uicontrol Generator, select \uicontrol Ninja.
|
|
\li Select \uicontrol OK to save your changes and close the dialog.
|
|
\li Select \uicontrol Close to close the
|
|
\uicontrol {Kit CMake Configuration} dialog
|
|
and return to \uicontrol {Build Settings}.
|
|
\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 Package Managers
|
|
|
|
To automatically set up the \l {Conan Package Manager}{Conan} or
|
|
\l {vcpkg Package Manager}{vcpkg} package manager for use with CMake:
|
|
|
|
\list 1
|
|
\li Create a CMake script file that installs dependencies from a
|
|
\c conanfile.txt, \c conanfile.py, or \c vcpkg.json file in
|
|
the project source directory.
|
|
\li Set the path to the script as the value of the
|
|
\c CMAKE_PROJECT_INCLUDE_BEFORE variable.
|
|
\li Go to \preferences > \uicontrol CMake > \uicontrol General and select
|
|
\uicontrol {Package manager auto setup}.
|
|
\endlist
|
|
|
|
\section1 QTC_RUN Environment Variable
|
|
|
|
\QC sets the environment variable \c QTC_RUN to \c 1 when executing
|
|
the \c cmake process.
|
|
|
|
This enables the CMake code to detect if it's being executed from \QC.
|
|
|
|
\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.webp {CMake clean steps}
|
|
|
|
The build errors and warnings are parsed and displayed in \l Issues.
|
|
|
|
\sa {Activate kits for a project}, {Add custom output parsers},
|
|
{Configure projects for building}, {Configure projects for running},
|
|
{Build with CMake}{How To: Build with CMake}, {Open projects}, {CMake}
|
|
*/
|