Difference between revisions of "IDE Window: Breakpoints"

From Free Pascal wiki
Jump to navigationJump to search
 
(49 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{IDE Window: Break Points}}
+
{{IDE Window: Breakpoints}}
  
<center>[[Image:Breakpoint_list.png]]</center>
+
== Navigation ==
== Important ==  
 
  
'''This page is under construction. It may contain wrong information and must be confirmed/repaired by [[User:Marc|Marc]].'''
+
[[Main menu|Main Menu]] > [[Main menu#View|View]] > Debug Windows > BreakPoints
  
You must setup the debugger and start the project to debug it. Only then the breakpoints are useful.
+
== Important ==
  
== State ==
+
You must [[Debugger_Setup |setup the debugger]] and start the project to debug it. Only then will this window be useful.
  
A breakpoint can be enabled or disabled. If it is enabled, then each time the program reaches the breakpoint, the condition is checked and if results true, the action(s) set for the breakpoint will be performed. The following actions are available: Break, Enable/Disable group(s), Log message, Evaluate expression, Ignore/Handle Exceptions. A complete description of these actions can be found on the [[IDE Window:Breakpoint properties|Breakpoint properties]] page.
+
{{Note| About Data/Watch breakpoints:
 +
:When setting the data/watch breakpoint the variable - which should be watched - must be in scope. (That is the program must be running and stopped at a breakpoint where the variable can be seen).
 +
:For that reason data/watch breakpoints are only valid until the app exits and then will be disabled. On the next debug they must be enabled again while stopped at a location where it is in scope.
 +
}}
  
== Filename/Address ==
+
== Breakpoint list ==
 +
[[Image:Breakpoint_list.png]]
  
Shows the position of the breakpoint in the source. If the corresponding position of the source is not know, the address in the executable is shown instead.
+
There are 3 kind of breakpoints:
  
== Line/Length ==
+
;Source Breakpoint: Specified by Unit-name and Line-number. The execution will be interrupted before the pascal statement on the specified line is executed. Can be set by clicking the gutter in the source-editor.
 +
;Address Breakpoint: Specified by an address. The execution will be interrupted before the <u>assembler</u> statement at the address is executed. Can be set by clicking the gutter in disassembler window.
 +
;Data/Watch Breakpoint: Specified by the name of a variable. The execution will be interrupted when the variable is changed. It can also detect read access. Support for this depends on the platform used.
  
Shows the position of the breakpoint in the source.
+
=== Data displayed ===
If you edit the source, this position can change. For example, if you insert a line in front, the breakpoint will move. But this has no effect the line numbers in the debugging information of the executable. It will still contain the old numbers. So, better stop debugging (i.e. stop the program) before editing.
 
  
== Condition ==
+
;State: A breakpoint can be enabled or disabled. If it is enabled, then each time the program reaches the breakpoint, the condition is checked and if results true, the action(s) set for the breakpoint will be performed.
  
Normally a reached breakpoint always stops the program. You can define a condition, which is executed and the program is stopped only, if the condition is met.
+
;Filename/Address<br>Line/Length: Depending on the type of the breakpoint the following is displayed:
 +
:*<u>Source Breakpoint:</u><br>Filename/Address: The name of the file where the breakpoint is set.<br> Line/Length: The line-number where the breakpoint is set.
 +
:*<u>Address Breakpoint:</u><br>Filename/Address The address of the breakpoint. This type of breakpoint is useful if there is no source available. <br> Line/Length: This is empty
 +
:*<u>Data Breakpoint:</u><br>Filename/Address: The name of the variable. <br> Line/Length: Will show the scope ("Global" / "Declaration") and the mode ("Read" / "Write" / "Read/Write")
  
== Action ==
+
;Condition: Normally a reached breakpoint performs the break action(s). When a condition is defined, this condition is evaluated. If this condition evaluates to True, the break action(s) are performed.
  
Not implemented yet:
+
;Action: The following actions are available: Break, Enable/Disable group(s), Log message, Evaluate expression, Ignore/Handle Exceptions. A complete description of these actions can be found on the [[IDE Window:Breakpoint properties|Breakpoint properties]] page.
Normally a breakpoint stops the program. Eventually other actions will be implemented, like enabling other breakpoints or groups.
 
  
== Pass Count ==
+
;Pass Count: How many times the enabled breakpoint has been reached. If a "Hitcount" is defined for this breakpoint, the debugger will  perform the break action(s) when the hitcount is reached.
  
How many times the enabled breakpoint has been reached.
+
;Group: The group where this breakpoint belongs to. This allows to quickly enabled/disable several breakpoints at once.
  
== Group ==
+
=== Interface ===
  
Not implemented yet:
+
<u>Toolbar</u>
Eventually you can group breakpoints. This allows to quickly enabled/disable several breakpoints at once.
+
;[[File:debugger enable.png]] Enable/[[File:debugger_disable.png]] Disable: Enables/Disables individual breakpoint(s).
 +
;[[File:laz delete.png]] Remove: Deletes the selected Breakpoint(s)
 +
;[[File:debugger_enable_all.png]] Enable all/[[File:debugger_disable_all.png]] Disable all: Enables/Disables all breakpoints.
 +
;[[File:menu_clean.png]] Delete all: Deletes all Breakpoints
 +
;[[File:menu_environment_options.png]] Properties: Change the properties of the current/selected breakpoint.
 +
 
 +
<u>Context menu</u>
 +
[[Image:Breakpoint_list_popmenu.png|right]]
 +
 
 +
;View Source: Jump to the source. (Only Source-Breakpoints)
 +
;Add: Opens a property dialog for the requested type of breakpoint. The location/address/variable can be set in the property dialog.
 +
;Enabled: Toggle the enabled state for individual breakpoint(s)
 +
;Delete: Deletes the selected Breakpoint(s)
 +
;Group: Clears or sets the group for the breakpoint. A list of existing groups will be in the menu. With "Set new group" a new group can be created.
 +
;Enable all/Disable all: Enables/Disables all breakpoints.
 +
;Delete all: Deletes all Breakpoints
 +
;Disable all in same source/Enable all in same source: Enables/Disables all breakpoints in the same unit as the current selected breakpoint. (Only Source-Breakpoints)
 +
;Delete all in same source: Deletes all Breakpoints in the same unit as the current selected breakpoint. (Only Source-Breakpoints)
 +
 
 +
== Breakpoint properties ==
 +
 
 +
[[File:BreakPoint_Properties.png]]
 +
 
 +
;Filename/Line: Location of the breakpoint
 +
;Condition: The breakpoint will only be triggered and perform the specified actions, if the condition evaluates to true. This can for example be used to test if a variable has reached a critical value.<br> <font size="+1"><b>Currently only very basic expressions are allowed. (GDB must be able to understand the expression)</b></font><br>
 +
:'''NOTE #1:''' The IDE does only apply a very limited pascal syntax fixing to the condition (#48 is escaped as char with ord val 48), so it needs to be C-like, so GDB understands the expression. eg: "i=2" or somechar='a'. Remember that the string (or rather char) value must be wrapper in single quotes, not double quotes. <br>
 +
:'''NOTE #2:''' <s>Strings can not be compared. They are seen as pchar, so they can only be compared to an address: "str=0x5a0b40".</s> Chars in a string can be compared (index is zero based/pchar) "(s[0]='a')and(s[1]='b')". And strings can be compared as PChar (zero terminated): $_streq(^char(MyString), "ValueToCompare") (with double quotes)  See: https://sourceware.org/gdb/onlinedocs/gdb/Convenience-Funs.html
 +
;HitCount: The breakpoint will be ignored until it has been hit the specified amount of times. One scenario where this is useful, if an event is triggered by the focus change (between IDE and debugged app) when the app is paused/resumed. The ignored passes of the breakpoint to not alter the focus.<br>
 +
:'''NOTE: #1''' The hitcount starts at 0. So if you want to break on the 10th iteration, set the HitCount to 9.<br>
 +
:'''NOTE: #2''' The hit count doesn't reset until you stop/start the debugging or actually delete the breakpoint and set it again (without the need to stop/start the debug session).
 +
;Auto continue after: This also avoids the focus change between IDE and app. It however indicates the execution line in the source editor, which leads to a visible indication. If the time is long enough watches might be evaluated.
 +
;Group: A breakpoint can be is one group (one only). Groups can be used with the Enable/Disable group feature.
 +
;Actions:
 +
:*<u>Break: </u>Pause the application. The application can be continued with the Run command or any of the stepping commands
 +
:*<u>Enable/Disable Group: </u>Enable or Disable all breakpoints in the given group(s). Usually  2 breakpoints would be set, one to enable, the other to disable. The breakpoints in the specified groups could then be enabled (or disabled) only, if they occur between the 2 points. The breakpoints that are changed could be in subroutines, that are called sometimes between the 2 points, but also from other locations.
 +
:*<u>Eval Expression: </u>Evaluates the expression and writes the value to the debug event log
 +
:*<u>Log Message: </u> Writes the message to the debug event log
 +
:*<u>Log Callstack: </u> Writes the callstack to the debug event log
 +
:*<u>Take a snapshot: </u> Evaluates all Watches, Locals, Callstack, Threads, and adds it to the snapshots in the History dialog.

Latest revision as of 15:05, 20 February 2023

Deutsch (de) English (en) français (fr) русский (ru)

Navigation

Main Menu > View > Debug Windows > BreakPoints

Important

You must setup the debugger and start the project to debug it. Only then will this window be useful.

Light bulb  Note: About Data/Watch breakpoints:

When setting the data/watch breakpoint the variable - which should be watched - must be in scope. (That is the program must be running and stopped at a breakpoint where the variable can be seen).
For that reason data/watch breakpoints are only valid until the app exits and then will be disabled. On the next debug they must be enabled again while stopped at a location where it is in scope.

Breakpoint list

Breakpoint list.png

There are 3 kind of breakpoints:

Source Breakpoint
Specified by Unit-name and Line-number. The execution will be interrupted before the pascal statement on the specified line is executed. Can be set by clicking the gutter in the source-editor.
Address Breakpoint
Specified by an address. The execution will be interrupted before the assembler statement at the address is executed. Can be set by clicking the gutter in disassembler window.
Data/Watch Breakpoint
Specified by the name of a variable. The execution will be interrupted when the variable is changed. It can also detect read access. Support for this depends on the platform used.

Data displayed

State
A breakpoint can be enabled or disabled. If it is enabled, then each time the program reaches the breakpoint, the condition is checked and if results true, the action(s) set for the breakpoint will be performed.
Filename/Address
Line/Length: Depending on the type of the breakpoint the following is displayed:
  • Source Breakpoint:
    Filename/Address: The name of the file where the breakpoint is set.
    Line/Length: The line-number where the breakpoint is set.
  • Address Breakpoint:
    Filename/Address The address of the breakpoint. This type of breakpoint is useful if there is no source available.
    Line/Length: This is empty
  • Data Breakpoint:
    Filename/Address: The name of the variable.
    Line/Length: Will show the scope ("Global" / "Declaration") and the mode ("Read" / "Write" / "Read/Write")
Condition
Normally a reached breakpoint performs the break action(s). When a condition is defined, this condition is evaluated. If this condition evaluates to True, the break action(s) are performed.
Action
The following actions are available: Break, Enable/Disable group(s), Log message, Evaluate expression, Ignore/Handle Exceptions. A complete description of these actions can be found on the Breakpoint properties page.
Pass Count
How many times the enabled breakpoint has been reached. If a "Hitcount" is defined for this breakpoint, the debugger will perform the break action(s) when the hitcount is reached.
Group
The group where this breakpoint belongs to. This allows to quickly enabled/disable several breakpoints at once.

Interface

Toolbar

debugger enable.png Enable/debugger disable.png Disable
Enables/Disables individual breakpoint(s).
laz delete.png Remove
Deletes the selected Breakpoint(s)
debugger enable all.png Enable all/debugger disable all.png Disable all
Enables/Disables all breakpoints.
menu clean.png Delete all
Deletes all Breakpoints
menu environment options.png Properties
Change the properties of the current/selected breakpoint.

Context menu

Breakpoint list popmenu.png
View Source
Jump to the source. (Only Source-Breakpoints)
Add
Opens a property dialog for the requested type of breakpoint. The location/address/variable can be set in the property dialog.
Enabled
Toggle the enabled state for individual breakpoint(s)
Delete
Deletes the selected Breakpoint(s)
Group
Clears or sets the group for the breakpoint. A list of existing groups will be in the menu. With "Set new group" a new group can be created.
Enable all/Disable all
Enables/Disables all breakpoints.
Delete all
Deletes all Breakpoints
Disable all in same source/Enable all in same source
Enables/Disables all breakpoints in the same unit as the current selected breakpoint. (Only Source-Breakpoints)
Delete all in same source
Deletes all Breakpoints in the same unit as the current selected breakpoint. (Only Source-Breakpoints)

Breakpoint properties

BreakPoint Properties.png

Filename/Line
Location of the breakpoint
Condition
The breakpoint will only be triggered and perform the specified actions, if the condition evaluates to true. This can for example be used to test if a variable has reached a critical value.
Currently only very basic expressions are allowed. (GDB must be able to understand the expression)
NOTE #1: The IDE does only apply a very limited pascal syntax fixing to the condition (#48 is escaped as char with ord val 48), so it needs to be C-like, so GDB understands the expression. eg: "i=2" or somechar='a'. Remember that the string (or rather char) value must be wrapper in single quotes, not double quotes.
NOTE #2: Strings can not be compared. They are seen as pchar, so they can only be compared to an address: "str=0x5a0b40". Chars in a string can be compared (index is zero based/pchar) "(s[0]='a')and(s[1]='b')". And strings can be compared as PChar (zero terminated): $_streq(^char(MyString), "ValueToCompare") (with double quotes) See: https://sourceware.org/gdb/onlinedocs/gdb/Convenience-Funs.html
HitCount
The breakpoint will be ignored until it has been hit the specified amount of times. One scenario where this is useful, if an event is triggered by the focus change (between IDE and debugged app) when the app is paused/resumed. The ignored passes of the breakpoint to not alter the focus.
NOTE: #1 The hitcount starts at 0. So if you want to break on the 10th iteration, set the HitCount to 9.
NOTE: #2 The hit count doesn't reset until you stop/start the debugging or actually delete the breakpoint and set it again (without the need to stop/start the debug session).
Auto continue after
This also avoids the focus change between IDE and app. It however indicates the execution line in the source editor, which leads to a visible indication. If the time is long enough watches might be evaluated.
Group
A breakpoint can be is one group (one only). Groups can be used with the Enable/Disable group feature.
Actions
  • Break: Pause the application. The application can be continued with the Run command or any of the stepping commands
  • Enable/Disable Group: Enable or Disable all breakpoints in the given group(s). Usually 2 breakpoints would be set, one to enable, the other to disable. The breakpoints in the specified groups could then be enabled (or disabled) only, if they occur between the 2 points. The breakpoints that are changed could be in subroutines, that are called sometimes between the 2 points, but also from other locations.
  • Eval Expression: Evaluates the expression and writes the value to the debug event log
  • Log Message: Writes the message to the debug event log
  • Log Callstack: Writes the callstack to the debug event log
  • Take a snapshot: Evaluates all Watches, Locals, Callstack, Threads, and adds it to the snapshots in the History dialog.