qtcreator.qdoc

    files selected in the file list. Since the commit page is just another
    editor, you can go back to it by closing the diff view. You can also check
    a diff view from the editor combo box showing the \gui{Opened files}.

    \image qtcreator-vcs-commit.png



    \section2 Using git-specific Menu Entries

    The git sub-menu contains additional entries:

    \table
        \row
            \i  \gui{Stash Snapshot...}
            \i  Allows you to save a snapshot of your current
                work under a name for later reference. For example, if you
                want to try out something and find out later that it does not work,
                you can discard it and return to the state of the snapshot.
        \row
            \i  \gui{Stash}
            \i  Stash local changes prior to executing a \bold{pull}.
        \row
            \i  \gui{Pull}
            \i  Pull changes from the remote repository. If there are locally
                modified files, you are prompted to stash those changes.
                The \bold{git} settings page contains an option to do
                a rebase operation while pulling.

        \row
            \i  \gui{Clean Repository.../Clean Project...}
            \i  Collect all files that are not under version control
                with the exception of patches and project files
                and show them as a checkable list in a dialog
                prompting for deletion. This lets you completely clean a build.

        \row
            \i  \gui{Branches...}
            \i  Displays the branch dialog showing the local branches at the
                top and remote branches at the bottom. To switch to the local
                branch, double-click on it. Double-clicking on a remote
                branch first creates a local branch with the same name that
                tracks the remote branch, and then switches to it.

                \image qtcreator-vcs-gitbranch.png


        \row
            \i  \gui{Stashes...}
            \i  Displays a dialog showing the stashes created by
                \gui{Stash Snapshot...} with options to restore,
                display or delete them.
    \endtable
*/


