diff --git a/doc/src/analyze/creator-analyze.qdoc b/doc/src/analyze/creator-analyze.qdoc new file mode 100644 index 0000000000000000000000000000000000000000..258d7468a23c82f6f262171d269acc154925f931 --- /dev/null +++ b/doc/src/analyze/creator-analyze.qdoc @@ -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 + +*/ + diff --git a/doc/src/analyze/creator-valgrind.qdoc b/doc/src/analyze/creator-valgrind.qdoc new file mode 100644 index 0000000000000000000000000000000000000000..d3b1d78b770d9da5c9c39552120fa48da0c5f409 --- /dev/null +++ b/doc/src/analyze/creator-valgrind.qdoc @@ -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 + +*/ diff --git a/doc/src/analyze/qtquick-profiler.qdoc b/doc/src/analyze/qtquick-profiler.qdoc new file mode 100644 index 0000000000000000000000000000000000000000..b4615bf2c89f0e558be4fed7598169a1df022699 --- /dev/null +++ b/doc/src/analyze/qtquick-profiler.qdoc @@ -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 + +*/