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

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

/*!
    \page creator-clang-tools.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title Analyze code with Clang-Tidy and Clazy

    \note The Clang static analyzer checks are a part of Clang-Tidy. To use
    the checks, you must create a custom configuration for the Clang tools and
    enable them for Clang-Tidy.

    \section1 Analyze the current file

    By default, Clang tools automatically analyze open files and show the results
    in the code editor and \l {Issues} view.

    \image {qtcreator-clang-diagnostics-in-editor-and-issues.webp}
    {Clang diagnostics shown in the editor and Issues view}
    \caption Clang diagnostics shown in the editor and Issues view.

    To turn off the analysis, go to \preferences > \uicontrol Analyzer >
    \uicontrol {Clang Tools} and clear \uicontrol {Analyze open files}.

    To run Clang-Tidy or Clazy to analyze the currently open file:

    \list
        \li Select
            \inlineimage {icons/debugger_singleinstructionmode.png} {Analyze File}
            (\uicontrol {Analyze File}) on the editor toolbar, and then
            select the tool: \uicontrol {Clang-Tidy} or \uicontrol {Clazy}.
        \li Select \uicontrol Tools > \uicontrol {C++} >
            \uicontrol {Analyze Current File with Clang-Tidy} or
            \uicontrol {Analyze Current File with Clazy}.
    \endlist

    \section1 Analyze an open project

    To run Clang-Tidy or Clazy to analyze an open project:

    \list 1

        \li Select \uicontrol Analyze > \uicontrol {Clang-Tidy} or
            \uicontrol {Clazy}.

        \li Select the files to apply the checks to.

            \image {qtcreator-files-to-analyze.webp} {Files to Analyze dialog}

        \li Select \uicontrol Analyze to start the checks.

    \endlist

    \section1 View diagnostics

    The \uicontrol {Clang-Tidy} or \uicontrol {Clazy} view shows the issues:

    \image {qtcreator-clang-tidy-view.webp} {Clang-Tidy view}
    \caption Diagnostics in the Clang-Tidy view.

    \note If you select \uicontrol Debug in the mode selector to open the
    \uicontrol Debug mode and then select \uicontrol {Clang-Tidy} or
    \uicontrol {Clazy}, you must select the
    \inlineimage {icons/qtcreator-analyze-start-button.png} {Analyze Project}
    (\uicontrol Analyze Project) button to open the \uicontrol {Files to Analyze}
    dialog.

    Double-click an issue to move to the location where the issue appears in
    the code editor.

    If a fixit exists for an issue, you can select the checkbox next to the
    issue to schedule it for fixing. Select the \uicontrol {Select Fixits}
    checkbox to select all fixits. To see the status of an issue, hover the
    mouse pointer over the icon next to the checkbox.

    To see more information about an issue that is marked with the
    \inlineimage {icons/refactormarker.png} {Light bulb icon}
    icon, hover the mouse pointer over the line.

    Select the \inlineimage {icons/settings.png} {Settings}
    button to customize diagnostics for the current project.

    \section2 Filter dianostics

    To filter diagnostics:

    \list 1
        \li Select \inlineimage {icons/filtericon.png} {Filter Diagnostics}
            to open the \uicontrol {Filter Diagnostics} dialog.
            \image {qtcreator-clang-tools-filter-diagnostics.webp} {Filter Diagnostics dialog}
        \li Select the diagnostics to view.
        \li Select \uicontrol OK.
    \endlist

    To view all diagnostics, select \uicontrol {Select All}. To view diagnostics
    that have fixits, select \uicontrol {Select All with Fixits}.

    To hide all diagnostics, select \uicontrol {Clear Selection}.

    To view diagnostics of a particular kind, right-click an entry in
    \uicontrol Diagnostics and select \uicontrol {Filter for This Diagnostic Kind}
    in the context menu. To hide diagnostics of that kind, select
    \uicontrol {Filter out This Diagnostic Kind}.

    \section2 Suppress diagnostics

    To suppress diagnostics, select \uicontrol {Suppress This Diagnostic} or
    \uicontrol {Suppress This Diagnostic Inline} in the context menu.

    To view the suppression list for a project and to remove
    diagnostics from it, select \uicontrol Projects >
    \uicontrol {Project Settings} > \uicontrol {Clang Tools}.

    \section1 Disable checks

    To disable checks of a particular type either globally or for a
    particular project, select \uicontrol {Disable This Check} or
    \uicontrol {Disable These Checks} in the context menu.

    \section1 Load diagnostics from YAML files

    In addition to running the tools to collect diagnostics, you can select
    \inlineimage {icons/open.png} {Load diagnostics from YAML files exported with "-export-fixes"}
    to load diagnostics from \l{https://yaml.org/}{YAML} files that you exported
    using the \c {-export fixes} option.

    \sa {Check code syntax}, {Configure Clang Diagnostics},
    {Analyze}{How to: Analyze}, {Specify Clang tools settings},
    {Set global preferences for Clang tools}, {Analyzers}
*/