/*!
    \contentspage index.html
    \previouspage creator-editor-refactoring.html
    \page creator-editor-locator.html
    \nextpage creator-editor-codepasting.html

    \title Searching With the Locator

    The locator provides one of the easiest ways in Qt Creator to browse
    through projects, files, classes, methods, documentation and file systems.
    You can find the locator in the bottom left of the Qt Creator window.

    To activate the locator, press \key Ctrl+K (\key Cmd+K on Mac OS
    X) or select \gui Tools > \gui Locate....

    \image qtcreator-locator.png

    To edit the currently open project's main.cpp file using the locator:
    \list 1
        \o Activate the locator by pressing \key Ctrl+K.
        \o Enter \tt{main.cpp}.

           \image qtcreator-locator-open.png
        \o Press \key Return.

           The main.cpp file opens in the editor.
    \endlist

    It is also possible to enter only a part of a search string.
    As you type, the locator shows the occurrences of that string regardless
    of where in the name of an component it appears.

    To narrow down the search results, you can use the following wildcard
    characters:
    \list
        \o To match any number of any or no characters, enter \bold{*}.
        \o To match a single instance of any character, enter \bold{?}.
    \endlist

    \section1 Using the Locator Filters

    The \gui Locator allows you to browse not only files, but any items
    defined by \bold{locator filters}. By default, the locator contains
    filters which locate:
    \list
        \o  Any open document
        \o  Files anywhere on your file system
        \o  Files belonging to your project, such as source, header resource,
            and .ui files
        \o  Class and method definitions in your project or anywhere referenced
            from your project
        \o  Help topics, including Qt documentation
        \o  Specific line in the document displayed in your editor
    \endlist

    To use a specific locator filter, type the assigned prefix followed by
    \key Space. The prefix is usually a single character.

    For example, to locate symbols matching
    \l{http://doc.trolltech.com/qdatastream.html}{QDataStream:}
    \list 1
        \o Activate the locator.
        \o Enter \tt{\bold{: QDataStream}} (: (colon) followed by a
           \key Space and the symbol name (QDataStream)).

           The locator lists the results.

           \image qtcreator-navigate-popup.png
    \endlist

    By default the following filters are enabled and you do not need to use
    their prefixes explicitly:
    \list
        \o Going to a line in the current file (l).
        \o Going to an open file (o).
        \o Going to a file in any open project (a).
    \endlist

    \section2 Using the Default Locator Filters

    The following locator filters are available by default:

    \table
        \header
            \o  Function
            \o  Enter in locator
            \o  Example
        \row
            \o  Go to a line in the current file.
            \o  \tt{\bold{l \e{Line number}}}
            \o  \image qtcreator-locator-line.png
        \row
            \o  Go to a symbol definition.
            \o  \tt{\bold{: \e{Symbol name}}}
            \o  \image qtcreator-locator-symbols.png
        \row
            \o  Go to a help topic.
            \o  \tt{\bold{? \e{Help topic}}}
            \o  \image qtcreator-locator-help.png
        \row
            \o  Go to an open file.
            \o  \tt{\bold{o \e{File name}}}
            \o  \image qtcreator-locator-opendocs.png
        \row
            \o  Go to a file in the file system (browse the file system).
            \o  \tt{\bold{f \e{File name}}}
            \o  \image qtcreator-locator-filesystem.png
        \row
            \o  Go to a file in any project currently open.
            \o  \tt{\bold{a \e{File name}}}
            \o  \image qtcreator-locator-files.png
        \row
            \o  Go to a file in the current project.
            \o  \tt{\bold{p \e{File name}}}
            \o  \image qtcreator-locator-current-project.png
        \row
            \o  Go to a class definition.
            \o  \tt{\bold{c \e{Class name}}}
            \o  \image qtcreator-locator-classes.png
        \row
            \o  Go to a method definition.
            \o  \tt{\bold{m \e{Method name}}}
            \o  \image qtcreator-locator-methods.png
    \endtable

    \section2 Creating Locator Filters

    To quickly access files not directly mentioned in your project, you can
    create your own locator filters. That way you can locate files in a
    directory structure you have defined.

    To create a locator filter:
    \list 1
        \o In the locator, click \inlineimage qtcreator-locator-magnify.png
           and select \gui Configure....

           \image qtcreator-locator-customize.png

        \o In the \gui{Options...} window click \gui Add.
        \o In the \gui{Filters} dialog:
        \list
            \o Name your filter.
            \o Select at least one directory. The locator searches directories
               recursively.
            \o Define the file pattern as a comma separated list. For example,
               to search all .h and .cpp files, enter \bold{*.h,*.cpp}
            \o Specify the prefix string.

               To show only results matching this filter, select
               \gui{Limit to prefix}.

               \image qtcreator-navigate-customfilter.png
        \endlist
        \o Click OK.
    \endlist

    \section3 Configuring the Locator Cache

    The locator searches the files matching your file pattern in the
    directories you have selected and caches that information. The cache for
    all default filters is updated as you write your code. The filters you have
    created Qt Creator by default updates once an hour.

    To update the cached information manually, click
    \inlineimage qtcreator-locator-magnify.png
    and select \gui Refresh.

    To set a new cache update time:
    \list 1
        \o Select \gui Tools > \gui Options... > \gui Locator.
        \o In \gui{Refresh interval} define new time in minutes.
    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-developing-symbian.html
    \page creator-project-managing-sessions.html
    \nextpage creator-building-running.html

    \title Managing Sessions

    In Qt Creator, a session is a collection of:

    \list
        \o Open projects with their dependencies
        \o Open editors
        \o Breakpoints and watches
        \o Bookmarks
    \endlist

    When you launch Qt Creator, a list of existing sessions is displayed on the
    \gui{Welcome screen}.

    \image qtcreator-welcome-session.png

    To switch between sessions, select the session from sessions listed in
    \gui File > \gui Session. If you do not create or select a session,
    Qt Creator always uses the default session.

    To create a new session or remove existing sessions, select \gui File >
    \gui Sessions > \gui{Session Manager}.

    \image qtcreator-session-manager.png
*/


