creator-debugger.qdoc 48.6 KB
Newer Older
1
2
3
4
/****************************************************************************
**
** This file is part of Qt Creator
**
5
** Copyright (c) 2012 Nokia Corporation and/or its subsidiary(-ies).
6
**
Eike Ziller's avatar
Eike Ziller committed
7
** Contact: http://www.qt-project.org/
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage index.html
28
    \previouspage creator-testing.html
29
    \page creator-debugging.html
30
    \nextpage creator-debugger-engines.html
31
32
33
34
35
36
37
38
39

    \title Debugging

    \QC provides a debugger plugin that acts as an interface between the \QC
    core and external native debuggers such as the GNU Symbolic Debugger (GDB),
    the Microsoft Console Debugger (CDB), and a QML/JavaScript debugger.

    \list

hjk's avatar
hjk committed
40
        \o  \l{Setting Up Debugger}
41

hjk's avatar
hjk committed
42
43
44
            The debugger plugin automatically selects a suitable
            native debugger for your projects from the ones found
            on your system. Manual overriding of this choice is possible.
45

46
47
        \o  \l{Launching the Debugger}

hjk's avatar
hjk committed
48
49
50
51
52
            To start an application from an open project under the control
            of a debugger, press the Debug button in the lower left corner
            of the main view, or press \key{F5}. Other, less common start
            options are available in the \gui{Debug} > \gui{Start Debugging}
            menu.
53
54
55

        \o  \l{Interacting with the Debugger}

hjk's avatar
hjk committed
56
57
            You can use the tool views in the \gui Debug mode to inspect the
            state of your application while debugging.
58
59

        \o  \l{Using Debugging Helpers}
60

61
62
63
64
            \QC is able to show complex data types in a customized,
            user-extensible manner. For this purpose, it takes advantage of
            two technologies, collectively referred to as \e {debugging
            helpers}. Using the debugging helpers is not essential for
hjk's avatar
hjk committed
65
66
            debugging with \QC, but they provide you with a powerful
            tool to quickly examine complex data.
67

68
        \o  \l{Debugging Qt Quick Projects}
69

hjk's avatar
hjk committed
70
71
            When debugging a Qt Quick application, you can inspect the state
            of the
72
73
74
75
76
            application while debugging JavaScript functions. You can set
            breakpoints, view call stack trace, and examine locals and
            expressions. When the application is interrupted by a breakpoint,
            you can use the QML Script Console to execute JavaScript expressions
            in the current context.
77

78
79
80
            While the application is running, you can use the QML Inspector
            view to explore the object structure, debug animations, and
            inspect colors.
81

hjk's avatar
hjk committed
82
83
84
85
86
87
88
89
        \o  \l{Debugging a C++ Example Application}

            Illustrates how to debug C++ applications in \QC.

        \o  \l{Debugging a Qt Quick Example Application}

            Illustrates how to debug Qt Quick applications in \QC.

90
        \o  \l{Troubleshooting Debugger}
91

92
93
            If you encounter problems while debugging, check for possible
            solutions to them.
94
95
96
97
98
99
100
    \endlist

*/


