// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
    \page creator-build-settings-incredibuild.html
    \previouspage creator-reference.html

    \ingroup creator-reference-build-configurations

    \title IncrediBuild Build Configuration

    \brief Build and clean steps for Incredibuild.

    To specify build settings for the selected \l{Kits}{kit}, go to
    \uicontrol Projects > \uicontrol {Build Settings}.

    You can specify build steps and clean steps for IncrediBuild.

    \section1 IncrediBuild Build Steps

    To use IncrediBuild, select \uicontrol {Add Build Step} >
    \uicontrol {IncrediBuild for Linux} or
    \uicontrol {IncrediBuild for Windows}.

    \image {qtcreator-incredibuild-build-steps-general.png} {IncrediBuild build steps}

    IncrediBuild automatically detects the build step by iterating over the
    build steps you already defined. The initial build step settings will
    be part of your IncrediBuild build step, so your usual build tool will
    still be used, but with the added benefit of IncrediBuild's build
    acceleration and graphical Build Monitor.

    In the \uicontrol {Target and configuration} group, specify the command
    helper and arguments that will be used to construct the build command.

    The build errors and warnings are parsed and displayed in \l Issues.

    Select \uicontrol {Keep original jobs number} to stop
    IncrediBuild from overriding the \c {-j} command-line switch, which
    controls the number of processes that the build tools executed by
    \QC run in parallel. The default value set by IncrediBuild is 200.

    The distribution control settings to specify depend on whether you are using
    Linux or Windows.

    \section2 Distribution Control Settings on Linux

    \image {qtcreator-incredibuild-build-steps-linux.png} {IncrediBuild build steps for Linux}

    You can specify the following settings for Linux builds:

    \list
        \li \uicontrol {Nice value} is a numeric value between -20 and 19
        \li \uicontrol {Force remote} forces \c allow_remote tasks to
            remote Helpers.
        \li \uicontrol {Alternate tasks preference}
    \endlist

    \section2 Distribution Control Settings on Windows

    \image {qtcreator-incredibuild-build-steps-windows.png} {IncrediBuild build steps for Windows}

    You can specify the following settings for Windows builds:

    \table
    \header
        \li Setting
        \li Value
    \row
        \li \uicontrol {Profile.xml}
        \li Defines how Automatic Interception
            Interface handles processes in a distributed job. It is not
            necessary for Visual Studio or Make and Build tools builds, but can
            be used to add configuration options if those builds use
            processes that are not included in those packages. It is
            required to configure distributable processes in Dev Tools builds.
    \row
        \li \uicontrol {Avoid local task execution}
        \li Frees up resources on the
            initiator machine. This might be beneficial for distribution if the
            initiator turns into a bottleneck for the build because of high
            CPU usage.
    \row
        \li \uicontrol {Maximum CPUs to utilize in the build}
        \li Specifies the
            maximum amount of remote cores to use in the build. Overrides the
            corresponding global setting.
    \row
        \li \uicontrol {Newest allowed helper machine OS}

            \uicontrol {Oldest allowed helper machine OS}
        \li Specify the newest and
            oldest operating system installed on a Helper machine to be allowed
            to participate as a Helper in the build.
    \row
        \li \uicontrol {Build title}
        \li Specifies a custom header line which will
            be displayed in the beginning of the build output text. This title
            will also be used for the Build History and Build Monitor displays.
    \row
        \li \uicontrol {Save IncrediBuild monitor file}
        \li Writes a copy of the
            build progress (\c{.ib_mon}) file to the specified location.
            If only a folder name is given, IncrediBuild generates a GUID for
            the file name. A message that has the location of the saved
            \c{.ib_mon} file is added to the end of the build output.
    \row
        \li \uicontrol {Suppress STDOUT}
        \li Does not write anything to the standard output.
    \row
        \li \uicontrol {Output Log file}
        \li Writes build output to a file.
    \row
        \li \uicontrol {Show Commands in output}
        \li Shows the command-line that IncrediBuild uses to build the file.
    \row
        \li \uicontrol {Show Agents in output}
        \li Shows the Agent used to build each file.
    \row
        \li \uicontrol {Show Time in output}
        \li Shows the start and finish time for each file built.
    \row
        \li \uicontrol {Hide IncrediBuild Header in output}
        \li Suppresses the IncrediBuild header in the build output.
    \row
        \li \uicontrol {Internal IncrediBuild logging level}
        \li Overrides the
            internal Incredibuild logging level for this build. Does not affect
            output or any user accessible logging. Used mainly to troubleshoot
            issues with the help of IncrediBuild support.
    \row
        \li \uicontrol {Set an Environment Variable}
        \li Sets or overrides
            environment variables for the context of the build.
    \row
        \li \uicontrol {Stop on errors}
        \li Stops the execution as soon as an error
            is encountered. This is the default behavior in Visual Studio
            builds, but not for Make and Build tools or Dev Tools builds.
    \row
        \li \uicontrol {Additional Arguments}
        \li Arguments that are concatenated to the final build console command
            line.
    \row
        \li \uicontrol {Open Build Monitor}
        \li Opens an IncrediBuild Build Monitor that graphically displays the
            build's progress once the build starts.
    \endtable

    \section1 IncrediBuild Clean Steps

    When building with IncrediBuild, you can add arguments and targets for the
    clean command in \uicontrol {Clean Steps}.

    The build errors and warnings are parsed and displayed in \l Issues.

    \sa {Activate kits for a project}, {Add clean steps},
    {Configure projects for building}, {Configure projects for running},
    {Open projects}, {Configuring projects}, {IncrediBuild}
*/