/*!
    \page creator-how-to-override-clang-tools-preferences.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-projects-configure

    \title Specify Clang tools settings

    To set Clang-Tidy and Clazy checks to run for the current project:

    \list 1
        \li Go to \uicontrol Projects > \uicontrol {Project Settings} >
            \uicontrol {Clang Tools}.
            \image {qtcreator-clang-tools-settings.webp} {Clang Tools customized settings}
        \li Clear \uicontrol {Use global settings}.
        \li Set preferences for the project.
        \li In \uicontrol {Suppressed diagnostics}, you can view the suppression
            list for a project and to remove diagnostics from it.
    \endlist

    To restore the global settings, select \uicontrol {Restore Global Settings}.
    To view and modify the global settings, select the link in
    \uicontrol {Use global settings}.

    To open the \uicontrol Clang-Tidy view, select \uicontrol {Go to Clang-Tidy}.
    To open the \uicontrol Clazy view, select \uicontrol {Go to Clazy}.

    \sa {Analyze code with Clang-Tidy and Clazy}, {Configure Clang diagnostics},
    {Set global preferences for Clang tools}
*/

/*!
    \page creator-preferences-analyzer-clang-tools.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title Set global preferences for Clang tools

    Detect problems in C, C++, and Objective-C programs with Clang-Tidy
    and Clazy.

    To configure Clang diagnostics globally for Clang tools:

    \list 1

        \li Go to \preferences > \uicontrol Analyzer >
            \uicontrol {Clang Tools}.

            \image {qtcreator-preferences-analyzer-clang-tools.webp} {Clang Tools tab in Analyzer preferences}

        \li In the \uicontrol Clang-Tidy and \uicontrol Clazy-Standalone fields,
            set the paths to the executables to use.

        \li The \uicontrol {Diagnostic configuration} field shows the
            checks to perform. Select the value of the field to open the
            \uicontrol {Diagnostic Configurations} dialog, where you can
            select and edit the checks to perform.

            To perform checks from a Clang-Tidy configuration file instead,
            select \uicontrol {Prefer .clang-tidy file, if present}.

        \li To build the project before running the Clang tools, select
            \uicontrol {Build the project before analysis}. The Clang
            tools do not require that you build the project before analysis, but
            they might display misleading warnings about files missing that are
            generated during the build. For big projects, not building the
            project might save some time.

        \li To disable automatic analysis of open documents, clear
            \uicontrol {Analyze open files}.

        \li In the \uicontrol {Parallel jobs} field, select the number of jobs
            to run in parallel to make the analysis faster on multi-core
            processors.
    \endlist

    \sa {Configure Clang diagnostics}, {Analyze code with Clang-Tidy and Clazy},
    {Specify Clang tools settings}, {Issues}
*/

