![[me]](logo/logo.png)
$debug(5)
[Home]
[Commands]
[Variables]
[Macro-Dev]
[Glossary]
NAME
SYNOPSIS
DESCRIPTION
$debug is used to control macro debugging, it is a bit based flag where:
0x01
Displays an error message when an un-handled exception is encountered, this is useful to locate problems in the macro code i.e. missing arguments etc. This setting may be used in normal running and macro execution is halted when an error is encountered, it is non-intrusive up until the point of failure. Enabling slightly slows execution but is not typically noticeable on modern processors.
0x02
Setting this bit enables the macro debugger. With macro debugging enabled, before a line of macro code is executed the line and its location is first print on the message line with a prompt allowing the user to view variables, abort execution, dive into sub macros etc. The behaviour of the macro debugger can be altered by bits 0x04 and 0x08.
0x04
When set all macro lines encountered are printed. When this bit is not set only the lines of code that are executed are printed, i.e. if a false !if was encountered the lines within the !if would not be printed. Problems arise with !elif and !else lines and this bit is not set as the !elif and !else lines are never printed.
0x08
When set the debug prompt is disabled so the macro line is printed on the message line and then immediately executed. This allows the user to see the execution flow of the macro code while still executing the code at a reasonable pace.
0x10
Setting this bit has no immediate effect. However as soon as the key bound to
abort-command(2) (typically "C-g") is pressed the macro debugger is enabled, i.e. bit 0x02 is set. This can be invaluable when tracing problems, for example the following macro code will loop infinitely:
!repeat
beginning-of-line
backward-char
!force forward-line
!until ¬ $status
This is a fairly obvious bug, but if buried in a thousand lines of macro code it could be very difficult to spot and to find it during execution would be very tedious if not impossible. But by setting $debug to 0x10 the macro can be executed as normal and as soon as the macro is stuck the user can simply press "C-g" to start macro debugging at the current execution point.
Note that the "C-g" which triggers the macro debugger is discarded so it does not cause the current command to abort.
0x20
Setting this bit is similar to 0x10 except the macro debugger is enabled by the ringing of the bell. When some commands fail they always print an error message and ring the bell as the error needs handling (e.g. missing argument in a !if statement). However if the macro has been called with a !force the execution will not be aborted so tracing this issue could be difficult without this setting.
SEE ALSO
Ref: $debug(5) File: m5var011.5 Date: 2025/06/29
(c) Copyright JASSPA 2026