/*!
    \contentspage index.html
    \previouspage creator-maemo-emulator.html
    \page creator-debugging.html
    \nextpage creator-debugging-cpp.html

    \title Debugging

    You can use the Qt Creator \gui Debug mode to inspect the state of your
    Qt and Qt Quick projects while debugging.

    Qt Creator does not include a debugger. It provides a debugger plugin that acts
    as an interface between the Qt Creator core and external native debuggers
    such as the GNU Symbolic Debugger (gdb), the Microsoft Console Debugger (CDB),
    and an internal Java Script debugger. You can use the native debuggers to
    debug the C++ language.

    \image qtcreator-debugger-views.png "Native debugger views"

    Qt Creator includes a QML inspector plugin that you can use to debug QML.

    \image qmldesigner-inspector.png "QML inspector views"

    When you start debugging, the appropriate tool is automatically selected depending
    on the type of the project. If you only develop one kind of projects, you can turn
    off this automation in \gui {Tools > Options... > Debugger > General}. Deselect the
    \gui {Change debugger language automatically} check box.

    The choice of language also determines the contents of the \gui Debug menu.
    The \gui {Start Debugging > Start Debugging} command starts debugging by using the
    tool appropriate for the project type. The availability of the other commands depends
    on whether \gui C++ or \gui QML is selected in \gui {Debug > Language}.

    You can create Qt Quick projects that contain C++ plugins or Qt projects that contain
    QML content. While debugging such projects, you can switch between the native
    debuggers and the QML inspector during debugging.

    To switch between debugged languages, select \gui {Debug > Language > C++} or
    \gui QML. You can also press \key {Ctrl+L, 1} to switch to the native debugger and
    \key {Ctrl+L, 2} to switch to the QML inspector.

*/

/*!
    \contentspage index.html
    \previouspage creator-debugging-helpers.html
    \page creator-debugging-qml.html
    \nextpage creator-qml-inspector.html

    \title Debugging Qt Quick Applications

    In the \gui Debug mode you can use the QML inspector plugin to:

    \list

        \o View the status of the application when it is executed.

        \o View debug output.

        \o Write JavaScript expressions and evaluate them.

        \o Modify the values of properties.

        \o Watch the values of expressions.


    \note You can press \key {Ctr+Alt+R} or select \gui {Tools > Qt Quick > Preview}
    to view QML files that do not belong to projects in the QML viewer. However,
    you can only debug QML files that belong to open projects, because the QML
    inspector plugin needs information about the project.

    \endlist

    \section1 Modes of Operation

    When a Qt Quick project is active and you select \gui {Debug > Start Debugging >
    Start Debugging} the application is started in the QML viewer and inspected by
    the QML inspector.

    If the Qt Quick project includes C++ plugins, select
    \gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.
    The QML runtime is started, debugged with the native debugger, and attached to
    the QML viewer.

    \note This command is available only if \gui QML is selected in
    \gui {Debug > Language (QML)}.

    To debug a Qt project that contains QML content, select
    \gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.
    The application is started under the control of the native debugger, attached
    to the QML viewer, and inspected by the QML inspector.

    You must use the native debugger to set breakpoints to C++ code and to examine
    the state of the interrupted Qt application. When a C++ program is interrupted,
    for example when a breakpoint is hit, you cannot use the QML inspector.

*/


