feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: Move common debugger functions to an include file

Browse Source 
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
2018-08-17 14:18:57 +02:00
parent 6a04f70e5b
commit 6564922254
5 changed files with 375 additions and 318 deletions
Download Patch File Download Diff File Expand all files Collapse all files

361
doc/src/debugger/creator-debugger-common.qdocinc Normal file
View 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]
*/

319
doc/src/debugger/creator-debugger.qdoc
View File

@@ -477,321 +477,10 @@
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 \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.
\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
\section1 Directly Interacting with Native Debuggers

2
doc/src/debugger/qtquick-debugger-example.qdoc
View File

@@ -33,7 +33,7 @@
\contentspage index.html
\page creator-qml-debugging-example.html
\if defined(qtdesignstudio)
\previouspage creator-qml-debugging-example.html
\previouspage creator-debugging-qml.html
\nextpage creator-qml-performance-monitor.html
\else
\previouspage creator-debugging-example.html

9
doc/src/debugger/qtquick-debugging.qdoc
View File

@@ -33,7 +33,7 @@
\contentspage index.html
\page creator-debugging-qml.html
\if defined(qtdesignstudio)
\previouspage creator-debug-mode.html
\previouspage studio-debugging.html
\nextpage creator-qml-debugging-example.html
\else
\previouspage creator-debugging-helpers.html
@@ -158,6 +158,13 @@
\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
When the application is interrupted by a breakpoint, you can use the

2
doc/src/qtquick/qtquick-profiler.qdoc
View File

@@ -33,7 +33,7 @@
\contentspage index.html
\page creator-qml-performance-monitor.html
\if defined(qtdesignstudio)
\previouspage creator-qml-performance-monitor.html
\previouspage creator-qml-debugging-example.html
\nextpage creator-help-overview.html
\else
\previouspage creator-analyze-mode.html