← Back to branch summary

~bzoltan/kubuntu-packaging/decouple_cmake_plugin

« back to all changes in this revision

Viewing changes to doc/src/debugger/creator-debugger.qdoc

  • Committer: Timo Jyrinki
  • Date: 2013-12-02 09:16:15 UTC
  • mfrom: (1.1.29)
  • Revision ID: timo.jyrinki@canonical.com-20131202091615-xbj1os1f604ber1m
New upstream release candidate.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/debugger/creator-debugger.qdoc
32
32
 
33
33
    \QC provides a debugger plugin that acts as an interface between the \QC
34
34
    core and external native debuggers such as the GNU Symbolic Debugger (GDB),
35
 
    the Microsoft Console Debugger (CDB), and a QML/JavaScript debugger.
 
35
    the Microsoft Console Debugger (CDB), a QML/JavaScript debugger, and the
 
36
    debugger of the low level virtual machine (LLVM) project, LLDB.
36
37
 
37
38
    \list
38
39
 
39
40
        \li \l{Setting Up Debugger}
40
41
 
41
42
            The debugger plugin automatically selects a suitable
42
 
            native debugger for your projects from the ones found
43
 
            on your system. Manual overriding of this choice is possible.
 
43
            native debugger for each \l{glossary-buildandrun-kit}{kit} from the
 
44
            ones found on your system. You can edit the kits to override this
 
45
            choice.
44
46
 
45
47
        \li \l{Launching the Debugger}
46
48
 
207
209
    \endcode
208
210
 
209
211
    To launch the debugger in the core mode, select \gui{Debug > Start
210
 
    Debugging > Attach to Core}.
 
212
    Debugging > Load Core File}.
211
213
 
212
214
    Also in this mode, using a properly configured project containing
213
215
    the sources of the crashed program is not strictly necessary, but
220
222
 
221
223
    The \QC installation program asks you whether you want to
222
224
    register \QC as a post-mortem debugger. To change the setting, select
223
 
    \gui{Tools > Options  > Debugger > Common > Use Qt Creator for post-mortem
224
 
    debugging}.
 
225
    \gui Tools > \gui Options > \gui Debugger > \gui General > \gui {Use Qt
 
226
    Creator for post-mortem debugging}.
225
227
 
226
228
    You can launch the debugger in the post-mortem mode if an application
227
229
    crashes on Windows. Click the \gui {Debug in \QC} button in the error
244
246
    the user of \QC. To start debugging on a remote target with the
245
247
    necessary helper processes running, select the corresponding
246
248
    \l{glossary-buildandrun-kit}{kit} in
247
 
    \gui{Projects > Build & Run} or in the \gui{Debug > Start Debugging} menu.
 
249
    \gui{Projects > Build & Run}, and then select a function to start remote
 
250
    debugging in the \gui{Debug > Start Debugging} menu.
248
251
 
249
252
    Special use cases, such as attaching to a running process on the
250
253
    target, might still require manual setup.
653
656
    The \gui{Locals and Expressions} view also provides access to the most
654
657
    powerful feature of the debugger: comprehensive display of data belonging
655
658
    to Qt's basic objects.
656
 
 
657
 
    To enable Qt's basic objects data display feature:
658
 
 
659
 
    \list
660
 
 
661
 
        \li Select \gui Tools > \gui {Options} > \gui Debugger >
662
 
            \gui{Debugging Helper} and check the \gui{Use Debugging Helper}
663
 
            checkbox.
664
 
 
665
 
        \li The \gui{Locals and Expressions} view is reorganized to provide a
666
 
            high-level view of the objects.
667
 
 
668
 
    \endlist
669
 
 
670
659
    For example, in case of QObject, instead of displaying a pointer to some
671
660
    private data structure, you see a list of children, signals and slots.
672
661
 
687
676
    values of QMap, select \gui {Change Local Display Format} > \gui Compact.
688
677
 
689
678
    You can use the \gui{Locals and Expressions} view to change the contents of
690
 
    variables of simple data types, for example, \c int or \c float when the
 
679
    variables of simple data types, for example, \c int, \c float, QString
 
680
    and \c std::string when the
691
681
    program is interrupted. To do so, click the \gui Value column, modify
692
682
    the value with the inplace editor, and press \key Enter (or \key Return).
693
683
 
 
684
    To change the complete contents of QVector or \c std::vector values,
 
685
    type all values separated by commas into the \gui Value column of
 
686
    the main entry.
 
687
 
694
688
    You can enable tooltips in the main editor displaying this information.
695
689
    For more information, see \l{Showing Tooltips in Debug Mode}.
696
690
 
748
742
 
749
743
    \section2 Viewing Threads
750
744
 
751
 
    If a multi-threaded program is interrupted, the \gui Thread view or the
752
 
    combobox named \gui Thread in the debugger's status bar can be used to
 
745
    If a multi-threaded program is interrupted, the \gui Threads view or the
 
