feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: move analyze mode topics to a separate folder

Browse Source 
Change-Id: I4fd791c42003c7fcf9b75ff5c7dee01b0115e3aa
Reviewed-on: http://codereview.qt-project.org/5606
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Eike Ziller <eike.ziller@nokia.com>
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
This commit is contained in:
Leena Miettinen
2011-09-27 11:52:15 +02:00
parent 35d81bb367
commit 10d33ae663
3 changed files with 525 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
doc/src/analyze/creator-analyze.qdoc Normal file
View File

@@ -0,0 +1,96 @@
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at info@qt.nokia.com.
**
****************************************************************************/
// **********************************************************************
// 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-troubleshooting-debugging.html
\page creator-analyze-mode.html
\nextpage creator-qml-performance-monitor.html
\title Analyzing Code
The memory available on mobile devices is limited and you should use it
carefully. \QC contains tools that you can use to analyze your code.
The \gui {QML Profiler} allows you to profile your Qt
Quick applications. You can inspect binding evaluations, signal handling,
and painting operations when running QML code. This is useful for
identifying potential bottlenecks, especially in the evaluation of bindings.
In addition, \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. You can run them on a remote
host from Windows. You have to download and install them
separately to use them from \QC.
You can use the code analysis tools in the \gui Analyze mode. To switch to
\gui Analyze mode, select \gui Analyze in the mode selector, or select the
\gui {Analyze} menu and then select a tool. When you are in the
\gui Analyze mode, you can switch
between tools by selecting them in the menu on the toolbar.
\image qtcreator-analyze-menu.png "Analyze mode menu"
By default, the views in the \gui Analyze mode are locked into place in the
workspace. Select \gui {Window > Views > Locked} to unlock the views. Drag
and drop the views into new positions on the screen. Drag view borders to
resize the views. The size and position of views are saved for future
sessions. Select \gui {Window > Views > Reset to Default Layout} to reset
the views to their original sizes and positions.
To run the Valgrind tools on a remote host over SSH, select \gui {Analyze
> Valgrind Analyze Memory (Remote)} or \gui {Valgrind Function Profile
(Remote)}.
To stop the currently running analyzer, select \gui {Analyze
> Stop}.
To select options for the Valgrind tools, select \gui {Tools > Options >
Analyzer}. You can override the general settings for each project in the
\gui {Run Settings} for the project.
The following sections describe how to use the code analysis tools:
\list
\o \l{Profiling QML Applications} describes how to inspect binding
evaluations, signal handling, and painting operations when running
QML code.
\o \l{Detecting Memory Leaks} describes how to use the Valgrind
Memcheck tool to detect problems in memory management.
\o \l{Profiling Function Execution} describes how to use the Valgrind
Callgrind tool to find cache misses in the code.
\o \l{Running Valgrind Tools Remotely} describes how to run the
Valgrind tools on a remote host.
\endlist
*/

246
doc/src/analyze/creator-valgrind.qdoc Normal file
View File

@@ -0,0 +1,246 @@
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at info@qt.nokia.com.
**
****************************************************************************/
// **********************************************************************
// 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-qml-performance-monitor.html
\page creator-analyzer.html
\nextpage creator-cache-profiler.html
\title Detecting Memory Leaks
You can use the Memcheck tool included in the
\l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect
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
\o In the \gui Projects mode, select a release build configuration.
\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
\inlineimage qtcreator-analyzer-stop-button.png "Stop button"
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"
Move the mouse on on a row to view more information about the function.
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
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.
\note Callgrind is supported locally on Linux and Mac OS. You can run it on
a remote host from Windows.
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
\inlineimage qtcreator-analyzer-stop-button.png "Stop button"
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.
\image qtcreator-valgrind-callgrind.png "Profile view"
\section1 Selecting Profiling Options
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
\nextpage creator-deployment.html
\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
\o Select \gui {Analyze > Valgrind Analyze Memory (Remote)} or
\gui {Valgrind Function Profile (Remote)}.
\image qtcreator-valgrind-remote-settings.png "Start Debugger dialog"
\o In the \gui Remote group, specify the connection to the remote host.
\o In the \gui Target group, specify the application to run and analyze
on the remote host.
\endlist
*/

183
doc/src/analyze/qtquick-profiler.qdoc Normal file
View File

