/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/

// **********************************************************************
// 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 index.html
    \previouspage creator-running-valgrind-remotely.html
    \page creator-clang-tools.html
    \nextpage creator-heob.html

    \title Using Clang Tools

    \QC integrates the following Clang tools for finding problems in C, C++, and
    Objective-C source code by using static analysis:

    \list

        \li \l{https://clang.llvm.org/extra/clang-tidy/}{Clang-Tidy}, which
            provides diagnostics and fixes for typical programming errors,
            such as style violations or interface misuse.

        \li \l{https://github.com/KDE/clazy/blob/master/README.md}{Clazy}, which
            helps Clang understand Qt semantics. It displays Qt related compiler
            warnings, ranging from unnecessary memory allocation to misuse of
            API and provides refactoring actions for fixing some of the issues.

    \endlist

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

    Clang tools are delivered and installed with \QC, and therefore you do not
    need to set them up separately.

    \section1 Running Clang Tools

    To run the Clang tools to analyze an open project:

    \list 1

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

            \image qtcreator-files-to-analyze.png "Analyzer Configuration dialog"

        \li In the \uicontrol {Diagnostic Configuration} group, select a Clang
            configuration in the list of pre-defined configurations (1). For
            more information about creating a custom configuration, see
            \l {Configuring Clang Tools}.

        \li In the \uicontrol {Files to Analyze} group, select the files to
            apply the checks to.

        \li Select \uicontrol Analyze to start the checks.

    \endlist

    If you select \uicontrol Debug in the mode selector to open the
    \uicontrol Debug mode and then select \uicontrol {Clang-Tidy and Clazy},
    you must select the \inlineimage qtcreator-analyze-start-button.png
    (\uicontrol Start) button to open the \uicontrol {Analyzer Configuration}
    dialog.

    The found issues are displayed in the \uicontrol {Clang-Tidy and Clazy}
    view:

    \image qtcreator-clang-tools.png "Clang-Tidy and Clazy view"

    Select the link in the \uicontrol Location column to move to the location
    where the issue appears in the code editor.

    In the \uicontrol {Fixit Status} column, select issues that you want to
    apply refactoring actions to, and then select \uicontrol {Apply Fixits}.
    The status of the issues is updated in the \uicontrol {Fixit Status} column.

    \section1 Configuring Clang Tools

    To configure Clang diagnostics globally for Clang tools:

    \list

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

            \image qtcreator-clang-tools-options.png "Clang Tools options tab"

        \li To build the project before running the Clang tools, select the
            \uicontrol {Build the project before analysis} check box. The Clang
            tools do not require the project to be built 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 In the \uicontrol {Simultaneous processes} field, select the number
            of processes to run simultaneously to make the analysis faster on
            multi-core processors.

        \li In the \uicontrol {Diagnostic Configuration} group, select
            \uicontrol Manage to create or edit a custom configuration.

        \li Select \uicontrol Copy to create a custom Clang configuration.

            \image qtcreator-diagnostics-configuration.png "Diagnostics Configuration dialog"

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

        \li In the \uicontrol {Clang-Tidy} tab, select the checks to
            perform.

            \image qtcreator-clang-tidy.png "Clang-Tidy tab"

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

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

            \image qtcreator-clazy.png "Clazy tab"

    \endlist

    To suppress diagnostics, select \uicontrol {Suppress This Diagnostic} 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}.

    \section2 Selecting Clazy Check Levels

    The Clazy checks are divided into levels from 0 to 3. Each level adds checks
    to the previous level. The checks at level 0 are very stable and provide
    hardly any false positives, while the checks at level 3 can be considered
    experimental.

    For more information about the checks run at each level, see
    \l{https://github.com/KDE/clazy/blob/master/README.md#list-of-checks}
    {List of Checks} in the Clazy documentation.

*/