/*!
    \contentspage index.html
101
    \previouspage creator-debugger-engines.html
102
103
104
105
106
    \page creator-debugger-operating-modes.html
    \nextpage creator-debug-mode.html

    \title Launching the Debugger

hjk's avatar
hjk committed
107
108
109
110
    To start an application from an open project under the control
    of a debugger, press the \gui Debug button in the lower left corner
    of the main view, or press \key{F5}.

111
    \QC checks whether the compiled program is up-to-date, and rebuilds
hjk's avatar
hjk committed
112
113
114
115
116
117
    and deploys it if the \gui{Always build project before deploying it} and
    \gui{Always deploy before running} options are selected in the
    \gui{Build and Run} options.

    The debugger then takes over and starts the program with suitable
    parameters.
118

hjk's avatar
hjk committed
119
    \note Starting a C++ program in the debugger can take a long
120
121
122
123
124
125
    time, typically in the range of several seconds to minutes if complex
    features (like QtWebKit) are used.


    \section1 Launching the Debugger in Different Modes

hjk's avatar
hjk committed
126
    The debugger plugin can run the native debuggers in various operating
127
128
    modes depending on where and how the debugged process is started and run.
    Some of the modes are only available for a particular operating system or
hjk's avatar
hjk committed
129
130
131
    platform.

    In general, the \key{F5} and the \gui{Debug} button are set up in a way
132
    to start the operating mode that is commonly used in a given context.
hjk's avatar
hjk committed
133
134
    So if the current project is set up as a C++ application using
    the MinGW toolchain targeting desktop Windows, the GDB engine will
135
    be started in Start Internal mode. If the current project is a
hjk's avatar
hjk committed
136
137
138
139
    QML application using C++ plugins targeting Meego
    a "mixed" QML/C++ engine will be started, with the C++ parts
    being handled by GDB and GDB server remote debugging.

140
    Change the run configuration
hjk's avatar
hjk committed
141
142
    parameters (such as \gui{Run in Terminal}) in the run settings of the
    project, or select options from the \gui{Debug} > \gui{Start Debugging}
143
    menu to select other modes of operation.
144

hjk's avatar
hjk committed
145
    The debugger can run in the following modes:
146
147
148

    \list

149
150
       \o  \bold{Start Internal} to debug applications developed inside
            \QC such as a Qt based GUI application.
151

152
153
154
       \o  \bold{Start External} to start and debug processes
            without a proper \QC project setup, either locally or
            on a remote machine.
155

156
157
158
       \o  \bold{Attach} to debug processes already started and
            running outside \QC, either locally or on a
            remote machine.
159

hjk's avatar
hjk committed
160
       \o  \bold{Core} to debug crashed processes on Unix.
161

hjk's avatar
hjk committed
162
       \o  \bold{Post-mortem} to debug crashed processes on Windows.
163
164
165

    \endlist

166
    \section2 Launching in Start Internal Mode
167

168
    Start Internal mode is the default start mode for most projects, including
hjk's avatar
hjk committed
169
170
    all projects using a desktop Qt version and plain C++ projects.

171
172
173
    If you need a console window to operate your application, for example because
    it accepts console input from the user, go to \gui {Projects > Run
    Settings} and select the \gui {Run in terminal} check box.
hjk's avatar
hjk committed
174

175
176
    To launch the debugger in Start Internal mode, click the
    \gui {Start Debugging} button for the active project.
177

178
179
    You can specify breakpoints before or after launching the debugger.
    For more information, see \l{Setting Breakpoints}.
180

181
    \section2 Launching in Start External Mode
182

183
184
185
    To run any executable already present on your local or a remote machine
    without using a project, select \gui{Debug > Start Debugging
    > Start and Debug External Application}.
186

187
    \section2 Launching in Attach Mode
188

189
190
191
    To attach the debugger to an application already running on your
    local or a remote machine, select
    \gui {Debug > Start Debugging > Attach to Running Application},
192
193
    and then select a process by its name or process ID to attach to.

hjk's avatar
hjk committed
194
195
196
197
    While this mode does not strictly require a project to be opened in \QC,
    it is beneficial to have open one, as it makes setting breakpoints
    and stepping throught the code easier.

198
199
    You can specify breakpoints before or after attaching the
    debugger to the application.
hjk's avatar
hjk committed
200
201
    For more information, see \l{Setting Breakpoints}.

202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
    \section2 Launching in Core Mode

    The Core mode is used to inspect \e {core} files (crash dumps) that are
    generated from crashed processes on Linux and Unix systems if the system
    is set up to allow this.

    To enable the dumping of core files on a Unix system, 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}.

    Also in this mode, using a properly configured project containing
    the sources of the crashed program is not strictly necessary, but
    helpful.

    \section2 Launching in Post-Mortem Mode

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

    The \QC installation program asks you whether you want to
    register \QC as a post-mortem debugger. To change the setting, select
    \gui{Tools > Options  > Debugger > Common > Use Qt 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 \QC} button in the error
    message that is displayed by the Windows operating system.

236

237
    \section1 Remote Debugging
238

239
240
241
242
    \QC provides very easy access to remote debugging.

    In general, the remote debugging setup consist of a probe running on the
    remote machine and a counterpart running on the host side.
hjk's avatar
hjk committed
243
244
    The probe is either integrated into the running process (e.g. for QML
    debugging) or runs a separate process (e.g. when using GDB server
245
    on embedded Linux). The host side typically
Leena Miettinen's avatar
Leena Miettinen committed
246
247
248
249
250
251
252
    consists of \QC itself, often with the help of an external process, such as
    \if defined(qcmanual)
    GDB or CDB.
    \else
    GDB.
    \endif

hjk's avatar
hjk committed
253
    While this setup might look daunting, it is mostly invisible to
254
    the user of \QC. To start debugging on a remote target with the
255
256
257
    necessary helper processes running, select the corresponding
    \l{glossary-buildandrun-kit}{kit} in
    \gui{Projects > Build & Run} or in the \gui{Debug > Start Debugging} menu.
hjk's avatar
hjk committed
258
259
260

    Special use cases, such as attaching to a running process on the
    target, might still require manual setup.
261
262
263

    \section3 Using GDB

hjk's avatar
hjk committed
264
265
266
    When debugging on a target supported by GDB server, a local GDB process
    talks to a GDB server running on the remote machine that controls the
    process to be debugged.
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284

    The GDB server process is started on the remote machines by passing a port
    number and the executable:

    \code
    gdbserver :1234 <executable>
    \endcode

    It then typically responds:
    \code
    Process bin/qtcreator created; pid = 5159
    Listening on port 1234
    \endcode

    On the local machine that runs \QC:

    \list 1

hjk's avatar
hjk committed
285
286
        \o  Select \gui {Debug > Start Debugging > Attach to Remote
            Debug Server}.
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366

        \o  In the \gui {Host and port} field, enter the name of the remote
            machine and the port number to use.

        \o  Select \gui{OK} to start debugging.

    \endlist

    \section3 Using CDB

    In remote mode, the local CDB process talks to a CDB process that
    runs on the remote machine. The process is started with special
    command line options that switch it into server mode. The remote CDB
    process must load the \QC CDB extension library that is shipped with
    \QC:

    \list 1

        \o  Install the \e{Debugging Tools for Windows} on the remote machine.
            The installation folder contains the CDB command line executable
            (cdb.exe).

        \o  Copy the \QC CDB extension library from the Qt installation
            directory to the a new folder on the remote machine
            (32 or 64 bit version depending on the version of the Debugging
            Tools for Windows
            used):

        \list

            \o  \c {\lib\qtcreatorcdbext32\qtcreatorcdbext.dll} (32 bit)

            \o  \c {\lib\qtcreatorcdbext64\qtcreatorcdbext.dll} (64 bit)

        \endlist

        \o  Set the _NT_DEBUGGER_EXTENSION_PATH environment variable to point
            to that folder.

        \o  To use TCP/IP as communication protocol, launch remote CDB as
            follows:

            \code
            cdb.exe -server tcp:port=1234 <executable>
            \endcode

        \o  On the local machine running \QC, select
            \gui {Debug > Start Debugging > Attach to Remote CDB Session}


        \o  In the \gui Connection field enter the connection parameters.
            For example, for TCP/IP:

            \code
            Server:Port
            \endcode

            If you chose some other protocol, specify one of the alternative
            formats:

            \code
            tcp:server=Server,port=Port[,password=Password][,ipversion=6]
            tcp:clicon=Server,port=Port[,password=Password][,ipversion=6]
            npipe:server=Server,pipe=PipeName[,password=Password]
            com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
            spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
            ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
            ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
            \endcode

            \o Click \gui{OK} to start debugging.

    \endlist
*/