/*!
    \contentspage index.html
    \previouspage creator-debugging-qml.html
    \page creator-qml-inspector.html
    \nextpage creator-version-control.html

    \title Using the QML Inspector

    In \gui Debug mode, you can use several views to interact with the
    application you are debugging. Frequently used views are shown by
    default and rarely used ones are hidden. To change the default settings,
    select \gui Debug > \gui Views, and then select views to display
    or hide. You can also lock views. The position of views is saved for future
    sessions.

    \image qmldesigner-inspector.png "QML inspector views"

    \section1 Starting the QML Inspector

    To start an active application under the control of the QML inspector, select
    \gui {Debug > Start Debugging > Start Debugging}, or press \key{F5}.

    The application is run in the QML viewer. It behaves and performs as usual.
    You can view the status of the application when it is executed and the debug
    output in the \gui {Application Output} view.

    \image qmldesigner-application-output.png "Application Output view"

    \section1 Starting Simultaneous QML and C++ Debugging

    To debug a Qt Quick project that includes C++ plugins, select
    \gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.

    \note This command is available only if \gui QML is selected in
    \gui {Debug > Language (QML)}.

    \image qmldesigner-debugging-simultaneous.png "Start Simultaneous QML and C++ Debugging view"

    Usually, the settings for the QML viewer are specified automatically and you do
    not need to change them:

    \list

        \o \gui {Debugging address} is the IP address to access the QML viewer.

        \o \gui {Debugging port} is the port to access the QML viewer. You can use any
        free port in the registered port range.

        \o \gui {Viewer path} is the path to QML viewer executable.

        \o \gui {Viewer arguments} sets arguments for running the QML viewer.
        The \c{-I <directory>} argument searches for C++ or QML plugins from
        the project folder. For a list of available arguments, enter \c {qml --help}
        on the command line.

    \endlist

    The QML runtime is started, debugged with the native debugger, and attached to
    the QML viewer.

    \section1 Viewing and Modifying Values of Properties

    The \gui {Properties and Watchers} view lists the JavaScript expressions
    in the project and their properties and values. The properties are grouped
    by type, but you can also view them in one long list.
    Right-click the list of properties to open a context-menu and then click
    \gui {Group by Item Type} to change the way in which the properties are
    sorted.

    If an item does not have an ID, you cannot change the values of its
    properties. The item type is enclosed in angle brackets and the value
    is grayed.

    Double-click an item to move to the place in code where it is declared.

    You can change the values of properties and see the results in the QML viewer.

    If the QML inspector cannot retrieve the value for an item or a property for
    inspection, the item or property is grayed in the view. Right-click the item list
    to open a context menu, and then click \gui {Show Uninspectable Items} to hide
    or show the items that cannot be inspected.

    \section1 Watching Expressions

    In the \gui {Properties and Watchers} view, you can specify that an expression is
    watched. Right-click a property and then click \gui {Watch Expression}.
    The \gui Name and \gui Value of the expression are displayed at the bottom
    of the view.

    \image qmldesigner-inspector-watchers.png "Watched expressions"

    You can add JavaScript expressions to object instances to evaluate them.
    Right-click the list of items and select \gui {Add Watch Expression}. Enter
    the expression to evaluate and click \gui OK.

    \image qmldesigner-inspector-add-watch.png "Add Watch Expression dialog"

    To stop watching a expression, right-click it and select \gui {Stop Watching}.

    The QML inspector cannot show the values for some items, such as composite objects
    or complicated item that you cannot change. These items cannot be watched.
    To show them, right-click the properties list, and then select
    \gui {Show Unwatchable Properties}.

    \section1 Executing JavaScript

    In the \gui {Script Console} view, you can write JavaScript expressions, see
    how they are executed, and evaluate them during runtime.

    You can also test the C++ code without rebuilding the whole application.

    \section1 Viewing Connections to the QML Viewer

    The \gui Output view displays the status of the connection between the QML
    inspector and the QML viewer.

    You specify the connection in the \gui {Run Settings} in the \gui Projects mode.
    For more information, see \l{Specifying Run Settings for Qt Quick Projects}.

    If the connection does not work, check the values of the \gui {Debugging address}
    and \gui {Debugging port} fields. Check that the default port number is not reserved
    by another application or another instance of the QML viewer that was not shut
    down properly. You can specify any free port number in the registered port range
    (1024-49151).

*/


