// 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-analyze-mode.html
    \previouspage creator-how-tos.html
    \nextpage creator-configuring-projects.html

    \title Analyzing code

    \quotation
    \l {Analyze}{How to: Analyze}
    \endquotation

    Use integrated code analysis tools to perform static code analysis,
    detect memory leaks, profile CPU and memory usage, check code coverage,
    and visualize trace events.

    \section1 Using code analysis tools

    To use a code analysis tool, select it in the \uicontrol Analyze menu or
    in the pull-down menu of the
    \inlineimage {icons/qtcreator-debug-button.png} {Start Debugging of Startup Project}
    (\uicontrol {Start Debugging of Startup Project}) button.

    QML Profiler, Performance Analyzer, and Chrome Trace Format Visualizer
    open in the \uicontrol Profile mode, and the other tools in the
    \uicontrol Debug mode. In both modes, switch between tools by selecting
    them in the menu on the toolbar.

    \image {qtcreator-performance-analyzer-toolbar.webp} {Performance Analyzer in Profile mode}

    Drag the views to new positions on the screen. The size and position of
    views are saved for future sessions. Select \uicontrol View >
    \uicontrol Views > \uicontrol {Reset to Default Layout} to reset the views
    to their original sizes and positions.

    \section1 Overview of the code analysis tools

    The following table describes code analysis tools you can use in \QC to
    analyze your code. Some tools are built in to \QC, while you can install
    others separately on the computer or run them from a server.

    \table
    \header
        \li Tool
        \li Language
        \li Availability
        \li Description
    \row
        \li \l{View Axivion static code analysis results}{Axivion Suite}
        \li C, C++, C#
        \li Requires Axivion server
        \li Analyze code, architecture, dependencies, metrics, and coding
            guidelines.
    \row
        \li \l{Analyze code with Clang-Tidy and Clazy}{Clang-Tidy and Clazy}
        \li C, C++, Objective-C
        \li Built-in
        \li Find diagnostics of style violations, interface misuse, and
            Qt-specific issues, and apply fixits.
    \row
        \li \l{Chrome Trace Format Visualizer}
        \li Any
        \li Built-in
        \li Explore traces generated by third-party tools in Chrome Trace
            Format.
    \row
        \li \l{Set up code coverage from Coco}{Coco}
        \li C, C++, C#, QML, Tcl
        \li Requires installation
        \li Find untested code, redundant tests, and dead code.
    \row
        \li \l{Detect errors in C++ code with Cppcheck}{Cppcheck}
        \li C, C++
        \li Requires installation
        \li Find undefined behavior and dangerous coding constructs in C and
            C++ code without running the application.
    \row
        \li \l{Heob}
        \li Any
        \li Requires installation (Windows)
        \li Find memory leaks and buffer overruns on Windows.
    \row
        \li \l{Performance Analyzer}
        \li Any
        \li Built-in (Linux)
        \li Analyze the CPU and memory usage of an application on Linux desktop
            and embedded devices.
    \row
        \li \l{Profiling QML applications}{QML Profiler}
        \li QML, JavaScript
        \li Built-in
        \li Find causes for typical performance problems in your applications,
            such as slowness and unresponsiveness.
    \row
        \li \l{JavaScript and QML checks}{Static checks for QML and JavaScript}
        \li QML, JavaScript
        \li Built-in
        \li Find common problems in your code, such as syntax errors, missing
            properties, and type mismatches.
    \row
        \li \l{Specify Valgrind settings for a project}{Valgrind}
        \li Any
        \li Requires installation (Linux, \macos 10.9-11.0, Intel only)
        \li Detect memory leaks, memory errors, and threading issues.
    \endtable

    \section1 Static analysis for C and C++

    \section2 Axivion Suite

    \l{Axivion Suite} is an enterprise-grade software quality suite that tracks
    architectural consistency, enforces team-wide coding guidelines, and
    measures quality trends over successive builds. It supports C, C++, and C#.

    With Axivion Suite, you can:

    \list
        \li Check the source code for potential runtime errors.
        \li Use metrics to generate quantitative information about the
            internal quality of the source code.
        \li Run style checks to achieve compliance with coding guidelines.
        \li Detect both duplicates and similar pieces of code in the source code.
        \li Recognize cyclical dependencies at different levels.
        \li Detect unreachable code.
    \endlist

    Install the Axivion Suite and enable the Axivion plugin in \QC to view the
    analysis results, including violations, metrics, and inline annotations.

    For more information, see:

    \list
        \li \l{Connect to Axivion dashboard servers}
        \li \l{Local analysis with Axivion}
        \li \l{View Axivion static code analysis results}
    \endlist

    \section2 Clang-Tidy and Clazy

    \QC includes built-in support for \l{Clang-Tidy} and
    \l{Clazy project homepage}{Clazy}, which are complementary static analysis
    tools for C, C++, and Objective-C code. By default, diagnostics are shown
    in real time for the open file as you edit. This lets you maintain
    code quality and consistency without waiting for a separate build step.

    Clang-Tidy checks for typical programming errors such as style violations,
    incorrect use of interfaces, and patterns that are likely to be bugs. It
    also offers automatic fixes for many of the issues it detects, including
    modernization of older C++ code.

    Clazy adds Qt-specific checks on top of the Clang diagnostics. These range
    from unnecessary memory allocation to misuse of Qt API. Clazy also provides
    refactoring actions to fix some of the issues it finds.

    For more information, see:

    \list
        \li \l{Analyze code with Clang-Tidy and Clazy}
        \li \l{Configure Clang diagnostics}
        \li \l{Set global preferences for Clang tools}
        \li \l{Specify Clang tools settings}
    \endlist

    \section2 Cppcheck

    \l{Cppcheck} is a lightweight static analysis tool focused on finding
    undefined behavior and dangerous coding constructs in C and C++ code.
    It analyzes the source code without building or running the application.

    Cppcheck looks for a wide range of issues, including out-of-bounds accesses,
    null pointer dereferences, use of uninitialized variables, resource leaks,
    and suspicious integer arithmetic. For the full list of checks, see
    \l{Cppcheck: List of checks}.

    Install Cppcheck separately and enable the Cppcheck plugin in \QC to
    integrate the results. Cppcheck is automatically run on open files and you
    can also run it manually on selected files from \uicontrol Analyze >
    \uicontrol Cppcheck.

    For more information, see \l{Detect errors in C++ code with Cppcheck}.

    \section1 QML and JavaScript

    \section2 Static checks for QML and JavaScript

    With the built-in static analyzer, you can run static checks on the QML and
    JavaScript code in your project to find common problems, similarly to
    using \l{JSLint}.

    The checks catch syntax errors, missing or misspelled properties, type
    mismatches, and other common mistakes without having to run the application.

    For more information, see \l{JavaScript and QML checks}.

    \section2 QML Profiler

    \QC comes with QML Profiler for inspecting binding evaluations and signal
    handling when running QML code. Use it to identify performance bottlenecks
    that are difficult to spot through code inspection alone.

    QML Profiler records events, such as signal handling, binding evaluations,
    and JavaScript execution, and visualizes them in a timeline view. This
    is useful for diagnosing slowness and unresponsiveness.

    For more information, see:

    \list
        \li \l{Profiling QML applications}
        \li \l{Profile QML applications}
    \endlist

    \section1 Memory analysis

    \section2 Valgrind

    Install Memcheck and Callgrind from \l{Valgrind's Tool Suite} and enable
    the Valgrind plugin in \QC to detect memory errors and profile function
    execution on Linux and \macos (10.9-11.0, Intel only). You can run the
    tools on a remote Linux machine or device from any development host.

    Memcheck finds memory management issues such as reads or writes to
    freed memory, use of uninitialized memory, memory leaks, and incorrect use
    of allocation functions. Callgrind records the call history of functions
    and the cache usage statistics.

    You can run the Valgrind tools either \e locally on the development host or
    \e remotely on another host. You can use them to analyze both applications
    for which you set up a project in \QC and applications for which you do not
    have a project.


    To run the Valgrind tools to analyze an application for which you have a
    project, open the project in \QC and select the kit to run the project. The
    kit specifies whether the Valgrind tools are run locally or remotely.

    To set preferences for the Valgrind tools, select \preferences >
    \uicontrol Analyzer > \uicontrol Valgrind. You can override the general
    settings for each project in the \uicontrol {Run Settings} for the project.

    For more information, see:

    \list
        \li \l{Valgrind Memcheck}
        \li \l{Valgrind Callgrind}
        \li \l{Detect memory leaks with Memcheck}
        \li \l{Run Valgrind tools on external applications}
        \li \l{Specify Valgrind settings for a project}
    \endlist

    \section2 Heob

    On Windows, install the Heob heap observer to detect buffer overruns and
    memory leaks.

    Heob raises an access violation on buffer overruns and records stack traces
    of the offending instruction and buffer allocation. You can see the results
    after Heob exits normally.

    For more information, see:

    \list
        \li \l{Heob sources}
        \li \l{Heob}
        \li \l{Detect memory leaks with Heob}
    \endlist

    \section1 Profiling and tracing

    \section2 Performance Analyzer

    On Linux, use Performance Analyzer to analyze the CPU and memory
    usage of an application on Linux desktop and embedded devices.

    Performance Analyzer uses the Perf tool bundled with the Linux kernel to
    take periodic snapshots of the call chain of an application and visualizes
    them in a timeline view or as a flame graph.

    For more information, see \l{Performance Analyzer}.

    \section2 Chrome Trace Format Visualizer

    Use the Chrome Trace Format Visualizer to view Chrome trace events. This
    is especially useful when viewing large trace files that are difficult to
    visualize using the built-in trace-viewer (\c{chrome://tracing}).

    Several tracing tools can generate information about Chrome trace events
    in Chrome Trace Format beyond Chrome-based tools. With the visualizer, you
    can navigate, zoom, and inspect events in the trace.

    For more information, see:

    \list
        \li \l{Chrome Trace Format Visualizer}
        \li \l{KDAB: Full Stack Tracing Part 1}
    \endlist

    \section1 Code coverage

    \section2 Coco

    Install the Coco code coverage toolchain and enable the Coco plugin in \QC
    for C, C++, C#, QML, and Tcl programs. Use it to analyze the way an
    application runs as part of a test suite, for example. Use the results
    to make the tests more efficient and complete.

    You can:

    \list
        \li Find untested code sections.
        \li Find redundant tests which can then be eliminated. Coco can
            identify portions of the source code that are covered by a test. It
            can detect whether a new test covers lines in the source code that
            the existing tests do not cover.
        \li Find dead code by displaying code that is never executed.
        \li Calculate the optimum test execution order so as to maximize
            test coverage for each run. This is particularly useful for manual
            testing.
        \li Analyze two separate versions of an application and compare the
            differences. This makes it possible to see which tests are affected
            by source code modifications and also to get some measure of the
            test coverage of a patch or hot fix.
        \li Measure the execution time of applications and tests.
    \endlist

    For more information, see:

    \list
        \li \l{Set up code coverage from Coco}
        \li \l{View code coverage reports from Coco}
        \li \l{Coco Manual}
    \endlist

    \sa {Activate kits for a project}, {Analyze}{How to: Analyze}, {Analyzers},
    {Enable and disable plugins}
*/