/*!
    \contentspage index.html
    \previouspage creator-debugger-operating-modes.html
    \page creator-debug-mode.html
367
    \nextpage creator-debugging-helpers.html
368
369
370

    \title Interacting with the Debugger

371
372
373
374
375
376
377
378
379
380
381
382
383
384
    You can use the \QC \gui Debug mode to inspect the state of your application
    while debugging. 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.

hjk's avatar
hjk committed
385
        \o  Examine and modify contents of local and global variables.
386
387

        \o  Examine and modify registers and memory contents of
hjk's avatar
hjk committed
388
            the debugged program.
389
390
391

        \o  Examine the list of loaded shared libraries.

hjk's avatar
hjk committed
392
393
        \o  Disassemble sections of code.

394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
        \o  Create snapshots of the current state of the debugged program
            and re-examine them later.

    \endlist

    \QC 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 expressions, registers, and so on, \QC 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 extensions.
    This deeper understanding is used to present objects of such classes in a
    useful way.

    \section1 Using the Debugger

414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
    In \gui Debug mode, you can use several views to interact with the
    program you are debugging. The availability of views depends on whether
    you are debugging C++ or QML. Frequently used views are shown by
    default and rarely used ones are hidden. To change the default settings,
    select \gui {Window > Views}, and then select views to display or hide.

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

    By default, the views are locked into place in the workspace. Select
    \gui {Window > Views > Locked} to unlock the views. Drag and drop the
    views into new positions on the screen. Drag view borders to resize the
    views. The size and position of views are saved for future sessions. Select
    \gui {Window > Views > Reset to Default Layout} to reset the views to
    their original sizes and positions.

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

    Once the program stops, \QC:

    \list

        \o  Retrieves data representing the call stack at the program's current
            position.

        \o  Retrieves the contents of local variables.

        \o  Examines \gui Expressions.

        \o  Updates the \gui Registers, \gui Modules, and \gui Disassembler
            views if you are debugging the C++ based applications.

    \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 subfunction, press \key{F11}.

       \o  To continue running the program, press \key{F5}.

       \o  To run to the selected function when you are stepping into a nested
           function, press \key{Ctrl+F6}.

    \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.

    \QC 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"

    You can associate breakpoints with:

    \list

        \o  Source code files and lines

        \o  Functions

        \o  Addresses

        \o  Throwing and catching exceptions

        \o  Executing and forking processes

        \o  Executing some system calls

        \o  Changes in a block of memory at a particular address when a
            program is running

    \endlist

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

    To set a breakpoint at a particular line you want the program to stop,
    click the left margin or press \key F9 (\key F8 for Mac OS X).

    To set breakpoints, select \gui {Add Breakpoint} in
    the context menu in the \gui Breakpoints view.

    \image qtcreator-add-breakpoint.png "Add Breakpoints" dialog

    \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.

    \section2 Setting Data Breakpoints

    To set a data breakpoint at an address:

    \list 1

        \o  Right-click in the \gui Breakpoints view to open the context menu,
            and select \gui {Add Breakpoint}.

        \o  In the \gui {Breakpoint type} field, select \gui {Break on data
            access at fixed address}.

        \o  In the \gui Address field, specify the address of the memory block.

        \o  Select \gui OK.

    \endlist

    If the address is displayed in the \gui {Locals and Expressions} view, you
    can select \gui {Add Data Breakpoint at Object's Address} in the context
    menu to set the data breakpoint.

    \section1 Viewing Call Stack Trace

    When the program being debugged is interrupted, \QC 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, \QC 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 Expressions}
    view, making it seem like the program was interrupted before entering the
    function.

    \section1 Locals and Expressions

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

    \image qtcreator-locals-expressions.png "Locals and Expressions 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
596
            \o  \bold{Note:}
597
598

        \row
599
            \o  GDB, and therefore \QC's debugger works for optimized
600
601
602
603
604
                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 Expressions} view to show unexpected
                data.
        \row
605
            \o  The debug information provided by GCC does not include enough
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
                information about the time when a variable is initialized.
                Therefore, \QC 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 Expressions} 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 Expressions} 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, \QC'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 Expressions} 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).

    You can enable tooltips in the main editor displaying this information.
    For more information, see \l{Showing Tooltips in Debug Mode}.

    \note The set of evaluated expressions is saved in your session.

    \section1 Directly Interacting with Native Debuggers

    In some cases, it is convenient to directly interact with the command
    line of the native debugger. In \QC, you can use the left
    pane of the \gui {Debugger Log} view for that purpose. When you press
Leena Miettinen's avatar
Leena Miettinen committed
655
    \key {Ctrl+Enter}, the contents of the line under the text cursor
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
    are sent directly to the native debugger. Alternatively, you
    can use the line edit at the bottom of the view. Output is displayed in the
    right pane of the \gui {Debugger Log} view.

    \note Usually, you do not need this feature, because \QC provides
    you with better ways to handle the task. For example, instead of using the
    GDB \c print command from the command line, you can evaluate an expression
    in the \gui{Locals and Expressions} view.

    \section1 Debugging C++ Based Applications

    The following sections describe additional debugging functions that apply
    only to debugging C++.

    \section2 Starting the Debugger from the Command Line

    You can use the \QC debugger interface from the command line. To
    attach it to a running process, specify the process ID as a parameter for
    the \c {-debug} option. To examine a core file, specify the file name.
    \QC executes all the necessary steps, such as searching for
    the binary that belongs to a core file.

    For example:

    \list

        \o \c {C:\qtcreator\bin>qtcreator -debug 2000}

        \o \c {C:\qtcreator\bin>qtcreator -debug core.2000}

    \endlist

    For more information, see \l{Using Command Line Options}.

    \section2 Stepping into Frameworks in Mac OS

    In Mac OS X, external libraries are usually built into so-called Frameworks,
    which may contain both release and debug versions of the library. When you run
    applications on the Mac OS desktop, the release version of Frameworks is used
    by default. To step into Frameworks, select the \gui {Use debug versions of
696
    Frameworks} option in the project run settings.
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762

    \section2 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.

    \section2 Viewing Modules

    The \gui{Modules} view displays information that the debugger plugin has
    about modules included in the application that is being debugged. A module
    is a dynamic link library (.dll) in Windows, a shared object (.so) in
    Linux, and a dynamic shared library (.dylib) in Mac OS.

    In addition, the view displays symbols within the modules and indicates
    where each module was loaded.

    Right-click the view to open a context menu that contains menu items for:

    \list

        \o  Updating the module list

        \o  Loading symbols for modules

        \o  Examining modules

        \o  Editing module files

        \o  Showing symbols in modules

        \o  Showing dependencies between modules (Windows only)

    \endlist

    By default, the \gui{Modules} view is hidden.

    \section2 Viewing Source Files

    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.

    Right-click the view to open a context menu that contains menu items for
    reloading data and opening files.

    By default, the \gui{Source Files} view is hidden.

    \section2 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.

*/


