creator-debugger.qdoc 50.9 KB
Newer Older
1
2
/****************************************************************************
**
Eike Ziller's avatar
Eike Ziller committed
3
4
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing
5
**
hjk's avatar
hjk committed
6
** This file is part of Qt Creator
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
**
**
** 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.
// **********************************************************************

/*!
26
    \contentspage {Qt Creator Manual}
27
    \previouspage creator-testing.html
28
    \page creator-debugging.html
29
    \nextpage creator-debugger-engines.html
30
31
32
33
34

    \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),
35
36
    the Microsoft Console Debugger (CDB), a QML/JavaScript debugger, and the
    debugger of the low level virtual machine (LLVM) project, LLDB.
37
38
39

    \list

40
        \li \l{Setting Up Debugger}
41

hjk's avatar
hjk committed
42
            The debugger plugin automatically selects a suitable
43
44
45
            native debugger for each \l{glossary-buildandrun-kit}{kit} from the
            ones found on your system. You can edit the kits to override this
            choice.
46

47
        \li \l{Launching the Debugger}
48

hjk's avatar
hjk committed
49
50
51
            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
52
            options are available in the \uicontrol{Debug} > \uicontrol{Start Debugging}
hjk's avatar
hjk committed
53
            menu.
54

55
        \li \l{Interacting with the Debugger}
56

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

60
        \li \l{Using Debugging Helpers}
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
65
            helpers}.
66

67
        \li \l{Debugging Qt Quick Projects}
68

hjk's avatar
hjk committed
69
            When debugging a Qt Quick application, you can inspect the state
70
            of the application while debugging JavaScript functions. You can set
71
            breakpoints, view call stack trace, and examine locals and
72
73
74
            expressions. While the application is running, you can inspect QML
            objects and user interfaces, as well as execute JavaScript
            expressions.
75

76
        \li \l{Debugging a C++ Example Application}
hjk's avatar
hjk committed
77
78
79

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

80
        \li \l{Debugging a Qt Quick Example Application}
hjk's avatar
hjk committed
81
82
83

            Illustrates how to debug Qt Quick applications in \QC.

84
        \li \l{Troubleshooting Debugger}
85

86
87
            If you encounter problems while debugging, check for possible
            solutions to them.
88
89
90
91
92
93
    \endlist

*/