/*!
    \contentspage index.html
    \previouspage creator-debugging.html
    \page creator-debugging-cpp.html
    \nextpage creator-debugging-example.html

    \title Debugging Qt Applications

    In the \gui Debug mode you can interact with the debugger in several ways, including
    the following:

    \list
        \o Go through a program line-by-line or instruction-by-instruction.
        \o Interrupt running programs.
        \o Set breakpoints.
        \o Examine the contents of the call stack.
        \o Examine and modify registers and memory contents of
           the debugged program.
        \o Examine and modify registers and memory contents of
           local and global variables.
        \o Examine the list of loaded shared libraries.
        \o Create snapshots of the current state of the debugged program
           and re-examine them later.
    \endlist

    Qt Creator displays the raw information provided by the native debuggers
    in a clear and concise manner with the goal to simplify the debugging process
    as much as possible without losing the power of the native debuggers.

    In addition to the generic IDE functionality provided by stack view, views for
    locals and watchers, registers, and so on, Qt Creator includes
    features to make debugging Qt-based applications easy. The debugger
    plugin understands the internal layout of several Qt classes, for
    example, QString, the Qt containers, and most importantly QObject
    (and classes derived from it), as well as most containers of the C++
    Standard Library and some gcc and Symbian extensions. This
    deeper understanding is used to present objects of such classes in
    a useful way.

    For an example of how to debug applications in the \gui Debug mode, see
    \l{Debugging the Example Application}.

    For more information about the functions available in the \gui Debug mode,
    see \l{Interacting with the Debugger}.

    If you install Qt Creator as part of a Qt SDK, the GNU Symbolic Debugger
    is installed automatically and you should be ready to start debugging after
    you create a new
    project. If you want a special setup, such as using debugging tools for Windows,
    see \l {Setting Up Debugger}.

    \section1 Modes of Operation

    The debugger plugin runs in different operating modes depending on where and
    how the process is started and run. Some of the modes are only available for
    a particular operating system or platform.

    You can launch the debugger in the following modes:

    \list

       \o \bold Plain to debug locally started applications, such as a
        Qt based GUI application.

       \o \bold Terminal to debug locally started processes that need a
       console, typically without a GUI.

       \o \bold Attach to debug local processes started outside Qt Creator.

       \o \bold Remote to debug a process running on a different machine.

       \o \bold Core to debug crashed processes on Unix.

       \o \bold Post-mortem to debug crashed processes on Windows.

       \o \bold TRK to debug processes running on a Symbian device.

    \endlist

    When you click the \gui {Start Debugging} button, the debugger is launched
    in the appropriate operating mode (plain, terminal, or TRK), based on the
    build and run settings for the active project. Select \gui Debug menu options
    to launch the debugger in the other modes.

    \section2 Plain Mode

    To launch the debugger in the plain mode, click the \gui {Start Debugging}
    button for the active project, or choose
    \gui {Debug > Start Debugging > Start and Debug External Application...}
    and specify an executable.

    \section2 Terminal Mode

    To launch the debugger in the terminal mode, select \gui {Projects > Run Settings}
    and select the \gui {Run in terminal} check box. Then click the
    \gui {Start Debugging} button for the active project.

    \section2 Attach Mode

    To launch the debugger in the attach mode, select
    \gui {Debug > Start Debugging >  Attach to Running External Application...},
    and then select a process by its name or process ID to attach to.

    \section2 Remote Mode

    The remote mode uses a \e{gdbserver} daemon that runs on the remote machine.

    To launch the debugger in the remote mode, select
    \gui {Debug > Start Debugging > Start and Attach to Remote Application...}.

    \section2 Core Mode

    The core mode is available only in Unix. It debugs crashed processes using
    the \e {core} files (crash dumps) that are generated if the setting
    is enabled in the shell.

    To enable the dumping of core files, enter the following command in the
    shell from which the application will be launched:

    \code
    ulimit -c unlimited
    \endcode

    To launch the debugger in the core mode, select
    \gui{Debug > Start Debugging >  Attach to Core...}.

    \section2 Post-Mortem Mode

    The post-mortem mode is available only on Windows, if you have installed
    the debugging tools for Windows.

    The Qt Creator installation program asks you whether you want to
    register Qt Creator as a post-mortem debugger. To change the setting, select
    \gui{Tools > Options...  > Debugger > Common > Use Creator for post-mortem debugging}.

    You can launch the debugger in the post-mortem mode if an application crashes
    on Windows. Click the \gui {Debug in Qt Creator} button in the error message
    that is displayed by the Windows operating system.

    \section2 TRK Mode

    The TRK mode is a special mode available only for Symbian. It
    debugs processes running on a Symbian
    device using the App TRK application that runs on the device.

    To launch the debugger in the TRK mode, open the project, select Symbian as the
    target, and click the \gui {Start Debugging} button.

    For more information on setting up Symbian projects, see
    \l{Setting Up Development Environment for Symbian}.


*/

