qtcreator.qdoc

    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.

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

*/

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


    \section1 Viewing Modules and Source Files

    The \gui{Modules} view and \gui{Source Files} views display information
    that the debugger plugin has about modules and source files included in
    the project. The \gui{Modules} view lists the modules in the project and
    symbols within the modules. In addition, it indicates where the module
    was loaded.

    The \gui{Source Files} view lists all the source files included in the project.
    If you cannot step into an instruction, you can check whether the source file is
    actually part of the project, or whether it was compiled
    elsewhere. The view shows the path to each file in the file system.

    By default, the \gui{Modules} view and \gui{Source Files} view are hidden.


    \section1 Viewing Disassembled Code and Register State

    The \gui{Disassembler} view displays disassembled code for the current
    function. The \gui{Registers} view displays the current state of the CPU's
    registers.

    The \gui{Disassembler} view and the \gui{Registers} view are both useful
    for low-level commands for checking single instructions, such as \gui{Step Into}
    and \gui{Step Over}. By default, both \gui{Disassembler} and
    \gui{Registers} view are hidden.

    \section1 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
    \gui{Locals and Watchers} view. The \gui{Locals and Watchers} view
    typically includes information about parameters of the function in that
    frame as well as the local variables.

    \image qtcreator-watcher.png "Locals and Watchers view"

    Compound variables of struct or class type are displayed as
    expandable in the view. Expand entries to show
    all members. Together with the display of value and type, you can
    examine and traverse the low-level layout of object data.


    \table
        \row
            \i  \bold{Note:}

        \row
            \i  Gdb, and therefore Qt Creator's debugger works for optimized
                builds on Linux and Mac OS X. Optimization can lead to
                re-ordering of instructions or removal of some local variables,
                causing the \gui{Locals and Watchers} view to show unexpected
                data.
        \row
            \i  The debug information provided by gcc does not include enough
                information about the time when a variable is initialized.
                Therefore, Qt Creator can not tell whether the contents of a
                local variable contains "real data", or "initial noise". If a
                QObject appears uninitialized, its value is reported as
                \gui {not in scope}. Not all uninitialized objects, however, can be
                recognized as such.
    \endtable


    The \gui{Locals and Watchers} view also provides access to the most
    powerful feature of the debugger: comprehensive display of data belonging
    to Qt's basic objects.

    To enable Qt's basic objects data display feature:
    \list
       \o  Select \gui Tools > \gui {Options...} > \gui Debugger >
           \gui{Debugging Helper} and check the \gui{Use Debugging Helper}
           checkbox.
       \o  The \gui{Locals and Watchers} view is reorganized to provide a
           high-level view of the objects.
    \endlist

    For example, in case of QObject, instead of displaying a pointer to some
    private data structure, you see a list of children, signals and slots.

    Similarly, instead of displaying many pointers and integers, Qt Creator's
    debugger displays the contents of a QHash or QMap in an orderly manner.
    Also, the debugger displays access data for QFileInfo and provides
    access to the "real" contents of QVariant.

    You can use the \gui{Locals and Watchers} view to change the contents of
    variables of simple data types, for example, \c int or \c float when the
    program is interrupted. To do so, click the \gui Value column, modify
    the value with the inplace editor, and press \key Enter (or \key Return).

    \note The set of watched items is saved in your session.