/*!
94
    \contentspage {Qt Creator Manual}
95
    \previouspage creator-debugger-engines.html
96
97
98
99
100
    \page creator-debugger-operating-modes.html
    \nextpage creator-debug-mode.html

    \title Launching the Debugger

hjk's avatar
hjk committed
101
    To start an application from an open project under the control
102
    of a debugger, press the \uicontrol Debug button in the lower left corner
hjk's avatar
hjk committed
103
104
    of the main view, or press \key{F5}.

105
    \QC checks whether the compiled program is up-to-date, and rebuilds
106
107
108
    and deploys it if the \uicontrol{Always build project before deploying it} and
    \uicontrol{Always deploy before running} options are selected in the
    \uicontrol{Build and Run} options.
hjk's avatar
hjk committed
109
110
111

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

hjk's avatar
hjk committed
113
    \note Starting a C++ program in the debugger can take a long
114
115
116
117
118
119
    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
120
    The debugger plugin can run the native debuggers in various operating
121
122
    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
123
124
    platform.

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

134
    Change the run configuration
135
136
    parameters (such as \uicontrol{Run in Terminal}) in the run settings of the
    project, or select options from the \uicontrol{Debug} > \uicontrol{Start Debugging}
137
    menu to select other modes of operation.
138

hjk's avatar
hjk committed
139
    The debugger can run in the following modes:
140
141
142

    \list

143
       \li \b{Start Internal} to debug applications developed inside
144
            \QC such as a Qt based GUI application.
145

146
       \li \b{Start External} to start and debug processes
147
148
            without a proper \QC project setup, either locally or
            on a remote machine.
149

150
       \li \b{Attach} to debug processes already started and
151
152
            running outside \QC, either locally or on a
            remote machine.
153

154
       \li \b{Core} to debug crashed processes on Unix.
155

156
       \li \b{Post-mortem} to debug crashed processes on Windows.
157
158
159

    \endlist

160
    \section2 Launching in Start Internal Mode
161

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

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

169
    To launch the debugger in Start Internal mode, click the
170
    \uicontrol {Start Debugging} button for the active project.
171

172
173
    You can specify breakpoints before or after launching the debugger.
    For more information, see \l{Setting Breakpoints}.
174

175
    \section2 Launching in Start External Mode
176

177
    To run any executable already present on your local or a remote machine
178
    without using a project, select \uicontrol{Debug > Start Debugging
179
    > Start and Debug External Application}.
180

181
    \section2 Launching in Attach Mode
182

183
184
    To attach the debugger to an application already running on your
    local or a remote machine, select
185
    \uicontrol {Debug > Start Debugging > Attach to Running Application},
186
187
    and then select a process by its name or process ID to attach to.

hjk's avatar
hjk committed
188
189
    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
Sergio Ahumada's avatar
Sergio Ahumada committed
190
    and stepping through the code easier.
hjk's avatar
hjk committed
191

192
193
    You can specify breakpoints before or after attaching the
    debugger to the application.
hjk's avatar
hjk committed
194
195
    For more information, see \l{Setting Breakpoints}.

196
197
198
199
200
201
202
203
204
205
206
207
208
    \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

209
    To launch the debugger in the core mode, select \uicontrol{Debug > Start
210
    Debugging > Load Core File}.
211
212
213
214
215
216
217
218
219
220
221
222

    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
223
224
    \uicontrol Tools > \uicontrol Options > \uicontrol Debugger >
    \uicontrol General > \uicontrol {Use QtCreator for post-mortem debugging}.
225
226

    You can launch the debugger in the post-mortem mode if an application
227
    crashes on Windows. Click the \uicontrol {Debug in \QC} button in the error
228
229
    message that is displayed by the Windows operating system.

230

231
    \section1 Remote Debugging
232

233
234
235
236
    \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
237
238
    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
239
    on embedded Linux). The host side typically
Leena Miettinen's avatar
Leena Miettinen committed
240
241
242
    consists of \QC itself, often with the help of an external process, such as
    GDB or CDB.

hjk's avatar
hjk committed
243
    While this setup might look daunting, it is mostly invisible to
244
    the user of \QC. To start debugging on a remote target with the
245
246
    necessary helper processes running, select the corresponding
    \l{glossary-buildandrun-kit}{kit} in
247
248
    \uicontrol{Projects > Build & Run}, and then select a function to start remote
    debugging in the \uicontrol{Debug > Start Debugging} menu.
hjk's avatar
hjk committed
249
250
251

    Special use cases, such as attaching to a running process on the
    target, might still require manual setup.
252
253
254

    \section3 Using GDB

hjk's avatar
hjk committed
255
256
257
    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.
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275

    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

276
        \li Select \uicontrol {Debug > Start Debugging > Attach to Running
hjk's avatar
hjk committed
277
            Debug Server}.
278

279
        \li In the \uicontrol {Host and port} field, enter the name of the remote
280
281
            machine and the port number to use.

282
        \li Select \uicontrol{OK} to start debugging.
283
284
285
286
287
288
289
290
291
292
293
294
295

    \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

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

300
        \li Copy the \QC CDB extension library from the Qt installation
301
302
303
304
305
306
307
            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

308
            \li \c {\lib\qtcreatorcdbext32\qtcreatorcdbext.dll} (32 bit)
309

310
            \li \c {\lib\qtcreatorcdbext64\qtcreatorcdbext.dll} (64 bit)
311
312
313

        \endlist

314
        \li Set the _NT_DEBUGGER_EXTENSION_PATH environment variable to point
315
316
            to that folder.

317
        \li To use TCP/IP as communication protocol, launch remote CDB as
318
319
320
321
322
323
            follows:

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

324
        \li On the local machine running \QC, select
325
            \uicontrol {Debug > Start Debugging > Attach to Remote CDB Session}
326
327


328
        \li In the \uicontrol Connection field enter the connection parameters.
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
            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

348
            \li  Click \uicontrol{OK} to start debugging.
349
350
351
352
353
354

    \endlist
*/


