forked from qt-creator/qt-creator
Doc: Move common debugger functions to an include file
Some debugger functions are used for both C++ and QML debugging. Putting them into an include file enables using the descriptions in both the Qt Creator Manual and Qt Design Studio Manual. Change-Id: Ief7e1e1c76a881eb6722161a1b216b3d711c6290 Reviewed-by: hjk <hjk@qt.io>
This commit is contained in:
Leena Miettinen
361
doc/src/debugger/creator-debugger-common.qdocinc
Normal file
361
doc/src/debugger/creator-debugger-common.qdocinc
Normal file
@@ -0,0 +1,361 @@
|
|||||||
|
/****************************************************************************
|
||||||
|
**
|
||||||
|
** Copyright (C) 2018 The Qt Company Ltd.
|
||||||
|
** Contact: https://www.qt.io/licensing/
|
||||||
|
**
|
||||||
|
** This file is part of the Qt Creator documentation.
|
||||||
|
**
|
||||||
|
** Commercial License Usage
|
||||||
|
** Licensees holding valid commercial Qt licenses may use this file in
|
||||||
|
** accordance with the commercial license agreement provided with the
|
||||||
|
** Software or, alternatively, in accordance with the terms contained in
|
||||||
|
** a written agreement between you and The Qt Company. For licensing terms
|
||||||
|
** and conditions see https://www.qt.io/terms-conditions. For further
|
||||||
|
** information use the contact form at https://www.qt.io/contact-us.
|
||||||
|
**
|
||||||
|
** GNU Free Documentation License Usage
|
||||||
|
** 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. Please review the following information to ensure
|
||||||
|
** the GNU Free Documentation License version 1.3 requirements
|
||||||
|
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
|
||||||
|
**
|
||||||
|
****************************************************************************/
|
||||||
|
|
||||||
|
/*!
|
||||||
|
|
||||||
|
//! [debugger-breakpoints]
|
||||||
|
|
||||||
|
\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 \uicontrol Breakpoints view which is enabled
|
||||||
|
by default. The \uicontrol 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
|
||||||
|
|
||||||
|
\li Source code files and lines
|
||||||
|
|
||||||
|
\li Functions
|
||||||
|
|
||||||
|
\li Addresses
|
||||||
|
|
||||||
|
\li Throwing and catching exceptions
|
||||||
|
|
||||||
|
\li Executing and forking processes
|
||||||
|
|
||||||
|
\li Executing some system calls
|
||||||
|
|
||||||
|
\li Changes in a block of memory at a particular address when a
|
||||||
|
program is running
|
||||||
|
|
||||||
|
\li Emitting QML signals
|
||||||
|
|
||||||
|
\li Throwing JavaScript exceptions
|
||||||
|
|
||||||
|
\endlist
|
||||||
|
|
||||||
|
The interruption of a program by a breakpoint can be restricted with certain
|
||||||
|
conditions.
|
||||||
|
|
||||||
|
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
|
||||||
|
(\key F8 for \macos) at a particular line you want the
|
||||||
|
program to stop.
|
||||||
|
|
||||||
|
\li In the \uicontrol Breakpoints view, double-click in the empty
|
||||||
|
part of the view.
|
||||||
|
|
||||||
|
\li In the \uicontrol Breakpoints view, select
|
||||||
|
\uicontrol {Add Breakpoint} in the context menu.
|
||||||
|
|
||||||
|
\endlist
|
||||||
|
|
||||||
|
\li In the \uicontrol {Breakpoint type} field, select the location in the
|
||||||
|
program code where you want the program to stop. The other options
|
||||||
|
to specify depend on the selected location.
|
||||||
|
|
||||||
|
\image qtcreator-add-breakpoint.png "Add Breakpoints" dialog
|
||||||
|
|
||||||
|
\li In the \uicontrol Condition field, set the condition to be evaluated
|
||||||
|
before stopping at the breakpoint if the condition evaluates as
|
||||||
|
true.
|
||||||
|
|
||||||
|
\li In the \uicontrol Ignore field, specify the number of times that the
|
||||||
|
breakpoint is ignored before the program stops.
|
||||||
|
|
||||||
|
\li In the \uicontrol Commands field, specify the commands to execute
|
||||||
|
when 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:
|
||||||
|
|
||||||
|
\list
|
||||||
|
|
||||||
|
\li Click the breakpoint marker in the text editor.
|
||||||
|
|
||||||
|
\li Select the breakpoint in the \uicontrol Breakpoints view and press
|
||||||
|
\key Delete.
|
||||||
|
|
||||||
|
\li Select \uicontrol {Delete Breakpoint} in the context menu in the
|
||||||
|
\uicontrol Breakpoints view.
|
||||||
|
|
||||||
|
\endlist
|
||||||
|
|
||||||
|
\section2 Enabling and Disabling Breakpoints
|
||||||
|
|
||||||
|
To temporarily disable a breakpoint without deleting it and losing associated
|
||||||
|
data like conditions and commands:
|
||||||
|
|
||||||
|
\list
|
||||||
|
|
||||||
|
\li Right-click the breakpoint marker in the text editor and select
|
||||||
|
\uicontrol{Disable Breakpoint}.
|
||||||
|
|
||||||
|
\li Select the breakpoint in the \uicontrol Breakpoints view and press
|
||||||
|
\key Space.
|
||||||
|
|
||||||
|
\li Select \uicontrol {Disabled Breakpoint} in the context menu in the
|
||||||
|
\uicontrol Breakpoints view.
|
||||||
|
|
||||||
|
\endlist
|
||||||
|
|
||||||
|
A disabled breakpoint is marked with a hollow read circle in the
|
||||||
|
text editor and the \uicontrol Breakpoint view.
|
||||||
|
|
||||||
|
To re-enable a temporarily disabled breakpoint:
|
||||||
|
|
||||||
|
\list
|
||||||
|
|
||||||
|
\li Right-click the marker of a disabled breakpoint in the text editor and
|
||||||
|
select \uicontrol{Enable Breakpoint}.
|
||||||
|
|
||||||
|
\li Select a disabled breakpoint in the \uicontrol Breakpoints view and press
|
||||||
|
\key Space.
|
||||||
|
|
||||||
|
\li Select \uicontrol {Disabled Breakpoint} in the context menu in the
|
||||||
|
\uicontrol Breakpoints view.
|
||||||
|
|
||||||
|
\endlist
|
||||||
|
|
||||||
|
With the notable exception of data breakpoints, breakpoints retain their
|
||||||
|
enabled or disabled state when the debugged program is restarted.
|
||||||
|
|
||||||
|
\section2 Setting Data Breakpoints
|
||||||
|
|
||||||
|
A \e {data breakpoint} stops the program when data is read or written at the
|
||||||
|
specified address.
|
||||||
|
|
||||||
|
To set a data breakpoint at an address:
|
||||||
|
|
||||||
|
\list 1
|
||||||
|
|
||||||
|
\li Right-click in the \uicontrol Breakpoints view to open the context
|
||||||
|
menu, and select \uicontrol {Add Breakpoint}.
|
||||||
|
|
||||||
|
\li In the \uicontrol {Breakpoint type} field, select
|
||||||
|
\uicontrol {Break on data access at fixed address}.
|
||||||
|
|
||||||
|
\li In the \uicontrol Address field, specify the address of the memory
|
||||||
|
block.
|
||||||
|
|
||||||
|
\li Select \uicontrol OK.
|
||||||
|
|
||||||
|
\endlist
|
||||||
|
|
||||||
|
If the address is displayed in the \uicontrol {Locals} or
|
||||||
|
\uicontrol {Expressions} view, you can select
|
||||||
|
\uicontrol {Add Data Breakpoint at Object's Address} in the
|
||||||
|
context menu to set the data breakpoint.
|
||||||
|
|
||||||
|
Data breakpoints will be disabled when the debugged program exits, as it
|
||||||
|
is unlikely that the used addresses will stay the same at the next program
|
||||||
|
launch. If you really want a data breakpoint to be active again, re-enable
|
||||||
|
it manually.
|
||||||
|
|
||||||
|
//! [debugger-breakpoints]
|
||||||
|
|
||||||
|
//! [debugger-call-stack-trace]
|
||||||
|
|
||||||
|
\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
|
||||||
|
\uicontrol 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 \uicontrol Stack view.
|
||||||
|
|
||||||
|
If you click a frame with a known source location, the text editor jumps to
|
||||||
|
the corresponding location and updates the \uicontrol {Locals} and
|
||||||
|
\uicontrol {Expressions} views, making it seem like the program
|
||||||
|
was interrupted before entering the function.
|
||||||
|
|
||||||
|
To find out which QML file is causing a Qt Quick 2 application to crash,
|
||||||
|
select \uicontrol {Load QML Stack} in the context menu in the
|
||||||
|
\uicontrol Stack view. 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.
|
||||||
|
|
||||||
|
//! [debugger-call-stack-trace]
|
||||||
|
|
||||||
|
//! [debugger-locals]
|
||||||
|
|
||||||
|
\section1 Local Variables and Function Parameters
|
||||||
|
|
||||||
|
The Locals view consists of the \uicontrol Locals pane and the
|
||||||
|
\uicontrol {Return Value} pane (hidden when empty).
|
||||||
|
|
||||||
|
\image qtcreator-locals.png "Locals view"
|
||||||
|
|
||||||
|
Whenever a program stops under the control of the debugger, it retrieves
|
||||||
|
information about the topmost stack frame and displays it in the
|
||||||
|
\uicontrol {Locals} view. The \uicontrol Locals pane shows
|
||||||
|
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 \key {Shift+F11}, the \uicontrol {Return Value}
|
||||||
|
pane displays the value returned by the function.
|
||||||
|
|
||||||
|
//! [debugger-locals]
|
||||||
|
|
||||||
|
//! [debugger-expressions]
|
||||||
|
|
||||||
|
\section1 Evaluating Expressions
|
||||||
|
|
||||||
|
To compute values of arithmetic expressions or function calls, use
|
||||||
|
expression evaluators in the \uicontrol Expressions view. To insert a new
|
||||||
|
expression evaluator, either double-click on an empty part of the
|
||||||
|
\uicontrol {Expressions} or \uicontrol {Locals} view, or select
|
||||||
|
\uicontrol {Add New Expression Evaluator} from the context menu, or drag and
|
||||||
|
drop an expression from the code editor.
|
||||||
|
|
||||||
|
\image qtcreator-debugger-expressions.png
|
||||||
|
|
||||||
|
\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]}.
|
||||||
|
|
||||||
|
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
|
||||||
|
\li \b{Note:}
|
||||||
|
|
||||||
|
\row
|
||||||
|
\li GDB and LLDB, and therefore \QC's debugger, also work for optimized
|
||||||
|
builds on Linux and \macos. Optimization can lead to re-ordering
|
||||||
|
of instructions or removal of some local variables, causing the
|
||||||
|
\uicontrol {Locals} and \uicontrol {Expressions} view to show
|
||||||
|
unexpected data.
|
||||||
|
\row
|
||||||
|
\li The debug information provided by GCC does not include enough
|
||||||
|
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
|
||||||
|
\uicontrol {not in scope}. Not all uninitialized objects,
|
||||||
|
however, can be recognized as such.
|
||||||
|
\endtable
|
||||||
|
|
||||||
|
The \uicontrol {Locals} and \uicontrol {Expressions} views also provide access
|
||||||
|
to the most 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.
|
||||||
|
|
||||||
|
Right-click in the \uicontrol {Locals} or the \uicontrol {Expressions} view
|
||||||
|
to open a context 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 values of QMap, select
|
||||||
|
\uicontrol {Change Value Display Format} > \uicontrol Compact.
|
||||||
|
|
||||||
|
You can use the \uicontrol {Locals} and \uicontrol {Expressions} view to change
|
||||||
|
the contents of variables of simple data types, for example, \c int, \c float,
|
||||||
|
\c QString and \c std::string when the program is interrupted. To do so,
|
||||||
|
click the \uicontrol Value column, modify the value with the inplace editor,
|
||||||
|
and press \key Enter (or \key Return).
|
||||||
|
|
||||||
|
To change the complete contents of QVector or \c std::vector values, type
|
||||||
|
all values separated by commas into the \uicontrol Value column of the main
|
||||||
|
entry.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
//! [debugger-expressions]
|
||||||
|
|
||||||
|
*/
|
||||||
@@ -477,321 +477,10 @@
|
|||||||
It is also possible to continue executing the program until the current
|
It is also possible to continue executing the program until the current
|
||||||
function completes or jump to an arbitrary position in the current function.
|
function completes or jump to an arbitrary position in the current function.
|
||||||
|
|
||||||
\section1 Setting Breakpoints
|
\include creator-debugger-common.qdocinc debugger-breakpoints
|
||||||
|
\include creator-debugger-common.qdocinc debugger-call-stack-trace
|
||||||
A breakpoint represents a position or sets of positions in the code that,
|
\include creator-debugger-common.qdocinc debugger-locals
|
||||||
when executed, interrupts the program being debugged and passes the control
|
\include creator-debugger-common.qdocinc debugger-expressions
|
||||||
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 \uicontrol Breakpoints view which is enabled
|
|
||||||
by default. The \uicontrol 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
|
|
||||||
|
|
||||||
\li Source code files and lines
|
|
||||||
|
|
||||||
\li Functions
|
|
||||||
|
|
||||||
\li Addresses
|
|
||||||
|
|
||||||
\li Throwing and catching exceptions
|
|
||||||
|
|
||||||
\li Executing and forking processes
|
|
||||||
|
|
||||||
\li Executing some system calls
|
|
||||||
|
|
||||||
\li 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.
|
|
||||||
|
|
||||||
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
|
|
||||||
(\key F8 for \macos) at a particular line you want the
|
|
||||||
program to stop.
|
|
||||||
|
|
||||||
\li In the \uicontrol Breakpoints view, double-click in the empty
|
|
||||||
part of the view.
|
|
||||||
|
|
||||||
\li In the \uicontrol Breakpoints view, select
|
|
||||||
\uicontrol {Add Breakpoint} in the context menu.
|
|
||||||
|
|
||||||
\endlist
|
|
||||||
|
|
||||||
\li In the \uicontrol {Breakpoint type} field, select the location in the
|
|
||||||
program code where you want the program to stop. The other options
|
|
||||||
to specify depend on the selected location.
|
|
||||||
|
|
||||||
\image qtcreator-add-breakpoint.png "Add Breakpoints" dialog
|
|
||||||
|
|
||||||
\li In the \uicontrol Condition field, set the condition to be evaluated
|
|
||||||
before stopping at the breakpoint if the condition evaluates as
|
|
||||||
true.
|
|
||||||
|
|
||||||
\li In the \uicontrol Ignore field, specify the number of times that the
|
|
||||||
breakpoint is ignored before the program stops.
|
|
||||||
|
|
||||||
\li In the \uicontrol Commands field, specify the commands to execute
|
|
||||||
when 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:
|
|
||||||
|
|
||||||
\list
|
|
||||||
|
|
||||||
\li Click the breakpoint marker in the text editor.
|
|
||||||
|
|
||||||
\li Select the breakpoint in the \uicontrol Breakpoints view and press
|
|
||||||
\key Delete.
|
|
||||||
|
|
||||||
\li Select \uicontrol {Delete Breakpoint} in the context menu in the
|
|
||||||
\uicontrol Breakpoints view.
|
|
||||||
|
|
||||||
\endlist
|
|
||||||
|
|
||||||
\section2 Enabling and Disabling Breakpoints
|
|
||||||
|
|
||||||
To temporarily disable a breakpoint without deleting it and losing associated
|
|
||||||
data like conditions and commands:
|
|
||||||
|
|
||||||
\list
|
|
||||||
|
|
||||||
\li Right-click the breakpoint marker in the text editor and select
|
|
||||||
\uicontrol{Disable Breakpoint}.
|
|
||||||
|
|
||||||
\li Select the breakpoint in the \uicontrol Breakpoints view and press
|
|
||||||
\key Space.
|
|
||||||
|
|
||||||
\li Select \uicontrol {Disabled Breakpoint} in the context menu in the
|
|
||||||
\uicontrol Breakpoints view.
|
|
||||||
|
|
||||||
\endlist
|
|
||||||
|
|
||||||
A disabled breakpoint is marked with a hollow read circle in the
|
|
||||||
text editor and the \uicontrol Breakpoint view.
|
|
||||||
|
|
||||||
To re-enable a temporarily disabled breakpoint:
|
|
||||||
|
|
||||||
\list
|
|
||||||
|
|
||||||
\li Right-click the marker of a disabled breakpoint in the text editor and
|
|
||||||
select \uicontrol{Enable Breakpoint}.
|
|
||||||
|
|
||||||
\li Select a disabled breakpoint in the \uicontrol Breakpoints view and press
|
|
||||||
\key Space.
|
|
||||||
|
|
||||||
\li Select \uicontrol {Disabled Breakpoint} in the context menu in the
|
|
||||||
\uicontrol Breakpoints view.
|
|
||||||
|
|
||||||
\endlist
|
|
||||||
|
|
||||||
With the notable exception of data breakpoints, breakpoints retain their
|
|
||||||
enabled or disabled state when the debugged program is restarted.
|
|
||||||
|
|
||||||
\section2 Setting Data Breakpoints
|
|
||||||
|
|
||||||
A \e {data breakpoint} stops the program when data is read or written at the
|
|
||||||
specified address.
|
|
||||||
|
|
||||||
To set a data breakpoint at an address:
|
|
||||||
|
|
||||||
\list 1
|
|
||||||
|
|
||||||
\li Right-click in the \uicontrol Breakpoints view to open the context
|
|
||||||
menu, and select \uicontrol {Add Breakpoint}.
|
|
||||||
|
|
||||||
\li In the \uicontrol {Breakpoint type} field, select
|
|
||||||
\uicontrol {Break on data access at fixed address}.
|
|
||||||
|
|
||||||
\li In the \uicontrol Address field, specify the address of the memory
|
|
||||||
block.
|
|
||||||
|
|
||||||
\li Select \uicontrol OK.
|
|
||||||
|
|
||||||
\endlist
|
|
||||||
|
|
||||||
If the address is displayed in the \uicontrol {Locals} or
|
|
||||||
\uicontrol {Expressions} view, you can select
|
|
||||||
\uicontrol {Add Data Breakpoint at Object's Address} in the
|
|
||||||
context menu to set the data breakpoint.
|
|
||||||
|
|
||||||
Data breakpoints will be disabled when the debugged program exits, as it
|
|
||||||
is unlikely that the used addresses will stay the same at the next program
|
|
||||||
launch. If you really want a data breakpoint to be active again, re-enable
|
|
||||||
it manually.
|
|
||||||
|
|
||||||
\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
|
|
||||||
\uicontrol 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 \uicontrol Stack view.
|
|
||||||
|
|
||||||
If you click a frame with a known source location, the text editor jumps to
|
|
||||||
the corresponding location and updates the \uicontrol {Locals} and
|
|
||||||
\uicontrol {Expressions} views, making it seem like the program
|
|
||||||
was interrupted before entering the function.
|
|
||||||
|
|
||||||
To find out which QML file is causing a Qt Quick 2 application to crash,
|
|
||||||
select \uicontrol {Load QML Stack} in the context menu in the
|
|
||||||
\uicontrol Stack view. 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.
|
|
||||||
|
|
||||||
\section1 Local Variables and Function Parameters
|
|
||||||
|
|
||||||
The Locals view consists of the \uicontrol Locals pane and the
|
|
||||||
\uicontrol {Return Value} pane (hidden when empty).
|
|
||||||
|
|
||||||
\image qtcreator-locals.png "Locals view"
|
|
||||||
|
|
||||||
Whenever a program stops under the control of the debugger, it retrieves
|
|
||||||
information about the topmost stack frame and displays it in the
|
|
||||||
\uicontrol {Locals} view. The \uicontrol Locals pane shows
|
|
||||||
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 \key {Shift+F11}, the \uicontrol {Return Value}
|
|
||||||
pane displays the value returned by the function.
|
|
||||||
|
|
||||||
|
|
||||||
\section1 Evaluating Expressions
|
|
||||||
|
|
||||||
To compute values of arithmetic expressions or function calls, use
|
|
||||||
expression evaluators in the \uicontrol Expressions view. To insert a new
|
|
||||||
expression evaluator, either double-click on an empty part of the
|
|
||||||
\uicontrol {Expressions} or \uicontrol {Locals} view, or select
|
|
||||||
\uicontrol {Add New Expression Evaluator} from the context menu, or drag and
|
|
||||||
drop an expression from the code editor.
|
|
||||||
|
|
||||||
\image qtcreator-debugger-expressions.png
|
|
||||||
|
|
||||||
\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]}.
|
|
||||||
|
|
||||||
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
|
|
||||||
\li \b{Note:}
|
|
||||||
|
|
||||||
\row
|
|
||||||
\li GDB and LLDB, and therefore \QC's debugger, also work for optimized
|
|
||||||
builds on Linux and \macos. Optimization can lead to re-ordering
|
|
||||||
of instructions or removal of some local variables, causing the
|
|
||||||
\uicontrol {Locals} and \uicontrol {Expressions} view to show
|
|
||||||
unexpected data.
|
|
||||||
\row
|
|
||||||
\li The debug information provided by GCC does not include enough
|
|
||||||
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
|
|
||||||
\uicontrol {not in scope}. Not all uninitialized objects,
|
|
||||||
however, can be recognized as such.
|
|
||||||
\endtable
|
|
||||||
|
|
||||||
|
|
||||||
The \uicontrol {Locals} and \uicontrol {Expressions} views also provide access
|
|
||||||
to the most 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.
|
|
||||||
|
|
||||||
Right-click in the \uicontrol {Locals} or the \uicontrol {Expressions} view
|
|
||||||
to open a context 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 values of QMap, select
|
|
||||||
\uicontrol {Change Value Display Format} > \uicontrol Compact.
|
|
||||||
|
|
||||||
You can use the \uicontrol {Locals} and \uicontrol {Expressions} view to change
|
|
||||||
the contents of variables of simple data types, for example, \c int, \c float,
|
|
||||||
\c QString and \c std::string when the program is interrupted. To do so,
|
|
||||||
click the \uicontrol Value column, modify the value with the inplace editor,
|
|
||||||
and press \key Enter (or \key Return).
|
|
||||||
|
|
||||||
To change the complete contents of QVector or \c std::vector values, type
|
|
||||||
all values separated by commas into the \uicontrol Value column of the main
|
|
||||||
entry.
|
|
||||||
|
|
||||||
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
|
\section1 Directly Interacting with Native Debuggers
|
||||||
|
|
||||||
|
|||||||
@@ -33,7 +33,7 @@
|
|||||||
\contentspage index.html
|
\contentspage index.html
|
||||||
\page creator-qml-debugging-example.html
|
\page creator-qml-debugging-example.html
|
||||||
\if defined(qtdesignstudio)
|
\if defined(qtdesignstudio)
|
||||||
\previouspage creator-qml-debugging-example.html
|
\previouspage creator-debugging-qml.html
|
||||||
\nextpage creator-qml-performance-monitor.html
|
\nextpage creator-qml-performance-monitor.html
|
||||||
\else
|
\else
|
||||||
\previouspage creator-debugging-example.html
|
\previouspage creator-debugging-example.html
|
||||||
|
|||||||
@@ -33,7 +33,7 @@
|
|||||||
\contentspage index.html
|
\contentspage index.html
|
||||||
\page creator-debugging-qml.html
|
\page creator-debugging-qml.html
|
||||||
\if defined(qtdesignstudio)
|
\if defined(qtdesignstudio)
|
||||||
\previouspage creator-debug-mode.html
|
\previouspage studio-debugging.html
|
||||||
\nextpage creator-qml-debugging-example.html
|
\nextpage creator-qml-debugging-example.html
|
||||||
\else
|
\else
|
||||||
\previouspage creator-debugging-helpers.html
|
\previouspage creator-debugging-helpers.html
|
||||||
@@ -158,6 +158,13 @@
|
|||||||
|
|
||||||
\endlist
|
\endlist
|
||||||
|
|
||||||
|
\if defined(qtdesignstudio)
|
||||||
|
\include creator-debugger-common.qdocinc debugger-breakpoints
|
||||||
|
\include creator-debugger-common.qdocinc debugger-call-stack-trace
|
||||||
|
\include creator-debugger-common.qdocinc debugger-locals
|
||||||
|
\include creator-debugger-common.qdocinc debugger-expressions
|
||||||
|
\endif
|
||||||
|
|
||||||
\section1 Executing JavaScript Expressions
|
\section1 Executing JavaScript Expressions
|
||||||
|
|
||||||
When the application is interrupted by a breakpoint, you can use the
|
When the application is interrupted by a breakpoint, you can use the
|
||||||
|
|||||||
@@ -33,7 +33,7 @@
|
|||||||
\contentspage index.html
|
\contentspage index.html
|
||||||
\page creator-qml-performance-monitor.html
|
\page creator-qml-performance-monitor.html
|
||||||
\if defined(qtdesignstudio)
|
\if defined(qtdesignstudio)
|
||||||
\previouspage creator-qml-performance-monitor.html
|
\previouspage creator-qml-debugging-example.html
|
||||||
\nextpage creator-help-overview.html
|
\nextpage creator-help-overview.html
|
||||||
\else
|
\else
|
||||||
\previouspage creator-analyze-mode.html
|
\previouspage creator-analyze-mode.html
|
||||||
|
|||||||
Reference in New Issue
Block a user