// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-how-set-project-environment.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-projects-configure

    \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
    automatically sets the necessary environment variables. You can edit
    existing environment variables or add, reset, and unset variables
    based on your project requirements.

    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 \l{Managing kits}{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 \uicontrol Environment.

    \image {qtcreator-preferences-environment-system.webp} {System tab in Environment preferences}

    \section1 Change the environment for a project

    To change the system environment for a project from the one in which
    \QC is started, select \uicontrol Projects > \uicontrol {Project Settings}
    > \uicontrol {Project Environment}.

    \image {qtcreator-projects-environment.webp} {Project Environment settings in Project Settings}

    You can edit existing environment variables or add, reset, unset, or
    temporarily disable variables.

    \section1 Specify the build environment

    To specify the build environment to use for a kit, go to \uicontrol Projects
    > \uicontrol {Build Settings} and select \uicontrol {Build Environment}.

    \image {qtcreator-build-environment.webp} {Build Environment section in Build Settings}

    To change the values of environment variables for the build environment,
    select the variable and then select \uicontrol Edit. Enter the new value
    in the editor on the right side.

    To add new variables, select \uicontrol {Add}.

    \section2 Clear the build environment

    To build with a clean system environment, select
    \uicontrol {Clear system environment}. \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. To edit the environment
    or select another environment, go to \uicontrol Projects >
    \uicontrol {Run Settings} and select \uicontrol {Environment}.

    \image {qtcreator-run-environment.webp} {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.

    \section2 Clean the run environment

    To run in a clean system environment, select \uicontrol {Clean Environment}.

    \section2 Set the environment for all run configurations

    To set environment variables for running and debugging applications, so
    that they don't affect \QC itself, set environment variables for run
    configurations of all projects:

    \list 1
        \li Go to \preferences > \uicontrol {Build & Run} > \uicontrol General.
        \li Select \uicontrol Change in \uicontrol {Application environment}.
        \li Set environment variables in \uicontrol {Edit Environment}.
            \image {qtcreator-edit-environment.webp} {Edit Environment dialog}
    \endlist

    For example, set \c QT_FORCE_STDERR_LOGGING=1 to see application output
    in \l {Application Output} instead of a journal or system log.

    Or, set \c QT_MESSAGE_PATTERN to add information to debugging messages.

    \section2 Use device environment

    When you run applications on a mobile device connected to the computer, \QC
    fetches information about the \uicontrol {Device Environment} from the device.
    Usually, it does not make sense to edit the device environment.

    \section1 Use environment variables from a file

    In addition to manually entering environment variable values in \QC, you can
    specify a file as the source for the environment variables. The file can
    be a simple text file containing the key and value pairs, or a script to
    be evaluated by the system shell.

    To use a file as the source for the environment variables:

    \list 1
        \li Go to any of the environment settings described above.
        \li Select \uicontrol {Get variables from text file or shell script}.
        \li Enter the path to the file.
    \endlist

    \sa {Edit environment settings}, {Configure projects for building},
    {Configure projects for running}, {Use \QC variables}
*/

/*!
    \page creator-how-to-edit-environment-settings.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-projects-configure

    \title Edit environment settings

    You can change the environment variable values for build or run environments
    globally or for a particular project or kit:

    \list
        \li To change values globally, go to \preferences >
            \uicontrol Environment > \uicontrol System, and select
            \uicontrol Change in \uicontrol {Environment}.
        \li To change values for a project, select \uicontrol Edit or
            \uicontrol {Add} 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.
        \li To change values for a kit, go to \preferences >
            \uicontrol Kits > \uicontrol Kits, and select
            \uicontrol {Edit Build Environment} or
            \uicontrol {Edit Run Environment} in \uicontrol {Environment}.
    \endlist

    \image {qtcreator-edit-environment.webp} {Edit Environment dialog}

    Use the following syntax to enter environment variable names and values:
    \c {<VARIABLE>=<VALUE>}.
    To temporarily disable a variable, add a hash character (#) to the beginning
    of the line.
    \note Using this approach for a different statement (append, prepend, unset)
    may result in unexpected changes of the environment.

    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
    building or running the project.

    To add a variable value to the environment, enter the variable name and
    value, separated by the equals sign. For example, the following line
    prepends the \c /opt/bin folder to the existing PATH:

    \list
        \li On Windows: \c {PATH=C:\opt\bin;${PATH}}
        \li On Linux: \c {PATH=/opt/bin:${PATH}}
    \endlist

    To add or remove several variables, place them on separate lines. The order
    is important. If you remove a value on a line, you cannot refer to it on the
    following lines. However, you can remove a value after you have referred to
    it on an earlier line.

    To add a comment or disable any of the above actions, prefix it with two hash
    characters (##).

    To use a file as the source for the environment variables, select
    \uicontrol {Get variables from text file or shell script} and enter
    the path to the file. For more information, see
    \l {Use environment variables from a file}.

    \section1 Set variable separators

    For environment variables that use non-standard list separators, you can
    set custom separators:

    \list 1
        \li Go to \preferences > \uicontrol Environment > \uicontrol System.
        \li Select \uicontrol Change in \uicontrol {Variable separators}.
        \li Select \uicontrol Add.
        \li Enter the variable name and separator.
        \li Select \uicontrol OK.
    \endlist

    \sa {Specify the environment for projects}, {Configure projects for building},
    {Configure projects for running}, {Use \QC variables}, {Managing kits}
*/
