qtcreator.qdoc

           You need to have Carbide C++ version 2.0 or later installed.
    \endlist

    \section2 Linux

    To compile a project in Qt Creator, Linux uses GNU Compiler Collection
    (GCC). Intel Compiler Collection (ICC) is supported as a drop-in
    replacement for GCC.

    To add a Qt version:
    \list 1
        \o Select \gui Tools > \gui Options... > \gui Qt4 >
           \gui{Qt Versions}.
        \o Click \inlineimage qtcreator-linux-add.png
           and enter the name of the version in \gui{Version Name}.
        \o Enter the path to the qmake binary in \gui{Path to qmake}.
    \endlist

    \section2 Mac OS X

    To compile a project in Qt Creator, Mac OS X uses GNU Compiler Collection
    (GCC), which is part of Xcode.

    To add a Qt version:
    \list 1
        \o Select \gui{Qt Creator} > \gui Preferences... > \gui{Qt Versions}.
        \o Click \inlineimage qtcreator-macosx-add.png
           and enter the name of the version in \gui{Version Name}.
        \o Enter the path to the qmake binary in \gui{Path to qmake}.

           \image qtcreator-qt4-qtversions.png
    \endlist


    \section1 Setting Up a Project

    To view and modify the settings for currently open projects, switch to the
    \gui Projects mode by pressing \key Ctrl+4.

    \image qtcreator-projectpane.png

    The project pane consists of three tabs
    \list
       \o Targets
       \o Editor Settings
       \o Dependencies
    \endlist

    Use the \gui Build and \gui Run buttons on *Desktop* to switch between
    the build and run settings for the active project.

    If you have multiple projects open in Qt Creator, use
    \gui{Select a Project} option at the top to navigate between different
    project edits.

    \section1 Build Settings

    Different build configurations allow you to quickly switch between
    different build settings. By default, Qt Creator creates \bold debug
    and \bold release build configurations. Both of these configurations use
    the \l{glossary-default-qt}{default Qt version}.

    \image qtcreator-ppbuildsettings.png

    \section2 Adding and Removing Build Configurations

    To add a new build configuration, click \gui Add and select the type of
    configuration you would like add. You can add as many build configurations
    as you need.

    To delete the build configuration currently selected, click \gui Remove.

    \section2 Editing Build Configurations

    To edit a build configuration:
    \list 1
        \o Select the build configuration you want to edit in
           \gui{Edit Build Configuration}.
        \o In section \gui General, you can specify:
        \list
            \o The \l{glossary-project-qt}{Qt version} you want to use to
               build your project. For more information, see
               \l{Selecting the Qt version}.
            \o The toolchain required to build the project.
            \o If you want to \l{glossary-shadow-build}{shadow build} your
               project, check the \gui{Shadow Build} checkbox and select the
               build directory.
        \endlist
    \endlist

    \section2 Build Steps

    The build system of Qt Creator is built on qmake and make. In
    \gui{Build Steps} you can change the settings for qmake and make. Qt
    Creator runs the make command using the Qt version defined for the current
    build configuration.

    \section2 Clean Steps

    The cleaning process is used to remove intermediate files. This process
    might help you to fix obscure issues during the process of building a
    project.

    You can define the cleaning steps for your builds in the \gui{Clean Steps}:
    \list
        \o To add a clean step using make or a custom process, click
           \gui{Add clean step} and select the type of step you want to add.

           By default, custom steps are disabled. Activate customs steps by
           checking the \gui{Enable Custom Process Step} check-box.
        \o To remove a clean step, click \gui{Remove clean step} and select the
           step you want to remove.
        \o To change the order of steps, click
           \inlineimage qtcreator-movestep.png
           .
    \endlist

    \section2 Build Environment

    You can specify the environment you want to use for building in the
    \bold{Build Environment} section. By default, the environment in which Qt
    Creator was started is used and modified to include the Qt version.
    Depending on the selected Qt version, Qt Creator automatically sets the
    necessary environment variables. You can edit existing environment
    variables or add, reset and unset new variables based on your project
    requirements.


    \section1 Run Settings

    Qt Creator automatically creates run configurations for your project.
    These run configurations derive their executable from the parsed .pro
    files. You can also create custom executable run configurations where you
    can set the executable to be run.

    \image qtcreator-pprunsettings.png


    \section1 File Encoding

    To define the default file encoding, select the desired encoding in the
    \gui{Editor Settings}. By default, the Qt Creator uses the file encoding
    used by your system.


    \section1 Dependencies

    If you have multiple projects loaded in your session, you can define the
    dependencies between them. This affects the build order of your
    projects.

    \note These dependencies are unrelated to the dependencies inside a qmake
    project.

    To define the dependencies:
    \list 1
        \o Select the project for which you want to configure dependencies.
        \o In the \gui Dependencies section check the checkboxes to select
           other projects as dependencies.
    \endlist


    \section1 Adding External Libraries to a qmake Project

    Through external libraries Qt Creator can support code completion and
    syntax highlighting as if they were part of the current project or the Qt
    library.

    To add an external library:
    \list
        \o Open your project file (.pro) using the \gui Projects pane.
        \o Follow the instructions at \l http://doc.trolltech.com/latest/qmake-project-files.html#declaring-other-libraries
           {Declaring other Libraries}.
    \endlist

    Syntax completion and highlighting work once your project successfully
    builds and links against the external library.
