// 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-how-to-memcheck.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title Detect memory leaks with Memcheck

    With the Memcheck tool in \l{Valgrind's Tool Suite}, you can detect
    problems that are related to memory management in applications. Use
    the tool together with the GDB debugger. When a problem is detected, the
    application is interrupted and you can debug it.

    \note You can install and run Memcheck locally on Linux. You can run
    it on a remote host or device from any computer. On Windows,
    you can use the \l{Detecting Memory Leaks with Heob}{Heob} heap observer to
    receive similar results.

    After you download and install Valgrind tools, you can use Memcheck from
    \QC.

    To detect memory leaks in applications:

    \list 1

        \li Go to the \uicontrol Projects mode, and select a debug build
            configuration.

        \li In the mode selector, select \uicontrol Debug > \uicontrol Memcheck.

            \image {qtcreator-valgrind-memcheck.webp} {Memcheck view}

        \li Select \inlineimage {icons/qtcreator-analyze-start-button.png}
            {Start} to start the application.

        \li Use the application to analyze it.

        \li Select \inlineimage {icons/stop_small.png} {Stop} to view the
            results of the analysis in \uicontrol {Memory Issues}.

    \endlist

    \section1 View memory issues

    While the application is running, Memcheck does the following:

    \list
        \li Checks all reads and writes of memory.
        \li Intercepts calls that allocate or free memory or create or
            delete memory blocks.
    \endlist

    You can see the results when you stop Memcheck. \QC divides the issues into
    categories and displays them if they belong to the running application. By
    default, it filters out other issues (such as issues from external libraries).

    Select a line to see the place where a memory leak occurred and a stack trace
    that shows what caused it.

    As an alternative to collecting data, select
    \inlineimage {icons/open.png} {Open} to load an external
    log file in XML format into the \uicontrol Memcheck view.

    Move the mouse on a row to view more information about the function.

    To move between rows, select \inlineimage {icons/prev.png} {Previous}
    or \inlineimage {icons/next.png} {Next}.

    For more information about using Memcheck, see
    \l{Interpreting Memcheck's Output} in the Valgrind documentation.

    \section1 Filter memory issues

    To filter the results, select \inlineimage {icons/filtericon.png} {Filter},
    and then select the types of issues to display in the view:

    \list
        \li Definite and possible memory leaks
        \li Use of uninitialized memory
        \li Invalid calls to \c free()
        \li Size and alignment errors
        \li File descriptor issues
    \endlist

    Select \uicontrol Other to show issues that do not belong to any category.

    Select \uicontrol {External errors} to also show issues from external
    libraries.

    \sa {Analyze}{How to: Analyze}, {Profile function execution},
    {Run Valgrind tools on external applications},
    {Specify Valgrind settings for a project}, {Analyzers}, {Valgrind Callgrind},
    {Valgrind Memcheck}, {Analyzing code}
*/

/*!
    \page creator-preferences-memcheck.html
    \previouspage creator-reference.html

    \ingroup creator-reference-preferences-analyzer

    \title Valgrind Memcheck

    \brief Set preferences for Valgrind Memcheck.

    Set \l{Valgrind's Tool Suite}{Valgrind} preferences either globally for all
    projects or separately for each project in the \l{Specifying Run Settings}
    {run settings} of the project.

    To set global preferences for Valgrind, select \preferences >
    \uicontrol Analyzer. Set Memcheck preferences in
    \uicontrol {Memcheck Memory Analysis Options}.

    \image {qtcreator-valgrind-memcheck-options.png} {Memcheck Memory Analysis Options in the Valgrind tab in Analyzer preferences}

    In \uicontrol {Extra Memcheck arguments}, specify additional arguments
    for launching the executable.

    \section1 Setting Stack Trace Length

    Stack traces can get quite large and confusing, and therefore, reading them
    from the bottom up can help. If the stack trace is not big enough or it is
    too big, select \preferences > \uicontrol Analyzer and define the length of
    the stack trace in the \uicontrol {Backtrace frame count} field.

    \section1 Tracking Origins of Uninitialized Memory

    Memcheck also reports uses of uninitialised values, most commonly with the
    message \uicontrol {Conditional jump or move depends on uninitialised value(s).}
    To determine the root cause of these errors, Memcheck tracks origins of
    uninitialized memory. Clear \uicontrol {Track origins of uninitialized memory}
    to make Memcheck run faster.

    \section1 Viewing a Summary

    Memcheck searches for memory leaks when the client application finishes. To
    view the amount of leaks that occurred, select \uicontrol {Summary Only} in the
    \uicontrol {Check for leaks on finish} field. To also view details of each leak,
    select \uicontrol Full.

    \section1 Showing Reachable and Indirectly Lost Blocks

    \e Reachable blocks are blocks that are pointed at by a pointer or chain
    of pointers and that might have been freed before the application exited.
    \e {Indirectly lost} blocks are considered lost because all the blocks that
    point to them are themselves lost. For example, all the children of a lost
    root node are indirectly lost.

    By default, Memcheck does not report reachable and indirectly lost blocks.
    To have them reported, select \uicontrol {Show reachable and indirectly lost
    blocks}.

    \section1 Suppressing Errors

    Memcheck detects numerous problems in the system libraries, such as the C
    library, which come pre-installed with your OS. As you cannot easily fix
    them, you want to suppress them. Valgrind reads a list of errors to suppress
    at startup. A default suppression file is created by the \c ./configure script
    when the system is built.

    You can write your own suppression files if parts of your project have
    errors you cannot fix and you do not want to be reminded of them. Select
    \uicontrol Add in the \uicontrol {MemCheck Memory Analysis} dialog to add
    the suppression files.

    For more information about writing suppression files, see
    \l{Suppressing Errors} in the Valgrind documentation.

    \sa {Detect memory leaks with Memcheck}, {Profile function execution},
    {Run Valgrind tools on external applications},
    {Specify Valgrind settings for a project}, {Valgrind Callgrind}
*/

/*!
    \page creator-cache-profiler.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title Profile function execution

    With the Callgrind tool in \l{Valgrind's Tool Suite}, you can detect problems
    that are related to executing functions. Load the data files generated by
    Callgrind into the \l{https://kcachegrind.github.io/html/Home.html}
    {KCachegrind} profile data visualization tool to browse the performance
    results.

    After you download and install Valgrind tools and KCachegrind, you can use
    Callgrind and KCachegrind from \QC.

    \note You can install and run Callgrind and KCachegrind locally on Linux.
    You can run Callgrind on a remote Linux machine or device from any
    computer.

    \section1 Build apps for profiling

    Callgrind records the call history of functions that are executed when the
    application is run. It collects the number of instructions that are
    executed, their relationship to source lines, the relationships of the
    caller and callee between functions, and the numbers of such calls. You can
    also use cache simulation or branch prediction to gather information about
    the runtime behavior of an application.

    Since the run-time characteristics of debug and release
    \l{glossary-build-config}{build configurations}
    differ significantly, analytical findings for one build configuration may
    not be relevant for the other. Profiling a debug build
    often finds a major part of the time being spent in low-level
    code, such as container implementations, while the same code
    does not show up in the profile of a release build of the
    same application due to inlining and other optimizations
    typically done there.

    Many recent compilers allow you to build an optimized application
    with debug information present at the same time. For example, typical
    options for GCC are: \c{-g -O2}. It is
    advisable to use such a setup for Callgrind profiling.

    \section1 Collect data

    To analyze applications:

    \list 1

        \li Go to the \uicontrol Projects mode, and select a release build
            configuration.

        \li In the mode selector, select \uicontrol Debug > \uicontrol Callgrind.

            \image {qtcreator-valgrind-callgrind-toolbar.webp} {Callgrind view toolbar}

        \li Select \inlineimage {icons/qtcreator-analyze-start-button.png} {Start}
            to start the application.

        \li Use the application to analyze it.

        \li Select \inlineimage {icons/stop_small.png} {Stop} to view the
            results of the analysis in the \uicontrol Functions view.

    \endlist

    Select \inlineimage {icons/pause-icon.png} {Pause}
    to speed up program execution during profiling by pausing event
    logging. No events are counted while logging is paused.

    Select \inlineimage {icons/reload_gray.png} {Reload}
    to reset all event counters.

    Select \inlineimage {icons/clean_pane_small.png} {Clean}
    to discard all collected data.

    Select \inlineimage {icons/kcachegrind.png} {KCachegrind}
    to view the data in KCachegrind. \QC launches KCachegrind
    and loads the data into it for visualization.

    \section1 View collected data

    The results of the analysis are displayed in the \uicontrol Callgrind views.
    You can detach views and move them around. To revert the changes, select
    \uicontrol Views > \uicontrol {Reset to Default Layout}.

    Select \uicontrol Views to show and hide views and view
    titles. The \uicontrol Visualization view is hidden by
    default. Select \inlineimage {icons/redo.png} {Redo}
    to refresh the data displayed in it when it is shown.

    As an alternative to collecting data, you can select
    \inlineimage {icons/open.png} {Open}
    to load an external log file into the \uicontrol Callgrind views.

    \image {qtcreator-valgrind-callgrind.png} {Callgrind views}

    Enter a string in the \uicontrol Filter field to filter the results.

    Move the cursor on a function in the \uicontrol Functions view for more
    information about it.

    Double-click a function to view information about the calling functions in
    the \uicontrol Callers view and about the called functions in the
    \uicontrol Callees view.

    Select \inlineimage {icons/prev.png} {Previous}
    or \inlineimage {icons/next.png} {Next}
    To move between functions in the \uicontrol Callee view.

    To set the cost format, select \uicontrol $. You can view absolute
    or relative costs, as well as relative costs to parent. Select
    \inlineimage {icons/filtericon.png} {Filter}
    to view only profiling info that originated from the project.

    To properly handle recursive or circular function calls, enable cycle
    detection by selecting \uicontrol O.

    To remove template parameter lists when displaying function names, select
    \uicontrol <>.

    \sa {Detect memory leaks with Memcheck}, {Profile function execution},
    {Run Valgrind tools on external applications},
    {Specify Valgrind settings for a project}, {Valgrind Callgrind},
    {Valgrind Memcheck}
*/

/*!
    \page creator-preferences-callgrind.html
    \previouspage creator-reference.html

    \ingroup creator-reference-preferences-analyzer

    \title Valgrind Callgrind

    \brief Set preferences for Valgrind Callgrind.

    Set \l{Valgrind's Tool Suite}{Valgrind} preferences either globally for all
    projects or separately for each project in the \l{Specifying Run Settings}
    {run settings} of the project.

    To set global preferences for Valgrind, select \preferences >
    \uicontrol Analyzer > \uicontrol Valgrind. Set Callgrind preferences in
    \uicontrol {Callgrind Profiling Options}.

    \image {qtcreator-valgrind-callgrind-options.png} {Callgrind Profiling Options in the Valgrind tab in Analyzer preferences}

    In the \uicontrol {KCachegrind executable} field, enter the path to the
    KCachegrind executable to launch.

    In \uicontrol {Extra Callgrind arguments}, specify additional arguments
    for launching the executable.

    In the \uicontrol {Result view: Minimum event cost} and
    \uicontrol {Visualization: Minimum event cost} fields,
    limit the amount of results the profiler presents and
    visualizes to increase profiler performance.

    To show additional information about events in tooltips, select
    \uicontrol {Show additional information for events in tooltips}.

    To collect information about the system call times, select
    \uicontrol {Collect system call time}. To collect the number of
    global bus events of the event type \c Ge that are executed,
    select \uicontrol {Collect global bus events}.

    \section1 Enabling Full Cache Simulation

    By default, only instruction read accesses (Ir) are counted. To fully
    simulate the cache, select \uicontrol {Enable cache simulation}.
    This enables the following additional event counters:

    \list

        \li Cache misses on instruction reads (I1mr/I2mr)

        \li Data read accesses (Dr) and related cache misses (D1mr/D2mr)

        \li Data write accesses (Dw) and related cache misses (D1mw/D2mw)

    \endlist

    \section1 Enabling Branch Prediction Simulation

    To enable the following additional event counters, select
    \uicontrol {Enable branch prediction simulation}:

    \list

        \li Number of conditional branches executed and related predictor misses
            (Bc/Bcm)

        \li Executed indirect jumps and related misses of the jump address
            predictor (Bi/Bim)

    \endlist

    \sa {Analyzing CPU Usage}, {Detect memory leaks with Memcheck},
    {Detach views}, {Run Valgrind tools on external applications},
    {Specify Valgrind settings for a project},
    {Valgrind Memcheck}
*/

/*!
    \page creator-running-valgrind-remotely.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title Run Valgrind tools on external applications

    With \l{Valgrind's Tool Suite}, you can detect memory leaks and profile
    function execution.

    To run the Valgrind tools to analyze external applications for which
    you do not have a \QC project:

    \list 1

        \li Go to \uicontrol Analyze > \uicontrol {Valgrind Memory Analyzer (External
            Application)} or \uicontrol {Valgrind Function Profiler (External Application)}.

            \image {qtcreator-valgrind-remote-settings.png} {Start Remote Analysis dialog}

        \li Select the application to run and analyze, as well as the
            \l{Managing kits}{kit} to use.

    \endlist

    \sa {Detect memory leaks with Memcheck}, {Profile function execution},
    {Managing kits}, {Specify Valgrind settings for a project}, {Valgrind Callgrind},
    {Valgrind Memcheck}
*/