/*!
    \contentspage index.html
763
    \previouspage creator-debug-mode.html
764
765
766
767
768
    \page creator-debugging-helpers.html
    \nextpage creator-debugging-qml.html

    \title Using Debugging Helpers

769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
    Structured data, such as objects of \c class, \c struct, or \c union
    types, is displayed in the \gui{Locals and Expressions} view as part
    of a tree.
    To access sub-structures of the objects, expand the tree nodes.
    The sub-structures are presented in their in-memory order, unless
    the \gui{Sort Members of Classes and Structs Alphabetically} option
    from the context menu is selected.

    Similarly, pointers are displayed as a tree item with a single child
    item representing the target of the pointer. In case the
    context menu item
    \gui{Dereference Pointers Automatically} is selected, the pointer
    and the target are combined into a single entry, showing the name
    and the type of the pointer and the value of the target.

    This standard representation is good enough for the examination
    of simple structures, but it does usually not give enough insight into
    more complex structures, such as \c QObjects or associative containers.
    These items are internally represented by a complex arrangement of
    pointers, often highly optimized, with part of the data not directly
    accessible through either sub-structures or pointers.

    To give the user simple access also to these items, \QC employs
    so-called Debugging Helpers. Debugging Helpers come in two varieties,
    compiled, and Python based, depending on the selected
794
    \l{glossary-buildandrun-kit}{kit}.
795
796
797
798
799
800
801
802
803
804
805
806
807
808

    By default, Debugging Helpers are automatically and transparently used.
    To disable them, select \gui Tools > \gui Options > \gui Debugger >
    \gui {Locals & Expressions}, and deselect the \gui{Use Debugging Helper}
    check box.

    \QC ships with Debugging Helpers for about 80 of the most
    popular Qt classes, Standard C++ containers and smart pointers,
    covering the usual needs of a C++ application developer out-of-the-box.

    The following sections describe how to extend the debugging helpers
    to your own data types.


809
810
811
812
813
814
    There are two approaches to displaying complex data types. The first and
    original one is to use debugging helpers based on C++. While it has been
    superseded on most  platforms by the more robust and more flexible second
    approch that uses Python scripting, it is the only feasible one on
    Windows/MSVC, Mac OS, and old Linux distributions. Moreover, this approach
    is automatically chosen as fallback if the Python based approach fails.
815
816
817
818
819
820
821

    \section1 Debugging Helpers Based on C++

    During debugging with the C++ based debugging helpers,
    \QC dynamically loads a helper library in form of a DLL or a
    shared object into the debugged process.
    The \QSDK package already contains a prebuilt debugging helper
822
823
    library. To create your own debugging helper library, select \gui{Tools >
    Options > Build & Run > Qt Versions}. As the internal data
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
    structures of Qt can change between versions, the debugging helper
    library is built for each Qt version.


    \section1 Debugging Helpers Based on Python

    \QC uses GDB builds that enable Python scripting to display
    information in the \gui {Locals and Expressions} view. When Python scripting
    is used, code (Debugging helpers) does not need to be injected into the
    debugged process to nicely display QStringList or \c std::map contents, for
    example.

    The code injection caused problems and put an extra stress on the debugged
    process. You can now easily extend the debugging helpers to other types. No
    compilation is required, just adding a few lines of Python.

    Python scripting vastly reduces the communication overhead compared
    with the previous solution. However, there are some obstacles:

    \list

        \o  There is no Python-enabled GDB for Mac OS. Mac OS continues
            injection with C++ based debugging helpers.

        \o  There is no GDB to communicate with MSVC compiled applications on
            Windows. So information can be displayed nicely only in a limited
            fashion by using a cdb extension DLL.

    \endlist

    \section2 Extending the Python Based Debugging Helpers

    On platforms featuring a Python-enabled version of the GDB debugger,
    the data extraction is done by a Python script. This is more robust
    as the script execution is separated from the debugged process. It
    is also easier to extend as the script is less dependent on the
    actual Qt version and does not need compilation.

    To extend the shipped Python based debugging helpers for custom types,
    define one Python function per user defined type in the
    GDB startup file. By default, the following startup file is used:
    \c{~/.gdbinit}. To use another file, select \gui {Tools > Options >
    Debugger > GDB}
    and specify a filename in the \gui {GDB startup script} field.

    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 value of type \c gdb.Value

    \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 Expressions} view.

    Example:

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

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

        innerType = templateArgument(value.type, 0)
        d.putItemCount(size)
        d.putNumChild(size)
        if d.isExpanded():
            p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
            charPtr = lookupType("char").pointer()
            d.putField("size", size)
            with Children(d, size, maxNumChild=2000, childType=innerType, addrBase=p,
                    addrStep=(p+1).cast(charPtr) - p.cast(charPtr)):
                for i in d.childRange():
                    d.putSubItem(i, p.dereference())
                    p += 1
    \endcode

    \section2 Dumper Class

    For each line in the \gui{Locals and Expressions} view, a string like the
    following needs to be created and channeled to the debugger plugin.
    \code
    "{iname='some internal name',           # optional
      addr='object address in memory',      # optional
      name='contents of the name column',   # optional
      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

    The value of the \gui{iname} field is 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. If it is not
    present, is it generated by concatenating the parent object's iname,
    a dot, and a sequential number.

    The value of the\gui{name} field is displayed in the \gui{name} column
    of the view. If it is not specified, a simple number in brackets
    is used instead.

    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 member functions of the \gui{Dumper} class are the following:

    \list

        \o  \gui{__init__(self)} - Initializes the output to an empty string and
            empties the child stack. This should not be used in user code.

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

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

        \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, priority=0)} - Appends a field \c {type=''}
            unless the \a type coincides with the parent's default child type or
            \c putType was already called for the current item with a higher
            value of \c priority.

        \o  \gui{putBetterType(self, type)} - Overrides the last recorded
            \c 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()} - Checks whether the current item
            is expanded in the view.

        \o  \gui{putIntItem(self, name, value)} - Equivalent to:
            \code
            with SubItem(self, name):
                self.putValue(value)
                self.putAddress(value.address)
                self.putType("int")
                self.putNumChild(0)
            \endcode

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

        \o  \gui{putCallItem(self, name, value, func, *args)} -
            Uses GDB to call the function \c func on the value specified by
1050
            \a {value} and output the resulting item.
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122

        \o  \gui{putItem(self, value)} - 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{putSubItem(self, component, value)} - Equivalent to:
            \code
            with SubItem(self, component):
                self.putItem(value)
            \endcode

            Exceptions raised by nested function calls are caught and all
            output produced by \c putItem 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, maxNumChild = None, addrBase = None,
    addrStep = None)} uses one mandatory argument and several
    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 maxNumChild is specified, only that many children are displayed.
    This should be used when dumping container contents that might take
    overly long otherwise. The parameters \c addrBase and \c addrStep
    can be used to reduce the amount of data produced by the child dumpers.
    Address printing for the \e{n}th child item will be suppressed if its address
    equals with \e{addrBase + n * addrStep}.

    Example:
    \code
    d.putNumChild(2)  # Annouce children to make the item expandable in the view.
    if d.isExpanded():
        with Children(d):
            with SubItem(d):
                d.putName("key")
                d.putItem(key)
            with SubItem(d):
                d.putName("value")
                d.putItem(value)
    \endcode

    Note that this can be written more conveniently as:
    \code
    d.putNumChild(2)
    if d.isExpanded():
        with Children(d):
            d.putSubItem("key", key)
            d.putSubItem("value", value)
    \endcode


    \section1 Debugging Helpers for QML

    The debugging helpers for QML provide you with code completion for custom modules
    (\c qmldump) and debugging Qt Quick UI projects (\c qmlobserver).

    You have to build the QML Inspector once for each Qt version that you want
    to debug
1123
    with. Select \gui{Tools > Options > Build & Run > Qt Versions}.
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142

    \note QML Inspector requires Qt 4.7.1 or later.

    \section1 Enabling Debugging Helpers for Qt's Bootstrapped Applications

    Qt's bootstrapped applications (such as moc and qmake) are built in a way
    that is incompatible with the default build of the debugging helpers. To
    work around this, add \c{dumper.cpp} to the compiled sources in the
    application Makefile.

    Choose \gui {Tools > Options > Debugger > Debugging Helper > Use debugging
    helper from custom location}, and specify an invalid location, such as
    \c{/dev/null}.

*/


