feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: Turn "Specifying Environment Settings" into how-tos

Browse Source 
Add a line drawing that describes the environment settings
hierarchy.

Task-number: QTCREATORBUG-29361
Change-Id: I7869797154c0e70263528a8635ea7f2dcee30f30
Reviewed-by: Eike Ziller <eike.ziller@qt.io>
This commit is contained in:
Leena Miettinen
2023-11-07 18:10:02 +01:00
parent e5c4d20e2b
commit 266f9bc632
16 changed files with 155 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/qtcreator/images/qtcreator-edit-environment.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.5 KiB

BIN
doc/qtcreator/images/qtcreator-environment-settings-hierarchy.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.6 KiB

BIN
doc/qtcreator/images/qtcreator-projects-environment.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

3
doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc
View File

@@ -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

9
doc/qtcreator/src/editors/creator-code-completion.qdoc
View File

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

4
doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc
View File

@@ -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

23
doc/qtcreator/src/howto/creator-external-tools.qdoc
View File

@@ -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
*/
/*!

2
doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc
View File

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

2
doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc
View File

@@ -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

6
doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc
View File

@@ -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

155
doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc
View File

@@ -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 {<VARIABLE>=<VALUE>}.
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}
*/

17
doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc
View File

@@ -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

2
doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdocinc
View File

@@ -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

25
doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc
View File

@@ -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

25
doc/qtcreator/src/projects/qtcreator-variables.qdocinc → doc/qtcreator/src/projects/creator-only/qtcreator-how-to-use-qtc-variables.qdoc
View File

@@ -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},
*/

1
doc/qtcreator/src/qtcreator-toc.qdoc
View File

@@ -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