*/


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

    \title Debugging the Example Application

    This section uses the \l{Creating a Qt C++ Application}{TextFinder} example to
    illustrate how to debug applications in the \gui Debug mode. TextFinder
    reads a text file into
    QString and then displays it with QTextEdit.
    To look at the example QString, \c{line}, and see the
    stored data, place a breakpoint and view the QString object
    data, as follows:

    \list 1
        \o Click in between the line number and the window border on the line
        where we invoke \l{http://doc.qt.nokia.com/4.7-snapshot/qtextedit.html#plainText-prop}{setPlainText()}
        to set a breakpoint.

        \image qtcreator-setting-breakpoint1.png

        \o Select \gui{Debug > Start Debugging > Start Debugging} or press \key{F5}.


        \o To view the breakpoint, click the \gui{Breakpoints} tab.

        \image qtcreator-setting-breakpoint2.png

        \o To remove a breakpoint, right-click it and select \gui{Delete Breakpoint}.


        \o To view the contents of \c{line}, go to the \gui{Locals and
    Watchers} view.

        \image qtcreator-watcher.png

    \endlist

    Modify the \c{on_findButton_clicked()} function to move back to
    the start of the document and continue searching once the cursor hits the
    end of the document. Add the following code snippet:

    \code
    void TextFinder::on_findButton_clicked()
    {
        QString searchString = ui->lineEdit->text();

        QTextDocument *document = ui->textEdit->document();
        QTextCursor cursor = ui->textEdit->textCursor();
        cursor = document->find(searchString, cursor,
            QTextDocument::FindWholeWords);
        ui->textEdit->setTextCursor(cursor);

        bool found = cursor.isNull();

        if (!found && previouslyFound) {
            int ret = QMessageBox::question(this, tr("End of Document"),
            tr("I have reached the end of the document. Would you like "
            "me to start searching from the beginning of the document?"),
            QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes);

            if (ret == QMessageBox::Yes) {
                cursor = document->find(searchString,
                    QTextDocument::FindWholeWords);
                ui->textEdit->setTextCursor(cursor);
            } else
                return;
        }
        previouslyFound = found;
    }
    \endcode

    If you compile and run the above code, however, the application does not
    work correctly due to a logic error. To locate this logic error, step
    through the code using the following buttons:

    \image qtcreator-debugging-buttons.png

 */


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

    \title Using Debugging Helpers

    \section1 Debugging Helper Library with C++

    While debugging, Qt Creator dynamically loads a helper library into your
    program. This helper library enables Qt Creator to pretty print Qt and STL
    types. The Qt SDK package already contains a prebuilt debugging helper
    library. To create your own debugging helper library, select \gui{Tools} >
    \gui{Options...} > \gui{Qt4} > \gui{Qt Versions}. As the internal data
    structures of Qt can change between versions, the debugging helper
    library is built for each Qt version.


    \section1 Debugging Helper Library with Python

    With the gdb Python version, you can
    use debugging helpers also for user defined types. To do so,
    define one Python function per user defined type in \c{.gdbinit}.

    The function name has to be qdump__NS__Foo, where NS::Foo is the class
    or class template to be examined. Nested namespaces are possible.

    The debugger plugin calls this function whenever you want to
    display an object of this type. The function is passed the following
    parameters:
    \list
       \o  \c d of type \c Dumper
       \o  \c item of type \c Item
    \endlist

    The function has to feed the Dumper object with certain information
    which is used to build up the object and its children's display in the
    \gui{Locals and Watchers} view.


    Example:

    \code
    def qdump__QVector(d, item):
        d_ptr = item.value["d"]
        p_ptr = item.value["p"]
        alloc = d_ptr["alloc"]
        size = d_ptr["size"]

        check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
        check(d_ptr["ref"]["_q_value"] > 0)

        innerType = item.value.type.template_argument(0)
        d.putItemCount(size)
        d.putNumChild(size)
        if d.isExpanded(item):
            p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
            with Children(d, [size, 2000], innerType)
                for i in d.childRange():
                    d.putItem(Item(p.dereference(), item.iname, i))
                    p += 1
    \endcode

    \section2 Item Class

    The Item Python class is a thin wrapper around values corresponding to one
    line in the \gui{Locals and Watchers} view. The Item members are as follows :

    \list

    \o \gui{__init__(self, value, parentiname, iname, name = None)} - A
       constructor. The object's internal name is created by concatenating
       \c parentiname and \c iname. If \c None is passed as \c name, a
       serial number is used.

    \o \gui{value} - An object of type gdb.Value representing the value to
        be displayed.

    \o \gui{iname} - The internal name of the object, constituting a dot-separated
    list of identifiers, corresponding to the position of the object's
    representation in the view.

    \o \gui{name} - An optional name. If given, is used in the
    \gui{name} column of the view. If not, a simple number in brackets
    is used instead.

    \endlist


    \section2 Dumper Class

    For each line in the \gui{Locals and Watchers} view, a string like the
    following needs to be created and channeled to the debugger plugin.
    \code
    "{iname='some internal name',
      addr='object address in memory',
      name='contents of the name column',
      value='contents of the value column',
      type='contents of the type column',
      numchild='number of children',        // zero/nonzero is sufficient
      childtype='default type of children', // optional
      childnumchild='default number of grandchildren', // optional
      children=[              // only needed if item is expanded in view
         {iname='internal name of first child',
          ... },
         {iname='internal name of second child',
          ... },
         ...
      ]}"
    \endcode

    While in theory, you can build up the entire string above manually, it is
    easier to employ the Dumper Python class for that purpose. The Dumper
    Python class contains a complete framework to take care of the \c iname and
    \c addr fields, to handle children of simple types, references, pointers,
    enums, known and unknown structs as well as some convenience methods to
    handle common situations.

    The Dumper members are the following:

    \list

    \o \gui{__init__(self)} - Initializes the output to an empty string and
        empties the child stack.

    \o \gui{put(self, value)} - Low level method to directly append to the
        output string.

    \o \gui{putCommaIfNeeded(self)} - Appends a comma if the current output
        ends in '}', '"' or ']' .

    \o \gui{putField(self, name, value)} - Appends a comma if needed, and a
         name='value' field.

    \o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.

    \o \gui{endItem(self)} - Ends writing a field by writing \c {'}.

    \o \gui{endChildren(self)} - Ends writing a list of children.

    \o \gui{childRange(self)} - Returns the range of children specified in
        the current \c Children scope.

    \o \gui{putItemCount(self, count)} - Appends a field  \c {value='<%d items'}
        to the output.

    \o \gui{putEllipsis(self)} - Appends fields
        \c {'{name="<incomplete>",value="",type="",numchild="0"}'}. This is
        automatically done by \c endChildren if the number of children to
        print is smaller than the number of actual children.

    \o \gui{putName(self, name)} - Appends a \c {name='...'} field.

    \o \gui{putType(self, type)} - Appends a field \c {type='...'} unless the
        \a type coincides with the parent's default child type.

    \o \gui{putNumChild(self, numchild)} - Appends a field \c {numchild='...'}
        unless the \c numchild coincides with the parent's default child numchild
        value.

    \o \gui{putValue(self, value, encoding = None)} - Append a file \c {value='...'},
        optionally followed by a field \c {valueencoding='...'}. The \c value
        needs to be convertible to a string entirely consisting of
        alphanumerical values. The \c encoding parameter can be used to
        specify the encoding in case the real value had to be encoded in some
        way to meet the alphanumerical-only requirement.
        Currently the following encodings are supported:

        \list
            \o 0: unencoded 8 bit data, interpreted as Latin1.

            \o 1: base64 encoded 8 bit data, used for QByteArray,
                double quotes are added.

            \o 2: base64 encoded 16 bit data, used for QString,
                double quotes are added.

            \o 3: base64 encoded 32 bit data,
                double quotes are added.

            \o 4: base64 encoded 16 bit data, without quotes (see 2)

            \o 5: base64 encoded 8 bit data, without quotes (see 1)

            \o 6: %02x encoded 8 bit data (as with \c QByteArray::toHex),
                double quotes are added.

            \o 7: %04x encoded 16 bit data (as with \c QByteArray::toHex),
                double quotes are added.
        \endlist

    \o \gui{putStringValue(self, value)} - Encodes a QString and calls
        \c putValue with the correct \c encoding setting.

    \o \gui{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
        \c putValue with the correct \c encoding setting.

    \o \gui{isExpanded(self, item)} - Checks whether the item with the
        internal name \c item.iname is expanded in the view.

    \o \gui{isExpandedIName(self, iname)} - Checks whether the item with the
        internal name \c iname is expanded in the view.

        \o \gui{putIntItem(self, name, value)} - Equivalent to:
        \code
        self.beginHash()
        self.putName(name)
        self.putValue(value)
        self.putType("int")
        self.putNumChild(0)
        self.endHash()
        \endcode

        \o \gui{putBoolItem(self, name, value)} - Equivalent to:
        \code
        self.beginHash()
        self.putName(name)
        self.putValue(value)
        self.putType("bool")
        self.putNumChild(0)
        self.endHash()
        \endcode

    \o \gui{pushOutput(self)} - Moves the output string to a safe location
        from with it is sent to the debugger plugin even if further operations
        raise an exception.

    \o \gui{putCallItem(self, name, item, func)} -
        Uses gdb to call the function \c func on the value specified by
        \a {item.value} and output the resulting item. This function is
        not available when debugging core dumps and it is not available
        on the Symbian platform due to restrictions imposed by AppTRK.

    \o \gui{putItemHelper(self, item)} - The "master function", handling
        basic types, references, pointers and enums directly, iterates
        over base classes and class members of compound types and calls
        \c qdump__* functions whenever appropriate.

    \o \gui{putItem(self, item)} - Equivalent to:
        \code
        with SubItem(self):
            self.putItemHelper(item)
        \endcode
        Exceptions raised by nested function calls are caught and all
        output produced by \c putItemHelper is replaced by the output of:
        \code
            ...
        except RuntimeError:
            d.put('value="<invalid>",type="<unknown>",numchild="0",')
        \endcode

    \endlist


    \section2 Children and SubItem Class

    The attempt to create child items might lead to errors if data is
    uninitialized or corrupted. To gracefully recover in such situations,
    use \c Children and \c SubItem \e{Context Managers} to create the nested items.

    The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
    childType = None, childNumChild = None)} uses one mandatory argument and three
    optional arguments.  The mandatory argument refers to the current \c Dumper
    object.  The optional arguments can be used to specify the number \c numChild
    of children, with type \c childType_ and \c childNumChild_ grandchildren each.
    If \c numChild_ is a list of two integers, the first one specifies the actual
    number of children and the second the maximum number of children to print.

    Similarly, using the \c SubItem class helps to protect individual items.

    Example:
    \code
    d.putNumChild(2)
    if d.isExpanded(item):
        with Children(d):
            with SubItem(d):
                d.putName("key")
                d.putItemHelper(Item(key, item.iname, "key"))
            with SubItem(d):
                d.putName("value")
                d.putItemHelper(Item(value, item.iname, "value"))
    \endcode