/*!
355
    \contentspage {Qt Creator Manual}
356
357
    \previouspage creator-debugger-operating-modes.html
    \page creator-debug-mode.html
358
    \nextpage creator-debugging-helpers.html
359
360
361

    \title Interacting with the Debugger

362
    You can use the \QC \uicontrol Debug mode to inspect the state of your application
363
364
365
366
367
    while debugging. You can interact with the debugger in several ways,
    including the following:

    \list

368
        \li Go through a program line-by-line or instruction-by-instruction.
369

370
        \li Interrupt running programs.
371

372
        \li Set breakpoints.
373

374
        \li Examine the contents of the call stack.
375

376
        \li Examine and modify contents of local and global variables.
377

378
        \li Examine and modify registers and memory contents of
hjk's avatar
hjk committed
379
            the debugged program.
380

381
        \li Examine the list of loaded shared libraries.
382

383
        \li Disassemble sections of code.
hjk's avatar
hjk committed
384

385
        \li Create snapshots of the current state of the debugged program
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
            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

405
    In \uicontrol Debug mode, you can use several views to interact with the
406
407
408
    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,
409
    select \uicontrol {Window > Views}, and then select views to display or hide.
410
411
    Alternatively, you can enable or disable views from the context menu
    of the title bar of any visible debugger view.
412
413
414

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

415
416
    You can drag and drop the views in \QD to new positions on the screen.
    The size and position of views are saved for future sessions. Select
417
    \uicontrol {Window > Views > Reset to Default Layout} to reset the views to
418
419
420
421
    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
422
    selecting \uicontrol{Debug} > \uicontrol {Interrupt}. The program is automatically
423
424
425
426
427
428
    interrupted when a breakpoint is hit.

    Once the program stops, \QC:

    \list

429
        \li Retrieves data representing the call stack at the program's current
430
431
            position.

432
        \li Retrieves the contents of local variables.
433

434
        \li Examines \uicontrol Expressions.
435

436
        \li Updates the \uicontrol Registers, \uicontrol Modules, and \uicontrol Disassembler
437
438
439
440
            views if you are debugging the C++ based applications.

    \endlist

441
    You can use the \uicontrol Debug mode views to examine the data in more detail.
442
443
444
445
446

    You can use the following keyboard shortcuts:

    \list

447
       \li To finish debugging, press \key{Shift+F5}.
448

449
450
       \li To execute a line of code as a whole, press \key{F10}
           (\key{Command+Shift+O} on OS X).
451

452
453
       \li To step into a function or a subfunction, press \key{F11}
           (\key{Command+Shift+I} on OS X).
454

455
456
       \li To leave the current function or subfunction, press \key{Shift+F11}
           (\key{Command+Shift+T} on OS X).
457

458
       \li To continue running the program, press \key{F5}.
459

Leena Miettinen's avatar
Leena Miettinen committed
460
       \li To run to the line containing the cursor, press \key{Ctrl+F10}
461
462
           (\key{Shift+F8} on OS X).

463
       \li To run to the selected function when you are stepping into a nested
464
465
466
467
468
469
470
471
472
473
474
475
476
477
           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.

478
479
    \QC shows breakpoints in the \uicontrol{Breakpoints} view which is enabled
    by default. The \uicontrol{Breakpoints} view is also accessible when the debugger
480
481
482
483
484
485
486
487
    and the program being debugged is not running.

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

    You can associate breakpoints with:

    \list

488
        \li Source code files and lines
489

490
        \li Functions
491

492
        \li Addresses
493

494
        \li Throwing and catching exceptions
495

496
        \li Executing and forking processes
497

498
        \li Executing some system calls
499

500
        \li Changes in a block of memory at a particular address when a
501
502
503
504
505
506
507
            program is running

    \endlist

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

508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
    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 Adding Breakpoints

    To add breakpoints:

    \list 1

        \li Add a new breakpoint in one of the following ways:

            \list

                \li In the code editor, click the left margin or press \key F9
523
                    (\key F8 for OS X) at a particular line you want the
524
525
                    program to stop.

526
                \li In the \uicontrol Breakpoints view, double-click in the empty
527
528
                    part of the view.

529
                \li In the \uicontrol Breakpoints view, select \uicontrol {Add Breakpoint}
530
531
532
533
                    in the context menu.

            \endlist

534
        \li In the \uicontrol {Breakpoint type} field, select the location in the
535
536
            program code where you want the program to stop. The other options
            to specify depend on the selected location.
537

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

540
        \li In the \uicontrol Condition field, set the condition to be evaluated
541
542
            before stopping at the breakpoint if the condition evaluates as
            true.
543

544
        \li In the \uicontrol Ignore field, specify the number of times that the
545
546
            breakpoint is ignored before the program stops.

547
        \li In the \uicontrol Commands field, specify the commands to execute when
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
            the program stops; one command on a line. GDB executes the commands
            in the order in which they are specified.

    \endlist

    For more information on breakpoints, see
    \l{http://sourceware.org/gdb/onlinedocs/gdb/Breakpoints.html#Breakpoints}
    {Breakpoints, Watchpoints, and Catchpoints} in GDB documentation.

    \section2 Moving Breakpoints

    To move the breakpoint, drag and drop a breakpoint marker to another line.

    \section2 Deleting Breakpoints

    To delete breakpoints:
564
565
566

    \list

567
        \li Click the breakpoint marker in the text editor.
568

569
        \li Select the breakpoint in the \uicontrol Breakpoints view and press
570
571
            \key{Delete}.

572
573
        \li Select \uicontrol{Delete Breakpoint} in the context menu in the
            \uicontrol Breakpoints view.
574
575
576
577
578

    \endlist

    \section2 Setting Data Breakpoints

579
580
581
    A \e {data breakpoint} stops the program when data is read or written at the
    specified address.

582
583
584
585
    To set a data breakpoint at an address:

    \list 1

586
587
        \li Right-click in the \uicontrol Breakpoints view to open the context menu,
            and select \uicontrol {Add Breakpoint}.
588

589
        \li In the \uicontrol {Breakpoint type} field, select \uicontrol {Break on data
590
591
            access at fixed address}.

592
        \li In the \uicontrol Address field, specify the address of the memory block.
593

594
        \li Select \uicontrol OK.
595
596
597

    \endlist

598
599
    If the address is displayed in the \uicontrol {Locals and Expressions} view, you
    can select \uicontrol {Add Data Breakpoint at Object's Address} in the context
600
601
602
603
604
605
606
607
608
    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
609
    file. This data is shown in the \uicontrol Stack view.
610
611
612
613
614
615

    \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
616
    corresponding source locations are grayed out in the \uicontrol{Stack} view.
617
618

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

Leena Miettinen's avatar
Leena Miettinen committed
623
    To find out which QML file is causing a Qt Quick 2 application to crash,
624
    select \uicontrol {Load QML Stack} in the context menu in the \uicontrol{Stack} view.
Leena Miettinen's avatar
Leena Miettinen committed
625
626
627
628
    The debugger tries to retrieve the JavaScript stack from the stopped
    executable and prepends the frames to the C++ frames, should it find any.
    You can click a frame in the QML stack to open the QML file in the editor.

629
630
    \section1 Locals and Expressions

631
    The Locals and Expressions view consists of three parts: the
632
633
634
    \uicontrol{Locals} pane at the top, the \uicontrol{Return Value} pane in the middle,
    and the \uicontrol{Expressions} pane at the bottom. The \uicontrol{Return Value}
    and \uicontrol{Expression} panes are only visible if they are not empty.
635
636
637

    \image qtcreator-locals-expressions.png "Locals and Expressions view"

638
639
    Whenever a program stops under the control of the debugger, it retrieves
    information about the topmost stack frame and displays it in the
640
    \uicontrol{Locals and Expressions} view. The \uicontrol{Locals} pane shows
641
642
643
    information about parameters of the function in that
    frame as well as the local variables. If the last operation in
    the debugger was returning from a function after pressing
644
    \key{Shift+F11}, the \uicontrol{Return Value} pane displays the value
645
646
647
    returned by the function.

    To compute values of arithmetic expressions or function
648
    calls, use expression evaluators in the \uicontrol{Expressions} pane.
649
    To insert a new expression evaluator, either double-click on an
650
651
    empty part of the \uicontrol{Locals and Expressions} view, or select
    \uicontrol{Add New Expression Evaluator} from the context menu, or
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
    drag and drop an expression from the code editor.

    \note Expression evaluators are powerful, but slow down debugger
    operation significantly. It is advisable to not use them excessively,
    and to remove unneeded expression evaluators as soon as possible.

    Expression evaluators are re-evaluated whenever the current
    frame changes. Note that functions used in the expressions are
    called each time, even if they have side-effects.

    All backends support simple C and C++ expressions. Functions
    can be called only if they are actually compiled into the
    debugged executable or a library used by the executable.
    Most notably, inlined functions such as most \c{operator[]}
    implementations of standard containers are typically \e{not}
    available.

    When using GDB or LLDB as backend, a special ranged
    syntax can be used to display multiple values with one
    expression. A sub-expression of form \c{foo[a..b]} is
    split into a sequence of individually evaluated expressions
    \c{foo[a], ..., foo[b]}.

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


    \table
        \row
683
            \li \b{Note:}
684
685

        \row
686
687
            \li GDB and LLDB, and therefore \QC's debugger, work for optimized
                builds on Linux and OS X. Optimization can lead to
688
                re-ordering of instructions or removal of some local variables,
689
                causing the \uicontrol{Locals and Expressions} view to show unexpected
690
691
                data.
        \row
692
            \li The debug information provided by GCC does not include enough
693
694
695
696
                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
697
                \uicontrol {not in scope}. Not all uninitialized objects, however, can be
698
699
700
701
                recognized as such.
    \endtable


702
    The \uicontrol{Locals and Expressions} view also provides access to the most
703
704
705
706
707
708
709
710
711
712
    powerful feature of the debugger: comprehensive display of data belonging
    to Qt's basic objects.
    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.

713
    Right-click in the \uicontrol{Locals and Expressions} view to open a context
714
715
716
717
718
719
720
721
    menu that provides additional options for viewing data. The available
    options depend on the type of the current items, and are provided by the
    \l{Using Debugging Helpers}{Debugging Helpers}. Typically, string-like data,
    such as \c{QByteArray} and \c{std::string}, offer a selection of encodings,
    as well as the possibility to use a full editor window. Map-like data, such
    as \c{QMap}, \c{QHash}, and \c{std::map}, offer a compact option using the
    \c{name} column for keys, resulting in a concise display of containers with
    short keys, such as numbers or short strings. For example, to expand all the
722
    values of QMap, select \uicontrol {Change Local Display Format} > \uicontrol Compact.
723

724
    You can use the \uicontrol{Locals and Expressions} view to change the contents of
725
726
    variables of simple data types, for example, \c int, \c float, QString
    and \c std::string when the
727
    program is interrupted. To do so, click the \uicontrol Value column, modify
728
729
    the value with the inplace editor, and press \key Enter (or \key Return).

730
    To change the complete contents of QVector or \c std::vector values,
731
    type all values separated by commas into the \uicontrol Value column of
732
733
    the main entry.

734
735
736
737
738
739
740
741
742
    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
743
    pane of the \uicontrol {Debugger Log} view for that purpose. When you press
Leena Miettinen's avatar
Leena Miettinen committed
744
    \key {Ctrl+Enter}, the contents of the line under the text cursor
745
746
    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
747
    right pane of the \uicontrol {Debugger Log} view.
748
749
750
751

    \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
752
    in the \uicontrol{Locals and Expressions} view.
753
754
755
756
757
758
759
760
761
762
763
764

    \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
765
766
    the binary that belongs to a core file. To connect to a debug server,
    specify the server location and port number.
767
768
769
770
771

    For example:

    \list

772
        \li  \c {C:\qtcreator\bin>qtcreator -debug 2000}
773
774
775
        \li  \c {C:\qtcreator\bin>qtcreator -debug core=core.2000}
        \li  \c {C:\qtcreator\bin>qtcreator -debug some.exe,core=core}
        \li  \c {C:\qtcreator\bin>qtcreator -debug server=some.dot.com:4251}
776
777
778
779
780

    \endlist

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

781
    \section2 Stepping into Frameworks in OS X
782

783
    In OS X, external libraries are usually built into so-called Frameworks,
784
    which may contain both release and debug versions of the library. When you run
785
    applications on the OS X desktop, the release version of Frameworks is used
786
    by default. To step into Frameworks, select the \uicontrol {Use debug versions of
787
    Frameworks} option in the project run settings.
788
789
790

    \section2 Viewing Threads

791
792
793
    If a multi-threaded program is interrupted, the \uicontrol Threads view or the
    combobox named \uicontrol Threads in the debugger status bar can be used to
    switch from one thread to another. The \uicontrol Stack view adjusts itself
794
795
796
797
    accordingly.

    \section2 Viewing Modules

798
    The \uicontrol{Modules} view displays information that the debugger plugin has
799
800
    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
801
    Linux, and a dynamic shared library (.dylib) in OS X.
802
803
804
805
806
807
808
809

    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

810
        \li Updating the module list
811

812
        \li Loading symbols for modules
813

814
        \li Examining modules
815

816
        \li Editing module files
817

818
        \li Showing symbols in modules
819

820
        \li Showing dependencies between modules (Windows only)
821
822
823

    \endlist

824
    By default, the \uicontrol{Modules} view is hidden.
825
826
827

    \section2 Viewing Source Files

828
    The \uicontrol{Source Files} view lists all the source files included in the project.
829
830
831
832
833
834
835
    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.

836
    By default, the \uicontrol{Source Files} view is hidden.
837
838
839

    \section2 Viewing Disassembled Code and Register State

840
841
    The \uicontrol{Disassembler} view displays disassembled code for the current
    function. The \uicontrol{Registers} view displays the current state of the CPU's
842
843
    registers.

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

849
850
851
852
853
    \section2 Creating Snapshots

    A snapshot contains the complete state of the debugged program
    at a time, including the full memory contents.

854
855
    To create snapshots of a debugged program, select \uicontrol {Create Snapshot} in
    the context menu in the \uicontrol Snapshots view.
856

857
    Double-click on entries in the \uicontrol Snapshots view to switch between
858
859
860
    snapshots. The debugger views are updated to reflect the
    state of the program at time of taking the snapshot.

861
862
863
864
*/


