When you run an application with debugging enabled, the application is compiled with instrumentation to detect runtime errors, and the debugger window appears within the application canvas. The debugger provides these features:

Debugging may cause the application to run more slowly, even if the debugger window is not visible.

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

2.1. The debug attribute

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 ****************************************************** -->

Flash

HTML5

Enabling the debugger using one of the methods described in Section 2, “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.

Example 51.2. Runtime exceptions printed once per line

<canvas debug="true" height="150" width="100%">
  <debug y="10"/>
  <handler name="oninit"><![CDATA[
    for (var i = 0; i < 10; i ++) {
      canvas.width();
    }
  ]]></handler>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2008 Laszlo Systems, Inc.  All Rights Reserved.                   *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

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() or Debug.format() (or one of its variants) to print to the debugger log. These methods are variadic: they take any number of arguments. The text representations of the arguments are printed to the debugger log, separated by spaces.

Example 51.3. Logging to the debugger

<canvas debug="true" height="200" width="100%">
<debug x="160" y="5" height="150" width="300"/>
  <script>Debug.debug('user code');</script>
  <button text="Get x, y" width="150" height="150" onclick="Debug.debug('click: x=%d, y=%d', getMouse('x'), getMouse('y'))"/>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2008 Laszlo Systems, Inc.  All Rights Reserved.                   *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

Debug.write() is the simplest way to log to the debugger, but it's often a better strategy to use Debug.format() or one of its variants (Debug.debug(), Debug.info(), Debug.warn(), and Debug.error(). These methods give you more control over the format of the output. See the reference pages for Debug and lz.Formatter for a complete description and examples. In addition, you can control which messages are logged to the debugger using Debug.messageLevel.

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

There simplest way to get LPS version information is to use canvas.lpsversion.

Example 51.4. Using canvas.lpsversion

<canvas width="100%" height="200" debug="true">
<debug x="5" y="50" height="100"/>
    <handler name="oninit">
        Debug.debug('LPS version %s', canvas.lpsversion)
    </handler>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2007, 2008 Laszlo Systems, Inc.  All Rights Reserved.             *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

You can get more information, for example the build number and target runtime, by using Debug.versionInfo().

Example 51.5. Using Debug.versionInfo()

<canvas width="100%" height="225" debug="true">
<debug x="5" y="5" height="200"/>
    <handler name="oninit">
        Debug.versionInfo()
    </handler>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2008 Laszlo Systems, Inc.  All Rights Reserved.                   *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