/*!
    \contentspage index.html
    \previouspage creator-debug-mode.html
    \page creator-debugger-engines.html
    \nextpage creator-debugging-helpers.html

    \title Setting Up Debugger

    Typically, the interaction between Qt Creator and the native debugger is set
    up automatically and you do not need to do anything. However, you might have an
    unsupported gdb version installed, your Linux environment might not have gdb
    installed at all, or you might want to use the debugging tools for Windows.

    \note To use the debugging tools for Windows, you must install them and add the
    Symbol Server provided by Microsoft to the symbol search path of the debugger.
    For more information, see \l{Setting the Symbol Server in Windows}.

    This section explains the
    options you have for debugging C++ code and provides installation notes for the
    supported native debuggers.

    \section1 Supported Native Debugger Versions

    The debugger plugin supports different builds of the gdb debugger, both
    with and without the ability to use Python scripting. The Python enabled
    versions are preferred, but they are not available on Mac and on older
    versions of Linux.
    On Windows, Symbian, and Maemo, only the Python version is supported.

    The non-Python versions use the compiled version of the debugging helpers,
    that you must enable separately. For more information, see
    \l{Debugging Helper Library with C++}.

    The Python version uses a script version of the debugging helpers
    that does not need any special setup.

    The CDB native debugger has similar funtionality to the non-Python gdb debugger
    engine. Specifically, it also uses compiled C++ code for the debugging
    helper library.

    The following table summarizes the support for debugging C++ code:

    \table
        \header
            \o Platform
            \o Compiler
            \o Native Debugger
            \o Python
            \o Debugger Modes
        \row
            \o Linux
            \o gcc
            \o gdb
            \o Optional
            \o Term, Plain, Attach (with Python, only), Remote
        \row
            \o Unix
            \o gcc
            \o gdb
            \o Yes
            \o Term, Plain, Attach, Remote
        \row
            \o Mac OS
            \o gcc
            \o gdb
            \o No
            \o Term, Plain, Attach
        \row
            \o Windows/MinGW
            \o gcc
            \o gdb
            \o No
            \o Term, Plain, Attach, Remote
        \row
            \o Windows/MSVC
            \o Microsoft Visual C++ Compiler
            \o Debugging Tools for Windows/CDB
            \o Not applicable
            \o Term, Plain, Attach, Post-Mortem
        \row
            \o Symbian
            \o gcc
            \o gdb
            \o Yes
            \o TRK
        \row
            \o Maemo
            \o gcc
            \o gdb
            \o Yes
            \o Remote
    \endtable

    \omit

    \section2 Gdb Adapter Modes

    [Advanced Topic]

    The gdb native debugger used internally by the debugger plugin runs in
    different adapter modes to cope with the variety
    of supported platforms and environments. All gdb adapters inherit from
    AbstractGdbAdapter:

    \list

       \o PlainGdbAdapter debugs locally started GUI processes.
       It is physically split into parts that are relevant only when Python is
       available, parts relevant only when Python is not available, and mixed code.

       \o TermGdbAdapter debugs locally started processes that need a
       console.

       \o AttachGdbAdapter debugs local processes started outside Qt Creator.

       \o CoreGdbAdapter debugs core files generated from crashes.

       \o RemoteGdbAdapter interacts with the gdbserver running on Linux.

       \o TrkGdbAdapter interacts with Symbian devices. The gdb protocol and
       the gdb serial protocol are used between gdb and the adapter. The TRK
       protocol is used between the adapter and AppTRK running on the device.

     \endlist

     \endomit

    \section1 Installing Native Debuggers

    There are various reasons why the debugger plugin may fail to automatically
    pick up a suitable native debugger. The native debugger might be missing
    (which is usually the case for the CDB debugger on Windows which always
    needs to be installed manually by the user) or the installed version is not
    supported.
    Check the table below for the supported versions and other important
    information about installing native debuggers.

    \table
        \header
            \o Native Debugger
            \o Notes
        \row
            \o Gdb
            \o On Linux, install version 6.8, 7.0.1 (version 7.0 is not supported),
            7.1, or later. On Mac OS X, install Apple gdb version 6.3.50-20050815
            (build 1344) or later.

        \row
            \o Debugging tools for Windows
            \o Using this engine requires you to install the
               \e{Debugging tools for Windows}
               \l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}{32-bit}
               or
               \l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}{64-bit}
               package (Version 6.11.1.404 for the 32-bit or the 64-bit version of Qt Creator, respectively),
               which is freely available for download from the
               \l{http://msdn.microsoft.com/en-us/default.aspx}
               {Microsoft Developer Network}.

               \note Visual Studio does not include the Debugging tools needed,
               and therefore, you must install them separately.

               The pre-built \e{Qt SDK for Windows} makes use
               of the library if it is present on the system. When manually building Qt
               Creator using the Microsoft Visual C++ Compiler, the build process checks
               for the required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}.

               It is highly recommended that you add the Symbol Server provided by Microsoft to the symbol
               search path of the debugger. The Symbol Server provides you
               with debugging informaton for the operating system libraries for debugging
               Windows applications. For more information, see
               \l{Setting the Symbol Server in Windows}.

       \row
           \o Debugging tools for Mac OS X
           \o The Qt binary distribution contains both debug and release
              variants of the libraries. But you have to explicitly tell the
              runtime linker that you want to use the debug libraries even if
              your application is compiled as debug as release is the default
              library.

              If you use a qmake based project in Qt Creator,  you can set a
              flag in your run configuration, in \gui Projects mode. In the run
              configuration, select \gui{Use debug version of frameworks}.

              For more detailed information about debugging on the Mac, see:
              \l http://developer.apple.com/mac/library/technotes/tn2004/tn2124.html

        \note The Mac OS X Snow Leopard (10.6) has a bug, that can be worked
              around as described in the link provided below:
              \l http://bugreports.qt.nokia.com/browse/QTBUG-4962.

    \endtable    

    \section1 Setting the Symbol Server in Windows

    To obtain debugging information for the operating system libraries for
    debugging Windows applications, add the Symbol Server provided
    by Microsoft to the symbol search path of the debugger:
    \list 1
        \o  Select \gui Tools > \gui{Options...} > \gui Debugger > \gui Cdb.
        \o  In the \gui {Symbol paths} field, open the \gui{Insert...} menu
            and select \gui{Symbol Server...}.
        \o  Select a directory where you want to store the cached information
            and click \gui OK.

            Use a subfolder in a temporary directory, such as
            \c {C:\temp\symbolcache}.
    \endlist

    \note Populating the cache might take a long time on a slow network
    connection.


    \omit In v2.1 and later:

    \note The first time you start debugging by using the
    Debugging tools for Windows, Qt Creator prompts you to add the Symbol
    Server.

    \endomit
*/

