/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing
**
** This file is part of Qt Creator
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage {Qt Creator Manual}
    \previouspage creator-debuggers.html
    \page creator-build-settings.html
    \nextpage creator-run-settings.html

    \title Specifying Build Settings

    Different build configurations allow you to quickly switch between
    different build settings. By default, \QC creates \b debug
    and \b release build configurations. A debug build contains additional
    debug symbols that you need for debugging the application but that you
    can leave out from the release version. Generally, you use the debug
    configuration for testing and the release configuration for creating
    the final installation file.

    You specify build settings in the \uicontrol Projects mode.
    To add a new build configuration, click \uicontrol Add and select the type of
    configuration you would like to add. You can add as many build
    configurations as you need.

    To delete the build configuration currently selected, click \uicontrol Remove.

    \section1 Editing Build Configurations

    Select the build configuration to edit in the
    \uicontrol {Edit build configuration} field.

    \image qtcreator-projectpane.png

    By default, \QC builds projects in a separate directory from the source
    directory, as \l{glossary-shadow-build} {shadow builds}. This keeps the
    files generated for each \l{glossary-buildandrun-kit}{build and run kit} separate.
    If you only build and run with a single \l{glossary-buildandrun-kit}{kit},
    you can deselect the \uicontrol {Shadow build}
    checkbox.

    To make in-source builds the default option for all projects, select
    \uicontrol Tools > \uicontrol Options > \uicontrol {Build & Run} >
    \uicontrol General, and enter a period (.) in the
    \uicontrol {Default build directory} field.

    \section1 Starting External Processes

    \QC executes external processes to accomplish tasks such as building
    and running applications. To execute the processes, \QC uses shell
    commands that are native to the system. It constructs the commands from
    an executable name and optional command line arguments.

    The executable name is specified in the executable fields: \uicontrol qmake,
    \uicontrol Make, \uicontrol Command, or \uicontrol Executable. It is either derived from the
    project or specified manually. When you specify executables manually, you
    can reference environment variables and \QC variables. However, no
    quoting rules
    apply.

    You can specify command-line arguments in the arguments fields:
    \uicontrol {Additional arguments}, \uicontrol {Command arguments},
    \uicontrol {Make arguments}, or \uicontrol Arguments. You can create shell command lines
    that can contain redirection and other advanced constructs. However, some
    more complex use cases, such as piping test data into the application being
    tested or grouping commands, are not supported because the value of the
    \uicontrol Executable field is always placed first when constructing the command.

    \section2 Using Environment Variables

    You can use any environment variables as values in the fields. For a list
    of variable names, click \uicontrol {Build Environment > Details} in the
    \uicontrol {Build Settings}. Environment variables are referenced using the native
    syntax: $VARNAME or ${VARNAME} on Unix and %VARNAME% on Windows.

    \section2 Using Qt Creator Variables

    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. Select the
    \inlineimage qtcreator-variables-button.png
    (\uicontrol {Variables}) button in a field to select from a list of variables that
    are available in a particular context.

    \section1 Build Steps

    The build system of \QC is built on qmake and make. In \uicontrol{Build Steps} you
    can change the settings for qmake and make. \QC runs the make command using
    the Qt version defined for the current build configuration.

    \image qtcreator-build-steps.png "Build steps"

    To override the shell command that \QC constructs by default, disable or remove
    the build step and add a custom build step that specifies another shell
    command.

    To generate debug symbols also for applications compiled in release mode,
    select the \uicontrol {Generate separate debug info} check box. For more
    information, see \l{Using the CPU Usage Analyzer}.

    \QC is integrated to \l{http://doc.qt.io/QtQuickCompiler/}
    {Qt Quick Compiler} (commercial only) that enables you to compile QML source
    code into the final binary. This
    improves the startup time of the application and eliminates the need to
    deploy QML files together with the application. \QC new project wizards
    create projects that the Qt Quick Compiler can compile, because they are
    set up to use the Qt Resource System. To compile Qt Quick projects, select
    the \uicontrol {Enable Qt Quick Compiler} check box.

    \note For more information about the build steps when using Qbs, see
    \l{Building Applications with Qbs}.

    \section2 Adding Custom Build Steps

    To add custom steps to the build settings, select \uicontrol {Add Build Step >
    Custom Process Step}.

    By default, custom steps are enabled. To disable a custom step, select
    the \inlineimage qtcreator-disable-steps.png
    (\uicontrol Disable) button.

    \image qtcreator-build-steps-custom.png "Custom Process Step"

    \section1 Clean Steps

    You can use the cleaning process to remove intermediate files. This process
    might help you to fix obscure issues during the process of building a
    project.

    \image qtcreator-clean-steps.png "Clean steps"

    You can define the cleaning steps for your builds in the \uicontrol{Clean Steps}:

    \list

        \li To add a clean step using make or a custom process, click
            \uicontrol{Add Clean Step} and select the type of step you want to add.

            By default, custom steps are enabled. To disable a custom step,
            select the \uicontrol Disable button.

        \li To remove a clean step, click \uicontrol{Remove Item}.

        \li To change the order of steps, click
            \inlineimage qtcreator-movestep.png
            (\uicontrol {Move Up} and \uicontrol {Move Down}).
    \endlist

    \note For more information about the cleaning steps when using Qbs, see
    \l{Building Applications with Qbs}.

    \section1 Build Environment

    You can specify the environment you want to use for building in the
    \uicontrol {Build Environment} section. 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 new variables based on your project
    requirements.

    \image qtcreator-build-environment.png "Build Environment"

    \note The changes are stored in the local project specific \c{.pro.user}
    file. 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 qmake, make the changes in the \c{.pro} file.

    \section2 Batch Editing

    To modify environment variable values for build or run environments,
    select \uicontrol {Batch Edit} in the build or run settings and enter environment
    variables in the \uicontrol {Edit Environment} dialog.

    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 \c /opt/bin to the existing PATH:

    \c {PATH=/opt/bin:${PATH}}

    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.

    \section2 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.

*/