Equilla Debugger

The Equilla debugger can be used to find and resolve problems in your Equilla scripts. It allows you to stop execution of your scripts, step through your source code and examine the state of variables used in your code.

Creating a debugger document


Debugger Attach Dialog
To create a new debugger document, select the Insert group on the Toolbar and click on the Debugger button.After clicking on the Debugger debugger, a dialog will be displayed asking you which document you would like to debug. The dialog shows a list of all open desktops, workspaces and documents and presents the following options:
  • Skip – Do not attach to a document yet. This is typically used if the document you want to debug isn’t open yet. You may execute the debuggers Attach command from the ribbon as soon as the document you want to debug is ready to be used.
  • Attach – Attaches the new debugger to the selected document.
  • Cancel – Abort the operation and do no create a new debugger document.
Please be aware that a debugger can only debug one document at a time and only one debugger can be attached to a specific document. You may create multiple debuggers simultaneously and attached each of them to a separate document.

In order to be able to debug an indicator or strategy it has to be compiled using Tradesignal 7.0 or higher. Equilla scripts that have been compiled with earlier versions of Tradesignal will not show up in the debugger document.

Please note: Only chart documents can be debugged.

The debugger document


The debugger
The debugger document enables you to debug your Equilla scripts. It consists of the following components:
  • Scripts – The debugger loads all scripts that are referenced in the debugged document.
  • Watch windows – A set of watch windows that help you inspect the state of your indicator or strategy. There are three predefined windows, showing common information and one window where you can enter debug expressions on your own.
  • Call Stack – Shows the nesting level of your scripts while debugging.
  • Breakpoints – Shows a list of all breakpoints that have been set up.
  • Objects – Provides a list of all Equilla indicators and strategies that are contained in the debugged document. You may enable or disable the debugging of specific objects as you need.

Scripts

Every script referenced in the debugged document will be loaded automatically. Here you can inspect the source code, add or manipulate breakpoints or examine the state of variables as you need.

The debugger editor has all the same functionality as the normal Equilla Editor.

To add a breakpoint, click on the left margin of the editor, select the Toggle Breakpoint command from the ribbon or use the corresponding context menu entry.

While the execution is paused, you can examine the state of variables or evaluate Equilla expression by hovering over the corresponding text with your mouse. To evaluate an Equilla expression containing space characters, you have to select the whole expression in the editor before hovering over it.

Note: If a script has been changed since the indicator or strategy has been compiled, the scripts tab will show a corresponding image. Please be aware that breakpoints and variables may behave unexpected in such a case.

If the evaluation is paused, the source code line that is about to be evaluated will be highlighted in the source code editor. Additionally the margin will show an arrow icon on the corresponding line.

Watch windows


Locals watch window
The Equilla debugger provides a quick way to check the state of the document as a whole or of specific elements in it.
  • Virtual Machine – This is a predefined view and cannot be modified. It shows information of all elements within the virtual machine. This includes all the indicator and strategies that have been created as well as the instruments that are used to evaluate your scripts.
  • This – This is a predefined view and cannot be modified. It provides access to the state of the currently debugged indicator or strategy. This includes general properties as well as the referenced parents and generated output data. You may also get access to child objects that have been applied to this indicator or strategy.
  • Locals - This is a predefined view and cannot be modified. This view provides access to all variables that are used in the currently debugged indicator, strategy or Equilla function. While stepping through your code, this view will be updated automatically to show only the variables that are relevant for the script that is about to be evaluated.
  • Watch - Use this view to track specific variables or Equilla expressions. The list of expressions will not change automatically while stepping through your code. To add an expression, simply type it into the list or use drag and drop to copy an expression from the source code editor or another watch window. The Quick Watch is an alternative to this view when the information for the inspected object or variable does not fit into the available space.

Call Stack


Call stack
The call stack shows the currently evaluated script and line number. The currently evaluated script is displayed on the top and the indicator or strategy script is displayed at the bottom.

For Equilla functions, the passed parameters will be displayed as well. Please be aware that the same limitations as for the evaluation of debug expression apply. Therefore the list of parameters might not be complete.

To navigate through the call stack, simple double click on an entry in the list.

Breakpoints


Breakpoints
This view shows a list of all the breakpoints that have been set up for a debugger. The displayed information includes the script file and line number, the breakpoint belongs to, as well as information about the state, conditions and the action that should be taken when the breakpoint is hit.

State
The breakpoint is valid and enabled.
The breakpoint is valid, but currently disabled.
The breakpoint cannot be mapped to any executable code.
To modify an existing breakpoint, either enable or disable it using the check box at the front of the entry or right click on an entry to show up a context menu.The context menu provides access to the following commands:
  • Enable/Disable breakpoint - Enable or disable the selected breakpoint
  • Remove Breakpoint - Delete the selected breakpoint
  • Goto - Go to the source code line the breakpoint is attached to.
  • Properties - Modify the breakpoint condition and action.

Breakpoint Properties


