The debugger is enabled on if the canvas debug attribute is set to true:

Example 51.1. The canvas debug attribute

<canvas width="100%" height="125" debug="true">
  <debug y="5"/>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2008 Laszlo Systems, Inc.  All Rights Reserved.                   *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Check the Debug checkbox on the developer console to request a copy of the application with debugging enabled. This is equivalent to recompiling the application with the debug="true".

Edit the URL that is used to request the application to include the debug=true query parameter. This is equivalent to checking the Debug checkbox in the developer console.

See the OpenLaszlo System Administrator's Guide for more information about request types.

Consider the following debugger evaluations. Notice that the second case is terminated with a semicolon; otherwise the expressions are identical:

lzx> function foo () { return 'Fu'; }
Function#0| foo
lzx> foo
WARNING: interactive-eval-2:-1: reference to undefined variable 'foo'
lzx> function foo () { return 'Fu'; };
lzx> foo
Function#2| foo

In the first case, a function named foo is created, but it is not the value of the global foo. Instead the Debug evaluator returns a value which is that function object. In the second case, the evaluator does not return a value, and the global foo is defined to be the function. Why is that?

The answer is that the debugger evaluator will first try to evaluate what you type as an expression, and if that fails, it will try to evaluate it as a statement. The second form is clearly not an expression (think of what you type as having parentheses around it—the semi-colon forces the second form to be a statement list, with an empty second statement). This distinction, although subtle, is correct ECMAscript semantics. It is not whether you name a function or not that determines when a global definition will be made; rather, two things must be true:

If the function declaration occurs in an expression context, all you have done is to create a named function object as the value of that expression, you have not defined that name as the function.

Therefore, if you ever wonder why when you define a function in the debugger it does not behave as you expect, take a clue from what the evaluator prints out: if it prints out a function object, all you did was create a function, not define a function. Add the semi-colon after your definition and you will define the function (and not see a value printed).

Within a debugger expression, _ refers to the value of the previous expression. For example, after evaluating canvas.width to display the width of the canvas, you can evaluate the expression _/2 to display half this width.

The debugger defines the following variables:

By default, the debugger will occupy the bottom half of your application's <canvas>. You can change the basic properties of the debugger by including the debug tag in your application, like this:

<debug x="100" y="100" height="500"/>

In DHTML, the debugger appears as a separate HTML frame, rather than in-line in the application. As a consequence the <debug> tag does not actually control the size of the debugger frame.

Note that this does not enable the debugger; it merely configures its appearance when the debugger is enabled. You still have use one of the methods in Section 2, “Enabling the Debugger” to enable debugging. The effect of this is that you can leave the <debug> tag in your program at all times (including in production code), and it will only have an effect when debugging is enabled.

Debug.write() displays the printable representation of an object. Where possible, the representation of an object is what you would type to represent that object in a program. This is the case for instances of Singleton types (types with only a single instance, e.g., Undefined and Null) and for instances of Atomic types (types whose members have only a single value, no properties; e.g., Boolean or Number). Instances of Strings are normally not presented in this fashion (i.e., they are not quoted), as usually they are either a message or formatting. Instances of compound types (types with properties, e.g., Array and Object) and Strings that are longer than Debug.printLength are printed in inspectable format:

where:

By default an object is described by its properties, a function by its name (if available).

In addition to Debug.write(), Debug.warn(), Debug.info(), Debug.format(), there are utilities for determining client environment (Debug.versionInfo() and others)

Descriptions and Strings are abbreviated to the first Debug.printLength characters. This property defaults to 1024. You can see all the properties of an abbreviated object, or all of a string by inspecting it (but take care to check the length of the object — it may take a very long time to print if it is large).

When the debugger prints an object, if the type part of the description is enclosed in ?'s, it means that the object is potentially corrupted. (Technically it means that object instanceof object.[[prototype]].constructor is not true.)

Debug messages are enabled/disabled by the setting of Debug.messageLevel. The valid levels are one of the keys of Debug.messageLevels. All messages of a lower level than the current setting will be suppressed.

Example 51.7. Setting the debug message level

<canvas width="100%" height="200" debug="true">
  <script>
    //one of: "ALL", "DEBUG", "INFO", "WARNING", "ERROR", "NONE"
    Debug.messageLevel = "WARNING";
    
    Debug.write("write");  
    Debug.debug("debug");
    Debug.info("info");
    Debug.warn("warn");
    Debug.error("error");
  </script>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2008 Laszlo Systems, Inc.  All Rights Reserved.                   *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Debug.formatToString produces formatted output to a string, formatting its arguments according to the control string:

There is an additional format specifier w that formats the argument as if by Debug.__String with the 'pretty' option and creates a 'hotlink' so the object can be inspected. If alternate format is requested (#), w uses the full Debug.__String format used by Debug.write. w format obeys Debug.printLength, binding it to the maximum width, if specified in the control string.

When the debugger prints a string and Debug.printPretty is false, it will escape all the SingleEscapeCharacter's in the string (i.e., ' " \ b \f \n \r \t \v). For example:

Debug.format('%#w', 'This is a "test"\nS\bring')  ->«string#6| "This is a \"test\"\nS\bring"»

Warnings and Errors are inspectable. If you click on them, you will inspect the warning or error object. If backtracing is enabled, a backtrace will be one of the properties of the object that you can inspect. Inspecting the backtrace will reveal the recorded stack frames which record: the function called, this and the arguments to the function.

When you invoke trace(), the debugger traces the named method of the object and prints a message to the Debug console each time it is called or returned from. When called, the message includes a timestamp, the name of the function and the arguments it was called with. When returned from, the message gives the name of the function and the value it returned (if any). If backtraces are enabled, inspecting the message will reveal the call chain that caused the modification.

The configuration parameter compiler.debug.backtrace, when true, causes the compiler to instrument functions to maintain a call stack. You must recompile both the OpenLaszlo Runtime Library and your program if you change the setting of this parameter. It defaults to false because there is significant overhead introduced in enabling backtracing; in general it is only useful on small test cases.

The configuration parameter is set in the configuration file lps.config , as explained in the OpenLaszlo System Administrator's Guide.

Backtracing is enabled if the Backtrace checkbox is checked in the developer's console. Backtracing is off by default because it imposes significant overhead on application runtime, but it can be invaluable in tracking down difficult bugs.

To create your own backtrace at any time:

Debug.backtrace()

There is an optional argument that is the number of frames to skip in creating the backtrace.

If you print a backtrace using Debug.write, it may be abbreviated, but clicking on it will reveal the full backtrace.

Debugger warnings will automatically include a backtrace. A backtrace snapshot can created by Debug.backtrace(). A backtrace is a subclass of array, converting it to a string will create a trace from innermost to outermost call, inspecting it will reveal the actual function objects that make up the array.

To get the full backtrace out of a debugger warning, you need to use:

Debug.ObjectForID(NN)

Where NN is the object ID of the backtrace object, and then click on the resulting object to see the full trace.

For debugging the DHTML runtime, we recommend the Firebug extension to Firefox. If Firebug reports an error (with a little tiny red X in the bottom right hand corner of your Firefox window) then there is probably a bug in your code or an OpenLaszlo bug. The errors reported by Firebug can be very obscure, but they usually happen when you are dereferencing a null pointer.

Firebug is more useful if you compile your DHTML application under debug mode (debug=true) so that method names show up in firebug stack traces. Dropping down the arrow next to an exception in firebug will show a complete stack trace - often helpful for tracking down the root cause. Please file bugs with a stack trace if possible!

When you're compiling to DHTML, you generally use a two-step/two debugger process. It is always a good practice for you to have Firebug, because the OpenLaszlo debugger does not catch _all_ errors (it would be too much overhead to do so). We try to make our code debuggable in Firebug, as much as possible, but there are several limitations:

	Note
	If you have Firebug enabled in Firefox, the LZX debugger echos all messages to the Firebug console, preserving objects. The Firebug debugger will attempt to interpret an object with a length field as an array and try to print every array element. This may cause a Script Running Slowly error. Disabling Firebug will prevent that.

If you are using Safari to debug DHTML, we recommend that you enable Preferences/Advanced/Show Develop menu in menu bar and from that menu Develop/Show Error Console. This will enable Safari's console, and as with Firebug, you will be able to catch errors not caught by the LZX debugger.

The Flash runtime is permissive about dereferencing a null reference and getting properties on an undefined object. DHTML blows up if you do this. By "blows up" we mean that each DHTML browser crashes or hangs in a different way when the application code dereferences a null pointer. Lots of legacy code doesn't check for null.

In JavaScript you are allowed to ask for a non-existent slot, but not for a slot on something that is not an object. Therefore, don't say foo.bar unless you know that foo is an object. If you know foo is either an object or null, you can say if (foo) before you say foo.bar. If you don't even know that, you would need to say if (foo is Object).

Furthermore, in DHTML you cannot reference a non-existent variable. Therefore you should declare all your variables. In SWF, you could get by without declaring them, and they would just appear to be undefined, in DHTML, you will get a has no properties error if you refer to foo and you have not first said var foo.