Doc: move analyze mode topics to a separate folder

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>

doc/src/analyze/creator-analyze.qdoc

+/****************************************************************************
+**
+** 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
+
+*/
+

doc/src/analyze/creator-valgrind.qdoc

+/****************************************************************************
+**
+** 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
+
+*/

doc/src/analyze/qtquick-profiler.qdoc

+/****************************************************************************
+**
+** 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
+
+*/