While the previous two methods give you version information, if you want to generat a full bug report, see Section 9, “Generating a bug report”.

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 lz.Browser.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.debug("%d", 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

Explain the style bindings of properties on a node For each attribute of the node that has a $style binding, the CSS rules that apply to the node that could affect that binding are displayed. The rules are displayed (with their source) from the most-specific to the least specific, and the style names and values of the rule that apply to this node are displayed. Values that are superseded by more specific rules are displayed in italics.

The following example demonstrates the use of Debug.explainStyleBindings(). Click on the color buttons to toggle the colors; click on the color swatches to see the CSS description.

Example 51.6. Dynamic CSS

<canvas width="100%" height="500" debug="true"> 
  <debug x="30%" width="65%" y="5%" height="90%"/>
  <stylesheet>
    /* default, should only be seen if things are broken */
    colorswatch { background-color: orange }

    /* Static for buttons */
    colorbutton[color=red] {background-color: red }
    /* `lime` is the HTML name for rgb(0,255,0) */
    colorbutton[color=green] {background-color: lime }
    colorbutton[color=blue] {background-color: blue }

    /* dynamic single selectors that apply to individual swatches */
    [red=off] colorswatch { background-color: cyan; opacity: 0.2 }
    [red=on] colorswatch { background-color: red; opacity: 0.95 }
    [green=off] colorswatch { background-color: magenta; opacity: 0.2 }
    [green=on] colorswatch { background-color: lime; opacity: 0.95 }
    [blue=off] colorswatch { background-color: yellow; opacity: 0.2 }
    [blue=on] colorswatch { background-color: blue; opacity: 0.95 }

    /* dynamic compound selectors that apply to mixer colorswatch */
    [red=off] [green=off] [blue=off] [name=mixer] colorswatch { background-color: black; opacity: 1 }
    [red=off] [green=off] [blue=on] [name=mixer] colorswatch { background-color: blue; opacity: 1 }
    [red=off] [green=on] [blue=off] [name=mixer] colorswatch { background-color: lime; opacity: 1 }
    [red=off] [green=on] [blue=on] [name=mixer] colorswatch { background-color: cyan; opacity: 1 }
    [red=on] [green=off] [blue=off] [name=mixer] colorswatch { background-color: red; opacity: 1 }
    [red=on] [green=off] [blue=on] [name=mixer] colorswatch { background-color: magenta; opacity: 1 }
    [red=on] [green=on] [blue=off] [name=mixer] colorswatch { background-color: yellow; opacity: 1 }
    [red=on] [green=on] [blue=on] [name=mixer] colorswatch { background-color: white; opacity: 1 }
  </stylesheet>

 <!-- button to toggle an attribute which should trigger style change -->
  <class name="colorbutton" width="40" height="20" align="center">
    <attribute name="bgcolor" style="background-color"/>
    <attribute name="color" type="string"/>
    <text fgcolor="white" text="${this.parent.on}" align="center"/>
    <attribute name="on" type="string" value="off"/>
    <handler name="onclick">
      this.setAttribute('on', this.on === 'on' ? 'off' : 'on' );
    </handler>
  </class>

  <!-- color swatch that is styled by background-color and opacity -->
  <class name="colorswatch" height="60" width="60" bgcolor="gray" align="center">
    <attribute name="swatchcolor" style="background-color" type="color"/>
    <attribute name="swatchopacity" style="opacity" value="1"/>
    <handler name="onclick">
      Debug.clear();
      Debug.explainStyleBindings(this);
    </handler>
    <view name="swatch" x="5" y="5" height="50" width="50">
      <attribute name="bgcolor" value="${parent.swatchcolor}"/>
      <attribute name="opacity" value="${parent.swatchopacity}"/>
    </view>
  </class>

  <!-- nested views with red, green, blue attributes that dynamically change
       to demonstrate the applicability of compound dynamic selectors  -->
  <view x="5%" y="5%" width="20%" height="80%" layout="axis: y; spacing: 5">
    <text width="100%" multiline="true">
      Toggle the red, green, and blue buttons on and off to
      dynamically update the applicable CSS selectors.  Click on a color
      swatch to explain the applicability of the CSS selectors.
    </text>
    <attribute name="red" value="${this.toggle.on}" type="string"/>
    <colorbutton name="toggle" color="red"/>
    <colorswatch/>
    <view width="100%" layout="axis: y; spacing: 5">
      <attribute name="green" value="${this.toggle.on}" type="string"/>
      <colorbutton name="toggle" color="green"/>
      <colorswatch/>
      <view width="100%" layout="axis: y; spacing: 5">
        <attribute name="blue" value="${this.toggle.on}" type="string"/>
        <colorbutton name="toggle" color="blue"/>
        <colorswatch/>
        <view width="100%" name="mixer" layout="axis: y; spacing: 5">
          <text align="center">Mixer</text>
          <colorswatch id="mixer"/>
        </view>
      </view>
    </view>
  </view>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
  * Copyright 2010 Laszlo Systems, Inc.  All Rights Reserved.                   *
  * Use is subject to license terms.                                            *
  * X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

Evaluating Debug.debug(object), where object is an expression that evaluates to a JavaScript object, displays an inspectable representation of the object in the debugger (not the actual object). Long objects are abbreviated based on the value of Debug.printLength (see Section 11, “Configuring the Debugger”). Abbreviated objects are shown enclosed in double angle quotes, with an ellipsis indicating abbreviation like this:

If you inspect the abbreviated output, it will print the full object.

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 __ (two 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 lz.dataset, 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.debug(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. Because it's easy to confuse these two calling styles, it's almost always better to use Debug.format() or one of its variants, like Debug.debug().

Example 51.7. Two ways of calling Debug.write

<canvas debug="true" height="250" width="100%">
  <debug y="10" height="200"/>
  <handler name="oninit">
    Debug.write('subviews: ' + canvas.subviews);
    Debug.write('subviews:',   canvas.subviews);
    Debug.debug('subviews: %#w',   canvas.subviews);
    Debug.debug('subviews: %w',   canvas.subviews);
  </handler>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2008 Laszlo Systems, Inc.  All Rights Reserved.                   *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

If you encounter a bug that prints a message in the debugger and you believe it is an OpenLaszlo bug, take the following steps to generate a bug report:

The Bug Report gives details of the exact build of OpenLaszlo that you are reporting on, the detailed error message, backtrace, and the details of all objects involved.

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.

	Note
	This section is unlikely to be of use to LZX users, but it can be helpful for LZX developers.

Messages can be written from an LZX application to the server log through the use of the logdebug=true query parameter and the Debug.log() method.

If you set logdebug to true, then any output to the debugger will be logged. This can be helpful if you find the system crashing before the debugger is started. We recommend using the console debugger first and only resort to logging if even the console debugger is not working. (For the DHTML runtimes, if there is a runtime console object with a log method, logging will be automatically turned on. This is the case for Safari if the Developer feature is enabled, or Firefox if the Firebug plug-in is installed.)

Where does logging information go? In the case of the SWF8 runtime, the information is logged back to the LZX server and can be seen by inspecting the server log. For the DHTML runtime, if the browser supports a console (e.g., developer versions of Firefox, Safari), the information will be logged to the browser console. For the SWF9 runtime, if the application is being run under the Flex debugger, fdb, the information will be logged to the debugger.

The Debug.log() method can be used to log directly to the server, independent of the setting of logdebug, but this is hardly ever necessary. It takes a single argument; if the argument is the result of Debug.formatToString, some runtimes (e.g., DHTML on Firefox) will "present" the formatted string in a way that will allow you to inspect the objects represented by the string, but this is not supported for all runtimes.

See the OpenLaszlo System Administrator's Guide for information about configuration and reading the server log.

The debugger has capabilities for formatting output according to control strings.

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

13.3. Inspecting Warnings and Errors

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.

13.3.1. Inspecting a debug message to see the backtrace

In the following example, when you click on the button, it causes a Debug message to be printed.

Clicking on the debug message will inspect that, and reveal the backtrace associated with the message.

Note

The <canvas compileroptions= "..." ensures that backtraces are on for this example. This option is only available in OpenLaszlo revisions 4.2.1 and later. Backtraces can also be enabled in the developer console, which is what you would normally do. In general, you would not deploy an application with backtraces on as they impact the performance of the application significantly. Backtraces are currently only available in SWF8 and DHTML runtimes.

If you click on one of the entries in the backtrace, you will see that it is a StackFrame, and will tell you the function that is called, the arguments, and the value of this in that call. Each of those in turn can be clicked on to inspect more deeply.

Example 51.9. Backtrace example

<canvas compileroptions="debug: true; backtrace: true" width="100%" height="300"> 
  <debug x="80" height="90%"/> 
  <button name="test" width="75" height="75"> 
    <handler name="onclick"> Debug.debug("Now click on this message, and then click on the backtrace value you see"); </handler> 
    Click Me! 
  </button> 
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2007, 2009 Laszlo Systems, Inc.  All Rights Reserved.             *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

Debug.monitor(who, what): Takes an object and property name and will emit a monitor message each time that property is changed.

Debug.unmonitor(who, what): Turns that off.

A monitor message consists of the function that caused the change, a timestamp, the object and property, and the old and new values. The following example uses Debug.monitor() and Debug.trace():

Example 51.10. Using Debug.monitor() and Debug.trace()

<canvas debug="true" width="100%" height="225">
<debug x="110" y="0" height="245" width="550"/>
  <button name="test" width="100" height="100">
    <handler name="onclick"> this.clicked(); </handler>
    <method name="clicked" args="ignore=null">
      this.x = this.getMouse('x');
      this.y = this.getMouse('y');
      return this.x * this.y;
    </method>
    Click Me!
  </button>
  <script>
    Debug.monitor(test, 'x');
    Debug.monitor(test, 'y');
    Debug.trace(test, 'clicked');
  </script>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2008 Laszlo Systems, Inc.  All Rights Reserved.                   *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

As shown in this example:

If backtracing is enabled, the trace and monitor messages also capture a backtrace (which you can see by inspecting the message). Can be especially handy if you are trying to figure out who/what/when is calling a method or clobbering a property.

A running OpenLaszlo application allocates parts of available virtual memory to store objects. When these objects are no longer needed the memory should be released by the application in order to become once again available for other use. Sometimes unneeded memory is not properly released, in which case the application tends to slow down over time as less and less memory becomes available. This is "leaking memory." The OpenLaszlo debugger can help you find memory leaks.

Three methods on Debug are used to find leaks:

You use them in that order. Typically, you will start up your program, run it for a bit until you think it has reached a steady state. Then invoke Debug.markObjects(). This runs in the background and will mark all the objects that are currently in use. When you see the output Trace Done you can move on to the next step.

     lzx> Debug.markObjects()
     WARNING: Memory tracing is for experimental use only in this runtime.
     Marking objects …
     lzx> DEBUG: 1 loops @ 7590 iterations, 1194.00 milliseconds
     … done!
   

You exercise your application in a way that you expect not to result in any retained storage (or some small amount of retained storage).

    lzx> canvas.thisIsALeak = {some: 'new', data: 42}
    «Object#136| {data: 42, some: 'new'}»
    

Run Debug.findNewObjects(). This also runs in the background and will find any new objects that have been allocated since the markObjects() call that have not yet been garbage-collected. When you see the output done! you can move on to the next step.

    lzx> Debug.findNewObjects()
    WARNING: Memory tracing is for experimental use only in this runtime.
    Finding new objects …
    lzx> DEBUG: 2 loops @ 3797 iterations, 674.50 milliseconds
    … done!
    

Call Debug.whyAlive(). This returns a leak list.

    lzx> Debug.whyAlive()
    WARNING: Memory tracing is for experimental use only in this runtime.
    18 smoots [1 objects @ ~18 smoots each]:
    global.canvas.thisIsALeak: (£18) «Object#136| {…, data: 42, some: 'new'}»
    «__LzLeaks(2)#140| 18 smoots [1 objects @ ~18 smoots each]»
    lzx>
  

showing <why>: (<size>): <what> pairs. <why> is the shortest path from global that is keeping the object from being collected; <size> is an approximation (in Smoots) of the size of the object and its descendants, which is a rough indication of the cost of the object; <what> is the debugger representation of the object. You can also inspect the leak list items to see the objects that have been retained.