746
    combobox named \gui Threads in the debugger status bar can be used to
753
747
    switch from one thread to another. The \gui Stack view adjusts itself
754
748
    accordingly.
755
749
 
811
805
    A snapshot contains the complete state of the debugged program
812
806
    at a time, including the full memory contents.
813
807
 
814
 
    To create snapshots of a debugged program, select \gui Create in the
815
 
    context menu in the \gui Snapshot view.
 
808
    To create snapshots of a debugged program, select \gui {Create Snapshot} in
 
809
    the context menu in the \gui Snapshots view.
816
810
 
817
 
    Double-click on entries in the snapshot view to switch between
 
811
    Double-click on entries in the \gui Snapshots view to switch between
818
812
    snapshots. The debugger views are updated to reflect the
819
813
    state of the program at time of taking the snapshot.
820
814
 
821
 
    By default, the \gui{Snapshots} view is hidden.
822
 
 
823
815
*/
824
816
 
825
817
 
912
904
 
913
905
        \li There is no GDB to communicate with MSVC compiled applications on
914
906
            Windows. So information can be displayed nicely only in a limited
915
 
            fashion by using a cdb extension DLL.
 
907
            fashion by using a CDB extension DLL.
916
908
 
917
909
    \endlist
918
910
 
997
989
      ]}"
998
990
    \endcode
999
991
 
1000
 
    The value of the \gui{iname} field is the internal name of the object,
 
992
    The value of the \c iname field is the internal name of the object,
1001
993
    constituting a dot-separated list of identifiers, corresponding to the
1002
994
    position of the object's representation in the view. If it is not
1003
995
    present, is it generated by concatenating the parent object's iname,
1004
996
    a dot, and a sequential number.
1005
997
 
1006
 
    The value of the\gui{name} field is displayed in the \gui{name} column
 
998
    The value of the \c name field is displayed in the \gui{Name} column
1007
999
    of the view. If it is not specified, a simple number in brackets
1008
1000
    is used instead.
1009
1001
 
1014
1006
    enums, known and unknown structs as well as some convenience functions to
1015
1007
    handle common situations.
1016
1008
 
1017
 
    The member functions of the \gui{Dumper} class are the following:
 
1009
    The member functions of the \c Dumper class are the following:
1018
1010
 
1019
1011
    \list
1020
1012
 
1021
 
        \li \gui{__init__(self)} - Initializes the output to an empty string and
 
1013
        \li \c{__init__(self)} - Initializes the output to an empty string and
1022
1014
            empties the child stack. This should not be used in user code.
1023
1015
 
1024
 
        \li \gui{put(self, value)} - Low level function to directly append to the
 
1016
        \li \c{put(self, value)} - Low level function to directly append to the
1025
1017
            output string. That is also the fastest way to append output.
1026
1018
 
1027
 
        \li \gui{putField(self, name, value)} - Appends a name='value' field.
 
1019
        \li \c{putField(self, name, value)} - Appends a \c{name='value'} field.
1028
1020
 
1029
 
        \li \gui{childRange(self)} - Returns the range of children specified in
 
1021
        \li \c{childRange(self)} - Returns the range of children specified in
1030
1022
            the current \c Children scope.
1031
1023
 
1032
 
        \li \gui{putItemCount(self, count)} - Appends a field
 
1024
        \li \c{putItemCount(self, count)} - Appends a field
1033
1025
            \c {value='<%d items'} to the output.
1034
1026
 
1035
 
        \li \gui{putEllipsis(self)} - Appends fields
 
1027
        \li \c{putEllipsis(self)} - Appends fields
1036
1028
            \c {'{name="<incomplete>",value="",type="",numchild="0"}'}. This is
1037
1029
            automatically done by \c endChildren if the number of children to
1038
1030
            print is smaller than the number of actual children.
1039
1031
 
1040
 
        \li \gui{putName(self, name)} - Appends a \c {name=''} field.
 
1032
        \li \c{putName(self, name)} - Appends a \c {name=''} field.
1041
1033
 
1042
 
        \li \gui{putType(self, type, priority=0)} - Appends a field \c {type=''}
 
1034
        \li \c{putType(self, type, priority=0)} - Appends a field \c {type=''}
1043
1035
            unless the \a type coincides with the parent's default child type or
1044
1036
            \c putType was already called for the current item with a higher
1045
1037
            value of \c priority.
1046
1038
 
1047
 
        \li \gui{putBetterType(self, type)} - Overrides the last recorded
 
1039
        \li \c{putBetterType(self, type)} - Overrides the last recorded
1048
1040
            \c type.
1049
1041
 
1050
 
        \li \gui{putNumChild(self, numchild)} - Appends a field \c {numchild=''}
 
1042
        \li \c{putNumChild(self, numchild)} - Appends a field \c {numchild=''}
1051
1043
            unless the \c numchild coincides with the parent's default child
1052
1044
            numchild value.
1053
1045
 
