From 837a779b86bb0499ad967727718a7815f863a594 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Mon, 6 Mar 2023 17:45:06 +0100 Subject: Doc: Describe changes in CMake build settings - Added `Show advanced options by default` to `Edit > Preferences > CMake > Tools` - Moved `Autorun CMake` to `Edit > Preferences > CMake > General` - Reorganize the building with CMake topic and add subtitles for readability Task-number: QTCREATORBUG-28721 Change-Id: Id8bab60bc2e148c067ac1eb3669b544d12031078 Reviewed-by: Cristian Adam --- .../qtcreator-build-settings-cmake-configure.webp | Bin 0 -> 5270 bytes .../qtcreator-build-settings-cmake-current.webp | Bin 0 -> 16632 bytes .../qtcreator-build-settings-cmake-initial.webp | Bin 0 -> 12268 bytes .../qtcreator-cmake-build-settings-initial.png | Bin 24618 -> 0 bytes .../images/qtcreator-cmake-build-settings.png | Bin 21459 -> 0 bytes .../src/cmake/creator-projects-cmake-building.qdoc | 113 ++++++++++++--------- .../src/cmake/creator-projects-cmake.qdoc | 9 +- .../creator-only/creator-projects-building.qdoc | 2 +- 8 files changed, 70 insertions(+), 54 deletions(-) create mode 100644 doc/qtcreator/images/qtcreator-build-settings-cmake-configure.webp create mode 100644 doc/qtcreator/images/qtcreator-build-settings-cmake-current.webp create mode 100644 doc/qtcreator/images/qtcreator-build-settings-cmake-initial.webp delete mode 100644 doc/qtcreator/images/qtcreator-cmake-build-settings-initial.png delete mode 100644 doc/qtcreator/images/qtcreator-cmake-build-settings.png diff --git a/doc/qtcreator/images/qtcreator-build-settings-cmake-configure.webp b/doc/qtcreator/images/qtcreator-build-settings-cmake-configure.webp new file mode 100644 index 0000000000..4b38b162f4 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-build-settings-cmake-configure.webp differ diff --git a/doc/qtcreator/images/qtcreator-build-settings-cmake-current.webp b/doc/qtcreator/images/qtcreator-build-settings-cmake-current.webp new file mode 100644 index 0000000000..24278f8dcc Binary files /dev/null and b/doc/qtcreator/images/qtcreator-build-settings-cmake-current.webp differ diff --git a/doc/qtcreator/images/qtcreator-build-settings-cmake-initial.webp b/doc/qtcreator/images/qtcreator-build-settings-cmake-initial.webp new file mode 100644 index 0000000000..cee22f09f6 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-build-settings-cmake-initial.webp differ diff --git a/doc/qtcreator/images/qtcreator-cmake-build-settings-initial.png b/doc/qtcreator/images/qtcreator-cmake-build-settings-initial.png deleted file mode 100644 index 3392c8ee67..0000000000 Binary files a/doc/qtcreator/images/qtcreator-cmake-build-settings-initial.png and /dev/null differ diff --git a/doc/qtcreator/images/qtcreator-cmake-build-settings.png b/doc/qtcreator/images/qtcreator-cmake-build-settings.png deleted file mode 100644 index 9c88b064d6..0000000000 Binary files a/doc/qtcreator/images/qtcreator-cmake-build-settings.png and /dev/null differ diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc index 322a72cd71..dac77727a8 100644 --- a/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc +++ b/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc @@ -16,42 +16,47 @@ the \l{Specifying Build Settings}{Build Settings} of the project. Alternatively, you can use CMake presets to configure CMake. - The \uicontrol Configuration field displays the effective CMake call that - is constructed by using the values of the \uicontrol {Build directory} and + 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-cmake-build-settings-initial.png {CMake build settings} - - \uicontrol {Initial Configuration} lists the variables that are used to - configure the CMake project for the first time. The default values that - are inherited from the kit's CMake configuration are displayed in italic. - The initial configuration list of variables is saved in the project's source - directory as the \e CMakeLists.txt.user file. - - \uicontrol {Current Configuration} lists the CMake variables in the - \c cmake-file-api JSON export in the \c {.cmake/api/v1/reply} directory. - The variables that are inherited from the initial configuration are - displayed in italic. Mismatched values are displayed in red. - - You can view and edit the actual values of the variables that are passed - to CMake. Variable names are listed in the \uicontrol Key column and their - current values in the \uicontrol Value column. For more information about - the available 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}. + \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 available options, click the link in the field name or see - \l{CMake: cmake(1)}. - - After successfully running CMake, you can view and modify the current - configuration in \uicontrol {Current Configuration}. + 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. + \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 CMake Presets You can use CMake presets files to specify common configure, build, and test @@ -63,9 +68,9 @@ \l{https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html} {cmake-presets(7)} and store them in project's root directory. - \QC supports presets up to version 3 (introduced in CMake 3.21), but version - checking is not enforced. All the fields from version 3 are read and used if - present. Test presets are not supported. + \QC supports presets up to version 3 (introduced in CMake 3.21), but does not + enforce version checking. It reads and uses all the fields from version 3 if + present. It does not support test presets. You can import the presets the first time you \l {Opening Projects} {open a project}, when no \c CMakeLists.txt.user file exists or you have @@ -292,9 +297,19 @@ are passed to CMake in \uicontrol {Initial Configuration} or \uicontrol {Current Configuration}. - \image qtcreator-cmake-build-settings.png {CMake variables} + \image qtcreator-build-settings-cmake-current.webp {Current CMake configuration} - To view all variables, select the \uicontrol Advanced check box. + You can select several variables and apply an action to them. To clear + the selection, click anywhere in the view. + + To change the environment variable values for the CMake build environment, + select \uicontrol {Batch Edit}. For more information, see \l{Batch Editing}. + + 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, @@ -309,36 +324,40 @@ To copy the name or value of the selected variable to the clipboard, select \uicontrol Copy in the context menu. - To modify the value of a variable, double-click it, or select it, + \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}. - You can apply actions to multiple variables at a time. To clear - the selection, select \uicontrol {Clear Selection}. - - To remove the selected variables, 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 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. - The variable values that you change are passed via \c -D