/*!
865
    \contentspage {Qt Creator Manual}
866
    \previouspage creator-debug-mode.html
867
868
869
870
871
    \page creator-debugging-helpers.html
    \nextpage creator-debugging-qml.html

    \title Using Debugging Helpers

872
    Structured data, such as objects of \c class, \c struct, or \c union
873
    types, is displayed in the \uicontrol{Locals and Expressions} view as part
874
875
876
    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
877
    the \uicontrol{Sort Members of Classes and Structs Alphabetically} option
878
879
880
881
882
    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
883
    \uicontrol{Dereference Pointers Automatically} is selected, the pointer
884
885
886
887
888
889
890
891
892
893
894
    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
895
896
897
898
899
    so-called \e{debugging helpers}. Debugging helpers come in two varieties,
    a compiled one, for use with the CDB backend, and a set of Python
    scripts for use with the GDB and LLDB backends.

    Debugging helpers are always automatically used. To force a plain
900
901
902
    C-like display of structures, select \uicontrol Tools > \uicontrol Options >
    \uicontrol Debugger > \uicontrol {Locals & Expressions}, and then deselect the
    \uicontrol{Use Debugging Helper} check box. For GDB
903
904
905
906
907
908
    and LLDB this will still use the Python scripts, but generate
    more basic output. To force plain display for a single object
    or for all objects of a given type, select the corresponding
    option from the context menu.

    \QC ships with debugging helpers for more than 130 of the most
909
910
911
    popular Qt classes, Standard C++ containers and smart pointers,
    covering the usual needs of a C++ application developer out-of-the-box.

912
    \section1 Extending GDB and LLDB Debugging Helpers
913

914
    When using either GDB or LLDB as the debugging backend, \QC uses Python
915
    scripts to display information in the \uicontrol {Locals and Expressions} view.
916

917
918
919
920
921
    You can easily extend these scripts to cover your own types,
    using the same code for both the GDB and the LLDB backend.
    No compilation is required, just adding a few lines of Python.
    The scripts can address multiple versions of Qt, or of your own
    library, at the same time.
922

923
924
    To extend the shipped Python based debugging helpers for custom
    types, add debugging helper implementations to the GDB startup file
925
926
    \c{~/.gdbinit}, or specify them directly in the \uicontrol{Additional
    Startup Commands} in \uicontrol {Tools > Options > Debugger > GDB}.
927
928
929
930
931
932
933

    The implementation of a debugging helper typically
    consists of a single Python function, which needs to be named
    \c{qdump__NS__Foo}, where \c{NS::Foo} is the class
    or class template to be examined. Note that the \c{::} scope
    resolution operator is replaced by double underscores \c{__}.
    Nested namespaces are possible.
934
935
936
937
938
939
940

    The debugger plugin calls this function whenever you want to
    display an object of this type. The function is passed the following
    parameters:

    \list

941
942
943
       \li \c d of type \c Dumper, an object containing current
           settings and providing facilities to build up an object
           representing part of the Locals and Expressions view,
944

945
946
947
948
       \li \c value of type \c Value, wrapping either a
           \l{https://sourceware.org/gdb/onlinedocs/gdb/Values-From-Inferior.html}{gdb.Value}
           or an
           \l{http://lldb.llvm.org/cpp_reference/html/classlldb_1_1SBValue.html}{lldb.SBValue}.
949
950
951

    \endlist

952
953
    The \c{qdump__*} function has to feed the Dumper object with certain
    information which is used to build up the object and its children's
954
    display in the \uicontrol{Locals and Expressions} view.
955
956
957
958

    Example:

    \code
959
960
961
    def qdump__QFiniteStack(d, value):
        alloc = int(value["_alloc"])
        size = int(value["_size"])
962
963
964
        d.putItemCount(size)
        d.putNumChild(size)
        if d.isExpanded():
965
966
            innerType = d.templateArgument(value.type, 0)
            d.putArrayData(innerType, value["_array"], size)
967
968
    \endcode

969
970
971
972
    \note To create dumper functions usable with both LLDB and GDB
    backends, avoid direct access to the \c gdb.* and \c lldb.* namespaces
    and use functions of the \c Dumper class instead.

973
974
    \section2 Dumper Class

975
    For each line in the \uicontrol{Locals and Expressions} view, a string like the
976
977
    following needs to be created and channeled to the debugger plugin.
    \code
978
     {iname='some internal name',           # optional
979
980
981
982
983
984
985
986
987
988
989
990
991
      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',
           },

992
      ]}
993
994
    \endcode

995
    The value of the \c iname field is the internal name of the object,
996
997
998
999
1000
    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.

1001
    The value of the \c name field is displayed in the \uicontrol{Name} column
1002
1003
1004
    of the view. If it is not specified, a simple number in brackets
    is used instead.

1005
    While in theory you can build up the entire string above manually, it is
1006
1007
1008
    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,
1009
    enums, known and unknown structs as well as some convenience functions to
1010
1011
    handle common situations.

1012
    The member functions of the \c Dumper class are the following:
1013
1014
1015

    \list

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

1019
        \li \c{put(self, value)} - Low level function to directly append to the
1020
1021
            output string. That is also the fastest way to append output.

1022
        \li \c{putField(self, name, value)} - Appends a \c{name='value'} field.
1023

1024
        \li \c{childRange(self)} - Returns the range of children specified in
1025
1026
            the current \c Children scope.

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

1030
        \li \c{putName(self, name)} - Appends a \c {name=''} field.
1031

1032
        \li \c{putType(self, type, priority=0)} - Appends a field \c {type=''}
1033
1034
1035
1036
            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.

1037
        \li \c{putBetterType(self, type)} - Overrides the last recorded
1038
1039
            \c type.

1040
        \li \c{putNumChild(self, numchild)} - Appends a field \c {numchild=''}
1041
1042
1043
            unless the \c numchild coincides with the parent's default child
            numchild value.

1044
        \li \c{putValue(self, value, encoding = None)} - Append a file \c {value=''},
1045
1046
1047
1048
1049
1050
1051
1052
1053
            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

1054
            \li 0: unencoded 8 bit data, interpreted as Latin1.
1055

1056
            \li 1: base64 encoded 8 bit data, used for QByteArray,
1057
1058
                double quotes are added.

1059
            \li 2: base64 encoded 16 bit data, used for QString,
1060
1061
                double quotes are added.

1062
            \li 3: base64 encoded 32 bit data,
1063
1064
                double quotes are added.

1065
            \li 4: base64 encoded 16 bit data, without quotes (see 2)
1066

1067
            \li 5: base64 encoded 8 bit data, without quotes (see 1)
1068

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

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

1076
        \li \c{putStringValue(self, value)} - Encodes a QString and calls
1077
1078
            \c putValue with the correct \c encoding setting.

1079
        \li \c{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
1080
1081
            \c putValue with the correct \c encoding setting.

1082
        \li \c{isExpanded()} - Checks whether the current item
1083
1084
            is expanded in the view.

1085
        \li \c{putIntItem(self, name, value)} - Equivalent to:
1086
1087
1088
1089
1090
1091
1092
1093
            \code
            with SubItem(self, name):
                self.putValue(value)
                self.putAddress(value.address)
                self.putType("int")
                self.putNumChild(0)
            \endcode

1094
        \li \c{putBoolItem(self, name, value)} - Equivalent to:
1095
1096
1097
1098
1099
1100
1101
            \code
            with SubItem(self, name):
                self.putValue(value)
                self.putType("bool")
                self.putNumChild(0)
            \endcode

1102
        \li \c{putCallItem(self, name, value, func, *args)} -
1103
            Uses GDB to call the function \c func on the value specified by