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

/*!
    \page creator-custom-output-parsers.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-build

    \title Add custom output parsers

    Custom output parsers scan command-line output for error
    and warning patterns that you specify and create entries
    for found patterns in \l Issues.

    To add or change custom output parsers, select \preferences >
    \uicontrol {Build & Run} > \uicontrol {Custom Output Parsers}.

    \image {qtcreator-preferences-build-run-custom-output-parsers.webp} {Custom Output Parsers tab in Build & Run preferences}

    To edit the settings of a custom output parser, select it in the list, and
    then select \uicontrol Edit.

    To use a custom output parser for all build or run configurations by default,
    select \uicontrol {Build default} or \uicontrol {Run default}.

    To remove the selected parsers, select \uicontrol Remove.

    To export the selected parsers into a JSON file, select \uicontrol Export.

    To import one or more parsers from a JSON file, select \uicontrol Import.

    \section1 Set custom parser preferences

    You can capture errors and  warnings separately, according to the settings
    you specify in the \uicontrol Error and \uicontrol Warning tab.

    To create a custom output parser:

    \list 1
        \li Select \preferences > \uicontrol {Build & Run} >
            \uicontrol {Custom Output Parsers} > \uicontrol Add.
            \image {qtcreator-custom-parser-options.png} {Custom Output Parsers tab in Build & Run preferences}

        \li In the \uicontrol {Error message capture pattern} field, specify
            a regular expression to define what is an error. The custom
            parser matches the compile output line by line against the
            regular expression and displays errors in \l Issues. Create
            regular expression groups that contain the file name, line number
            and error message.
        \li In the \uicontrol {Capture Positions} field, map the regular
            expression groups to \uicontrol {File name}, \uicontrol {Line number},
            and \uicontrol Message.
        \li In the \uicontrol {Capture Output Channels} field, specify whether
            messages from standard output, standard error, or both channels
            should be captured.
        \li In the \uicontrol {Test} group, you can test how the message that
            you enter in the \uicontrol {Error message} field is matched when
            using the current settings.
        \li Select \uicontrol OK to add the parser to the list of parsers
            and return to the \uicontrol {Custom Output Parsers} tab.
        \li Double-click the parser name to change it to something more
            descriptive than the default value.
    \endlist

    \sa {Activate custom output parsers}, {Configure projects for building},
    {Configure projects for running}
*/

/*!
    \page creator-how-to-activate-custom-output-parsers.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-build

    \title Activate custom output parsers

    You can activate custom output parsers in the
    \uicontrol {Custom Output Parsers} section of
    \uicontrol {Build Settings} and \uicontrol {Run Settings},
    as well as in the custom compiler settings.

    To activate a custom output parser, go to \uicontrol Projects >
    \uicontrol {Build Settings} or \uicontrol {Run Settings}:

    \list 1
        \li In the \uicontrol {Custom Output Parsers} section, select
            \uicontrol Details.
            \image {qtcreator-custom-parser.png} {Custom Output Parsers}
        \li Select custom parsers to activate them for building or running
            the project.
    \endlist

    Select \uicontrol {Parse standard output during build} to make output
    parsers look for diagnostics on \c stdout in addition to \c stderr.

    \sa {Add custom compilers}, {Add custom output parsers},
    {Configure projects for building}, {Configure projects for running}
*/
