Jmol/debugging

From Proteopedia

Debugging refers to finding and fixing errors in programs or scripts. Jmol has an extensive scripting language that implements a dialect of javascript. Because this dialect is not completely compatible with javascript, it is not possible to debug Jmol scripts using debuggers made for javascript. Instead, there are ways to debug right in the Jmol application or in a browser running JSmol.

General debugging techniques

There are multiple ways to insert breakpoints into Jmol scripts, pausing the script to verify the script progress at a certain point, and allowing you to check the state of variables at this point. The "pause" command pauses the script and gives control to you until you type "resume" in the console. The "prompt" command, given without parameters, opens a pop-up screen with the stack trace of the script.

There are a variety of commands described under "set (debugging)" in the manual that help with debugging and analyzing program crashes. For example, you can use the history function in the Jmol console to see which commands executed after setting the historyLevel to a non-zero value.

Of course, it is also possible to add strategic "print" statements to the script but the techniques described above are more flexible because they pause the script or give you a chance of a post-mortem analysis.

Techniques specific to the Jmol application

You can open the Jmol script editor to step through a script. If you are in an endless loop, you can pause the script to see where you are stuck. After a script crashes, you can open the Java console to see which Java exception was raised.

Techniques specific to JSmol run in a browser

When JSmol is running in a browser, bugs can occur either in the browser javascript that sends commands to JSmol, or in the JSmol commands themselves. To look for bugs in javascript, open the browser's console. For example, in Firefox: Tools, Web Developer, Browser Console.

To open the JSmol Console: Right click in JSmol so that the menu appears, and then click on Console.

You can use the JSmol Console to query variable values:

print jmol-expression

or

javascript alert(javascript-expression)

Acknowledgements

Some of these techniques were suggested by Bob Hanson and Eric Martz in response to a query on the Jmol listserv.