Jmol/debugging

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 techniquesGeneral debugging techniques

There are multiple ways to insert breakpoints into Jmol scripts, pausing the script to verify the script progresses to 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 applicationTechniques 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 browserTechniques specific to JSmol run in a browser

You can use the JSmol Console to query variable values as

javascript alert(javascript-expression)

or

javascript alert(jmolEvaluate(jmol-expression))

AcknowledgementsAcknowledgements

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