creator-valgrind.qdoc 9.5 KB
Newer Older
1
2
/****************************************************************************
**
hjk's avatar
hjk committed
3
4
** Copyright (c) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
5
**
hjk's avatar
hjk committed
6
** This file is part of Qt Creator
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
**
**
** GNU Free Documentation License
**
** 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.
**
**
****************************************************************************/

// **********************************************************************
// 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
27
    \previouspage creator-valgrind-overview.html
28
29
30
31
32
33
    \page creator-analyzer.html
    \nextpage creator-cache-profiler.html

    \title Detecting Memory Leaks

    You can use the Memcheck tool included in the
34
    Valgrind tool suite to detect
35
36
37
38
39
40
41
42
43
44
45
46
    problems that are related to memory management in applications.

    \note Memcheck is supported locally on Linux and Mac OS. You can run it on
    a remote host from Windows.

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

    To analyze applications:

    \list 1

47
        \o  In the \gui Projects mode, select a debug build configuration.
48
49
50
51
52
53
54
55
56
57
58
59

        \o  Select \gui Analyze to open the \gui Analyze mode.

        \o  Select \gui {Analyze Memory} on the toolbar.

        \o  Select the
            \inlineimage qtcreator-analyze-start-button.png "Start button"
            button to start the application.

        \o  Use the application to analyze it.

        \o  Select the
60
            \inlineimage qtcreator-debug-button-stop.png "Stop button"
61
62
63
64
65
66
67
68
69
70
71
72
73
            button to view the results of the analysis in the
            \gui {Analysis} view.

    \endlist

    While the application is running, Memcheck checks all reads and writes of
    memory and intercepts calls that allocate or free memory or create or
    delete memory blocks. When you stop Memcheck, it displays the results in
    the \gui Analysis view. Click a line to view where a memory leak
    occurred and a stack trace that shows what caused it.

    \image analyzer-issues.png "Analysis view"

74
    Move the mouse on a row to view more information about the function.
75
76
77
78
79
80
81

    For more information about using Memcheck, see
    \l{http://valgrind.org/docs/manual/quick-start.html#quick-start.mcrun}
    {Interpreting Memcheck's Output} in the Valgrind documentation.

    \section1 Selecting Options for Memory Analysis

82
83
84
85
    You can specify analyzer settings either globally for all projects or
    separately for each project in the \l{Specifying Run Settings}{run settings}
    of the project.

86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
    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 \gui {Tools > Options > Analyzer}.
    Define the length of the stack trace in the \gui {Backtrace frame count}
    field.

    \image qtcreator-valgrind-memcheck-options.png "Memory Analysis options"

    Memcheck also reports uses of uninitialised values, most commonly with the
    message \gui {Conditional jump or move depends on uninitialised value(s).}
    To determine the root cause of these errors, the \gui {Track origins of
    uninitialized memory} check box is selected by default. You can deselect it
    to make Memcheck run faster.

    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 ./configure script
    when the system is built.

    You can write your own suppression files if parts of your project contain
    errors you cannot fix and you do not want to be reminded of them. Click
    \gui Add in the \gui {Memory Analysis} dialog to add the suppression files.
    For more information about writing suppression files, see
    \l{http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress}
    {Suppressing Errors} in the Valgrind documentation.

*/


/*!
    \contentspage index.html
    \previouspage creator-analyzer.html
    \page creator-cache-profiler.html
    \nextpage creator-running-valgrind-remotely.html

    \title Profiling Function Execution

    You can use the Callgrind tool included in the
    \l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect
    problems that are related to executing functions.

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

131
132
    \note Callgrind is supported locally on Linux and Mac OS. You can run
    it on a remote Linux machine or device from any development machine.
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

    To analyze applications:

    \list 1

        \o  In the \gui Projects mode, select a release build configuration.

        \o  Select \gui Analyze to open the \gui Analyze mode.

        \o  Select \gui Profile on the toolbar.

        \o  Select the
            \inlineimage qtcreator-analyze-start-button.png "Start button"
            button to start the application.

        \o  Use the application to analyze it.

        \o  Select the
151
            \inlineimage qtcreator-debug-button-stop.png "Stop button"
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
            button to view the results of the analysis in the \gui Profile
            view.

    \endlist

    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.

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

168
169
170
171
    Since the run-time characteristics of debug and release
    \l{glossary-build-config}{build configurations}
    differ significantly, analytical findings for one build configuration may or
    not be relevant for the other. Profiling a debug build
172
173
    often finds a major part of the time being spent in low-level
    code like container implementations, while the same code
174
    does not show up in the profile of a release build of the
175
176
177
178
179
180
181
182
183
    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. Typical
    options for GCC are for instance \c{-g -O2}. It is
    advisable to use such a setup for Callgrind profiling.


184
185
186
187
    \image qtcreator-valgrind-callgrind.png "Profile view"

    \section1 Selecting Profiling Options

188
189
190
191
    You can specify analyzer settings either globally for all projects or
    separately for each project in the \l{Specifying Run Settings}{run settings}
    of the project.

192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
    To specify settings for Valgrind, select \gui {Tools > Options >
    Analyzer}. The \gui {Profiling Options} group contains Callgrind options.

    \image qtcreator-valgrind-callgrind-options.png "Valgrind options"

    In the \gui {Result view: Minimum event cost}
    field, limit the amount of results the profiler gives you to increase
    profiler performance.

    You can collect information about the system call times and the number of
    global bus events of the event type \c Ge that are executed.

    \section2 Enabling Full Cache Simulation

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

    \list

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

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

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

    \endlist

    \section2 Enabling Branch Prediction Simulation

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

    \list

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

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

    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-cache-profiler.html
    \page creator-running-valgrind-remotely.html
242
    \nextpage creator-publish-ovi.html
243
244
245
246
247
248
249
250
251
252
253
254

    \title Running Valgrind Tools Remotely

    \QC integrates Valgrind code analysis tools for detecting memory
    leaks and profiling function execution. These tools are supported locally
    only on Linux and Mac OS, but you can run them on a remote host from
    Windows.

    To run the Valgrind tools on a remote host over SSH:

    \list 1

255
256
        \o  Select \gui {Analyze > Valgrind Memory Analyzer (External)} or
            \gui {Valgrind Function Profiler (External)}.
257

258
            \image qtcreator-valgrind-remote-settings.png "Start Analyzer dialog"
259

260
261
        \o  Specify the application to run and analyze, and the \l{glossary-buildandrun-kit}{kit}
            to use.
262
263
264
265

    \endlist

*/