Breakpoint Properties Dialog
Every breakpoint supports a range of properties to control its behavior. To examine or modify these properties, right click on a breakpoint and select Properties from the context menu.

Breakpoints can be configured to only pause evaluation under a certain condition. To make a breakpoint conditional, check the Active the breakpoint based on the following condition option. Type the condition as Equilla code in the corresponding editor and specify how to interpret the condition.

Beside conditions, you can also specify what to do when the break point is hit. The default behavior is to pause evaluation, but you can also specify that the debugger should simply print a message to the output window. Available options are:
  • Break – Pauses the evaluation when the breakpoint is hit. This is the default behavior.
  • Print a message on historic bars – Prints the specified message when the breakpoint is hit while evaluating historic bars.
  • Print a message on real-time bars – Prints the specified message when the breakpoint is hit while evaluating real-time bars.
  • Print a message on every bar – Always prints the specified message when the breakpoint is hit.
  • Continue execution – Specifies if the debugger should continue execution when the breakpoint is hit or if the evaluation should be paused as it is done for standard breakpoints.

Breaking on runtime errors

By default, if a runtime error occurs, the debugger will automatically break on the instruction that caused the error. This allows the developer to identify exactly what went wrong, without having to manually set breakpoints to stop just before the error.

This feature may be enabled or disabled in the property inspector, using the Break on Runtime Error property.

In the case that runtime errors are disabled in a Equilla Script, the break point will still be triggered, although the execution can then be resumed afterwards.

Objects


Objects view
The objects view shows what objects are available for debugging. It also enables you to filter what items should be debugged.

To enable or disable debugging for an object, simply set or clear the check box in front of it.

Use the context menu to toggle between these two modes.

Debugger Commands

The debugger document supports the following commands:

Debug Group

  • Break - Pauses the execution when the next evaluation starts. Please be aware that some new data has to arrive in order to trigger an evaluation. If the market is closed, the debugger will pause with the next tick that arrives.
  • Continue – Continues evaluation when the evaluation is paused.
  • Restart - Restarts the evaluation of the complete chart. All scripts will be reevaluated starting with bar 1.
  • Step In – Steps into an Equilla script function, entering the next level in the call stack. If the next instruction is not an Equilla script function, this command acts like the Step Over command.
  • Step Over – Steps over the next line.
  • Step Out – Steps out of the current Equilla script, going back one level in the call stack.
  • Quick Watch – Shows the quick watch dialog that can be used to evaluate Equilla expressions or inspect the state of variables and objects.
  • Attach – Attaches the debugger to a document.
  • Detach – Detaches the debugger from the currently debugged document.

Breakpoints Group

  • Toggle Breakpoint – Adds a new or removes an existing breakpoint.
  • Enable/Disable – Enables or disables an existing breakpoint.
  • Remove Breakpoint – Removes an existing breakpoint.

Properties

The debugger document offers the following properties to be modified from the Property Inspector:
  • Fontsize''' – Controls the size of the text in the Equilla script views. The default value is 9.
  • Trace Order State Changes (Historic) – Enables or disables the tracing of order state changes while evaluating historic data. The default value is false.
  • Trace Order State Changes (Real-time) – Enables or disables the tracing of order state changes while evaluating real-time bars. The default value is false.
  • Quick Watch


    Quick Watch Dialog
    The Quick Watch can be used to inspect the state of variables and object and to evaluate Equilla expressions.

    While providing the same functionality as the Watch view it allows the resizing of the output area without affecting the general layout of the debugger document. Therefor it can be used to quickly inspect the state of a variable or object even if the information does not fit into the space available for the Watch view.

    Debug Expressions

    The Equilla debugger supports a wide range of debug expressions that can be evaluated in the Watch view or the Quick Watch dialog. This includes some predefined expressions that provide information about the debugged document or the currently debugged object.

    Predefined expressions

    • VM – This expression provides access to the state of the debugged document. This includes settings, references to all instruments used in the document as well as all elements in the chart, like instruments, indicators, strategies and tools. When debugging strategies it also provides information about positions, orders and statistics.
    • This – This expression provides access to the state of the currently debugged object. This includes parent objects and input instruments, as well as, error information, generated output data and trading related data.

    Equilla expressions

    In addition to the predefined debug expressions, you can evaluate standard Equilla code and evaluate it in the debugger. While you can use all build-in Equilla functions, you cannot use any Equilla script function.

    Valid examples, using only build-in functions or standard operators:
    Sum(close, 10) / 10

    (Close[1] + Close) / 2
    Invalid example, using a script function rather than a build in function:
    Average(Close, 10)
    Please be aware that some variable might not be available in the debugger. This is caused by code optimizations that are applied to the source code when compiling it. This may result in variables being removed or replaced in order to save resources and increase the evaluation speed. Additionally the compiler may reorder the instructions in its optimization phase, leading to unexpected jumps while stepping through the code.

    Chart


    Debugged chart
    When attaching a debugger to a chart document, the chart will display a corresponding hint below the standard legend.