1054
 
        \li \gui{putValue(self, value, encoding = None)} - Append a file \c {value=''},
 
1046
        \li \c{putValue(self, value, encoding = None)} - Append a file \c {value=''},
1055
1047
            optionally followed by a field \c {valueencoding=''}. The \c value
1056
1048
            needs to be convertible to a string entirely consisting of
1057
1049
            alphanumerical values. The \c encoding parameter can be used to
1083
1075
                double quotes are added.
1084
1076
        \endlist
1085
1077
 
1086
 
        \li \gui{putStringValue(self, value)} - Encodes a QString and calls
1087
 
            \c putValue with the correct \c encoding setting.
1088
 
 
1089
 
        \li \gui{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
1090
 
            \c putValue with the correct \c encoding setting.
1091
 
 
1092
 
        \li \gui{isExpanded()} - Checks whether the current item
 
1078
        \li \c{putStringValue(self, value)} - Encodes a QString and calls
 
1079
            \c putValue with the correct \c encoding setting.
 
1080
 
 
1081
        \li \c{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
 
1082
            \c putValue with the correct \c encoding setting.
 
1083
 
 
1084
        \li \c{isExpanded()} - Checks whether the current item
1093
1085
            is expanded in the view.
1094
1086
 
1095
 
        \li \gui{putIntItem(self, name, value)} - Equivalent to:
 
1087
        \li \c{putIntItem(self, name, value)} - Equivalent to:
1096
1088
            \code
1097
1089
            with SubItem(self, name):
1098
1090
                self.putValue(value)
1101
1093
                self.putNumChild(0)
1102
1094
            \endcode
1103
1095
 
1104
 
        \li \gui{putBoolItem(self, name, value)} - Equivalent to:
 
1096
        \li \c{putBoolItem(self, name, value)} - Equivalent to:
1105
1097
            \code
1106
1098
            with SubItem(self, name):
1107
1099
                self.putValue(value)
1109
1101
                self.putNumChild(0)
1110
1102
            \endcode
1111
1103
 
1112
 
        \li \gui{putCallItem(self, name, value, func, *args)} -
 
1104
        \li \c{putCallItem(self, name, value, func, *args)} -
1113
1105
            Uses GDB to call the function \c func on the value specified by
1114
1106
            \a {value} and output the resulting item. Use \c{putCallItem}
1115
1107
            only if there is no other way to access the data.
1118
1110
            and have the potential to change the state of the debugged
1119
1111
            program.
1120
1112
 
1121
 
        \li \gui{putItem(self, value)} - The "master function", handling
 
1113
        \li \c{putItem(self, value)} - The "master function", handling
1122
1114
            basic types, references, pointers and enums directly, iterates
1123
1115
            over base classes and class members of compound types and calls
1124
1116
            \c qdump__* functions whenever appropriate.
1125
1117
 
1126
 
        \li \gui{putSubItem(self, component, value)} - Equivalent to:
 
1118
        \li \c{putSubItem(self, component, value)} - Equivalent to:
1127
1119
            \code
1128
1120
            with SubItem(self, component):
1129
1121
                self.putItem(value)
1146
1138
    use \c Children and \c SubItem \e{Context Managers} to create the nested
1147
1139
    items.
1148
1140
 
1149
 
    The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
 
1141
    The \c Children constructor \c{__init__(self, dumper, numChild = 1,
1150
1142
    childType = None, childNumChild = None, maxNumChild = None, addrBase = None,
1151
1143
    addrStep = None)} uses one mandatory argument and several
1152
1144
    optional arguments.  The mandatory argument refers to the current \c Dumper
1180
1172
            d.putSubItem("key", key)
1181
1173
            d.putSubItem("value", value)
1182
1174
    \endcode
1183
 
 
1184
 
 
1185
 
    \section1 Debugging Helpers for QML
1186
 
 
1187
 
    The debugging helpers for QML provide you with code completion for custom modules
1188
 
    (\c qmldump) and debugging Qt Quick UI projects (\c qmlobserver).
1189
 
 
1190
 
    You have to build the QML Inspector once for each Qt version that you want
1191
 
    to debug
1192
 
    with. Select \gui{Tools > Options > Build & Run > Qt Versions}.
1193
 
 
1194
 
    \note QML Inspector requires Qt 4.7.1 or later.
1195
 
 
1196
 
    \section1 Enabling Debugging Helpers for Qt's Bootstrapped Applications
1197
 
 
1198
 
    Qt's bootstrapped applications (such as moc and qmake) are built in a way
1199
 
    that is incompatible with the default build of the debugging helpers. To
1200
 
    work around this, add \c{dumper.cpp} to the compiled sources in the
1201
 
    application Makefile.
1202
 
 
1203
 
    Choose \gui {Tools > Options > Debugger > Debugging Helper > Use debugging
1204
 
    helper from custom location}, and specify an invalid location, such as
1205
 
    \c{/dev/null}.
1206
 
 
1207
1175
*/
1208
1176
 
1209
1177