*/


/*!
    \contentspage index.html
    \previouspage creator-quick-tour.html
    \page creator-writing-program.html
    \nextpage creator-editor-using.html

    \title Writing a Simple Program

    \note This tutorial assumes that you have experience in writing basic Qt
    applications, using Qt Designer to design user interfaces and using the Qt
    Resource System.

    In this example, we describe the steps involved in using Qt Creator
    to create a small Qt program, Text Finder. Inspired by the QtUiTools'
    \l{http://doc.trolltech.com/uitools-textfinder.html}{Text Finder}
    example, we write a similar but simplified version of it, as shown
    below.

    \image qtcreator-textfinder-screenshot.png

    \section1 Setting Up Your Environment

    Once you have installed Qt Creator, it detects automatically if Qt's
    location is in your \c PATH variable. If not, please follow the
    instructions in \l{Selecting the Qt version}.

    \section1 Setting Up the Project

    We begin with a Qt4 Gui Application project generated by Qt Creator. The
    \l{Creating a project} document describes this process in
    detail. Remember to select QWidget as the Text Finder's base class. If
    your project is not yet loaded, load it by selecting \gui{File} > \gui{Open}.

    In your project, you have the following files:

    \list
        \o \c{textfinder.h}
        \o \c{textfinder.cpp}
        \o \c{main.cpp}
        \o \c{textfinder.ui}
        \o \c{textfinder.pro}
    \endlist

    The \c{.h} and \c{.cpp} files come with the necessary boiler plate code.
    The \c{.pro} file is also complete.

    \section1 Filling in the Missing Pieces

    We begin by designing the user interface and then move on to filling
    in the missing code. Finally, we add the find functionality.

    \section2 The User Interface

    To begin designing the user interface, double-click on the
    \c{textfinder.ui} file in the \gui{Project Explorer}. This launches the
    integrated Qt Designer.

    Design the form below with:
    \list
        \o \l{http://doc.trolltech.com/qlabel.html}{QLabel}
        \o \l{http://doc.trolltech.com/qlinedit.html}{QLineEdit} (named lineEdit)
        \o \l{http://doc.trolltech.com/qpushbutton.html}{QPushButton} (named findButton)
        \o \l{http://doc.trolltech.com/qtextedit.html}{QTextEdit} (named textEdit)
    \endlist

    \image qtcreator-textfinder-ui.png

    We recommend that you use a \l{http://doc.trolltech.com/qgridlayout.html}{QGridLayout}
    to lay out the label, the line edit and the push button.
    The grid layout and the text edit can then be added to a
    \l{http://doc.trolltech.com/qvboxlayout.html}{QVBoxLayout}.
    If you are new to designing forms with \QD, see the
    \l{http://doc.trolltech.com/designer-manual.html}{Qt Designer Manual}.

    \section2 The Header File

    The \c{textfinder.h} file already has the necessary #includes, a
    constructor, a destructor, and the \c{Ui} object. We need to add a private
    slot, \c{on_findButton_clicked()}, to carry out our find operation. We
    also need a private function, \c{loadTextFile()}, to read and display the
    contents of our input text file in the
    \l{http://doc.trolltech.com/qtextedit.html}{QTextEdit}. This is done with
    the following code:

    \snippet examples/textfinder/textfinder.h 0

    \note The \c{Ui::TextFinder} object is already provided.

    \section2 The Source File

    Now that our header file is complete we move on to our source file,
    \c{textfinder.cpp}. We begin by filling in the functionality to load a
    text file. This is described in the code snippet below:

    \snippet examples/textfinder/textfinder.cpp 0

    Basically, we load a text file using
    \l{http://doc.trolltech.com/qfile.html}{QFile}, read it with
    \l{http://doc.trolltech.com/qtextstream.html}{QTextStream}, and
    then display it on \c{textEdit} with
    \l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()}
    which requires adding the following additional #includes to textfinder.cpp:

    \snippet examples/textfinder/textfinder.cpp 1

    For the \c{on_findButton_clicked()} slot, we extract the search string and
    use the \l{http://doc.trolltech.com/qtextedit.html#find}{find()} function
    to look for the search string within the text file. This is described in
    the code snippet below:

    \snippet examples/textfinder/textfinder.cpp 2

    Once we have both of these functions complete, we call \c{loadTextFile()} in
    our constructor.

    \snippet examples/textfinder/textfinder.cpp 3

    The \c{on_findButton_clicked()} slot is called automatically in
    the uic generated \c{ui_textfinder.h} file by this line of code:

    \code
    QMetaObject::connectSlotsByName(TextFinder);
    \endcode

    \section2 The Resource File

    We require a resource file (\c{.qrc}) within which we embed the input
    text file. This can be any \c{.txt} file with a paragraph of text.

    To add a resource file:
    \list 1
        \o Right-click on \gui{Resource Files} in the \gui{Project Explorer}.
        \o Select \gui{Add New File...}.
    \endlist
    The wizard dialog below is displayed.

    \image qtcreator-add-resource-wizard.png

    \list 3
        \o Enter "textfinder" in the \gui{Name} field. Use the given \gui{Path}.
        \o Click on \gui{Continue}.
    \endlist
    This page is displayed:

    \image qtcreator-add-resource-wizard2.png

    \list 5
        \o Choose to which project you want to add the new file. Select "TextFinder"
        as the \gui{Project}.
        \o Make sure that \gui{Add to Project} is checked.
        \o Click on \gui{Done}.
    \endlist

    Your resource file is now displayed in the resource editor.

    \list 8
        \o Select \gui{Add} > \gui{Add Prefix} from the drop-down list. The prefix we
        require is a slash (\c{/}).
        \o Select \gui{Add} > \gui{Add File} from the drop-down list.
        \o Locate the text file you are going to use. We use \c{input.txt}.
    \endlist

    Once the resource file has been successfully added, the following is displayed:

    \image qtcreator-add-resource.png

    \section1 Compiling and Running Your Program

    Now that you have all the necessary files, click the \inlineimage qtcreator-run.png
    button to compile your program.

*/


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

    \title Using Version Control Systems

    \table
        \caption    Version control systems supported by Qt Creator
        \row
            \i  \bold{git}
            \i  \l{http://git-scm.com/}
            \i
        \row
            \i  \bold{Subversion}
            \i  \l{http://subversion.tigris.org/}
            \i
        \row
            \i  \bold{Perforce}
            \i  \l{http://www.perforce.com}
            \i  Server version 2006.1 and later
        \row
            \i  \bold{CVS}
            \i  \l{http://www.cvshome.org}
            \i
    \endtable


    \section1 Setting Up Version Control Systems

    Qt Creator uses the version control system's command line clients to
    access your repositories. To set it up, you must ensure that these command
    line clients can be located via the \c{PATH} environment variable.
    To specify the path to the command line client's executable, go to the settings
    pages in \gui{Tools} > \gui{Options...}.


    \section1 Setting Up Common Options

    The \gui{Version Control > Common} settings page features common settings for
    version control systems, such as commit message line wrapping and checking
    options.

    \gui{Submit message checking script} is a script or program that can be
    used to perform checks on the submit message before submitting. The submit
    message is passed in as the script's first parameter. If there is an error,
    the script should output a message on standard error and return a non-zero
    exit code.

    \gui{User/alias configuration file} takes a file in mailmap format that
    lists user names and aliases. For example:

    \code
    Jon Doe <Jon.Doe@company.com>
    Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
    \endcode

    Notice that the second line specifies the alias \e{hm} and the
    corresponding email address for \e{Hans Mustermann}. If the user/alias
    configuration file is present, the submit editor displays a context
    menu with \gui{Insert name...} that pops up a dialog letting the user
    select a name.

    \gui{User fields configuration file} is a simple text file consisting of
    lines specifying submit message fields that take user names, for example:

    \code
    Reviewed-by:
    Signed-off-by:
    \endcode

    These fields appear below the submit message. They provide completion
    for the aliases/public user names specified in the
    \e{User/alias configuration file} as well as a button that opens the
    aforementioned user name dialog.


    \section1 Using Version Control Systems

    The version control sub-menus are in \gui Tools > \gui Options...
    > \gui{Version Control}. The version control system
    managing the current project is displayed here.

    Each version control system adds a pane to the \gui{Application Output}
    panes within which it logs the commands it executes, prepended by a
    timestamp and the relevant output.

    \image qtcreator-vcs-pane.png


    \section2 Adding Files

    When you create a new file or a new project, the wizard displays a page
    asking whether the files should be added to a version control system.
    This happens when the parent directory or the project is already
    under version control and the system supports the concept of adding files,
    e.g., \bold{Perforce} and \bold{Subversion}. Alternatively, you can
    add files later by using the version control tool menus.

    With \bold{git}, there is no concept of adding files. Instead, all modified
    files must be \e{staged} for a commit.


    \section2 Viewing Diff Output

    All version control systems provide menu options to \e{diff} the current
    file or project: to compare it with the latest version stored in the
    repository and to display the differences. In Qt Creator, a diff is
    displayed in a read-only editor. If the file is accessible, you can
    double-click on a selected diff chunk and Qt Creator opens an editor
    displaying the file, scrolled to the line in question.

    \image qtcreator-vcs-diff.png


    \section2 Annotating Files

    Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
    This displays the lines of the file prepended by the change identifier
    they originate from. Clicking on the change identifier shows a detailed
    description of the file.

    To show the annotation of a previous version in the \gui Annotate or
    \gui Blame view, right-click on the version in the code. This option
    allows you to navigate through the history of the file and obtain the
    previous version of the code. This option also works for \gui git/hg
    using SHA.

    The file log view for a single file has \gui Annotate in
    the context menu of the version mentioned in the log, the user can
    right-click a line to open a context menu which contains
    \gui{Annotate Previous}.

    To set up a VCS repository for new projects, select \gui File >
    \gui{New File or Project...}. It enables you to initialize a
    repository for VCS that supports \gui git/hg


    \section2 Committing Changes

    Once you have finished making changes, you can submit them to the version
    control system by choosing \gui{Commit} or \gui{Submit}. Qt Creator
    displays a commit page containing a text editor, where you can enter your
    commit message, and a checkable list of modified files to be included.
    When you are done, click on \gui{Commit} to start committing. In addition,
    there is a \gui{Diff Selected Files} button that brings up a diff view of the
    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. Alternatively, you
    can view it from the editor combo box showing the \gui{Opened files}.

    \image qtcreator-vcs-commit.png


    \section2 Viewing Versioning History and Change Details

    The versioning history of a file is displayed by selecting
    \gui{Log} (for \bold{git}) or \gui{Filelog} (for \bold{Perforce} and
    \bold{Subversion}). Typically, the log output contains the
    date, the commit message, and a change or revision identifier.
    Click on the identifier to display a description of the change including the diff.

    \image qtcreator-vcs-log.png
    \image qtcreator-vcs-describe.png


    \section2 Using git-specific Menu Entries

    The git sub-menu contains additional entries:

    \table
        \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.
        \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
    \endtable
*/


/*!
    \contentspage index.html
    \previouspage creator-editor-refactoring.html
    \page creator-editor-locator.html
    \nextpage creator-project-managing.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 \bold{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 item 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 \tt \bold{*}.
        \o To match a single instance of any character, enter \tt \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 systems
        \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{Filter Configuration} 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 \tt \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-project-generic.html
    \page creator-project-managing-sessions.html
    \nextpage creator-developing-applications.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 exisitng sessions, select \gui File >
    \gui Sessions > \gui{Session Manager...}.

    \image qtcreator-session-manager.png
*/


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

    \title Debugging


    \section1 About Debugging with Qt Creator

    Qt Creator does not have its own debugger. Instead, it provides a graphical
    frontend to various debugger engines:

    \table
        \header
            \o Platform
            \o Compiler
            \o Debugger Engine
        \row
            \o Linux, Unixes, Mac OS
            \o gcc
            \o GNU Symbolic Debugger (gdb)
        \row
            \o Windows/MinGW
            \o gcc
            \o GNU Symbolic Debugger (gdb)
        \row
            \o Windows
            \o Microsoft Visual C++ Compiler
            \o Debugging Tools for Windows/Microsoft Console Debugger (CDB)
    \endtable

    The frontend allows you to:
    \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, local and global variables, etc.
    \endlist

    Qt Creator displays the raw information provided by the engine
    in a clear and concise manner. This simplifies the debugging process.

    Qt Creator comes with generic IDE functionality: stack view, views for locals and
    watchers, registers, etc. In addition, Qt Creator includes features to make
    debugging Qt-based applications easy. The debugger frontend understands the
    internal layout of several Qt classes such as QString, the QTL containers,
    and most importantly QObject (and classes derived from it), as well as
    most containers of the C++ Standard Library. Therefore, the debugger can
    present their contents in a useful way.


    \section1 Debugger Engine Installation Notes

    \table
        \header
            \o Debugger engine
            \o Notes
        \row
            \o Gdb
            \o Requires gdb version 6.8 on Linux. On Mac OS X, please install the latest available Xcode
               available for your OS version.
        \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}.

               The pre-built \e{Qt SDK for Windows} makes use
               of the library if it is present on the system. When building Qt
               Creator using the Microsoft Visual C++ Compiler, the
               \c{"%ProgramFiles%\Debugging Tools for Windows"} path is
               checked to ensure that all required header files are there.
       \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 Projects mode. In the run
              configuration, select \gui{Use debug version of frameworks}.

              For more detailed information about debugging on the Mac, refer:
              \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 Interaction with the Debugger

    In \gui Debug mode, several dock widgets are used to interact with the
    program you are debugging. The frequently used dock widgets are visible by
    default; the rarely used ones are hidden. To change the default settings,
    select \gui Debug and then select \gui View.

    \image qtcreator-debug-view.png

    Here, you can lock or unlock the location of your dock widgets as well as
    display or hide them. The position of your dock widgets is saved for future
    sessions.


    \section2 Usage of the Debugger

    To start a program under the debugger's control, select the \gui{Debug}
    menu and \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.
    The user can interrupt a running program by selecting
    \gui {Interrupt} from the \gui{Debug} menu. 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 debugger views to examine the data in more detail.

    To finish debugging, press \key{Shift+F5}. A line of code can be executed
    as a whole with \key F10; to step into a function or a sub-function, use
    \key F11. Alternatively, you can continue running the program with \key F5.
    It is also possible to continue executing the program until the current
    function completes or jump to an arbitrary position in the current
    function.


    \section2 Breakpoints

    Breakpoints are shown in the \gui{Breakpoints} view which is enabled
    by default. This view is also accessible when the debugger and the program
    being debugged is not running.

    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 the user. The user is then free to examine the state of the
    interrupted program, or continue execution either line-by-line or continuously.

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

    Also, the interruption of a program by a breakpoint can be restricted with
    certain conditions.

    You can set a breakpoint:

    \list
       \o At a particular line you want the program to stop -- click on 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 breakpoints view.
    \endlist

    \note

    You can remove a breakpoint:

    \list
        \o By clicking on 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 breakpoint's context
           menu in the \gui Breakpoints view.
    \endlist

    Breakpoints can be set and deleted before the program has actually started
    running or while it is running under the debugger's control. Also,
    breakpoints are saved together with a session.


    \section2 Stack

    When the program being debugged is interrupted, Qt Creator displays the
    nested function calls leading to the current position as a \e call stack
    trace. This stack trace is built up from \e{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. These frames are
    grayed out in the \gui Stack view.

    If you click on 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.


    \section2 Threads

    If a multi-threaded program is interrupted, the \gui Thread view  or the
    combobox named \gui Thread in the debugger's status bar can be used to
    switch from one thread to another. The \gui Stack view adjusts itself
    accordingly.


    \section2 Modules View and Source Files View

    These views display the debugger's idea of the components of the
    application. By default, both views are hidden.


    \section2 Disassembler View and Registers View

    By default, both \gui Disassembler and \gui Registers view are hidden.
    The \gui Disassembler view displays disassembled code for the current
    function; the \gui Registers view displays the current state of the CPU's
    registers. Both views are useful for low-level commands such as
    \gui{Step Single Instruction} and \gui{Step Over Single Instruction}.

    \section2 Locals and Watchers

    Whenever a program stops under the control of the debugger, it retrieves
    information about the topmost stack frame and displays it in the