/*!
    \contentspage index.html
1143
    \previouspage creator-qml-debugging-example.html
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
    \page creator-troubleshooting-debugging.html
    \nextpage creator-analyze-mode.html

    \title Troubleshooting Debugger

    This section lists some typical problems that you might encounter while
    debugging and solutions to them.

    \section1 Cannot Launch Debugger

    Some anti-virus applications do not allow debuggers to retrieve data. For
    example, on Windows, launching the debugger might fail with the following
    message if the Avira AntiVir is installed on the development PC: \e{The
    inferior stopped because it received a signal from the operating system.
    Signal name:? signal meaning: Unknown signal.}

    Some versions of Avira AntiVir Desktop-Products contain known issues in
    various development environments, including \QC. To fix the problem,
    Avira instructs you to update to version \c {avipbb.sys 10.0.22.22}. For
    more information, see
    \l{http://www.avira.com/en/support-for-business-knowledgebase-detail/kbid/805}
    {Restricted Usability of IDE/Debuggers since 2010-12-08}.

   \section1 Debugger Does Not Hit Breakpoints

    You might have created a release build that does not contain debug
    information. A GNU Compiler Collection (GCC) debug build has the \c {-g}
    option on the compiler command line. Check that this option is present in
    the \gui {Compile Output} pane. If it is not, adjust your build settings
    in the \gui {Projects} mode.

    \section1 Debugger Does Not Work

    If the debugger does not work properly, try the following:

    \list 1

        \o  Make sure you use at least \QC 2.1.

        \o  Make sure the debugger is set up properly. For more information,
            see \l{Setting Up Debugger}.

        \o  In the \gui Debug mode, select \gui {Windows > Views > Debugger
            Log} to open the \gui {Debugger Log} view. Browse the contents of
            the pane on the right hand side to find out what went wrong.
            Always attach the contents of the pane to debugger-related
            questions to the \QC mailing list (qt-creator@trolltech.com)
            or paste them to
            \l{http://creator.pastebin.com}{creator.pastebin.com} before
            asking questions in the IRC (on the #qt-creator channel at
            FreeNode).

    \endlist

    \section1 Pointer Variable Members Are Not Displayed Directly

    When you use the \gui {Locals and Expressions} view to inspect a pointer
    variable and expand the variable tree item, another tree item level
    is displayed. To directly display the members of the pointer variable,
    select \gui {Dereference Pointers Automatically} in the context menu in the
    \gui {Locals and Expressions} view.

    \section1 Structure Members Are Not Sorted According to Structure Layout

    By default, structure members are displayed in alphabetic order.
    To inspect the real layout in memory, deselect \gui {Sort Members of
    Classes and Structs Alphabetically} in the context menu in the
    \gui {Locals and Expressions} view.

    \section1 Built-in Debugger Is Slow During Startup and Runtime

1215
1216
1217
1218
1219
1220
    The part of the slowness that is related to the loading of
    debug information is hard to avoid. Another part stems from
    maintaining breakpoints inside the debugger (under some circumstances
    all breakpoints need to be inserted and removed again for each step)
    and the evaluation of expressions after each step. We recommend that
    you minimize the number of breakpoints and watched expressions.
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265

    \section1 Debugger Displays <not in scope> Message

    The message is created by the debugging helpers. \QC posts an
    expression to the GDB command line to invoke the debugging helpers.
    The expression includes the address of the object to examine. This
    address might be modified by GDB before the helper function is called. It
    is unclear why and when this happens, but if it happens, the debugging
    helpers operate on wrong data and come to wrong conclusions. Most likely,
    they find garbage and declare the variable to be <not in scope>.

    \section1 Application Crashes when Debugging on Mac OS X Snow Leopard

    You must use a workaround to use the DYLD_IMAGE_SUFFIX option in the
    \gui Projects tab on Mac OS X  Snow Leopard. For more information on the
    issue, see
    \l{http://wimleers.com/blog/dyld-image-suffix-causing-havoc-on-mac-os-x-snow-leopard}
    {DYLD_IMAGE_SUFFIX causing havoc on Mac OS X Snow Leopard}.

    To use the option, enter the following commands in the Terminal
    application:
           \code
           sudo mv /usr/lib/libSystem.B_debug.dylib /usr/lib/libSystem.B_debug.dylib.backup
           sudo cp /usr/lib/libSystem.B.dylib /usr/lib/libSystem.B_debug.dylib.backup
           \endcode

     \section1 Debugger Cannot Attach to Running Process on Linux

    GDB uses \c ptrace to attach to running processes. Some Linux distributions
    do not allow this, which stops all attempts to either directly attach to an
    existing process or use the \gui {Run in terminal} option in \QC.

    The reasons for this are described in
    \l{https://wiki.ubuntu.com/SecurityTeam/Roadmap/KernelHardening#ptrace%20Protection}
    {KernelHardening}.

    However, the usefulness of this security measure seems dubious,
    because this feature can be easily disabled. With root permissions, you can
    disable the feature immediately by writing \c{0} into
    \c{/proc/sys/kernel/yama/ptrace_scope}. Even if you do not have elevated
    permissions, you can disable the feature later by adding a library that
    calls \c{prctl(0x59616d61, getppid(), 0, 0, 0);}, such as the one in
    \c{$QTCREATORDIR/lib/libptracepreload.so} to the LD_PRELOAD environment.

*/