/*!
    \contentspage index.html
    \previouspage creator-debugging-example.html
    \page creator-debug-mode.html
    \nextpage creator-debugger-engines.html

    \title Interacting with the Debugger

    In \gui Debug mode, you can use several views to interact with the
    program you are debugging. Frequently used views are shown by
    default and rarely used ones are hidden. To change the default settings,
    select \gui Debug > \gui Views, and then select views to display
    or hide. You can also lock views. The position of views is saved for future
    sessions.

    \image qtcreator-debugger-views.png "Debug mode views"


    \section1 Starting the Debugger

    To start a program under the debugger's control, select \gui{Debug} >
    \gui{Start Debugging} > \gui{Start Debugging}, or press \key{F5}.
    Qt Creator checks whether the compiled program is up-to-date, rebuilding
    it if necessary. The debugger then takes over and starts the program.

    \note Starting a program in the debugger can take a considerable amount of
    time, typically in the range of several seconds to minutes if complex
    features (like QtWebKit) are used.

    Once the program starts running, it behaves and performs as usual.
    You can interrupt a running program by selecting \gui{Debug} >
    \gui {Interrupt}. The program is automatically interrupted as soon as a
    breakpoint is hit.

    Once the program stops, Qt Creator:

    \list
        \o Retrieves data representing the call stack at the program's current
           position.
        \o Retrieves the contents of local variables.
        \o Examines \gui Watchers.
        \o Updates the \gui Registers, \gui Modules, and \gui Disassembler
           views.
    \endlist


    You can use the \gui Debug mode views to examine the data in more detail.

    You can use the following keyboard shortcuts:

    \list

       \o To finish debugging, press \key{Shift+F5}.
       \o  To execute a line of code as a whole, press \key{F10}.
       \o  To step into a function or a sub-function, press \key{F11}.
       \o  To continue running the program, press \key{F5}.

    \endlist

    It is also possible to continue executing the program until the current
    function completes or jump to an arbitrary position in the current function.


    \section1 Setting Breakpoints

    A breakpoint represents a position or sets of positions in the code that,
    when executed, interrupts the program being debugged and passes the control
    to you. You can then examine the state of the interrupted program, or
    continue execution either line-by-line or continuously.

    Qt Creator shows breakpoints in the \gui{Breakpoints} view which is enabled
    by default. The \gui{Breakpoints} view is also accessible when the debugger
    and the program being debugged is not running.

    \image qtcreator-debug-breakpoints.png "Breakpoints view"

    Typically, breakpoints are associated with a source code file and line, or
    the start of a function -- both are allowed in Qt Creator.

    The interruption of a program by a breakpoint can be restricted with
    certain conditions.

    To set a breakpoint:

    \list
       \o At a particular line you want the program to stop, click the
          left margin or press \key F9 (\key F8 for Mac OS X).
       \o At a function that you want the program to interrupt, enter the
          function's name in \gui{Set Breakpoint at Function...} located in the
          context menu of the \gui{Breakpoints} view.
    \endlist

    \note You can remove a breakpoint:
    \list
        \o By clicking the breakpoint marker in the text editor.
        \o By selecting the breakpoint in the breakpoint view and pressing
           \key{Delete}.
        \o By selecting \gui{Delete Breakpoint} from the context
           menu in the \gui Breakpoints view.
    \endlist

    You can set and delete breakpoints before the program starts running or
    while it is running under the debugger's control. Breakpoints are saved
    together with a session.


    \section1 Viewing Call Stack Trace

    When the program being debugged is interrupted, Qt Creator displays the
    nested function calls leading to the current position as a call stack
    trace. This stack trace is built up from call stack frames, each
    representing a particular function. For each function, Qt Creator tries
    to retrieve the file name and line number of the corresponding source
    file. This data is shown in the \gui Stack view.

    \image qtcreator-debug-stack.png

    Since the call stack leading to the current position may originate or go
    through code for which no debug information is available, not all stack
    frames have corresponding source locations. Stack frames without
    corresponding source locations are grayed out in the \gui{Stack} view.

    If you click a frame with a known source location, the text editor
    jumps to the corresponding location and updates the \gui{Locals and Watchers}
    view, making it seem like the program was interrupted before entering the
    function.


    \section1 Viewing Threads

    If a multi-threaded program is interrupted, the \gui Thread view or the