@@ -0,0 +1,183 @@
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at info@qt.nokia.com.
**
****************************************************************************/
// **********************************************************************
// 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-analyze-mode.html
\page creator-qml-performance-monitor.html
\nextpage creator-analyzer.html
\title Profiling QML Applications
To monitor the performance of an application in the QML Profiler:
\list 1
\o To be able to profile an application, you must set up QML debugging
for the project. For more information, see
\l{Setting Up QML Debugging}.
\o In the \gui Projects mode, select Qt 4.7.4 in the \gui {Qt version}
field.
\note To profile applications on devices, you must install Qt 4.7.4
or later libraries on them.
\o Select \gui {Analyze > QML Profiler} to profile the current
application.
\image qtcreator-qml-performance-monitor-toolbar.png "QML Profiler toolbar"
\o Select the
\inlineimage qtcreator-analyze-start-button.png "Start button"
button to start the application from the QML Profiler.
\note If data collection does not start automatically, select the
\inlineimage qtcreator-analyzer-button.png "Analyzer button"
button.
\endlist
When you start analyzing an application, the application is launched, and
the QML Profiler immediately begins to collect data. This is indicated by
the time running in the \gui Elapsed field.
Data is collected until you select the
\inlineimage qtcreator-analyzer-stop-button.png "Stop button"
button. Data collection takes time, and therefore, there might be a delay
before the data is displayed.
Do not use application commands to exit the application, because data is
sent to the QML Profiler when you select the \gui Stop button.
The application continues to run for some seconds, after which it is stopped
automatically. If you exit the application, the data is not sent.
Select the \inlineimage qtcreator-analyzer-button.png "Analyzer button"
button to disable the automatic start of the data collection when an
application is launched. Data collection starts when you select the button
again.
\section1 Analyzing Collected Data
The \gui Timeline view displays graphical representations of:
\list
\o Painting operations
\o Compiling the QML sources
\o Creating elements
\o Binding evaluations
\o Signal handling
\o Summary of the recorded period
\endlist
\image qtcreator-qml-performance-monitor.png "QML Profiler"
The outline summarizes the period for which data was collected. Drag the
zoom range or click the outline to move on the outline. You can also move
between events by clicking the \gui Previous and \gui Next buttons.
Click the zoom buttons or drag the zoom handles to zoom in and out.
You can define an event range to view the frame rate of events and to
compare it with the frame rate of similar events. Click on the timeline to
specify the beginning of the event range. Drag the cursor to define the end
of the range. The length of the range indicates the frame rate of the event.
You can drag the timeline below the event range to compare events.
Additional information is displayed on the rows above the outline.
Each row in the timeline describes a type of QML events that were recorded.
Move the cursor on an event on a row to see how long it takes and where
in the source it is being called.
On the \gui Binding row, you can see when a binding is evaluated and how
long the evaluation takes. Move the mouse over the binding for details
about the binding: location in the source code, duration, and source
code.
Click the binding to move the cursor in the code editor to the part of the
code where the binding is called.
The time bar at the top of the \gui Timeline view displays the time in
seconds. To see the time in milliseconds, move the mouse on the time bar.
\section1 Viewing Events
The \gui Events view displays the number of times each binding is called
and the time the calls take. This allows you to examine which events you
need to optimize. A high number of calls might indicate that a binding is
called unnecessarily. Click on a binding to move to it in the source code
in the code editor.
\image qtcreator-analyzer-bindings.png "Events view"
\section1 Viewing Calling and Called Events
The \gui Callees and \gui Callers views show dependencies between events.
They allow you to examine the internal functions of the application.
The \gui Callees view summarizes the QML events that a binding triggers.
This tells you which QML events are affected if you change a binding.
\image qtcreator-qml-performance-monitor-callees.png "Callees view"
The \gui Callers view summarizes the QML events that trigger a binding.
This tells you what caused a change in a binding.
\image qtcreator-qml-performance-monitor-callers.png "Callers view"
Click on a binding to move to it in the source code in the code editor.
\section2 Viewing More Data
The QML JavaScript engine optimizes trivial bindings. The QML Profiler
does not receive information about optimized bindings, and
therefore, it displays the text \gui {<bytecode>} and the message
\gui {Source code not available} in the \gui Callees and \gui {Callers}
views.
To inspect the optimized bindings, turn off the QML optimizer by setting the
environment variable QML_DISABLE_OPTIMIZER to 1. To set the environment
variable for the current project in the project settings:
\list 1
\o Select \gui {Projects > Run}.
\o In \gui {Run Environment}, click \gui Add.
\o Add the QML_DISABLE_OPTIMIZER variable and set its value to 1.
\endlist
*/