$DEBUG: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(One intermediate revision by the same user not shown)
Line 35: Line 35:
File:Osx.png|'''yes'''
File:Osx.png|'''yes'''
</gallery>
</gallery>
<!-- Additional availability notes go below the gallery -->
<!-- Additional availability notes go below here -->
* Since '''QB64-PE v4.0.0''' the precompiler flag ''_DEBUG_'' indicates the state of '''$DEBUG''' at compile time.
* Since '''QB64-PE v4.0.0''' the precompiler flag ''_DEBUG_'' indicates the state of '''$DEBUG''' at compile time.


Line 48: Line 48:
** Lines marked for skipping are indicated by an exclamation mark next to the line number.
** Lines marked for skipping are indicated by an exclamation mark next to the line number.
* '''F4''' opens the Variable List dialog, which allows you to add variables to the Watch List.
* '''F4''' opens the Variable List dialog, which allows you to add variables to the Watch List.
** There's a neat hidden feature here, if you set focus to the variables list (in the "Add Watch" dialog or in the "Watch List" during running/debugging) and then press '''Ctrl-C''', the whole list is copied to clipboard.
** It's a nice quick way to obtain a report of all variables used in your program.
* During execution, the Variable List dialog also allows you to set the values of variables and also to create Watchpoints.
* During execution, the Variable List dialog also allows you to set the values of variables and also to create Watchpoints.
* Watchpoints halt execution, similarly to breakpoints, but do so when a variable matches the condition you specify.
* Watchpoints halt execution, similarly to breakpoints, but do so when a variable matches the condition you specify.
Line 56: Line 58:
* '''F8''' can be used to run line by line without entering sub/function calls (Step Over).
* '''F8''' can be used to run line by line without entering sub/function calls (Step Over).
* '''F12''' can be used to show the current call stack (which procedure calls led to the current line).
* '''F12''' can be used to show the current call stack (which procedure calls led to the current line).
** Clicking the "<Copy>" button or pressing '''Ctrl-C''' will copy the entire call stack to clipboard.





Latest revision as of 12:07, 8 December 2024

$DEBUG is precompiler metacommand, which enables debugging features, allowing you to step through your code running line by line and to inspect variables and change their values in real time.


Syntax

$DEBUG


Description

  • $DEBUG injects extra code in the resulting binary, allowing the IDE to control the execution flow of your program.
  • When $DEBUG is used, the IDE will connect to your running program using a local TCP/IP connection.
    • You may get a prompt from your Operating System regarding this, so it may be necessary to allow the IDE to receive connections.
    • No external connections are created, and your running program will only attempt to connect locally to the IDE.
  • The default TCP/IP port starts at 9001. Multiple running instances of the IDE will attempt to open ports 9002 and up.
    • You can change the base port in the Debug menu.
  • The metacommand is supposed to be removed once your program is ready for release, although leaving it in won't have any effect if your program isn't run from the IDE.
    • The only drawback of leaving the metacommand in is that your binary will end up being larger than required.
  • In newer versions a precompiler flag named _DEBUG_ is available (see Availability):
    • The flag is one(1) if the program is compiled with $DEBUG and zero(0) if compiled without it.
    • You may use it to include/exclude debugging related code using precompiler $IF..$ELSE...$END IF blocks.

Problems

  • Note that C++ code optimization may badly interfere with the debugging features and that $CHECKING:OFF sections cannot be debugged by single stepping.
  • For best debugging experience we recommend the following preparational steps:
    • Remove or comment all $CHECKING:OFF lines in your program, at least for the sections which you intent to debug.
    • From the Options menu select Compiler Settings and there disable the C++ code optimization check box and also make sure no -O flags are entered in the C++ Compiler Flags text box.


Availability

  • Since QB64-PE v4.0.0 the precompiler flag _DEBUG_ indicates the state of $DEBUG at compile time.


$DEBUG Mode Operation

  • To start execution in pause mode, you can use F7 or F8.
  • There will be an arrow next to the line number where execution is paused, indicating the next line that will be run.
  • When you enable $DEBUG mode, you can set breakpoints by clicking the line number at which you wish to stop execution. This can also be achieved by using the F9 key.
    • Breakpoints are indicated by a red dot next to the line number.
    • To clear all breakpoints, hit F10.
  • To skip a line during execution, shift-click a line number
    • Lines marked for skipping are indicated by an exclamation mark next to the line number.
  • F4 opens the Variable List dialog, which allows you to add variables to the Watch List.
    • There's a neat hidden feature here, if you set focus to the variables list (in the "Add Watch" dialog or in the "Watch List" during running/debugging) and then press Ctrl-C, the whole list is copied to clipboard.
    • It's a nice quick way to obtain a report of all variables used in your program.
  • During execution, the Variable List dialog also allows you to set the values of variables and also to create Watchpoints.
  • Watchpoints halt execution, similarly to breakpoints, but do so when a variable matches the condition you specify.
    • You can use relational operators (=, <>, >=, <=, >, <) to create watchpoint conditions.
  • After a breakpoint or a watchpoint is reached, F5 can be used to continue execution.
  • F6 can be used when the execution pointer is inside a sub/function. When used, execution will proceed until the procedure is ended.
  • F7 can be used to run line by line, and can be used to debug code inside subs/functions (Step Into).
  • F8 can be used to run line by line without entering sub/function calls (Step Over).
  • F12 can be used to show the current call stack (which procedure calls led to the current line).
    • Clicking the "<Copy>" button or pressing Ctrl-C will copy the entire call stack to clipboard.


See also



Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link