diff --git a/doc/qtcreator/images/qtcreator-edit-environment.webp b/doc/qtcreator/images/qtcreator-edit-environment.webp new file mode 100644 index 00000000000..f68eb52540e Binary files /dev/null and b/doc/qtcreator/images/qtcreator-edit-environment.webp differ diff --git a/doc/qtcreator/images/qtcreator-environment-settings-hierarchy.webp b/doc/qtcreator/images/qtcreator-environment-settings-hierarchy.webp new file mode 100644 index 00000000000..574b2a75470 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-environment-settings-hierarchy.webp differ diff --git a/doc/qtcreator/images/qtcreator-projects-environment.webp b/doc/qtcreator/images/qtcreator-projects-environment.webp new file mode 100644 index 00000000000..36011d22263 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-projects-environment.webp differ diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc index f8c8842b1f5..9c971d24798 100644 --- a/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc +++ b/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc @@ -88,7 +88,8 @@ 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}. + select \uicontrol {Batch Edit}. For more information, see + \l{Batch edit environment settings}. To build using the current configuration, select \uicontrol {Run CMake}. While building, the button text changes to \uicontrol {Stop CMake}. Select diff --git a/doc/qtcreator/src/editors/creator-code-completion.qdoc b/doc/qtcreator/src/editors/creator-code-completion.qdoc index b3d1830640b..e608400f35d 100644 --- a/doc/qtcreator/src/editors/creator-code-completion.qdoc +++ b/doc/qtcreator/src/editors/creator-code-completion.qdoc @@ -197,12 +197,13 @@ \if defined(qtcreator) Also specify a text string or C++ or QML code construct in the snippet editor, depending on the snippet category. + + You can use \l{Use Qt Creator variables}{predefined variables} in + snippets. \else Also specify a text string or QML code in the snippet editor, depending on the snippet category. \endif - You can use \l{Using Qt Creator Variables}{predefined variables} in - snippets. The snippet editor offers: @@ -299,8 +300,6 @@ \preferences > \uicontrol Nim > \uicontrol Tools, and enter the path to the tool executable in the \uicontrol Path field. - \sa {Document code} - \else - \include qtcreator-variables.qdocinc qtcreator variables + \sa {Document code}, {Use Qt Creator variables} \endif */ diff --git a/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc b/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc index 8ebbaa74d4b..0a89789d4a7 100644 --- a/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc +++ b/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc @@ -81,7 +81,7 @@ \li In the \uicontrol Name field, enter a name for the language server. Select the \inlineimage icons/replace.png (\uicontrol {Variables}) button to use a variable for the server - name. For more information, see \l{Using Qt Creator Variables}. + name. For more information, see \l{Use Qt Creator variables}. \li In the \uicontrol {Language} field, select \uicontrol {Set MIME Types} to select the MIME types of the files to send to the language server. In the field below, you can enter file @@ -113,7 +113,7 @@ \li In the \uicontrol Name field, enter a name for the language server. Select the \inlineimage icons/replace.png (\uicontrol {Variables}) button to use a variable for the server - name. For more information, see \l{Using Qt Creator Variables}. + name. For more information, see \l{Use Qt Creator variables}. \li In the \uicontrol Java field, enter the path to the Java executable. \li In the \uicontrol {Java Language Server} field, enter the path to the Java language server \c .jar file. You can download the Java diff --git a/doc/qtcreator/src/howto/creator-external-tools.qdoc b/doc/qtcreator/src/howto/creator-external-tools.qdoc index 53ba24a3f4b..3f29dfc57bf 100644 --- a/doc/qtcreator/src/howto/creator-external-tools.qdoc +++ b/doc/qtcreator/src/howto/creator-external-tools.qdoc @@ -35,10 +35,12 @@ \image qtcreator-external-tools.png + \if defined(qtcreator) Select the \inlineimage icons/replace.png (\uicontrol {Variables}) button in a field to select from a list of - \l{Using Qt Creator Variables}{variables} that are available in a + \l{Use Qt Creator variables}{variables} that are available in a particular context. + \endif To configure external tools: @@ -71,8 +73,8 @@ \if defined(qtcreator) \li In the \uicontrol {Base environment} field, select whether to run - the tool in the system environment or the \l{Build Environment} - {build environment} or \l {Selecting the Run Environment} + the tool in the system environment or the \l{Specify the environment for projects} + {build environment} or \l {Specify the run environment} {run environment} of the active project. Select the build or run environment if the system environment does not have the necessary PATH settings to find the tool chain, for example. @@ -82,20 +84,12 @@ \li In the \uicontrol Environment field, select \uicontrol Change to modify environment variable values for build and run environments in - the \uicontrol {Edit Environment Changes} dialog. - \if defined(qtcreator) - For more information about how to add and remove variable values, - see \l{Batch Editing}. - \endif - + the \uicontrol {Edit Environment} dialog. To globally change the system environment from the one in which \QC is started, select \preferences > \uicontrol Environment > \uicontrol System, and then select \uicontrol Change in the \uicontrol Environment field. - \if defined(qtcreator) - For more information, see \l{Specifying Environment Settings}. - \endif \li Select the \uicontrol {Modifies current document} check box to make sure that if the current document is modified by the tool, it is saved @@ -121,6 +115,11 @@ configuration file to the folder. \sa {Run QML files}, {Use external text editors}, {Use Qt Linguist} + + \if defined(qtcreator) + \sa {Batch edit environment settings}, {Specify the environment for projects}, + {Use Qt Creator variables} + \endif */ /*! diff --git a/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc b/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc index 2d427ee15aa..ea95ce05924 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc @@ -21,7 +21,7 @@ checkbox. Select the build directory in the \uicontrol {Build Directory} field. You - can use the \l{Using Qt Creator Variables}{variables} that are listed when + can use the \l{Use Qt Creator variables}{variables} that are listed when you select the \inlineimage icons/replace.png (\uicontrol {Variables}) button. diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc index 3e1f9fcd62e..dc0fe3abc42 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc @@ -151,7 +151,7 @@ \li Select \uicontrol Change to modify environment variable values for build environments in the \uicontrol {Edit Environment Changes} dialog. For more information about how to add and remove variable - values, see \l{Batch Editing}. + values, see \l{Batch edit environment settings}. \row \li \uicontrol {Force UTF-8 MSVC compiler output} \li Either switches the language of MSVC to English or keeps the diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc index 3a54e8e4e7e..222c7e5d48f 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc @@ -110,10 +110,8 @@ tested or grouping commands, are not supported because the value of the \uicontrol Executable field is always placed first when constructing the command. - You can use \l {Using Environment Variables}{environment variables} as - values in the fields. In addition, you can \l {Using Qt Creator Variables} - {use \QC variables} in arguments, executable paths, and working - directories. + You can \l {Use Qt Creator variables}{use \QC variables} in arguments, + executable paths, and working directories. \section1 Build Steps diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc index 4459d0b9063..504f9d02732 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc @@ -1,16 +1,17 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-build-dependencies.html - \page creator-project-settings-environment.html - \nextpage creator-custom-output-parsers.html + \page creator-how-set-project-environment.html + \previouspage creator-how-tos.html - \title Specifying Environment Settings + \ingroup creator-how-to-projects - You can specify the environment you want to use for building - a project in the \uicontrol {Build Environment} section of - the \uicontrol {Build Settings}. + \title Specify the environment for projects + + The environment for a project is determined according to a settings hierarchy: + + \image qtcreator-environment-settings-hierarchy.webp {Environment settings hierarchy} By default, the environment in which \QC was started is used and modified to include the Qt version. Depending on the selected Qt version, \QC @@ -18,36 +19,109 @@ existing environment variables or add, reset and unset new variables based on your project requirements. - To globally change the system environment from the one in which - \QC is started, select \preferences > - \uicontrol Environment > \uicontrol System, and then select - \uicontrol Change in the \uicontrol Environment field. + The final environment is specified separately for each kit. With + project-specific environment settings you can change the environment for + all kits that you use to build, deploy, and run the project simultaneously, + rather than having to change it separately for each kit. + + The changes are stored in the local project-specific \c{CMakeLists.txt.user} + or \c{.pro.user} file, depending on the build system you use, such as CMake + or qmake. Therefore, they are not suitable for sharing between developers or + development PCs. To share settings, incorporate them into the build system. + For example, if you use CMake, make the changes in the \c {CMakeLists.txt} + file, and if you use qmake, make the changes in the \c{.pro} file. + + \section1 Globally change the environment + + To globally change the environment from the one in which \QC is started, + select \preferences > \uicontrol Environment > \uicontrol System, and then + select \uicontrol Change in the \uicontrol Environment field. \image qtcreator-preferences-environment-system.webp "Environment preferences System tab" - In addition, you can specify custom environment variables in the - \uicontrol {Project Settings} > \uicontrol Environment settings. - They are added to all build environments. The final build environment - is specified separately for each kit. The project-specific environment - settings enable you to amend the build environment for all kits that - you use to build the project simultaneously, rather than having to edit - it separately for each kit. + \section1 Change the environment for a project - \image qtcreator-build-environment.png "Build Environment" + To change the system environment for a project from the one in which + \QC is started, select \uicontrol Projects > \uicontrol {Project Settings} + > \uicontrol Environment. - The changes are stored in the local project specific \c{CMakeLists.txt.user} - or \c{.pro.user} file, depending on the build system you use. Therefore, - they are not suitable for sharing between developers or development PCs. To - share settings, incorporate them into the build system. For example, if you - use CMake, make the changes in the \c {CMakeLists.txt} file, and if you use - qmake, make the changes in the \c{.pro} file. + \image qtcreator-projects-environment.webp {Environment tab in Project Settings} - \section1 Batch Editing + \section1 Specify the build environment - To modify environment variable values for build or run environments, - select \uicontrol {Batch Edit} in the \uicontrol {Build Environment} - or \uicontrol {Environment} pane and enter environment variables in - the \uicontrol {Edit Environment} dialog. + Specify the build environment to use for a kit in \uicontrol Projects > + \uicontrol {Build Settings} > \uicontrol {Build Environment}. + + \image qtcreator-build-environment.png {Build Environment section in Build Settings} + + \section2 Clear the build environment + + To build with a clean system environment, select the \uicontrol {Clear + system environment} check box. \QC discards the current environment, and + populates a clean system environment with the environment variables that + the compilers and tools need. Therefore, the environment is never totally + empty, even after you clear it. + + \section1 Specify the run environment + + \QC automatically selects the environment used for running the application + based on the \l{glossary-device}{device} type. You can edit the environment + or select another environment in \uicontrol Projects > + \uicontrol {Run Settings} > \uicontrol {Environment}. + + You can edit existing environment variables or add, reset and unset new + variables. + + \image qtcreator-run-environment.png {Environment section in Run Settings} + + When running on the desktop, the \uicontrol {Build Environment} is used by + default, but you can also use the \uicontrol {System Environment} without the + additions made to the build environment. + + To modify the environment variable values for the run environment, + double-click environment variables or their values and change them inline, + or select \uicontrol {Batch Edit} to change several variable values at a + time. + + \section2 Clean the run environment + + To run in a clean system environment, select \uicontrol {Clean Environment}. + + \section2 Run on devices + + When running on a mobile device connected to the development host, \QC + fetches information about the \uicontrol {Device Environment} from the device. + Usually, it does not make sense to edit the device environment. + + \sa {Batch edit environment settings}, {Specifying Build Settings}, + {Specifying Run Settings}, {Use Qt Creator variables} +*/ + +/*! + \page creator-how-to-batch-edit-environment-settings.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-projects + + \title Batch edit environment settings + + You can change the environment variable values for build or run environments + either for a particular project or globally for all projects in the + \uicontrol {Edit Environment} dialog: + + \list + \li To change values globally, select \uicontrol Change in the + \l {Globally change the environment}{global environment preferences}. + \li To change values for a project, select \uicontrol {Batch Edit} in the + \l {Change the environment for a project}{project}, + \l {Specify the build environment}{build}, or + \l {Specify the run environment}{run} environment settings. + \endlist + + \image qtcreator-edit-environment.webp {Edit Environment dialog} + + Use the following syntax to enter environment variable names and values: + \c {=}. To remove a variable value from the environment, enter the variable name. For example, \c TEST sets the value of the \c TEST variable empty when @@ -70,21 +144,6 @@ To temporarily disable a variable, add a hash character (#) to the beginning of the line. - \section1 Clearing the System Environment - - To build with a clean system environment, select the \uicontrol {Clear - system environment} check box. \QC discards the current environment, and - populates a clean system environment with the environment variables that - the compilers and tools need. Therefore, the environment is never totally - empty, even after you clear it. - - \section1 Using Environment Variables - - You can use any environment variables in build, deploy, and run - configurations. For a list of variable names, select \uicontrol {Build - Settings} > \uicontrol {Build Environment} > \uicontrol Details. - Environment variables are referenced using the native syntax: $VARNAME - or ${VARNAME} on Unix and %VARNAME% on Windows. - - \include qtcreator-variables.qdocinc qtcreator variables + \sa {Specify the environment for projects}, {Specifying Build Settings}, + {Use Qt Creator variables} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc index 6a15f763200..ab8a2f164ba 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc @@ -14,13 +14,12 @@ \title Configuring Projects - When you install Qt for a target platform, such as Android or QNX, - \l{https://www.qt.io/download-qt-installer}{\QOI} - creates \l{glossary-buildandrun-kit}{kits} for the development - targets. + When you install Qt for a development or target platform, such as Linux, + \macos, Windows, Android or QNX, \l{https://www.qt.io/download-qt-installer} + {\QOI} creates \l{glossary-buildandrun-kit}{kits} for the development targets. - Select the kits to use in the \uicontrol {Configure Projects} - view when you open a project for the first time. At least one kit must be + Select the kits to use for a project in the \uicontrol {Configure Projects} + view when you open the project for the first time. At least one kit must be active. To maintain the list of active kits for a currently open project, switch to @@ -29,7 +28,7 @@ \image qtcreator-projects-kits.webp {Sidebar in the Projects mode} To specify build or run settings for a kit, select \uicontrol Build or - \uicontrol Run below the kit. + \uicontrol Run below the kit name. \section1 Overriding Global Preferences @@ -45,7 +44,7 @@ \li \l{Specify dependencies}{Dependencies} \li \l{Document code}{Documentation Comments} \li \l{Specify editor settings}{Editor} - \li \l{Specifying Environment Settings}{Environment} + \li \l{Specify the environment for projects}{Environment} \li \l{Applying Refactoring Actions}{Quick Fixes} \li \l{To-Do Entries}{To-Do} (experimental) \endlist @@ -69,7 +68,7 @@ lists the kits that are compatible with your project. To activate one or more kits, click them. - \image qtcreator-project-kits.png + \image qtcreator-project-kits.png {List of kits in Projects mode sidebar} The list displays kits from \preferences > \uicontrol Kits. Warning and error icons indicate that the kit configuration diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdocinc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdocinc index caadbe3b463..74e6357ee7b 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdocinc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdocinc @@ -27,7 +27,7 @@ To run with special environment variables set up, select them in the \uicontrol {Run Environment} section. For more information, see - \l {Selecting the Run Environment}. + \l {Specify the run environment}. When building an application, \QC creates a list of directories where the linker will look for libraries that the application links to. By diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc index e574c00a4c3..14205f59db2 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc @@ -95,31 +95,6 @@ \include creator-projects-settings-run-qnx.qdocinc run settings qnx \include linux-mobile/creator-projects-settings-run-b2qt.qdocinc run settings boot2qt - \section1 Selecting the Run Environment - - \QC automatically selects the environment used for running the application - based on the \l{glossary-device}{device} type. You can edit the environment - or select another environment in the \uicontrol {Run Environment} section. - - You can edit existing environment variables or add, reset and unset new - variables. - - \image qtcreator-run-environment.png {Run Environment section} - - When running on the desktop, the \uicontrol {Build Environment} is used by - default, but you can also use the \uicontrol {System Environment} without the - additions made to the build environment. For more information, see - \l {Build Environment} and \l{Specifying Environment Settings}. - - To run in a clean system environment, select \uicontrol {Clean Environment}. - - When running on a mobile device connected to the development host, \QC - fetches information about the \uicontrol {Device Environment} from the device. - Usually, it does not make sense to edit the device environment. - - To modify the environment variable values for the run environment, select - \uicontrol {Batch Edit}. For more information, see \l{Batch Editing}. - \section1 Specifying a Custom Executable to Run If you use CMake, Meson or the generic project type in \QC, or want diff --git a/doc/qtcreator/src/projects/qtcreator-variables.qdocinc b/doc/qtcreator/src/projects/creator-only/qtcreator-how-to-use-qtc-variables.qdoc similarity index 64% rename from doc/qtcreator/src/projects/qtcreator-variables.qdocinc rename to doc/qtcreator/src/projects/creator-only/qtcreator-how-to-use-qtc-variables.qdoc index eef38706981..cf8100a68ae 100644 --- a/doc/qtcreator/src/projects/qtcreator-variables.qdocinc +++ b/doc/qtcreator/src/projects/creator-only/qtcreator-how-to-use-qtc-variables.qdoc @@ -1,13 +1,19 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -//! [qtcreator variables] - \section1 Using Qt Creator Variables + \page creator-how-to-use-qtc-variables.html + \previouspage creator-how-tos.html - You can use \QC variables in arguments, executable paths, and working - directories. The variables take care of quoting their expansions, so you do - not need to put them in quotes. + \ingroup creator-how-to-projects + + \title Use Qt Creator variables + + You can use \QC variables in \uicontrol Preferences, + \uicontrol {Build Settings}, and \uicontrol {Run Settings}, in fields that + set arguments, executable paths, and working directories, for example. The + variables take care of quoting their expansions, so you do not need to put + them in quotes. Select the \inlineimage icons/replace.png (\uicontrol {Variables}) button in a field to select from a list of @@ -15,7 +21,7 @@ For more information about each variable, move the cursor over it in the list. - \image qtcreator-variables.png "Qt Creator Variables dialog displaying a tooltip" + \image qtcreator-variables.png {Qt Creator Variables dialog showing a tooltip} The following syntax enables you to use environment variables as \QC variables: %{Env:VARNAME}. @@ -38,7 +44,7 @@ backreferences. For example, if \c %{variable} is \c my123var, then \c %{variable/(..)(\d+)/\2\1} is expanded to \c {123myvar}. - Instead of the forward slash, you can also use the pound sign (\c #) as + Instead of the forward slash, you can also use the number sign (\c #) as the substitution character. This can be helpful if the value is supposed to be a file path, in which case forward slashes might get translated to backslashes on Windows hosts. @@ -48,5 +54,6 @@ \badcode %{variable:-default} \endcode -//! [qtcreator variables] + + \sa {Specify the environment for projects}, {Specifying Build Settings}, */ diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index 0e3f3883d51..ad60462b0f4 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -39,7 +39,6 @@ \li \l{Conan Build Configuration} \endlist \li \l{Specifying Run Settings} - \li \l{Specifying Environment Settings} \li \l{Using Custom Output Parsers} \li \l{Sharing Project Settings} \endlist