/*!
    \page creator-how-to-configure-clang-diagnostics.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title Configure Clang diagnostics

    Detect problems in C, C++, and Objective-C programs with Clang-Tidy
    and Clazy.

    To select and edit the Clang checks to perform:

    \list 1

        \li Select \preferences > \uicontrol Analyzer >
            \uicontrol {Clang Tools}.

            \image {qtcreator-preferences-analyzer-clang-tools.webp} {Clang Tools tab in Analyzer preferences}

        \li The \uicontrol {Diagnostic configuration} field shows the
            checks to perform. Select the value of the field to open the
            \uicontrol {Diagnostic Configurations} dialog, where you can
            select and edit the checks to perform.

            \image {qtcreator-clang-tools-diagnostics-configuration.png} {Diagnostic Configurations dialog}

            To perform checks from a Clang-Tidy configuration file instead,
            select \uicontrol {Prefer .clang-tidy file, if present} in the
            \uicontrol {Clang Tools} tab.

        \li Select \uicontrol Copy to copy the selected diagnostics for editing.

            \image {qtcreator-clang-copy-diagnostic-configuration.png} {Copy Diagnostic Configurations dialog}

        \li In the \uicontrol {Diagnostic configuration name} field, give the
            configuration a name, and then select \uicontrol OK.

        \li In the \uicontrol {Clang Warnings} tab, select
            \uicontrol {Use diagnostic flags from the build system}
            to forward diagnostic flags, such as warning flags, from the build
            system to the Clang code model for displaying annotations in the
            code editor.

        \li In the \uicontrol {Clang-Tidy Checks} tab, select
            \uicontrol {Select Checks} to select the checks to perform.
            To filter the checks, enter a string in the
            \uicontrol {Filter by name} field.

            \image {qtcreator-clang-tidy.png} {Clang-Tidy Checks tab in the Diagnostic Configurations dialog}

            For more information about the available checkers, see
            \l{https://clang-analyzer.llvm.org/available_checks.html}
            {Clang Static Analyzer documentation}.

        \li To edit the selected checks as plain text, select
            \uicontrol {Edit Checks as String}.

        \li In the \uicontrol {Clazy Checks} tab, select the level of Clazy
            checks to perform.

            \image {qtcreator-clazy.webp} {Clazy Checks tab in the Diagnostic Configurations dialog}

        \li To edit the selected checks as plain text, select
            \uicontrol {Edit Checks as String}.


        \li In the \uicontrol Filters field, select topics to view
            only checks related to those areas in the \uicontrol Checks field.
            To filter the checks in the selected areas, enter a string in the
            \uicontrol {Filter by name} field.

        \li To view all checks again, select \uicontrol {Reset Topic Filter}.

        \li To view more information about the checks online, select the
            \uicontrol {Web Page} links next to them.

    \endlist

    \section2 Select Clazy check levels

    The Clazy checks are divided into levels from 0 to 3. The checks at level 0
    are very stable and show hardly any false positives, while the checks at
    level 3 are experimental. You can select the checks to perform
    at each level. To include the checks from the lower levels automatically,
    select \uicontrol {Enable lower levels automatically}.

    \section2 Create Clang-Tidy configuration files

    Clang-Tidy reads the configuration for each source file from a .clang-tidy
    file located in the closest parent directory of the source file. If any
    configuration options have a corresponding command-line option, the
    command-line option takes precedence. The effective configuration can be
    inspected using \c {-dump-config}.

    \QC creates the configuration for you based on the checks you select. To
    store the checks in file format, you can create a .clang-tidy file, as
    follows:

    \list 1
        \li Select \uicontrol {Edit Checks as String} and copy the contents of
            the field.
        \li Pipe the output of \c {clang-tidy -dump-config} into a file named
            \c {.clang-tidy}. For example:
            \c {clang-tidy -checks=-*,bugprone-*,cppcoreguidelines-avoid-* -dump-config > .clang-tidy}
        \li Move the .clang-tidy file to the parent directory of the sources.
    \endlist

    To add more checks using \QC later on, copy the checks from your .clang-tidy
    file into the \uicontrol {Edit Checks as String} field, select additional
    checks, and copy-paste the contents of the field to the .clang-tidy file.

    \sa {Analyze code with Clang-Tidy and Clazy}, {Specify Clang tools settings},
    {Set global preferences for Clang tools}
*/
