Template:IDE Window: Breakpoints/Exceptions
Navigation
editMain Menu > View > Debug Windows > BreakPoints/Exceptions
Overview
editThis window is part of the IDE's Debugger frontend. It provides an overview of all Breakpoints, WatchPoints and Exception-filters for the current project.
Some of the properties described for those objects may depend on your debugger setup. Some Debugger backends may implement only a sub-set of the described features. See setup the debugger for choosing a backend.
Breakpoints/WatchPoints
editThere 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.
- Watchpoint
- 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.
About Watchpoints (aka Data-Breakpoints):
When setting a Watchpoints 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 Watchpoints 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.
Some backends may be able to set Watchpoints on global variables automatically when the project is started in the debugger.
Exception-Filter
editWhen the debugged app encounters an exception then the debugger will pause it. This applies to "raise exception.create", "run-errors" (e.g. range check), or faults such as access violations.
Exception filter allow to ignore individual exceptions by class and let the app continue and handle the exception itself. (Same as pressing F9 (or "continue step") after pausing on an exception.
Conditions and Hitcount on Exception filters:
Exception filters work the opposite way to breakpoints. That is instead of pausing the application, they prevent the app from pausing.
Conditions must be true, to prevent the pause (aka "continue" the app)
HitCount allows the app to continue until the n-th time. Where a breakpoint does not pause (not execute its action) for n-times, an exception filter does execute its action "continue" for n-times and then no more. (this also applies for other actions specified)
Breakpoints/Exceptions Window
editGrouped![]() |
Ungrouped![]() |
The toolbar
edit
Turn On/Off Breakpoints- When turned off, the debugger will ignore all breakpoints.
Turn On/Off Exception handling- When turned off, the debugger will ignore all exceptions.
That is the debugger will not pause at any exception at all. It ignores the exceptions, not the filters.
|
|
Display either only breakpoints&watchpoints, only exception-filter or both- The selection which kind of objects will be shown also affects actions such as "Delete all", "Enable/Disable all".
Adds a new item- Opens a dropdown with a choice of "Source Breakpoint", "Address Breakpoint", "Data Breakpoint" or "Exception-filter". The details can then be configured in the properties dialog.
Enable / Disable selected items- Any items that are disabled are ignored by the debugger.
A disabled Break/Watchpoint will not pause the application, nor perform any other actions. A disabled exception filter will not "continue" (not prevent the pause for) an exception.
Delete the selected item(s)
Delete all items.
Enable / Disable all items.
Open properties for selected item(s)
Toggle between grouped and ungrouped view
Data displayed
edit- 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 - Watchpoint:
Filename/Address: The name of the variable.
Line/Length: Will show the scope ("Global" / "Declaration") and the mode ("Read" / "Write" / "Read/Write") - Exception-filter:
Filename/Address: The class of the exception that the filter act on (prevents pausing for).
- Source Breakpoint:
- 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. For exception-filters, the exception will not pause when the condition is true.
- 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) after the hitcount is reached. For an exception-filter actions will be performed before (until) the Hitcount is reached.
- Group
-
The group where this breakpoint belongs to. This allows to quickly enabled/disable several breakpoints at once.
Context menu
edit
- 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
edit
- Filename/Line
- Location of the breakpoint. Classname for Exception-filter.
- 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.
See section on Conditions below - Hitcount
- The breakpoint will be ignored until it has been hit the specified amount of times. Exception-filter will be executed until they reach the hitcount.
The "Pass count" (which is compared) is only increased if the item is enabled, and if it either does not have a condition or the condition evaluates to true. - NOTE: #1 A hitcount of 0 means its not tested. A hitcount of 1 is effectively equal to this, as the first hit is reached without passing/ignoring any hits before.
- NOTE: #2 The hitcount 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).
- Pass count
- IDE shows here how many times the breakpoint was activated.
- Auto continue after
- This works when "Break" is checked. After breaking activates, IDE runs the specified pause and automatically resumes the program running after that pause. 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, and/or the pause button can be pressed to cancel the timer and pause until execution is resumed with run/step commands.
Auto continue continues with "Run/F9". It does not work well with stepping - Group
- A breakpoint can be in one group (one only). This option must be valid Pascal identifier. Groups can be used with the "Enable/Disable group" feature.
- Actions
-
- Break (breakpoint):Pause the application. The application can be continued with the Run command or any of the stepping commands.
- Continue (exception-filter):Ignore the exception, don't pause the application.
- Enable/Disable Groups: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.
- Break (breakpoint):Pause the application. The application can be continued with the Run command or any of the stepping commands.
Conditions
editThe availability and extend of conditions depends on the backend and the type of item (breakpoint vs exception filter).
For debuggers that involve GDB or LLDB (including debuggers that use FpDebug together with any of those), conditions must be written in a form that is understood by GDB or LLDB directly. Pascal based syntax may not work here.
- LLDB - Break/Watchpoints
- Needs testing/confirmation
- LLDB - Exception-filter
- NOT supported. Conditions have no effect
- GDB - Break/Watchpoints
- Require Syntax for GDB
- GDB - Exception-filter
- Require Syntax for GDB
- NOTE #1: For GDB: 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: For GDB:
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
- FpDebug - Break/Watchpoints/Exception-filter
- Conditions are supported with full Pascal Syntax (as in watches window)
- Exception-filter (all backends)
- The condition can only contain global variables. It is currently executed in the context of the RTL function raising the exception, rather than in user code.
Notes on FpDebug
For breakpoints the :i2o intrinsic FpDebug-Watches-Intrinsic-Functions is not yet supported. The :e (exception) is also not supported.
For exception-filters the :e intrinsic FpDebug-Watches-Intrinsic-Functions#E_(Exception_object) can be used to access the exception object.

