There are three ways to turn on the debugger in your application:

Enabling the debugger has two effects:

A program that is compiled with runtime error checking will contain code that checks for the following conditions:

Each runtime exception warning is printed once per line per program run, not once each time the exception is encountered. The following program will print one warning, not ten.

<canvas debug="true" height="150">
  <handler name="oninit"><![CDATA[
    for (var i = 0; i > 10; i ++) {
      canvas.width();
    }
  ]]></handler>
</canvas>

Turning on runtime error checking makes an application bigger and slower. You should only perform size and speed optimization on the non-debug version of a program. Nonetheless, you will frequently want to run the debug warning to see whether you have introduced any runtime errors.

The top portion of the debugger window is the debugger log. Use Debug.write() to print to the debugger log. This method is variadic: it takes any number of arguments. The text representations of the arguments are printed to the debugger log, separated by spaces.

Example 50.3. Logging to the debugger

<canvas debug="true" height="150">
  <script>
    Debug.write('user code');
  </script>
  <button onclick="Debug.write('click', getMouse('x'))"/>
</canvas>

Some object are inspectable. See Section 1.5, “Inspecting Objects” for more about the inspect feature of the debugger. See Section 2.2, “Customizing Debug.write()” to see how to customize the display of objects within the debugger.

The bottom portion of the debugger window is the evaluator. This is a command-line interface for evaluating JavaScript expressions and statements within the application. Enter a JavaScript statement into this area and press the Enter key (in single-line mode) or the Evaluate button (in multi-line mode) to evaluate the statement within the application. If the statement is an expression, its result (if the result is not undefined) is printed to the debugger log. If it is a statement but not an expression, it is executed for effect.

Examples of expressions are canvas.x, 1+2, and LzBrowser.LoadURL('http://www.laszlosystems.com/', '_blank'). (The last expression returns the value undefined, so the debugger does not print the expression value in the debugger log.) An example of a non-expression statements is for (int i = 0; i < 10; i++) Debug.write(i). This is evaluated for effect, and the statement itself does not result in a value, although each execution of the loop prints the value of i to the debugger log.

The debugger can be used to define global variables. Use the var keyword to define a new global variable. For example, after evaluating var n=100, evaluating n+1 will print the value 101.

	Note
	The var keyword is only necessary to define new global variables. You do not need it to change the value of existing variables. For example, after evaluating var n=100, you can evaluate n=200 to change the value of n. You do not need to evaluate var n=200 (although the extra var is harmless.)

You can also use var to create new global functions. var f = function (x) {return x+1} creates a new function named f, which can be used in subsequent expressions such as f(1).

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

Evaluating Debug.write(object), where object is an expression that evaluates to a JavaScript object, displays an inspectable representation of the object in the debugger. Clicking on an inspectable object displays its non-private properties and their values. Those values which are objects are also displayed as inspectable objects, so that they can be clicked on as well.

An object's private properties are those whose names begin with $ or ___ (three underscore characters). These names are used by the compiler and by the OpenLaszlo Runtime Library implementation, respectively, and are not part of the documented API for the object.

An inspectable object can be an OpenLaszlo Runtime Library object such as a window or LzDataset, or a built-in JavaScript object: for example, an array such as [1, 2, 3], or a Object such as {a: 1, b: 2}.

The Debug.inspect() function also displays the object and its properties. Evaluating Debug.inspect(object) is equivalent to evaluating Debug.write(object) and then clicking on the object's representation.

	Note
	Debug.write() behaves differently depending on whether its argument is a string or a non-string object. Note the difference between the two calls to Debug.write() in the example below.

Example 50.4. Two ways of calling Debug.write

<canvas debug="true" height="150">
  <handler name="oninit">
    Debug.write('subviews: ' + canvas.subviews); 
    Debug.write('subviews:',   canvas.subviews);  
  </handler>
</canvas>

	The (only) argument to Debug.write() is a string, so the value of canvas.subviews is not inspectable.
	The second argument to Debug.write() is an non-string Object, so it is inspectable.

Sometimes you may have computations that you need to make only when you're debugging an application. For example, you may include some time stamps in order to measure performance of certain sections of code.

The best practice here is to enclose any debug-only computations in

if ($debug) {
  ...
}

The compiler will omit those statements when you compile without debugging.

By default, the debugger comes up over the top left corner of your application. You can change the basic properties of the debugger by including the <debug> tag in your app, like this: <debug x="100" y="100" height="500"/>.

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 1.1, “Enabling the Debugger” to enable debugging. The effect of this is that you can leave the <debug> 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 addtion 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.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 the debug.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 System Administrator's Guide.

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:

__LzDebug.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:

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.

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 instanceof 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, it is an error to refer to foo if you have not first said var foo.

If you are trying to make some legacy code work, you can ask if ('foo' in global) to see if foo had been declared, but that's sloppy. It's better to inspect your code to make sure that all variables are initialized before they're referenced. Even if you're not planning to compile to DHTML, you should use the more conservative style, as this will enhance maintainability and allow you to retarget for DHTML in the future if you decide to do so.