*/


/*!
    \contentspage index.html
    \previouspage creator-project-qmake.html
    \page creator-project-cmake.html
    \nextpage creator-project-generic.html

    \title Setting Up a CMake Project

    CMake is an alternative to qmake for automating the generation of makefiles.
    It controls the software compilation process by using simple configuration
    files, called CMakeLists.txt files. CMake generates native makefiles and
    workspaces that you can use in the compiler environment of your choice.

    Since Qt Creator 1.1, CMake configuration files are supported.
    Qt Creator 1.3 supports the Microsoft Toolchain if the CMake version
    is at least 2.8.

    \section1 Setting the Path for CMake

    You can set the path for the \c CMake executable in \gui{Tools} >
    \gui{Options... > Projects > CMake}.

    \image qtcreator-cmakeexecutable.png

    \note Before you open a \c CMake project it is necessary to modify the
    \c{PATH} environment variable to include the bin folders of \c mingw and
    Qt Creator in the SDK.

    For instance, if you have the Qt Creator SDK installed in your C drive,
    use the following command to set the environment variables in
    the command line prompt:
    \code
    set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin;
    \endcode
    Then start Qt Creator by typing:
    \code
    C:\qtsdk\bin\qtcreator.exe
    \endcode

    \section1 Opening CMake Projects

    To open a \c CMake project:
    \list 1
        \o  Select \gui{File} > \gui{Open File or Project...}.
        \o  Select the \c{CMakeLists.txt} file from your \c CMake project.
    \endlist

    A wizard guides you through the rest of the process.

    \note If the \c CMake project does not have an in-place build, Qt Creator
    lets you specify the directory in which the project is built
   (\l{glossary-shadow-build}{shadow build}).

    \image qtcreator-cmake-import-wizard1.png

    The screenshot below shows how you can specify command line arguments to
    \c CMake for your project.

    \image qtcreator-cmake-import-wizard2.png

    Normally, there is no need to pass any command line arguments for projects
    that are already built, as \c CMake caches that information.


    \section1 Building CMake Projects

    Qt Creator builds \c CMake projects by running \c make, \c mingw32-make, or
    \c nmake depending on your platform. The build errors and warnings are
    parsed and displayed in the \gui{Build Issues} output pane.

    By default, Qt Creator builds the \bold{all} target. You can specify which
    targets to build in \gui{Project} mode, under \gui{Build Settings}.

    \image qtcreator-cmake-build-settings.png

    Qt Creator supports multiple build configurations. The build
    directory can also be modified after the initial import.

    \section1 Running CMake Projects